API
***

This part of the documentation documents all the public classes and
functions in Flask-SQLAlchemy.


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

class flask.ext.sqlalchemy.SQLAlchemy(app=None, use_native_unicode=True, session_options=None, metadata=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.

   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.

   You may also define your own SessionExtension instances as well
   when defining your SQLAlchemy class instance. You may pass your
   custom instances to the *session_extensions* keyword. This can be
   either a single SessionExtension instance, or a list of
   SessionExtension instances. In the following use case we use the
   VersionedListener from the SQLAlchemy versioning examples.:

      from history_meta import VersionedMeta, VersionedListener

      app = Flask(__name__)
      db = SQLAlchemy(app, session_extensions=[VersionedListener()])

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

   The *session_options* parameter can be used to override session
   options.  If provided it's a dict of parameters passed to the
   session's constructor.

   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.

   Query

      The "BaseQuery" class.

   apply_driver_hacks(app, info, 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*.

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

      Creates all tables.

      Changed in version 0.12: Parameters were added

   create_scoped_session(options=None)

      Helper factory method that creates a scoped session.  It
      internally calls "create_session()".

   create_session(options)

      Creates the session.  The default implementation returns a
      "SignallingSession".

      New in version 2.0.

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

      Drops all tables.

      Changed in version 0.12: Parameters were added

   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, bind=None)

      Returns a specific engine.

      New in version 0.12.

   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, bind=None)

      Creates the connector for a given state and bind.

   make_declarative_base(metadata=None)

      Creates the declarative base.

   metadata

      Returns the metadata

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

      Reflects tables from the database.

      Changed in version 0.12: Parameters were added


Models
======

class flask.ext.sqlalchemy.Model

   Baseclass for custom user models.

   __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.

   query = None

      an instance of "query_class".  Can be used to query the database
      for instances of this model.

   query_class

      the query class used.  The "query" attribute is an instance of
      this class.  By default a "BaseQuery" is used.

      alias of "BaseQuery"

class flask.ext.sqlalchemy.BaseQuery(entities, session=None)

   The default query object used for models, and exposed as "Query".
   This can be subclassed and replaced for individual models by
   setting the "query_class" attribute.  This is a subclass of a
   standard SQLAlchemy "Query" class and has all the methods of a
   standard query as well.

   all()

      Return the results represented by this query as a list.  This
      results in an execution of the underlying query.

   order_by(*criterion)

      apply one or more ORDER BY criterion to the query and return the
      newly resulting query.

   limit(limit)

      Apply a LIMIT  to the query and return the newly resulting
      query.

   offset(offset)

      Apply an OFFSET  to the query and return the newly resulting
      query.

   first()

      Return the first result of this query or *None* if the result
      doesn’t contain any rows.  This results in an execution of the
      underlying query.

   first_or_404()

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

   get(ident)

      Return an instance based on the given primary key identifier, or
      "None" if not found.

      E.g.:

         my_user = session.query(User).get(5)

         some_object = session.query(VersionedFoo).get((5, 10))

      "get()" is special in that it provides direct access to the
      identity map of the owning "Session". If the given primary key
      identifier is present in the local identity map, the object is
      returned directly from this collection and no SQL is emitted,
      unless the object has been marked fully expired. If not present,
      a SELECT is performed in order to locate the object.

      "get()" also will perform a check if the object is present in
      the identity map and marked as expired - a SELECT is emitted to
      refresh the object as well as to ensure that the row is still
      present. If not, "ObjectDeletedError" is raised.

      "get()" is only used to return a single mapped instance, not
      multiple instances or individual column constructs, and strictly
      on a single primary key value.  The originating "Query" must be
      constructed in this way, i.e. against a single mapped entity,
      with no additional filtering criterion.  Loading options via
      "options()" may be applied however, and will be used if the
      object is not yet locally present.

      A lazy-loading, many-to-one attribute configured by
      "relationship()", using a simple foreign-key-to-primary-key
      criterion, will also use an operation equivalent to "get()" in
      order to retrieve the target value from the local identity map
      before querying the database.  See */orm/loading_relationships*
      for further details on relationship loading.

      Parameters:
         **ident** -- A scalar or tuple value representing the primary
         key.   For a composite primary key, the order of identifiers
         corresponds in most cases to that of the mapped "Table"
         object's primary key columns.  For a "mapper()" that was
         given the "primary key" argument during construction, the
         order of identifiers corresponds to the elements present in
         this collection.

      Returns:
         The object instance, or "None".

   get_or_404(ident)

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

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

      Returns *per_page* items from page *page*.  By default it will
      abort with 404 if no items were found and the page was larger
      than 1.  This behavor can be disabled by setting *error_out* to
      *False*.

      If page or per_page are None, they will be retrieved from the
      request query.  If the values are not ints and "error_out" is
      true, it will abort with 404.  If there is no request or they
      aren't in the query, they default to page 1 and 20 respectively.

      Returns an "Pagination" object.


Sessions
========

class flask.ext.sqlalchemy.SignallingSession(db, autocommit=False, autoflush=True, app=None, **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.

   app = None

      The application that this session belongs to.


Utilities
=========

class flask.ext.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.

   has_next

      True if a next page exists.

   has_prev

      True if a previous page exists

   items = None

      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.

   next_num

      Number of the next page

   page = None

      the current page number (1 indexed)

   pages

      The total number of pages

   per_page = None

      the number of items to be displayed on a page.

   prev(error_out=False)

      Returns a "Pagination" object for the previous page.

   prev_num

      Number of the previous page.

   query = None

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

   total = None

      the total number of items matching the query

flask.ext.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.
