Engines

One or more SQLAlchemy engines can be configured through Flask’s app.config. The engines are created when SQLAlchemy.init_app() is called, changing config after that will have no effect. Both sync and async engines can be configured.

Flask Config

flask_sqlalchemy_lite.SQLALCHEMY_ENGINES

A dictionary defining sync engine configurations. Each key is a name for an engine, used to refer to them later. Each value is the engine configuration.

If the value is a dict, it consists of keyword arguments to be passed to sqlalchemy.create_engine(). The 'url' key is required; it can be a connection string (dialect://user:pass@host:port/name?args), a sqlalchemy.engine.URL instance, or a dict representing keyword arguments to pass to sqlalchemy.engine.URL.create().

As a shortcut, if you only need to specify the URL and no other arguments, the value can be a connection string or URL instance.

flask_sqlalchemy_lite.SQLALCHEMY_ASYNC_ENGINES

The same as SQLALCHEMY_ENGINES, but for async engine configurations.

URL Examples

The following configurations are all equivalent.

SQLALCHEMY_ENGINES = {
    "default": "sqlite:///default.sqlite"
}

from sqlalchemy import URL
SQLALCHEMY_ENGINES = {
    "default": URL.create("sqlite", database="default.sqlite")
}

SQLALCHEMY_ENGINES = {
    "default": {"url": "sqlite:///default.sqlite"}
}

from sqlalchemy import URL
SQLALCHEMY_ENGINES = {
    "default": {"url": URL.create("sqlite", database="default.sqlite")}
}

SQLALCHEMY_ENGINES = {
    "default": {"url": {"drivername": "sqlite", "database": "default.sqlite"}}
}

Default Options

Default engine options can be passed as the engine_options parameter when creating the SQLAlchemy instance. The config for each engine will be merged with these default options, overriding any shared keys. This applies to both sync and async engines. You can use specific config if you need different options for each.

SQLite Defaults

A relative database path will be relative to the app’s instance_path instead of the current directory. The instance folder will be created if it does not exist.

When using a memory database (no path, or :memory:), a static pool will be used, and check_same_thread=False will be passed. This allows multiple workers to share the database.

MySQL Defaults

When using a queue pool (default), pool_recycle is set to 7200 seconds (2 hours), forcing SQLAlchemy to reconnect before MySQL would discard the idle connection.

The connection charset is set to utf8mb4.

The Default Engine and Bind

The "default" key is special, and will be used for engine and as the default bind for sessionmaker. By default, it is an error not to configure it for one of sync or async engines.

Custom Engines

You can ignore the Flask config altogether and create engines yourself. In that case, you pass require_default_engine=False when creating the extension to ignore the check for default config. Adding custom engines to the engines map will make them accessible through the extension, but that’s not required either. You will want to call db.sessionmaker.configure(bind=..., binds=...) to set up these custom engines if you plan to use the provided session management though.