Get SQLAlchemy

Version 1.3

Latest 1.3 Release: 1.3.11 (1.3.11 via Cheeseshop) (CHANGES)

SQLAlchemy 1.3.11 is signed using Michael Bayer’s PGP key id C4DAFEE1 (use gpg --recv-keys C4DAFEE1 to import).

Please be sure to review the 1.2 to 1.3 migration guide, found at What's New in 1.3?, for full details on changes made since 1.2.

Version 1.2

Latest 1.2 Release: 1.2.19 (1.2.19 via Cheeseshop) (CHANGES)

Release Support: Maintenance Mode

Please note: the 1.2 series is the current "Maintenance" series. Updates for critical fixes will be made available as needed, but applications which continue to be under active development are advised to begin upgrading to the current series of SQLAlchemy (currently the 1.3 series).

SQLAlchemy 1.2.19 is signed using Michael Bayer’s PGP key id C4DAFEE1 (use gpg --recv-keys C4DAFEE1 to import).

Please be sure to review the 1.1 to 1.2 migration guide, found at What's New in 1.2?, for full details on changes made since 1.1.

Development Versions

SQLAlchemy on GitHub

For further details on Git repository access please see development.

License

SQLAlchemy is covered by the MIT License.

Version Numbering Scheme

All projects within the SQLAlchemy Organization use the same version numbering scheme, which is like that of many projects, a modified "semantic versioning" scheme. It is based roughly on the Python version numbering scheme, with slight adjustments to suit the particular needs of SQLAlchemy and Alembic:

Given a version number like "1.3.6", we can break it up into major, minor, and point release.

Point Releases

Point releases are the most common release series, occurring as often as every few weeks or less for active projects. A point release should always be fully compatible for any project to move to that version with no changes, given a particular major/minor series.. This means, if a project is on version 1.2.3 of SQLAlchemy, in the ideal case this project should be able to upgrade directly to the latest 1.2.x series, such as 1.2.19 without the need to move to interim releases.

A point release includes three categories of change:

  • Bug fixes - the primary purpose of a point release is to release fixes for bugs with no backwards incompatible changes being made. A bug fix that is determined to be too risky towards backwards compatibility will instead be pushed into a minor release.
  • Use case additions - A "use case" is a category of change that falls in between a "bug fix" and a "feature", and they most often apply to support for new database capabilities. As new database capabilites are created or requested by users continuously, and usually refer to particular datatypes or small SQL syntaxes, these capabilities are often added to a point release provided they don't break backwards compatibility within SQLAlchemy or within Alembic migrations. Larger use case additions are released within a minor release.
  • Small feature additions - As the release cycle for point releases are every few weeks, whereas the release cycle for a minor release is usually at least a year or more, feature additions that have no impact on any current code or APis will often be included in point releases; an example would be the ability to create sub-options on an ORM loader option.

Note that while point releases are the most conservative and frequent release stream, it is always possible that an accidental regression may be introduced. It is advised that projects always fully test their software including the use of test suites and/or staging environments when upgrading to a new version of any SQLAlchemy organization software.

Minor Releases

Minor releases in SQLAlchemy are actually kind of "major" events as they typically take a year to produce; for related projects, minor releases may come less frequently. A change in minor release means that the project includes changes that are typically backwards compatible within the range of not-previously-deprecated APIs and current Python versions, with some risk of non-backwards compatibility, particularly within SQLAlchemy itself; this risk is usually unavoidable due to the nature of the changes.

For this reason, a minor release is not really that "minor" for SQLAlchemy itself, and there is always an extensive migration notes section describing in great detail every API adjustment and behavioral change which may need to be identified. For other projects, a minor release typically refers to changes in Python version support, such as dropping support for Python 2.6, or Alembic dropping support for SQLAlchemy 0.9; a general idea of what's new is in the changelog.

A minor release, particularly in SQLAlchemy itself, will include:

  • Major new features - new API features and capabilities, as well as structural and performance improvements, are part of every minor release for SQLAlchemy itself and very often for related projects. These additions are generally fully backwards-compatible, however as they often change lots of code internally, there is a higher risk of regressions, particularly in SQLAlchemy; these regressions are usually worked out within the first few point releases of a new minor release. As always, downstream applications should run their test suites and report any issues with a new minor release.

  • Behavioral changes - Most behavioral changes are subtle and unlikely to cause issues in the general case. These changes may however be backwards-incompatible with end-user code that is either relying upon a previously broken behavior, or which was working around the old behavior which will no longer produce the same result. A typical example is a SQL rendering that was previously not quoting or escaping correctly, which is then repaired; downstream applications will typically be working around this problem by applying the quoting manually, which becomes redundant once SQLAlchemy repairs it. An example of such a change is The column-level COLLATE keyword now quotes the collation name, which adds quoting to database collation names which must be specified in a case sensitive manner.

    Behavioral changes that aren't expected to cause issues are nonetheless documented in case some unforeseen issue arises; an example is FOR UPDATE clause is rendered within the joined eager load subquery as well as outsideĀ¶, which modifies how "FOR UPDATE" is rendered in a SELECT that includes joined eager loading. This change impacts users of MySQL the most, as it works around a known MySQL issue and will suddenly start locking table rows from a related table in a joined-eager load, whereas this was not the case before on this particular backend.

  • API Deprecations - SQLAlchemy and related projects attempt to add new deprecations only within a minor release and not within a point release. Any deprecated API should to the greatest degree possible emit a DeprecationWarning when that API is used. While this was not always the case for older versions, the goal is that deprecations are only added in minor releases and that they should emit warnings when used. This is so that projects have an entire minor release cycle to migrate off the old API and that the deprecation is easy to recognize.

  • Removal of previously deprecated APIs - an API that was deprecated in a particular minor release may be removed as soon as the next minor release, though often a deprecated API will remain for multiple minor releases. In modern releases, deprecated APIs should be emitting warning when used throughout the span of a particular minor release.

Major releases

Major releases refer to the general maturity state of the project, which is a multi-year status. A project begins with 0, e.g. sqlalchemy-collectd-0.0.4, which indicates the range of maturity from initial alpha releases into long-term stable releases, with the notion that major breaking changes may occur across each minor release. At major version 1, the project is considered to be mature. Major version 2 and higher each indicate major new shifts for the project of a similar nature as that of Python 2 to Python 3.

Release Status

This table summarizes the overall history of SQLAlchemy releases with further links for more recent minor releases.

Major/Minor Version First Release Latest Release Latest Point Release Release Status
1.4 [docs] [What's New?] Development
1.3 [docs] [What's New?] 2018-11-17 (beta) 2019-11-11 1.3.11 [changes] Current Release
1.2 [docs] [What's New?] 2017-07-10 (beta) 2019-04-15 1.2.19 [changes] Maintenance
1.1 [docs] [What's New?] 2016-06-16 (beta) 2018-03-06 1.1.18 [changes] EOL
1.0 [What's New?] 2015-03-13 (beta) 2017-08-03 1.0.19 [changes] EOL
0.9 2013-12-30 2015-07-22 0.9.10 [changes] EOL
0.8 2012-12-14 (beta) 2014-07-22 0.8.7 [changes] EOL
0.7 2011-05-21 2013-02-08 0.7.10 [changes] EOL
0.6 2010-02-03 (beta) 2012-05-06 0.6.9 [changes] EOL
0.5 2008-06-12 (beta) 2010-01-16 0.5.8 [changes] EOL
0.4 2007-08-12 (beta) 2008-10-12 0.4.8 [changes] EOL
0.3 2006-10-22 2007-10-14 0.3.11 [changes] EOL
0.2 2006-05-27 2006-09-05 0.2.8 [changes] EOL
0.1 2006-02-14 2006-05-05 0.1.7 [changes] EOL

About Release Status Categories

The following table summarizes each status category:

Release Status Explanation
Development Active development for the next major release of SQLAlchemy. The "development" status is by definition not released on Pypi and only exists within the git repository, typically under the master branch. When the first release of the "development" status is created, the status moves to "beta".
Beta Evaluation releases for the current development version. These releases are available on Pypi, however include a 'b' character in their version name so that per pep-0440 these releases will not be installed by the pip tool unless the --pre flag is specified. The "beta" status is generally mutually exclusive versus the "development" status.
Current Release The current official release of SQLAlchemy. Ongoing work is performed to close out regressions and bugs that can still be applied without significant risk of destabilization. Applications which are under active development should seek to always refer to at least the "current" release.
Maintenance The maintenance series exists when the "beta" series has become "current", and the previous "current" series becomes "maintenance". The maintenance series accepts a limited set of critical bug fixes as they are encountered, as it is expected that applications under active development will be migrating to the "current" release if they have not done so already. Once the next development version begins, the "maintenance" series is no longer released and moves to "EOL".
EOL This release version is no longer maintained and is considered legacy. Applications in production use against an EOL milestone are strongly advised to upgrade to a newer version.