|
| 1 | +Storage Engines |
| 2 | +=============== |
| 3 | + |
| 4 | +Every time you login to Telegram, some personal piece of data are created and held by both parties (the client, Pyrogram |
| 5 | +and the server, Telegram). This session data is uniquely bound to your own account, indefinitely (until you logout or |
| 6 | +decide to manually terminate it) and is used to authorize a client to execute API calls on behalf of your identity. |
| 7 | + |
| 8 | +Persisting Sessions |
| 9 | +------------------- |
| 10 | + |
| 11 | +In order to make a client reconnect successfully between restarts, that is, without having to start a new |
| 12 | +authorization process from scratch each time, Pyrogram needs to store the generated session data somewhere. |
| 13 | + |
| 14 | +Other useful data being stored is peers' cache. In short, peers are all those entities you can chat with, such as users |
| 15 | +or bots, basic groups, but also channels and supergroups. Because of how Telegram works, a unique pair of **id** and |
| 16 | +**access_hash** is needed to contact a peer. This, plus other useful info such as the peer type, is what is stored |
| 17 | +inside a session storage. |
| 18 | + |
| 19 | +So, if you ever wondered how is Pyrogram able to contact peers just by asking for their ids, it's because of this very |
| 20 | +reason: the peer *id* is looked up in the internal database and the available *access_hash* is retrieved, which is then |
| 21 | +used to correctly invoke API methods. |
| 22 | + |
| 23 | +Different Storage Engines |
| 24 | +------------------------- |
| 25 | + |
| 26 | +Let's now talk about how Pyrogram actually stores all the relevant data. Pyrogram offers two different types of storage |
| 27 | +engines: a **File Storage** and a **Memory Storage**. These engines are well integrated in the library and require a |
| 28 | +minimal effort to set up. Here's how they work: |
| 29 | + |
| 30 | +File Storage |
| 31 | +^^^^^^^^^^^^ |
| 32 | + |
| 33 | +This is the most common storage engine. It is implemented by using **SQLite**, which will store the session and peers |
| 34 | +details. The database will be saved to disk as a single portable file and is designed to efficiently save and retrieve |
| 35 | +peers whenever they are needed. |
| 36 | + |
| 37 | +To use this type of engine, simply pass any name of your choice to the ``session_name`` parameter of the |
| 38 | +:obj:`~pyrogram.Client` constructor, as usual: |
| 39 | + |
| 40 | +.. code-block:: python |
| 41 | +
|
| 42 | + from pyrogram import Client |
| 43 | +
|
| 44 | + with Client("my_account") as app: |
| 45 | + print(app.get_me()) |
| 46 | +
|
| 47 | +Once you successfully log in (either with a user or a bot identity), a session file will be created and saved to disk as |
| 48 | +``my_account.session``. Any subsequent client restart will make Pyrogram search for a file named that way and the |
| 49 | +session database will be automatically loaded. |
| 50 | + |
| 51 | +Memory Storage |
| 52 | +^^^^^^^^^^^^^^ |
| 53 | + |
| 54 | +In case you don't want to have any session file saved on disk, you can use an in-memory storage by passing the special |
| 55 | +session name "**:memory:**" to the ``session_name`` parameter of the :obj:`~pyrogram.Client` constructor: |
| 56 | + |
| 57 | +.. code-block:: python |
| 58 | +
|
| 59 | + from pyrogram import Client |
| 60 | +
|
| 61 | + with Client(":memory:") as app: |
| 62 | + print(app.get_me()) |
| 63 | +
|
| 64 | +This database is still backed by SQLite, but exists purely in memory. However, once you stop a client, the entire |
| 65 | +database is discarded and the session details used for logging in again will be lost forever. |
| 66 | + |
| 67 | +Session Strings |
| 68 | +--------------- |
| 69 | + |
| 70 | +Session strings are useful when you want to run authorized Pyrogram clients on platforms like |
| 71 | +`Heroku <https://www.heroku.com/>`_, where their ephemeral filesystems makes it much harder for a file-based storage |
| 72 | +engine to properly work as intended. |
| 73 | + |
| 74 | +In case you want to use an in-memory storage, but also want to keep access to the session you created, call |
| 75 | +:meth:`~pyrogram.Client.export_session_string` anytime before stopping the client... |
| 76 | + |
| 77 | +.. code-block:: python |
| 78 | +
|
| 79 | + from pyrogram import Client |
| 80 | +
|
| 81 | + with Client(":memory:") as app: |
| 82 | + print(app.export_session_string()) |
| 83 | +
|
| 84 | +...and save the resulting string somewhere. You can use this string as session name the next time you want to login |
| 85 | +using the same session; the storage used will still be completely in-memory: |
| 86 | + |
| 87 | +.. code-block:: python |
| 88 | +
|
| 89 | + from pyrogram import Client |
| 90 | +
|
| 91 | + session_string = "...ZnUIFD8jsjXTb8g_vpxx48k1zkov9sapD-tzjz-S4WZv70M..." |
| 92 | +
|
| 93 | + with Client(session_string) as app: |
| 94 | + print(app.get_me()) |
| 95 | +
|
0 commit comments