Storages

Storages out of the box

MemoryStorage

class aiogram.fsm.storage.memory.MemoryStorage

Default FSM storage; uses a regular dict to store data and does not persist it across restarts.

Warning

This storage is not recommended for production use, as all data is lost when the bot restarts

__init__() → None

RedisStorage

class aiogram.fsm.storage.redis.RedisStorage(redis: ~redis.asyncio.client.Redis, key_builder: ~aiogram.fsm.storage.base.KeyBuilder | None = None, state_ttl: int | ~datetime.timedelta | None = None, data_ttl: int | ~datetime.timedelta | None = None, json_loads: ~collections.abc.Callable[[...], ~typing.Any] = <function loads>, json_dumps: ~collections.abc.Callable[[...], str] = <function dumps>)

Redis storage requires the redis package (pip install redis)

__init__(redis: ~redis.asyncio.client.Redis, key_builder: ~aiogram.fsm.storage.base.KeyBuilder | None = None, state_ttl: int | ~datetime.timedelta | None = None, data_ttl: int | ~datetime.timedelta | None = None, json_loads: ~collections.abc.Callable[[...], ~typing.Any] = <function loads>, json_dumps: ~collections.abc.Callable[[...], str] = <function dumps>) → None

Parameters:

• redis – instance of Redis connection

• key_builder – builder that helps to convert contextual key to string

• state_ttl – TTL for state records

• data_ttl – TTL for data records

classmethod from_url(url: str, connection_kwargs: dict[str, Any] | None = None, **kwargs: Any) → RedisStorage

Create an instance of RedisStorage with the specified connection url

Parameters:

• url – the connection url (i.e. redis://user:password@host:port/db)

• connection_kwargs – see redis docs

• kwargs – arguments passed to RedisStorage

Returns:

an instance of RedisStorage

MongoStorage

class aiogram.fsm.storage.pymongo.PyMongoStorage(client: AsyncMongoClient[Any], key_builder: KeyBuilder | None = None, db_name: str = 'aiogram_fsm', collection_name: str = 'states_and_data')

MongoDB storage requires the pymongo package (pip install pymongo).

__init__(client: AsyncMongoClient[Any], key_builder: KeyBuilder | None = None, db_name: str = 'aiogram_fsm', collection_name: str = 'states_and_data') → None

Parameters:

• client – instance of AsyncMongoClient

• key_builder – builder that helps to convert contextual key to string

• db_name – name of the MongoDB database for FSM

• collection_name – name of the collection for storing FSM states and data

classmethod from_url(url: str, connection_kwargs: dict[str, Any] | None = None, **kwargs: Any) → PyMongoStorage

Create an instance of PyMongoStorage with the specified connection url

Parameters:

• url – the connection url (i.e. mongodb://user:password@host:port)

• connection_kwargs – see pymongo docs

• kwargs – arguments passed to PyMongoStorage

Returns:

an instance of PyMongoStorage

class aiogram.fsm.storage.mongo.MongoStorage(client: AsyncIOMotorClient, key_builder: KeyBuilder | None = None, db_name: str = 'aiogram_fsm', collection_name: str = 'states_and_data')

Warning

DEPRECATED: Use PyMongoStorage instead. This class will be removed in future versions.

MongoDB storage required motor package installed (pip install motor)

__init__(client: AsyncIOMotorClient, key_builder: KeyBuilder | None = None, db_name: str = 'aiogram_fsm', collection_name: str = 'states_and_data') → None

Parameters:

• client – Instance of AsyncIOMotorClient

• key_builder – builder that helps to convert contextual key to string

• db_name – name of the MongoDB database for FSM

• collection_name – name of the collection for storing FSM states and data

classmethod from_url(url: str, connection_kwargs: dict[str, Any] | None = None, **kwargs: Any) → MongoStorage

Create an instance of MongoStorage with specifying the connection string

Parameters:

• url – for example mongodb://user:password@host:port

• connection_kwargs – see motor docs

• kwargs – arguments to be passed to MongoStorage

Returns:

an instance of MongoStorage

KeyBuilder

Keys inside Redis and Mongo storages can be customized via key builders:

class aiogram.fsm.storage.base.KeyBuilder

Base class for key builder.

abstract build(key: StorageKey, part: Literal['data', 'state', 'lock'] | None = None) → str

Build key to be used in storage’s db queries

Parameters:

• key – contextual key

• part – part of the record

Returns:

key to be used in storage’s db queries

class aiogram.fsm.storage.base.DefaultKeyBuilder(*, prefix: str = 'fsm', separator: str = ':', with_bot_id: bool = False, with_business_connection_id: bool = False, with_destiny: bool = False)

Simple key builder with default prefix.

Generates a colon-joined string with prefix, chat_id, user_id, optional bot_id, business_connection_id, destiny and field.

Format:

<prefix>:<bot_id?>:<business_connection_id?>:<chat_id>:<user_id>:<destiny?>:<field?>

build(key: StorageKey, part: Literal['data', 'state', 'lock'] | None = None) → str

Build key to be used in storage’s db queries

Parameters:

• key – contextual key

• part – part of the record

Returns:

key to be used in storage’s db queries

Writing own storages

class aiogram.fsm.storage.base.BaseStorage

Base class for all FSM storages

abstract async set_state(key: StorageKey, state: str | State | None = None) → None

Set state for specified key

Parameters:

• key – storage key

• state – new state

abstract async get_state(key: StorageKey) → str | None

Get key state

Parameters:

key – storage key

Returns:

current state

abstract async set_data(key: StorageKey, data: Mapping[str, Any]) → None

Write data (replace)

Parameters:

• key – storage key

• data – new data

abstract async get_data(key: StorageKey) → dict[str, Any]

Get current data for key

Parameters:

key – storage key

Returns:

current data

async update_data(key: StorageKey, data: Mapping[str, Any]) → dict[str, Any]

Update date in the storage for key (like dict.update)

Parameters:

• key – storage key

• data – partial data

Returns:

new data

abstract async close() → None

Close storage (database connection, file or etc.)