Changes¶
Version 3.1.1¶
Released 2023-09-11
Deprecate the
__version__attribute. Use feature detection, orimportlib.metadata.version("flask-sqlalchemy"), instead. #5230
Version 3.1.0¶
Released 2023-09-11
Drop support for Python 3.7. #1251
Add support for the SQLAlchemy 2.x API via
model_classparameter. #1140Bump minimum version of SQLAlchemy to 2.0.16.
Remove previously deprecated code.
Pass extra keyword arguments from
get_or_404tosession.get. #1149Fix bug with finding right bind key for clause statements. #1211
Version 3.0.5¶
Released 2023-06-21
Version 3.0.4¶
Released 2023-06-19
Version 3.0.3¶
Released 2023-01-31
Version 3.0.2¶
Released 2022-10-14
Update compatibility with SQLAlchemy 2. #1122
Version 3.0.1¶
Released 2022-10-11
Version 3.0.0¶
Released 2022-10-04
Drop support for Python 2, 3.4, 3.5, and 3.6.
Bump minimum version of Flask to 2.2.
Bump minimum version of SQLAlchemy to 1.4.18.
Remove previously deprecated code.
The session is scoped to the current app context instead of the thread. This requires that an app context is active. This ensures that the session is cleaned up after every request.
An active Flask application context is always required to access
sessionandengine, regardless of if an application was passed to the constructor. #508, #944Different bind keys use different SQLAlchemy
MetaDataregistries, allowing tables in different databases to have the same name. Bind keys are stored and looked up on the resulting metadata rather than the model or table.SQLALCHEMY_DATABASE_URIdoes not default tosqlite:///:memory:. An error is raised if neither it norSQLALCHEMY_BINDSdefine any engines. #731Configuring SQLite with a relative path is relative to
app.instance_pathinstead ofapp.root_path. The instance folder is created if necessary. #462Added
get_or_404,first_or_404,one_or_404, andpaginatemethods to the extension object. These use SQLAlchemy’s preferredsession.execute(select())pattern instead of the legacy query interface. #1088Setup methods that create the engines and session are renamed with a leading underscore. They are considered internal interfaces which may change at any time.
All parameters to
SQLAlchemyexceptappare keyword-only.Renamed the
bindparameter tobind_keyand removed theappparameter from variousSQLAlchemymethods.The extension object uses
__getattr__to alias names from the SQLAlchemy package, rather than copying them as attributes.The extension object is stored directly as
app.extensions["sqlalchemy"]. #698The session class can be customized by passing the
class_key in thesession_optionsparameter. #327SignallingSessionis renamed toSession.Session.get_bindmore closely matches the base implementation.Model classes and the
dbinstance are available without imports inflask shell. #1089The
CamelCasetosnake_casetable name converter handles more patterns correctly. If model that was already created in the database changed, either use Alembic to rename the table, or set__tablename__to keep the old name. #406Modelreprdistinguishes between transient and pending instances. #967A custom model class can implement
__init_subclass__with class parameters. #1002db.Tableis a subclass instead of a function.The
engine_optionsparameter is applied as defaults before per-engine configuration.SQLALCHEMY_BINDSvalues can either be an engine URL, or a dict of engine options including URL, for each bind.SQLALCHEMY_DATABASE_URIandSQLALCHEMY_ENGINE_OPTIONScorrespond to theNonekey and take precedence. #783Engines are created when calling
init_apprather than the first time they are accessed. #698db.enginesexposes the map of bind keys to engines for the current app.get_engine,get_tables_for_bind, andget_bindsare deprecated.SQLite driver-level URIs that look like
sqlite:///file:name.db?uri=trueare supported. #998, #1045SQLite engines do not use
NullPoolifpool_sizeis 0.MySQL engines use the “utf8mb4” charset by default. #875
MySQL engines do not set
pool_sizeto 10.MySQL engines don’t set a default for
pool_recycleif not using a queue pool. #803Queryis renamed fromBaseQuery.Added
Query.one_or_404.The query class is applied to
backrefinrelationship. #417Creating
Paginationobjects manually is no longer a public API. They should be created withdb.paginateorquery.paginate. #1088Pagination.iter_pagesandQuery.paginateparameters are keyword-only.Paginationis iterable, iterating over its items. #70Pagination count query is more efficient.
Pagination.iter_pagesis more efficient. #622Pagination.iter_pagesright_currentparameter is inclusive.Pagination
per_pagecannot be 0. #1091Pagination
max_per_pagedefaults to 100. #1091Added
Pagination.firstandlastproperties, which give the number of the first and last item on the page. #567SQLALCHEMY_RECORD_QUERIESis disabled by default, and is not enabled automatically withapp.debugorapp.testing. #1092get_debug_queriesis renamed toget_recorded_queriesto better match the config and functionality.Recorded query info is a dataclass instead of a tuple. The
contextattribute is renamed tolocation. Finding the location uses a more inclusive check.SQLALCHEMY_TRACK_MODIFICATIONSis disabled by default. #727SQLALCHEMY_COMMIT_ON_TEARDOWNis deprecated. It can cause various design issues that are difficult to debug. Calldb.session.commit()directly instead. #216
Version 2.5.1¶
Released 2021-03-18
Fix compatibility with Python 2.7.
Version 2.5.0¶
Released 2021-03-18
Update to support SQLAlchemy 1.4.
SQLAlchemy
URLobjects are immutable. Some internal methods have changed to return a new URL instead ofNone. #885
Version 2.4.4¶
Released 2020-07-14
Change base class of meta mixins to
type. This fixes an issue caused by a regression in CPython 3.8.4. #852
Version 2.4.3¶
Released 2020-05-26
Deprecate
SQLALCHEMY_COMMIT_ON_TEARDOWNas it can cause various design issues that are difficult to debug. Calldb.session.commit()directly instead. #216
Version 2.4.2¶
Released 2020-05-25
Fix bad pagination when records are de-duped. #812
Version 2.4.1¶
Released 2019-09-24
Fix
AttributeErrorwhen using multiple binds with polymorphic models. #651
Version 2.4.0¶
Released 2019-04-24
Drop support for Python 2.6 and 3.3. #687
Address SQLAlchemy 1.3 deprecations. #684
Make engine configuration more flexible. Added the
engine_optionsparameter andSQLALCHEMY_ENGINE_OPTIONSconfig. Deprecated the individual engine option config keysSQLALCHEMY_NATIVE_UNICODE,SQLALCHEMY_POOL_SIZE,SQLALCHEMY_POOL_TIMEOUT,SQLALCHEMY_POOL_RECYCLE, andSQLALCHEMY_MAX_OVERFLOW. #684get_or_404()andfirst_or_404()now accept adescriptionparameter to control the 404 message. #636Use
time.perf_counterfor Python 3 on Windows. #638Add an example of Flask’s tutorial project, Flaskr, adapted for Flask-SQLAlchemy. #720
Version 2.3.2¶
Released 2017-10-11
Don’t mask the parent table for single-table inheritance models. #561
Version 2.3.1¶
Released 2017-10-05
If a model has a table name that matches an existing table in the metadata, use that table. Fixes a regression where reflected tables were not picked up by models. #551
Raise the correct error when a model has a table name but no primary key. #556
Fix
repron models that don’t have an identity because they have not been flushed yet. #555Allow specifying a
max_per_pagelimit for pagination, to avoid users specifying high values in the request args. #542For
paginatewitherror_out=False, the minimum value forpageis 1 andper_pageis 0. #558
Version 2.3.0¶
Released 2017-09-28
Multiple bugs with
__tablename__generation are fixed. Names will be generated for models that define a primary key, but not for single-table inheritance subclasses. Names will not override adeclared_attr.PrimaryKeyConstraintis detected. #541Passing an existing
declarative_base()asmodel_classtoSQLAlchemy.__init__will use this as the base class instead of creating one. This allows customizing the metaclass used to construct the base. #546The undocumented
DeclarativeMetainternals that the extension uses for binds and table name generation have been refactored to work as mixins. Documentation is added about how to create a custom metaclass that does not do table name generation. #546Model and metaclass code has been moved to a new
modelsmodule._BoundDeclarativeMetais renamed toDefaultMeta; the old name will be removed in 3.0. #546Models have a default
reprthat shows the model name and primary key. #530Fixed a bug where using
init_appwould cause connectors to always use thecurrent_apprather than the app they were created for. This caused issues when multiple apps were registered with the extension. #547
Version 2.2¶
Released 2017-02-27, codename Dubnium
Minimum SQLAlchemy version is 0.8 due to use of
sqlalchemy.inspect.Added support for custom
query_classandmodel_classas args to theSQLAlchemyconstructor. #328Allow listening to SQLAlchemy events on
db.session. #364Allow
__bind_key__on abstract models. #373Allow
SQLALCHEMY_ECHOto be a string. #409Warn when
SQLALCHEMY_DATABASE_URIis not set. #443Don’t let pagination generate invalid page numbers. #460
Drop support of Flask < 0.10. This means the db session is always tied to the app context and its teardown event. #461
Tablename generation logic no longer accesses class properties unless they are
declared_attr. #467
Version 2.1¶
Released 2015-10-23, codename Caesium
Table names are automatically generated in more cases, including subclassing mixins and abstract models.
Allow using a custom MetaData object.
Add support for binds parameter to session.
Version 2.0¶
Released 2014-08-29, codename Bohrium
Changed how the builtin signals are subscribed to skip non-Flask-SQLAlchemy sessions. This will also fix the attribute error about model changes not existing.
Added a way to control how signals for model modifications are tracked.
Made the
SignallingSessiona public interface and added a hook for customizing session creation.If the
bindparameter is given to the signalling session it will no longer cause an error that a parameter is given twice.Added working table reflection support.
Enabled autoflush by default.
Consider
SQLALCHEMY_COMMIT_ON_TEARDOWNharmful and remove from docs.
Version 1.0¶
Released 2013-07-20, codename Aurum
Added Python 3.3 support.
Dropped Python 2.5 compatibility.
Various bugfixes.
Changed versioning format to do major releases for each update now.
Version 0.16¶
New distribution format (flask_sqlalchemy).
Added support for Flask 0.9 specifics.
Version 0.15¶
Added session support for multiple databases.
Version 0.14¶
Make relative sqlite paths relative to the application root.
Version 0.13¶
Fixed an issue with Flask-SQLAlchemy not selecting the correct binds.
Version 0.12¶
Added support for multiple databases.
Expose
BaseQueryasdb.Query.Set default
query_classfordb.relation,db.relationship, anddb.dynamic_loadertoBaseQuery.Improved compatibility with Flask 0.7.
Version 0.11¶
Fixed a bug introduced in 0.10 with alternative table constructors.
Version 0.10¶
Added support for signals.
Table names are now automatically set from the class name unless overridden.
Model.querynow always works for applications directly passed to theSQLAlchemyconstructor. Furthermore the property now raises aRuntimeErrorinstead of beingNone.Added session options to constructor.
Fixed a broken
__repr__.db.Tableis now a factory function that creates table objects. This makes it possible to omit the metadata.
Version 0.9¶
Applied changes to pass the Flask extension approval process.
Version 0.8¶
Added a few configuration keys for creating connections.
Automatically activate connection recycling for MySQL connections.
Added support for the Flask testing mode.
Version 0.7¶
Initial public release