API
***


Configuration
=============

class flask_sqlalchemy.SQLAlchemy(app=None, use_native_unicode=True, session_options=None, metadata=None, query_class=<class 'flask_sqlalchemy.BaseQuery'>, model_class=<class 'flask_sqlalchemy.model.Model'>, engine_options=None)

   This class is used to control the SQLAlchemy integration to one or
   more Flask applications.  Depending on how you initialize the
   object it is usable right away or will attach as needed to a Flask
   application.

   There are two usage modes which work very similarly.  One is
   binding the instance to a very specific Flask application:

      app = Flask(__name__)
      db = SQLAlchemy(app)

   The second possibility is to create the object once and configure
   the application later to support it:

      db = SQLAlchemy()

      def create_app():
          app = Flask(__name__)
          db.init_app(app)
          return app

   The difference between the two is that in the first case methods
   like "create_all()" and "drop_all()" will work all the time but in
   the second case a "flask.Flask.app_context()" has to exist.

   By default Flask-SQLAlchemy will apply some backend-specific
   settings to improve your experience with them.

   As of SQLAlchemy 0.6 SQLAlchemy will probe the library for native
   unicode support.  If it detects unicode it will let the library
   handle that, otherwise do that itself. Sometimes this detection can
   fail in which case you might want to set "use_native_unicode" (or
   the "SQLALCHEMY_NATIVE_UNICODE" configuration key) to "False".
   Note that the configuration key overrides the value you pass to the
   constructor.  Direct support for "use_native_unicode" and
   SQLALCHEMY_NATIVE_UNICODE are deprecated as of v2.4 and will be
   removed in v3.0.  "engine_options" and "SQLALCHEMY_ENGINE_OPTIONS"
   may be used instead.

   This class also provides access to all the SQLAlchemy functions and
   classes from the "sqlalchemy" and "sqlalchemy.orm" modules.  So you
   can declare models like this:

      class User(db.Model):
          username = db.Column(db.String(80), unique=True)
          pw_hash = db.Column(db.String(80))

   You can still use "sqlalchemy" and "sqlalchemy.orm" directly, but
   note that Flask-SQLAlchemy customizations are available only
   through an instance of this "SQLAlchemy" class.  Query classes
   default to "BaseQuery" for *db.Query*, *db.Model.query_class*, and
   the default query_class for *db.relationship* and *db.backref*.  If
   you use these interfaces through "sqlalchemy" and "sqlalchemy.orm"
   directly, the default query class will be that of "sqlalchemy".

   Check types carefully: Don't perform type or *isinstance* checks
   against *db.Table*, which emulates *Table* behavior but is not a
   class. *db.Table* exposes the *Table* interface, but is a function
   which allows omission of metadata.

   The "session_options" parameter, if provided, is a dict of
   parameters to be passed to the session constructor.  See "Session"
   for the standard options.

   The "engine_options" parameter, if provided, is a dict of
   parameters to be passed to create engine.  See "create_engine()"
   for the standard options.  The values given here will be merged
   with and override anything set in the "'SQLALCHEMY_ENGINE_OPTIONS'"
   config variable or othewise set by this library.

   New in version 0.10: The *session_options* parameter was added.

   New in version 0.16: *scopefunc* is now accepted on
   *session_options*. It allows specifying  a custom function which
   will define the SQLAlchemy session's scoping.

   New in version 2.1: The *metadata* parameter was added. This allows
   for setting custom naming conventions among other, non-trivial
   things.The *query_class* parameter was added, to allow
   customisation of the query class, in place of the default of
   "BaseQuery".The *model_class* parameter was added, which allows a
   custom model class to be used in place of "Model".

   Changed in version 2.1: Utilise the same query class across
   *session*, *Model.query* and *Query*.

   New in version 2.4: The *engine_options* parameter was added.

   Changed in version 2.4: The *use_native_unicode* parameter was
   deprecated.

   Changed in version 2.4.3: "COMMIT_ON_TEARDOWN" is deprecated and
   will be removed in version 3.1. Call "db.session.commit()" directly
   instead.

   Query = None

      Default query class used by "Model.query" and other queries.
      Customize this by passing "query_class" to "SQLAlchemy()".
      Defaults to "BaseQuery".

   apply_driver_hacks(app, sa_url, options)

      This method is called before engine creation and used to inject
      driver specific hacks into the options.  The *options* parameter
      is a dictionary of keyword arguments that will then be used to
      call the "sqlalchemy.create_engine()" function.

      The default implementation provides some saner defaults for
      things like pool sizes for MySQL and sqlite.  Also it injects
      the setting of *SQLALCHEMY_NATIVE_UNICODE*.

      Changed in version 2.5: Returns "(sa_url, options)". SQLAlchemy
      1.4 made the URL immutable, so any changes to it must now be
      passed back up to the original caller.

   apply_pool_defaults(app, options)

      Changed in version 2.5: Returns the "options" dict, for
      consistency with "apply_driver_hacks()".

   create_all(bind='__all__', app=None)

      Creates all tables.

      Changed in version 0.12: Parameters were added

   create_engine(sa_url, engine_opts)

      Override this method to have final say over how the SQLAlchemy
      engine is created.

      In most cases, you will want to use
      "'SQLALCHEMY_ENGINE_OPTIONS'" config variable or set
      "engine_options" for "SQLAlchemy()".

   create_scoped_session(options=None)

      Create a "scoped_session" on the factory from
      "create_session()".

      An extra key "'scopefunc'" can be set on the "options" dict to
      specify a custom scope function.  If it's not provided, Flask's
      app context stack identity is used. This will ensure that
      sessions are created and removed with the request/response
      cycle, and should be fine in most cases.

      Parameters:
         **options** -- dict of keyword arguments passed to session
         class  in "create_session"

   create_session(options)

      Create the session factory used by "create_scoped_session()".

      The factory **must** return an object that SQLAlchemy recognizes
      as a session, or registering session events may raise an
      exception.

      Valid factories include a "Session" class or a "sessionmaker".

      The default implementation creates a "sessionmaker" for
      "SignallingSession".

      Parameters:
         **options** -- dict of keyword arguments passed to session
         class

   drop_all(bind='__all__', app=None)

      Drops all tables.

      Changed in version 0.12: Parameters were added

   property engine

      Gives access to the engine.  If the database configuration is
      bound to a specific application (initialized with an
      application) this will always return a database connection.  If
      however the current application is used this might raise a
      "RuntimeError" if no application is active at the moment.

   get_app(reference_app=None)

      Helper method that implements the logic to look up an
      application.

   get_binds(app=None)

      Returns a dictionary with a table->engine mapping.

      This is suitable for use of
      sessionmaker(binds=db.get_binds(app)).

   get_engine(app=None, bind=None)

      Returns a specific engine.

   get_tables_for_bind(bind=None)

      Returns a list of all tables relevant for a bind.

   init_app(app)

      This callback can be used to initialize an application for the
      use with this database setup.  Never use a database in the
      context of an application not initialized that way or
      connections will leak.

   make_connector(app=None, bind=None)

      Creates the connector for a given state and bind.

   make_declarative_base(model, metadata=None)

      Creates the declarative base that all models will inherit from.

      Parameters:
         * **model** -- base model class (or a tuple of base classes)
           to pass to "declarative_base()". Or a class returned from
           "declarative_base", in which case a new base class is not
           created.

         * **metadata** -- "MetaData" instance to use, or none to use
           SQLAlchemy's default.

   property metadata

      The metadata associated with "db.Model".

   reflect(bind='__all__', app=None)

      Reflects tables from the database.

      Changed in version 0.12: Parameters were added


Models
======

class flask_sqlalchemy.Model

   Base class for SQLAlchemy declarative base model.

   To define models, subclass "db.Model", not this class. To customize
   "db.Model", subclass this and pass it as "model_class" to
   "SQLAlchemy".

   __bind_key__

      Optionally declares the bind to use. "None" refers to the
      default bind. For more information see Multiple Databases with
      Binds.

   __tablename__

      The name of the table in the database. This is required by
      SQLAlchemy; however, Flask-SQLAlchemy will set it automatically
      if a model has a primary key defined. If the "__table__" or
      "__tablename__" is set explicitly, that will be used instead.

class flask_sqlalchemy.BaseQuery(entities, session=None)

   SQLAlchemy "Query" subclass with convenience methods for querying
   in a web application.

   This is the default "query" object used for models, and exposed as
   "Query". Override the query class for an individual model by
   subclassing this and setting "query_class".

   first_or_404(description=None)

      Like "first()" but aborts with 404 if not found instead of
      returning "None".

   get_or_404(ident, description=None)

      Like "get()" but aborts with 404 if not found instead of
      returning "None".

   paginate(page=None, per_page=None, error_out=True, max_per_page=None)

      Returns "per_page" items from page "page".

      If "page" or "per_page" are "None", they will be retrieved from
      the request query. If "max_per_page" is specified, "per_page"
      will be limited to that value. If there is no request or they
      aren't in the query, they default to 1 and 20 respectively.

      When "error_out" is "True" (default), the following rules will
      cause a 404 response:

      * No items are found and "page" is not 1.

      * "page" is less than 1, or "per_page" is negative.

      * "page" or "per_page" are not ints.

      When "error_out" is "False", "page" and "per_page" default to 1
      and 20 respectively.

      Returns a "Pagination" object.


Sessions
========

class flask_sqlalchemy.SignallingSession(db, autocommit=False, autoflush=True, **options)

   The signalling session is the default session that Flask-SQLAlchemy
   uses.  It extends the default session system with bind selection
   and modification tracking.

   If you want to use a different session you can override the
   "SQLAlchemy.create_session()" function.

   New in version 2.0.

   New in version 2.1: The *binds* option was added, which allows a
   session to be joined to an external transaction.

   get_bind(mapper=None, clause=None)

      Return the engine or connection for a given model or table,
      using the "__bind_key__" if it is set.


Utilities
=========

class flask_sqlalchemy.Pagination(query, page, per_page, total, items)

   Internal helper class returned by "BaseQuery.paginate()".  You can
   also construct it from any other SQLAlchemy query object if you are
   working with other libraries.  Additionally it is possible to pass
   *None* as query object in which case the "prev()" and "next()" will
   no longer work.

   property has_next

      True if a next page exists.

   property has_prev

      True if a previous page exists

   items

      the items for the current page

   iter_pages(left_edge=2, left_current=2, right_current=5, right_edge=2)

      Iterates over the page numbers in the pagination.  The four
      parameters control the thresholds how many numbers should be
      produced from the sides.  Skipped page numbers are represented
      as *None*. This is how you could render such a pagination in the
      templates:

         {% macro render_pagination(pagination, endpoint) %}
           <div class=pagination>
           {%- for page in pagination.iter_pages() %}
             {% if page %}
               {% if page != pagination.page %}
                 <a href="{{ url_for(endpoint, page=page) }}">{{ page }}</a>
               {% else %}
                 <strong>{{ page }}</strong>
               {% endif %}
             {% else %}
               <span class=ellipsis>…</span>
             {% endif %}
           {%- endfor %}
           </div>
         {% endmacro %}

   next(error_out=False)

      Returns a "Pagination" object for the next page.

   property next_num

      Number of the next page

   page

      the current page number (1 indexed)

   property pages

      The total number of pages

   per_page

      the number of items to be displayed on a page.

   prev(error_out=False)

      Returns a "Pagination" object for the previous page.

   property prev_num

      Number of the previous page.

   query

      the unlimited query object that was used to create this
      pagination object.

   total

      the total number of items matching the query

flask_sqlalchemy.get_debug_queries()

   In debug mode Flask-SQLAlchemy will log all the SQL queries sent to
   the database.  This information is available until the end of
   request which makes it possible to easily ensure that the SQL
   generated is the one expected on errors or in unittesting.  If you
   don't want to enable the DEBUG mode for your unittests you can also
   enable the query recording by setting the
   "'SQLALCHEMY_RECORD_QUERIES'" config variable to *True*.  This is
   automatically enabled if Flask is in testing mode.

   The value returned will be a list of named tuples with the
   following attributes:

   *statement*
      The SQL statement issued

   *parameters*
      The parameters for the SQL statement

   *start_time* / *end_time*
      Time the query started / the results arrived.  Please keep in
      mind that the timer function used depends on your platform.
      These values are only useful for sorting or comparing.  They do
      not necessarily represent an absolute timestamp.

   *duration*
      Time the query took in seconds

   *context*
      A string giving a rough estimation of where in your application
      query was issued.  The exact format is undefined so don't try to
      reconstruct filename or function name.
