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 "URL" instance. See below and
   Engine Configuration for examples.

   At least one of this and "SQLALCHEMY_BINDS" must 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_options" argument to
   "SQLAlchemy", 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 "URL" instance. Or it can be a dict of
   arguments, including the "url" key, that will be passed to
   "sqlalchemy.create_engine()". The "None" key can be used to
   configure the default bind, but "SQLALCHEMY_ENGINE_OPTIONS" and
   "SQLALCHEMY_DATABASE_URI" take precedence.

   At least one of this and "SQLALCHEMY_DATABASE_URI" must be set.

   Added in version 0.12.

flask_sqlalchemy.config.SQLALCHEMY_ECHO

   The default value for "echo" and "echo_pool" for every engine. This
   is useful to quickly debug the connections and queries issued from
   SQLAlchemy.

   Changed in version 3.0: Sets "echo_pool" in addition to "echo".

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", and "delete" operations on
   models are recorded, then sent in "models_committed" and
   "before_models_committed" signals when "session.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_options" argument is given to "SQLAlchemy", it sets
  default options for *all* engines. "SQLALCHEMY_ECHO" sets the
  default value for both "echo" and "echo_pool" for all engines.

* The options for each engine in "SQLALCHEMY_BINDS" override those
  defaults.

* "SQLALCHEMY_ENGINE_OPTIONS" overrides the "None" key in
  "SQLALCHEMY_BINDS", and "SQLALCHEMY_DATABASE_URI" overrides the
  "url" key 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.
