Storage Engines

A storage engine holds everything a client needs to resume a session: the datacenter and auth key, the peer cache, the usernames, and the update state. Client takes one through its storage_engine argument, and defaults to a SQLite file next to your script.

Storage Engines is the guide — which engine to pick, what the hybrid one trades away, and how to write your own. This page is the reference.

Local

class pyrogram.storage.SQLiteStorage[source]
class pyrogram.storage.FileStorage[source]
class pyrogram.storage.MemoryStorage[source]

Remote

class pyrogram.storage.RemoteStorage[source]

Base for storage engines that keep the session somewhere other than a local file.

A subclass implements the primitives listed below and gets the whole Storage surface from here, including the two caches that keep the hot path off the network:

  • session attributes are read once and then served from memory, so dc_id() on every send is a dict lookup rather than a round trip;

  • peer rows are held in a bounded cache, and update_peers skips peers whose access hash has not changed - every invoke feeds r.users and r.chats back through fetch_peers, so without that filter the same unchanged peers are rewritten on every single RPC.

USERNAME_TTL is enforced here, on read, rather than by an expiry feature of the store: a backend that drops the row itself would disagree with what the SQLite engine does with a stale one.

class pyrogram.storage.MongoStorage[source]

Keep the session in MongoDB.

Every read that matters is served from the caches in RemoteStorage, so Mongo is touched on open, on a peer the client has never seen, and on writes.

Parameters:

  • name (str) – Session name. Also the default database name.

  • connection (str | object) – A connection URI, or an already-created motor / async_pymongo client to reuse.

  • database (str, optional) – Database to use. Defaults to name.

  • session_string (str, optional) – Load this session string into the store when opening.

class pyrogram.storage.RedisStorage[source]

Keep the session in Redis.

Warning

An evicted session key is a lost login. Peers are a cache and can be evicted safely, but the session hash cannot - run the database with maxmemory-policy noeviction, or give wzgram a database of its own. Opening this storage logs a warning when the server reports any other policy.

Parameters:

  • name (str) – Session name, used to build the key prefix.

  • connection (str | object) – A connection URI, or an already-created redis.asyncio client.

  • prefix (str, optional) – Key prefix. Defaults to wzgram:<name>.

  • session_string (str, optional) – Load this session string into the store when opening.

Hybrid

class pyrogram.storage.HybridStorage[source]

A local cache in front of a persistent backend.

Every read is served by a local SQLiteStorage, so resolve_peer never pays network latency. Writes land locally first and are mirrored to the backend by a background task, coalesced by key.

What that buys, and what it costs:

  • the backend can be slow, or briefly gone, without the client noticing: a failed write is retried with backoff and reads keep working;

  • the last few writes live only in the local cache until the writer drains, so a hard kill can lose them. close() flushes; a SIGKILL does not.

Parameters:

  • name (str) – Session name.

  • backend (Storage) – Where the session is persisted. Usually a RemoteStorage subclass.

  • workdir (Path, optional) – Where the local cache file goes when cache_in_memory is False.

  • cache_in_memory (bool, optional) – Keep the local cache in memory. Defaults to True. Pass False to keep it in a file, which survives a restart and skips the bulk load.

  • queue_size (int, optional) – Pending backend writes to hold. Defaults to 1024.

  • warm_peers (int, optional) – How many peers to pull into the cache on open. Defaults to 4096, the size of the in-memory peer cache. Pass 0 to fill on demand instead.

  • flush_timeout (float, optional) – Seconds close() waits for the queue to drain. Defaults to 10.

  • session_string (str, optional) – Load this session string into both layers when opening.

Base class

class pyrogram.storage.Storage[source]