Configuration¶
Configuration Keys¶
Configuration is loaded from the Flask app.config when SQLAlchemy.init_app()
is called. The configuration is not read again after that. Therefore, all configuration
must happen before initializing the application.
- flask_sqlalchemy.config.SQLALCHEMY_DATABASE_URI¶
The database connection URI used for the default engine. It can be either a string or a SQLAlchemy
URLinstance. See below and Engine Configuration for examples.At least one of this and
SQLALCHEMY_BINDSmust be set.Changed in version 3.0: No longer defaults to an in-memory SQLite database if not set.
- flask_sqlalchemy.config.SQLALCHEMY_ENGINE_OPTIONS¶
A dict of arguments to pass to
sqlalchemy.create_engine()for the default engine.This takes precedence over the
engine_optionsargument toSQLAlchemy, which can be used to set default options for all engines.Changed in version 3.0: Only applies to the default bind.
Added in version 2.4.
- flask_sqlalchemy.config.SQLALCHEMY_BINDS¶
A dict mapping bind keys to engine options. The value can be a string or a SQLAlchemy
URLinstance. Or it can be a dict of arguments, including theurlkey, that will be passed tosqlalchemy.create_engine(). TheNonekey can be used to configure the default bind, butSQLALCHEMY_ENGINE_OPTIONSandSQLALCHEMY_DATABASE_URItake precedence.At least one of this and
SQLALCHEMY_DATABASE_URImust be set.Added in version 0.12.
- flask_sqlalchemy.config.SQLALCHEMY_ECHO¶
The default value for
echoandecho_poolfor every engine. This is useful to quickly debug the connections and queries issued from SQLAlchemy.Changed in version 3.0: Sets
echo_poolin addition toecho.
- flask_sqlalchemy.config.SQLALCHEMY_RECORD_QUERIES¶
If enabled, information about each query during a request will be recorded. Use
get_recorded_queries()to get a list of queries that were issued during the request.Changed in version 3.0: Not enabled automatically in debug or testing mode.
- flask_sqlalchemy.config.SQLALCHEMY_TRACK_MODIFICATIONS¶
If enabled, all
insert,update, anddeleteoperations on models are recorded, then sent inmodels_committedandbefore_models_committedsignals whensession.commit()is called.This adds a significant amount of overhead to every session. Prefer using SQLAlchemy’s ORM Events directly for the exact information you need.
Changed in version 3.0: Disabled by default.
Added in version 2.0.
Changed in version 3.1: Removed SQLALCHEMY_COMMIT_ON_TEARDOWN.
Changed in version 3.0: Removed SQLALCHEMY_NATIVE_UNICODE, SQLALCHEMY_POOL_SIZE,
SQLALCHEMY_POOL_TIMEOUT, SQLALCHEMY_POOL_RECYCLE, and
SQLALCHEMY_MAX_OVERFLOW.
Connection URL Format¶
See SQLAlchemy’s documentation on Engine Configuration for a complete description of syntax, dialects, and options.
A basic database connection URL uses the following format. Username, password, host, and port are optional depending on the database type and configuration.
dialect://username:password@host:port/database
Here are some example connection strings:
# SQLite, relative to Flask instance path
sqlite:///project.db
# PostgreSQL
postgresql://scott:tiger@localhost/project
# MySQL / MariaDB
mysql://scott:tiger@localhost/project
SQLite does not use a user or host, so its URLs always start with _three_ slashes
instead of two. The dbname value is a file path. Absolute paths start with a
_fourth_ slash (on Linux or Mac). Relative paths are relative to the Flask application’s
instance_path.
Default Driver Options¶
Some default options are set for SQLite and MySQL engines to make them more usable by default in web applications.
SQLite relative file paths are relative to the Flask instance path instead of the
current working directory. In-memory databases use a static pool and
check_same_thread to work across requests.
MySQL (and MariaDB) servers are configured to drop connections that have been idle for
8 hours, which can result in an error like 2013: Lost connection to MySQL server
during query. A default pool_recycle value of 2 hours (7200 seconds) is used to
recreate connections before that timeout.
Engine Configuration Precedence¶
Because Flask-SQLAlchemy has support for multiple engines, there are rules for which
config overrides other config. Most applications will only have a single database and
only need to use SQLALCHEMY_DATABASE_URI and SQLALCHEMY_ENGINE_OPTIONS.
If the
engine_optionsargument is given toSQLAlchemy, it sets default options for all engines.SQLALCHEMY_ECHOsets the default value for bothechoandecho_poolfor all engines.The options for each engine in
SQLALCHEMY_BINDSoverride those defaults.SQLALCHEMY_ENGINE_OPTIONSoverrides theNonekey inSQLALCHEMY_BINDS, andSQLALCHEMY_DATABASE_URIoverrides theurlkey in that engine’s options.
Timeouts¶
Certain databases may be configured to close inactive connections after a period of
time. MySQL and MariaDB are configured for this by default, but database services may
also configure this type of limit. This can result in an error like
2013: Lost connection to MySQL server during query.
If you encounter this error, try setting pool_recycle in the engine options to
a value less than the database’s timeout.
Alternatively, you can try setting pool_pre_ping if you expect the database to close
connections often, such as if it’s running in a container that may restart.
See SQAlchemy’s docs on dealing with disconnects for more information.