Storage Engines

Every time you login to Telegram, some personal piece of data are created and held by both parties (the client, Pyrogram

and the server, Telegram). This session data is uniquely bound to your own account, indefinitely (until you logout or

decide to manually terminate it) and is used to authorize a client to execute API calls on behalf of your identity.

Persisting Sessions

In order to make a client reconnect successfully between restarts, that is, without having to start a new

authorization process from scratch each time, Pyrogram needs to store the generated session data somewhere.

Other useful data being stored is peers' cache. In short, peers are all those entities you can chat with, such as users

or bots, basic groups, but also channels and supergroups. Because of how Telegram works, a unique pair of **id** and

**access_hash** is needed to contact a peer. This, plus other useful info such as the peer type, is what is stored

inside a session storage.

So, if you ever wondered how is Pyrogram able to contact peers just by asking for their ids, it's because of this very

reason: the peer *id* is looked up in the internal database and the available *access_hash* is retrieved, which is then

used to correctly invoke API methods.

Different Storage Engines

Let's now talk about how Pyrogram actually stores all the relevant data. Pyrogram offers two different types of storage

engines: a **File Storage** and a **Memory Storage**. These engines are well integrated in the library and require a

minimal effort to set up. Here's how they work:

File Storage

This is the most common storage engine. It is implemented by using **SQLite**, which will store the session and peers

details. The database will be saved to disk as a single portable file and is designed to efficiently save and retrieve

peers whenever they are needed.

To use this type of engine, simply pass any name of your choice to the ``session_name`` parameter of the

:obj:`~pyrogram.Client` constructor, as usual:

.. code-block:: python

Once you successfully log in (either with a user or a bot identity), a session file will be created and saved to disk as

``my_account.session``. Any subsequent client restart will make Pyrogram search for a file named that way and the

session database will be automatically loaded.

Memory Storage

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

session name "**:memory:**" to the ``session_name`` parameter of the :obj:`~pyrogram.Client` constructor:

.. code-block:: python

This database is still backed by SQLite, but exists purely in memory. However, once you stop a client, the entire

database is discarded and the session details used for logging in again will be lost forever.

Session Strings

Session strings are useful when you want to run authorized Pyrogram clients on platforms like

`Heroku <https://www.heroku.com/>`_, where their ephemeral filesystems makes it much harder for a file-based storage

engine to properly work as intended.

In case you want to use an in-memory storage, but also want to keep access to the session you created, call

:meth:`~pyrogram.Client.export_session_string` anytime before stopping the client...

.. code-block:: python

...and save the resulting string somewhere. You can use this string as session name the next time you want to login

using the same session; the storage used will still be completely in-memory:

.. code-block:: python