.. changelog::
:version: 1.4.0b1
- :released: November 2, 2020
-
- .. change::
- :tags: feature, orm
- :tickets: 5159
-
- The ORM can now generate queries previously only available when using
- :class:`_orm.Query` using the :func:`_sql.select` construct directly.
- A new system by which ORM "plugins" may establish themselves within a
- Core :class:`_sql.Select` allow the majority of query building logic
- previously inside of :class:`_orm.Query` to now take place within
- a compilation-level extension for :class:`_sql.Select`. Similar changes
- have been made for the :class:`_sql.Update` and :class:`_sql.Delete`
- constructs as well. The constructs when invoked using :meth:`_orm.Session.execute`
- now do ORM-related work within the method. For :class:`_sql.Select`,
- the :class:`_engine.Result` object returned now contains ORM-level
- entities and results.
-
- .. seealso::
-
- :ref:`change_5159`
-
- .. change::
- :tags: feature,sql
- :tickets: 4737
-
- Added "from linting" as a built-in feature to the SQL compiler. This
- allows the compiler to maintain graph of all the FROM clauses in a
- particular SELECT statement, linked by criteria in either the WHERE
- or in JOIN clauses that link these FROM clauses together. If any two
- FROM clauses have no path between them, a warning is emitted that the
- query may be producing a cartesian product. As the Core expression
- language as well as the ORM are built on an "implicit FROMs" model where
- a particular FROM clause is automatically added if any part of the query
- refers to it, it is easy for this to happen inadvertently and it is
- hoped that the new feature helps with this issue.
-
- .. seealso::
-
- :ref:`change_4737`
-
- .. change::
- :tags: deprecated, orm
- :tickets: 5606
-
- The "slice index" feature used by :class:`_orm.Query` as well as by the
- dynamic relationship loader will no longer accept negative indexes in
- SQLAlchemy 2.0. These operations do not work efficiently and load the
- entire collection in, which is both surprising and undesirable. These
- will warn in 1.4 unless the :paramref:`_orm.Session.future` flag is set in
- which case they will raise IndexError.
-
-
- .. change::
- :tags: sql, change
- :tickets: 4617
-
- The "clause coercion" system, which is SQLAlchemy Core's system of receiving
- arguments and resolving them into :class:`_expression.ClauseElement` structures in order
- to build up SQL expression objects, has been rewritten from a series of
- ad-hoc functions to a fully consistent class-based system. This change
- is internal and should have no impact on end users other than more specific
- error messages when the wrong kind of argument is passed to an expression
- object, however the change is part of a larger set of changes involving
- the role and behavior of :func:`_expression.select` objects.
-
-
- .. change::
- :tags: bug, mysql
-
- The MySQL and MariaDB dialects now query from the information_schema.tables
- system view in order to determine if a particular table exists or not.
- Previously, the "DESCRIBE" command was used with an exception catch to
- detect non-existent, which would have the undesirable effect of emitting a
- ROLLBACK on the connection. There appeared to be legacy encoding issues
- which prevented the use of "SHOW TABLES", for this, but as MySQL support is
- now at 5.0.2 or above due to :ticket:`4189`, the information_schema tables
- are now available in all cases.
-
-
- .. change::
- :tags: bug, orm
- :tickets: 5122
-
- A query that is against a mapped inheritance subclass which also uses
- :meth:`_query.Query.select_entity_from` or a similar technique in order to
- provide an existing subquery to SELECT from, will now raise an error if the
- given subquery returns entities that do not correspond to the given
- subclass, that is, they are sibling or superclasses in the same hierarchy.
- Previously, these would be returned without error. Additionally, if the
- inheritance mapping is a single-inheritance mapping, the given subquery
- must apply the appropriate filtering against the polymorphic discriminator
- column in order to avoid this error; previously, the :class:`_query.Query` would
- add this criteria to the outside query however this interferes with some
- kinds of query that return other kinds of entities as well.
-
- .. seealso::
-
- :ref:`change_5122`
-
- .. change::
- :tags: bug, engine
- :tickets: 5004
-
- Revised the :paramref:`.Connection.execution_options.schema_translate_map`
- feature such that the processing of the SQL statement to receive a specific
- schema name occurs within the execution phase of the statement, rather than
- at the compile phase. This is to support the statement being efficiently
- cached. Previously, the current schema being rendered into the statement
- for a particular run would be considered as part of the cache key itself,
- meaning that for a run against hundreds of schemas, there would be hundreds
- of cache keys, rendering the cache much less performant. The new behavior
- is that the rendering is done in a similar manner as the "post compile"
- rendering added in 1.4 as part of :ticket:`4645`, :ticket:`4808`.
-
- .. change::
- :tags: usecase, sql
- :tickets: 527
-
- The :meth:`.Index.create` and :meth:`.Index.drop` methods now have a
- parameter :paramref:`.Index.create.checkfirst`, in the same way as that of
- :class:`_schema.Table` and :class:`.Sequence`, which when enabled will cause the
- operation to detect if the index exists (or not) before performing a create
- or drop operation.
-
-
- .. change::
- :tags: sql, postgresql
- :tickets: 5498
-
- Allow specifying the data type when creating a :class:`.Sequence` in
- PostgreSQL by using the parameter :paramref:`.Sequence.data_type`.
-
- .. change::
- :tags: change, mssql
- :tickets: 5084
-
- SQL Server OFFSET and FETCH keywords are now used for limit/offset, rather
- than using a window function, for SQL Server versions 11 and higher. TOP is
- still used for a query that features only LIMIT. Pull request courtesy
- Elkin.
-
- .. change::
- :tags: deprecated, engine
- :tickets: 5526
-
- The :class:`_engine.URL` object is now an immutable named tuple. To modify
- a URL object, use the :meth:`_engine.URL.set` method to produce a new URL
- object.
-
- .. seealso::
-
- :ref:`change_5526` - notes on migration
-
-
- .. change::
- :tags: change, postgresql
-
- When using the psycopg2 dialect for PostgreSQL, psycopg2 minimum version is
- set at 2.7. The psycopg2 dialect relies upon many features of psycopg2
- released in the past few years, so to simplify the dialect, version 2.7,
- released in March, 2017 is now the minimum version required.
-
-
- .. change::
- :tags: usecase, sql
-
- The :func:`.true` and :func:`.false` operators may now be applied as the
- "onclause" of a :func:`_expression.join` on a backend that does not support
- "native boolean" expressions, e.g. Oracle or SQL Server, and the expression
- will render as "1=1" for true and "1=0" false. This is the behavior that
- was introduced many years ago in :ticket:`2804` for and/or expressions.
-
- .. change::
- :tags: feature, engine
- :tickets: 5087, 4395, 4959
-
- Implemented an all-new :class:`_result.Result` object that replaces the previous
- ``ResultProxy`` object. As implemented in Core, the subclass
- :class:`_result.CursorResult` features a compatible calling interface with the
- previous ``ResultProxy``, and additionally adds a great amount of new
- functionality that can be applied to Core result sets as well as ORM result
- sets, which are now integrated into the same model. :class:`_result.Result`
- includes features such as column selection and rearrangement, improved
- fetchmany patterns, uniquing, as well as a variety of implementations that
- can be used to create database results from in-memory structures as well.
-
-
- .. seealso::
-
- :ref:`change_result_14_core`
-
-
- .. change::
- :tags: renamed, engine
- :tickets: 5244
-
- The :meth:`_reflection.Inspector.reflecttable` was renamed to
- :meth:`_reflection.Inspector.reflect_table`.
-
- .. change::
- :tags: change, orm
- :tickets: 4662
-
- The condition where a pending object being flushed with an identity that
- already exists in the identity map has been adjusted to emit a warning,
- rather than throw a :class:`.FlushError`. The rationale is so that the
- flush will proceed and raise a :class:`.IntegrityError` instead, in the
- same way as if the existing object were not present in the identity map
- already. This helps with schemes that are using the
- :class:`.IntegrityError` as a means of catching whether or not a row
- already exists in the table.
-
- .. seealso::
-
- :ref:`change_4662`
-
-
- .. change::
- :tags: bug, sql
- :tickets: 5001
-
- Fixed issue where when constructing constraints from ORM-bound columns,
- primarily :class:`_schema.ForeignKey` objects but also :class:`.UniqueConstraint`,
- :class:`.CheckConstraint` and others, the ORM-level
- :class:`.InstrumentedAttribute` is discarded entirely, and all ORM-level
- annotations from the columns are removed; this is so that the constraints
- are still fully pickleable without the ORM-level entities being pulled in.
- These annotations are not necessary to be present at the schema/metadata
- level.
-
- .. change::
- :tags: bug, mysql
- :tickets: 5568
-
- The "skip_locked" keyword used with ``with_for_update()`` will render "SKIP
- LOCKED" on all MySQL backends, meaning it will fail for MySQL less than
- version 8 and on current MariaDB backends. This is because those backends
- do not support "SKIP LOCKED" or any equivalent, so this error should not be
- silently ignored. This is upgraded from a warning in the 1.3 series.
-
-
- .. change::
- :tags: performance, postgresql
- :tickets: 5401
-
- The psycopg2 dialect now defaults to using the very performant
- ``execute_values()`` psycopg2 extension for compiled INSERT statements,
- and also implements RETURNING support when this extension is used. This
- allows INSERT statements that even include an autoincremented SERIAL
- or IDENTITY value to run very fast while still being able to return the
- newly generated primary key values. The ORM will then integrate this
- new feature in a separate change.
-
- .. seealso::
-
- :ref:`change_5401` - full list of changes regarding the
- ``executemany_mode`` parameter.
-
-
- .. change::
- :tags: feature, orm
- :tickets: 4472
-
- Added the ability to add arbitrary criteria to the ON clause generated
- by a relationship attribute in a query, which applies to methods such
- as :meth:`_query.Query.join` as well as loader options like
- :func:`_orm.joinedload`. Additionally, a "global" version of the option
- allows limiting criteria to be applied to particular entities in
- a query globally.
-
- .. seealso::
-
- :ref:`loader_option_criteria`
-
- :ref:`do_orm_execute_global_criteria`
-
- :func:`_orm.with_loader_criteria`
-
- .. change::
- :tags: renamed, sql
-
- :class:`_schema.Table` parameter ``mustexist`` has been renamed
- to :paramref:`_schema.Table.must_exist` and will now warn when used.
-
- .. change::
- :tags: removed, sql
- :tickets: 4632
-
- The "threadlocal" execution strategy, deprecated in 1.3, has been
- removed for 1.4, as well as the concept of "engine strategies" and the
- ``Engine.contextual_connect`` method. The "strategy='mock'" keyword
- argument is still accepted for now with a deprecation warning; use
- :func:`.create_mock_engine` instead for this use case.
-
- .. seealso::
-
- :ref:`change_4393_threadlocal` - from the 1.3 migration notes which
- discusses the rationale for deprecation.
-
- .. change::
- :tags: mssql, postgresql, reflection, schema, usecase
- :tickets: 4458
-
- Improved support for covering indexes (with INCLUDE columns). Added the
- ability for postgresql to render CREATE INDEX statements with an INCLUDE
- clause from Core. Index reflection also report INCLUDE columns separately
- for both mssql and postgresql (11+).
-
- .. change::
- :tags: change, platform
- :tickets: 5400
-
- The ``importlib_metadata`` library is used to scan for setuptools
- entrypoints rather than pkg_resources. as importlib_metadata is a small
- library that is included as of Python 3.8, the compatibility library is
- installed as a dependency for Python versions older than 3.8.
-
-
- .. change::
- :tags: feature, sql, mssql, oracle
- :tickets: 4808
-
- Added new "post compile parameters" feature. This feature allows a
- :func:`.bindparam` construct to have its value rendered into the SQL string
- before being passed to the DBAPI driver, but after the compilation step,
- using the "literal render" feature of the compiler. The immediate
- rationale for this feature is to support LIMIT/OFFSET schemes that don't
- work or perform well as bound parameters handled by the database driver,
- while still allowing for SQLAlchemy SQL constructs to be cacheable in their
- compiled form. The immediate targets for the new feature are the "TOP
- N" clause used by SQL Server (and Sybase) which does not support a bound
- parameter, as well as the "ROWNUM" and optional "FIRST_ROWS()" schemes used
- by the Oracle dialect, the former of which has been known to perform better
- without bound parameters and the latter of which does not support a bound
- parameter. The feature builds upon the mechanisms first developed to
- support "expanding" parameters for IN expressions. As part of this
- feature, the Oracle ``use_binds_for_limits`` feature is turned on
- unconditionally and this flag is now deprecated.
-
- .. seealso::
-
- :ref:`change_4808`
-
- .. change::
- :tags: feature, sql
- :tickets: 1390
-
- Add support for regular expression on supported backends.
- Two operations have been defined:
-
- * :meth:`_sql.ColumnOperators.regexp_match` implementing a regular
- expression match like function.
- * :meth:`_sql.ColumnOperators.regexp_replace` implementing a regular
- expression string replace function.
-
- Supported backends include SQLite, PostgreSQL, MySQL / MariaDB, and Oracle.
-
- .. seealso::
-
- :ref:`change_1390`
-
- .. change::
- :tags: bug, orm
- :tickets: 4696
-
- The internal attribute symbols NO_VALUE and NEVER_SET have been unified, as
- there was no meaningful difference between these two symbols, other than a
- few codepaths where they were differentiated in subtle and undocumented
- ways, these have been fixed.
-
-
- .. change::
- :tags: oracle, bug
-
- Correctly render :class:`_schema.Sequence` and :class:`_schema.Identity`
- column options ``nominvalue`` and ``nomaxvalue`` as ``NOMAXVALUE` and
- ``NOMINVALUE`` on oracle database.
-
- .. change::
- :tags: bug, schema
- :tickets: 4262
-
- Cleaned up the internal ``str()`` for datatypes so that all types produce a
- string representation without any dialect present, including that it works
- for third-party dialect types without that dialect being present. The
- string representation defaults to being the UPPERCASE name of that type
- with nothing else.
-
-
- .. change::
- :tags: deprecated, sql
- :tickets: 5010
-
- The :meth:`_sql.Join.alias` method is deprecated and will be removed in
- SQLAlchemy 2.0. An explicit select + subquery, or aliasing of the inner
- tables, should be used instead.
-
-
- .. change::
- :tags: bug, orm
- :tickets: 4194
-
- Fixed bug where a versioning column specified on a mapper against a
- :func:`_expression.select` construct where the version_id_col itself were against the
- underlying table would incur additional loads when accessed, even if the
- value were locally persisted by the flush. The actual fix is a result of
- the changes in :ticket:`4617`, by fact that a :func:`_expression.select` object no
- longer has a ``.c`` attribute and therefore does not confuse the mapper
- into thinking there's an unknown column value present.
-
- .. change::
- :tags: bug, orm
- :tickets: 3858
-
- An ``UnmappedInstanceError`` is now raised for :class:`.InstrumentedAttribute`
- if an instance is an unmapped object. Prior to this an ``AttributeError``
- was raised. Pull request courtesy Ramon Williams.
-
- .. change::
- :tags: removed, platform
- :tickets: 5634
-
- Dropped support for python 3.4 and 3.5 that has reached EOL. SQLAlchemy 1.4
- series requires python 2.7 or 3.6+.
-
- .. seealso::
-
- :ref:`change_5634`
-
- .. change::
- :tags: performance, sql
- :tickets: 4639
-
- An all-encompassing reorganization and refactoring of Core and ORM
- internals now allows all Core and ORM statements within the areas of
- DQL (e.g. SELECTs) and DML (e.g. INSERT, UPDATE, DELETE) to allow their
- SQL compilation as well as the construction of result-fetching metadata
- to be fully cached in most cases. This effectively provides a transparent
- and generalized version of what the "Baked Query" extension has offered
- for the ORM in past versions. The new feature can calculate the
- cache key for any given SQL construction based on the string that
- it would ultimately produce for a given dialect, allowing functions that
- compose the equivalent select(), Query(), insert(), update() or delete()
- object each time to have that statement cached after it's generated
- the first time.
-
- The feature is enabled transparently but includes some new programming
- paradigms that may be employed to make the caching even more efficient.
-
- .. seealso::
-
- :ref:`change_4639`
-
- :ref:`sql_caching`
-
- .. change::
- :tags: orm, removed
- :tickets: 4638
-
- All long-deprecated "extension" classes have been removed, including
- MapperExtension, SessionExtension, PoolListener, ConnectionProxy,
- AttributeExtension. These classes have been deprecated since version 0.7
- long superseded by the event listener system.
-
-
- .. change::
- :tags: feature, mssql, sql
- :tickets: 4384
-
- Added support for the :class:`_types.JSON` datatype on the SQL Server
- dialect using the :class:`_mssql.JSON` implementation, which implements SQL
- Server's JSON functionality against the ``NVARCHAR(max)`` datatype as per
- SQL Server documentation. Implementation courtesy Gord Thompson.
-
- .. change::
- :tags: change, sql
- :tickets: 4868
-
- Added a core :class:`Values` object that enables a VALUES construct
- to be used in the FROM clause of an SQL statement for databases that
- support it (mainly PostgreSQL and SQL Server).
-
- .. change::
- :tags: usecase, mysql
- :tickets: 5496
-
- Added a new dialect token "mariadb" that may be used in place of "mysql" in
- the :func:`_sa.create_engine` URL. This will deliver a MariaDB dialect
- subclass of the MySQLDialect in use that forces the "is_mariadb" flag to
- True. The dialect will raise an error if a server version string that does
- not indicate MariaDB in use is received. This is useful for
- MariaDB-specific testing scenarios as well as to support applications that
- are hardcoding to MariaDB-only concepts. As MariaDB and MySQL featuresets
- and usage patterns continue to diverge, this pattern may become more
- prominent.
-
-
- .. change::
- :tags: bug, postgresql
-
- The pg8000 dialect has been revised and modernized for the most recent
- version of the pg8000 driver for PostgreSQL. Changes to the dialect
- include:
-
- * All data types are now sent as text rather than binary.
-
- * Using adapters, custom types can be plugged in to pg8000.
-
- * Previously, named prepared statements were used for all statements.
- Now unnamed prepared statements are used by default, and named
- prepared statements can be used explicitly by calling the
- Connection.prepare() method, which returns a PreparedStatement
- object.
-
- Pull request courtesy Tony Locke.
-
- .. change::
- :tags: bug, orm
- :tickets: 5074
-
- The :class:`.Session` object no longer initiates a
- :class:`.SessionTransaction` object immediately upon construction or after
- the previous transaction is closed; instead, "autobegin" logic now
- initiates the new :class:`.SessionTransaction` on demand when it is next
- needed. Rationale includes to remove reference cycles from a
- :class:`.Session` that has been closed out, as well as to remove the
- overhead incurred by the creation of :class:`.SessionTransaction` objects
- that are often discarded immediately. This change affects the behavior of
- the :meth:`.SessionEvents.after_transaction_create` hook in that the event
- will be emitted when the :class:`.Session` first requires a
- :class:`.SessionTransaction` be present, rather than whenever the
- :class:`.Session` were created or the previous :class:`.SessionTransaction`
- were closed. Interactions with the :class:`_engine.Engine` and the database
- itself remain unaffected.
-
- .. seealso::
-
- :ref:`change_5074`
-
-
- .. change::
- :tags: oracle, change
-
- The LIMIT / OFFSET scheme used in Oracle now makes use of named subqueries
- rather than unnamed subqueries when it transparently rewrites a SELECT
- statement to one that uses a subquery that includes ROWNUM. The change is
- part of a larger change where unnamed subqueries are no longer directly
- supported by Core, as well as to modernize the internal use of the select()
- construct within the Oracle dialect.
-
-
- .. change::
- :tags: feature, engine, orm
- :tickets: 3414
-
- SQLAlchemy now includes support for Python asyncio within both Core and
- ORM, using the included :ref:`asyncio extension <asyncio_toplevel>`. The
- extension makes use of the `greenlet
- <https://greenlet.readthedocs.io/en/latest/>`_ library in order to adapt
- SQLAlchemy's sync-oriented internals such that an asyncio interface that
- ultimately interacts with an asyncio database adapter is now feasible. The
- single driver supported at the moment is the
- :ref:`dialect-postgresql-asyncpg` driver for PostgreSQL.
-
- .. seealso::
-
- :ref:`change_3414`
-
-
- .. change::
- :tags: removed, sql
-
- Removed the ``sqlalchemy.sql.visitors.iterate_depthfirst`` and
- ``sqlalchemy.sql.visitors.traverse_depthfirst`` functions. These functions
- were unused by any part of SQLAlchemy. The
- :func:`_sa.sql.visitors.iterate` and :func:`_sa.sql.visitors.traverse`
- functions are commonly used for these functions. Also removed unused
- options from the remaining functions including "column_collections",
- "schema_visitor".
-
-
- .. change::
- :tags: orm, performance
-
- The bulk update and delete methods :meth:`.Query.update` and
- :meth:`.Query.delete`, as well as their 2.0-style counterparts, now make
- use of RETURNING when the "fetch" strategy is used in order to fetch the
- list of affected primary key identites, rather than emitting a separate
- SELECT, when the backend in use supports RETURNING. Additionally, the
- "fetch" strategy will in ordinary cases not expire the attributes that have
- been updated, and will instead apply the updated values directly in the
- same way that the "evaluate" strategy does, to avoid having to refresh the
- object. The "evaluate" strategy will also fall back to expiring
- attributes that were updated to a SQL expression that was unevaluable in
- Python.
-
- .. seealso::
-
- :ref:`change_orm_update_returning_14`
-
- .. change::
- :tags: bug, orm
- :tickets: 4829
-
- Added new entity-targeting capabilities to the ORM query context
- help with the case where the :class:`.Session` is using a bind dictionary
- against mapped classes, rather than a single bind, and the :class:`_query.Query`
- is against a Core statement that was ultimately generated from a method
- such as :meth:`_query.Query.subquery`. First implemented using a deep
- search, the current approach leverages the unified :func:`_sql.select`
- construct to keep track of the first mapper that is part of
- the construct.
-
-
- .. change::
- :tags: mssql
-
- The mssql dialect will assume that at least MSSQL 2005 is used.
- There is no hard exception raised if a previous version is detected,
- but operations may fail for older versions.
-
- .. change::
- :tags: bug, inheritance, orm
- :tickets: 4212
-
- An :class:`.ArgumentError` is now raised if both the ``selectable`` and
- ``flat`` parameters are set to True in :func:`.orm.with_polymorphic`. The
- selectable name is already aliased and applying flat=True overrides the
- selectable name with an anonymous name that would've previously caused the
- code to break. Pull request courtesy Ramon Williams.
-
- .. change::
- :tags: mysql, usecase
- :tickets: 4976
-
- Added support for use of the :class:`.Sequence` construct with MariaDB 10.3
- and greater, as this is now supported by this database. The construct
- integrates with the :class:`_schema.Table` object in the same way that it does for
- other databases like PostgreSQL and Oracle; if is present on the integer
- primary key "autoincrement" column, it is used to generate defaults. For
- backwards compatibility, to support a :class:`_schema.Table` that has a
- :class:`.Sequence` on it to support sequence only databases like Oracle,
- while still not having the sequence fire off for MariaDB, the optional=True
- flag should be set, which indicates the sequence should only be used to
- generate the primary key if the target database offers no other option.
-
- .. seealso::
-
- :ref:`change_4976`
-
-
- .. change::
- :tags: deprecated, engine
- :tickets: 4634
-
- The :paramref:`_schema.MetaData.bind` argument as well as the overall
- concept of "bound metadata" is deprecated in SQLAlchemy 1.4 and will be
- removed in SQLAlchemy 2.0. The parameter as well as related functions now
- emit a :class:`_exc.RemovedIn20Warning` when :ref:`deprecation_20_mode` is
- in use.
-
- .. seealso::
-
- :ref:`migration_20_implicit_execution`
-
-
-
- .. change::
- :tags: change, extensions
- :tickets: 5142
-
- Added new parameter :paramref:`_automap.AutomapBase.prepare.autoload_with`
- which supersedes :paramref:`_automap.AutomapBase.prepare.reflect`
- and :paramref:`_automap.AutomapBase.prepare.engine`.
-
-
-
- .. change::
- :tags: usecase, mssql, postgresql
- :tickets: 4966
-
- Added support for inspection / reflection of partial indexes / filtered
- indexes, i.e. those which use the ``mssql_where`` or ``postgresql_where``
- parameters, with :class:`_schema.Index`. The entry is both part of the
- dictionary returned by :meth:`.Inspector.get_indexes` as well as part of a
- reflected :class:`_schema.Index` construct that was reflected. Pull
- request courtesy Ramon Williams.
-
- .. change::
- :tags: mssql, feature
- :tickets: 4235, 4633
-
- Added support for "CREATE SEQUENCE" and full :class:`.Sequence` support for
- Microsoft SQL Server. This removes the deprecated feature of using
- :class:`.Sequence` objects to manipulate IDENTITY characteristics which
- should now be performed using ``mssql_identity_start`` and
- ``mssql_identity_increment`` as documented at :ref:`mssql_identity`. The
- change includes a new parameter :paramref:`.Sequence.data_type` to
- accommodate SQL Server's choice of datatype, which for that backend
- includes INTEGER, BIGINT, and DECIMAL(n, 0). The default starting value
- for SQL Server's version of :class:`.Sequence` has been set at 1; this
- default is now emitted within the CREATE SEQUENCE DDL for all backends.
-
- .. seealso::
-
- :ref:`change_4235`
-
- .. change::
- :tags: bug, orm
- :tickets: 4718
-
- Fixed issue in polymorphic loading internals which would fall back to a
- more expensive, soon-to-be-deprecated form of result column lookup within
- certain unexpiration scenarios in conjunction with the use of
- "with_polymorphic".
-
- .. change::
- :tags: mssql, reflection
- :tickets: 5527
-
- As part of the support for reflecting :class:`_schema.Identity` objects,
- the method :meth:`_reflection.Inspector.get_columns` no longer returns
- ``mssql_identity_start`` and ``mssql_identity_increment`` as part of the
- ``dialect_options``. Use the information in the ``identity`` key instead.
-
- .. change::
- :tags: schema, sql
- :tickets: 5362, 5324, 5360
-
- Added the :class:`_schema.Identity` construct that can be used to
- configure identity columns rendered with GENERATED { ALWAYS |
- BY DEFAULT } AS IDENTITY. Currently the supported backends are
- PostgreSQL >= 10, Oracle >= 12 and MSSQL (with different syntax
- and a subset of functionalities).
-
- .. change::
- :tags: change, orm, sql
-
- A selection of Core and ORM query objects now perform much more of their
- Python computational tasks within the compile step, rather than at
- construction time. This is to support an upcoming caching model that will
- provide for caching of the compiled statement structure based on a cache
- key that is derived from the statement construct, which itself is expected
- to be newly constructed in Python code each time it is used. This means
- that the internal state of these objects may not be the same as it used to
- be, as well as that some but not all error raise scenarios for various
- kinds of argument validation will occur within the compilation / execution
- phase, rather than at statement construction time. See the migration
- notes linked below for complete details.
-
- .. seealso::
-
- :ref:`change_deferred_construction`
-
-
- .. change::
- :tags: usecase, mssql, reflection
- :tickets: 5506
-
- Added support for reflection of temporary tables with the SQL Server dialect.
- Table names that are prefixed by a pound sign "#" are now introspected from
- the MSSQL "tempdb" system catalog.
-
- .. change::
- :tags: firebird, deprecated
- :tickets: 5189
-
- The Firebird dialect is deprecated, as there is now a 3rd party
- dialect that supports this database.
-
- .. change::
- :tags: misc, deprecated
- :tickets: 5189
-
- The Sybase dialect is deprecated.
-
-
- .. change::
- :tags: mssql, deprecated
- :tickets: 5189
-
- The adodbapi and mxODBC dialects are deprecated.
-
-
- .. change::
- :tags: mysql, deprecated
- :tickets: 5189
-
- The OurSQL dialect is deprecated.
-
- .. change::
- :tags: postgresql, deprecated
- :tickets: 5189
-
- The pygresql and py-postgresql dialects are deprecated.
-
- .. change::
- :tags: bug, sql
- :tickets: 4649, 4569
-
- Registered function names based on :class:`.GenericFunction` are now
- retrieved in a case-insensitive fashion in all cases, removing the
- deprecation logic from 1.3 which temporarily allowed multiple
- :class:`.GenericFunction` objects to exist with differing cases. A
- :class:`.GenericFunction` that replaces another on the same name whether or
- not it's case sensitive emits a warning before replacing the object.
-
- .. change::
- :tags: orm, performance, postgresql
- :tickets: 5263
-
- Implemented support for the psycopg2 ``execute_values()`` extension
- within the ORM flush process via the enhancements to Core made
- in :ticket:`5401`, so that this extension is used
- both as a strategy to batch INSERT statements together as well as
- that RETURNING may now be used among multiple parameter sets to
- retrieve primary key values back in batch. This allows nearly
- all INSERT statements emitted by the ORM on behalf of PostgreSQL
- to be submitted in batch and also via the ``execute_values()``
- extension which benches at five times faster than plain
- executemany() for this particular backend.
-
- .. seealso::
-
- :ref:`change_5263`
-
- .. change::
- :tags: change, general
- :tickets: 4789
-
- "python setup.py test" is no longer a test runner, as this is deprecated by
- Pypa. Please use "tox" with no arguments for a basic test run.
-
-
- .. change::
- :tags: usecase, oracle
- :tickets: 4857
-
- The max_identifier_length for the Oracle dialect is now 128 characters by
- default, unless compatibility version less than 12.2 upon first connect, in
- which case the legacy length of 30 characters is used. This is a
- continuation of the issue as committed to the 1.3 series which adds max
- identifier length detection upon first connect as well as warns for the
- change in Oracle server.
-
- .. seealso::
-
- :ref:`oracle_max_identifier_lengths` - in the Oracle dialect documentation
-
-
- .. change::
- :tags: bug, oracle
- :tickets: 4971
-
- The :class:`_oracle.INTERVAL` class of the Oracle dialect is now correctly
- a subclass of the abstract version of :class:`.Interval` as well as the
- correct "emulated" base class, which allows for correct behavior under both
- native and non-native modes; previously it was only based on
- :class:`.TypeEngine`.
-
-
- .. change::
- :tags: bug, orm
- :tickets: 4994
-
- An error is raised if any persistence-related "cascade" settings are made
- on a :func:`_orm.relationship` that also sets up viewonly=True. The "cascade"
- settings now default to non-persistence related settings only when viewonly
- is also set. This is the continuation from :ticket:`4993` where this
- setting was changed to emit a warning in 1.3.
-
- .. seealso::
-
- :ref:`change_4994`
-
-
-
- .. change::
- :tags: bug, sql
- :tickets: 5054
-
- Creating an :func:`.and_` or :func:`.or_` construct with no arguments or
- empty ``*args`` will now emit a deprecation warning, as the SQL produced is
- a no-op (i.e. it renders as a blank string). This behavior is considered to
- be non-intuitive, so for empty or possibly empty :func:`.and_` or
- :func:`.or_` constructs, an appropriate default boolean should be included,
- such as ``and_(True, *args)`` or ``or_(False, *args)``. As has been the
- case for many major versions of SQLAlchemy, these particular boolean
- values will not render if the ``*args`` portion is non-empty.
-
- .. change::
- :tags: removed, sql
-
- Removed the concept of a bound engine from the :class:`.Compiler` object,
- and removed the ``.execute()`` and ``.scalar()`` methods from
- :class:`.Compiler`. These were essentially forgotten methods from over a
- decade ago and had no practical use, and it's not appropriate for the
- :class:`.Compiler` object itself to be maintaining a reference to an
- :class:`_engine.Engine`.
-
- .. change::
- :tags: performance, engine
- :tickets: 4524
-
- The pool "pre-ping" feature has been refined to not invoke for a DBAPI
- connection that was just opened in the same checkout operation. pre ping
- only applies to a DBAPI connection that's been checked into the pool
- and is being checked out again.
-
- .. change::
- :tags: deprecated, engine
-
- The ``server_side_cursors`` engine-wide parameter is deprecated and will be
- removed in a future release. For unbuffered cursors, the
- :paramref:`_engine.Connection.execution_options.stream_results` execution
- option should be used on a per-execution basis.
-
- .. change::
- :tags: bug, orm
- :tickets: 4699
-
- Improved declarative inheritance scanning to not get tripped up when the
- same base class appears multiple times in the base inheritance list.
-
-
- .. change::
- :tags: orm, change
- :tickets: 4395
-
- The automatic uniquing of rows on the client side is turned off for the new
- :term:`2.0 style` of ORM querying. This improves both clarity and
- performance. However, uniquing of rows on the client side is generally
- necessary when using joined eager loading for collections, as there
- will be duplicates of the primary entity for each element in the
- collection because a join was used. This uniquing must now be manually
- enabled and can be achieved using the new
- :meth:`_engine.Result.unique` modifier. To avoid silent failure, the ORM
- explicitly requires the method be called when the result of an ORM
- query in 2.0 style makes use of joined load collections. The newer
- :func:`_orm.selectinload` strategy is likely preferable for eager loading
- of collections in any case.
-
- .. seealso::
-
- :ref:`joinedload_not_uniqued`
-
- .. change::
- :tags: bug, orm
- :tickets: 4195
-
- Fixed bug in ORM versioning feature where assignment of an explicit
- version_id for a counter configured against a mapped selectable where
- version_id_col is against the underlying table would fail if the previous
- value were expired; this was due to the fact that the mapped attribute
- would not be configured with active_history=True.
-
-
- .. change::
- :tags: mssql, bug, schema
- :tickets: 5597
-
- Fixed an issue where :meth:`_reflection.has_table` always returned
- ``False`` for temporary tables.
-
- .. change::
- :tags: mssql, engine
- :tickets: 4809
-
- Deprecated the ``legacy_schema_aliasing`` parameter to
- :meth:`_sa.create_engine`. This is a long-outdated parameter that has
- defaulted to False since version 1.1.
-
- .. change::
- :tags: usecase, orm
- :tickets: 1653
-
- The evaluator that takes place within the ORM bulk update and delete for
- synchronize_session="evaluate" now supports the IN and NOT IN operators.
- Tuple IN is also supported.
-
-
- .. change::
- :tags: change, sql
- :tickets: 5284
-
- The :func:`_expression.select` construct is moving towards a new calling
- form that is ``select(col1, col2, col3, ..)``, with all other keyword
- arguments removed, as these are all suited using generative methods. The
- single list of column or table arguments passed to ``select()`` is still
- accepted, however is no longer necessary if expressions are passed in a
- simple positional style. Other keyword arguments are disallowed when this
- form is used.
-
-
- .. seealso::
-
- :ref:`change_5284`
-
- .. change::
- :tags: change, sqlite
- :tickets: 4895
-
- Dropped support for right-nested join rewriting to support old SQLite
- versions prior to 3.7.16, released in 2013. It is expected that
- all modern Python versions among those now supported should all include
- much newer versions of SQLite.
-
- .. seealso::
-
- :ref:`change_4895`
-
-
- .. change::
- :tags: deprecated, engine
- :tickets: 5131
-
- The :meth:`_engine.Connection.connect` method is deprecated as is the concept of
- "connection branching", which copies a :class:`_engine.Connection` into a new one
- that has a no-op ".close()" method. This pattern is oriented around the
- "connectionless execution" concept which is also being removed in 2.0.
-
- .. change::
- :tags: bug, general
- :tickets: 4656, 4689
-
- Refactored the internal conventions used to cross-import modules that have
- mutual dependencies between them, such that the inspected arguments of
- functions and methods are no longer modified. This allows tools like
- pylint, Pycharm, other code linters, as well as hypothetical pep-484
- implementations added in the future to function correctly as they no longer
- see missing arguments to function calls. The new approach is also
- simpler and more performant.
-
- .. seealso::
-
- :ref:`change_4656`
-
- .. change::
- :tags: sql, usecase
- :tickets: 5191
-
- Change the method ``__str`` of :class:`ColumnCollection` to avoid
- confusing it with a python list of string.
-
- .. change::
- :tags: sql, reflection
- :tickets: 4741
-
- The "NO ACTION" keyword for foreign key "ON UPDATE" is now considered to be
- the default cascade for a foreign key on all supporting backends (SQlite,
- MySQL, PostgreSQL) and when detected is not included in the reflection
- dictionary; this is already the behavior for PostgreSQL and MySQL for all
- previous SQLAlchemy versions in any case. The "RESTRICT" keyword is
- positively stored when detected; PostgreSQL does report on this keyword,
- and MySQL as of version 8.0 does as well. On earlier MySQL versions, it is
- not reported by the database.
-
- .. change::
- :tags: sql, reflection
- :tickets: 5527, 5324
-
- Added support for reflecting "identity" columns, which are now returned
- as part of the structure returned by :meth:`_reflection.Inspector.get_columns`.
- When reflecting full :class:`_schema.Table` objects, identity columns will
- be represented using the :class:`_schema.Identity` construct.
- Currently the supported backends are
- PostgreSQL >= 10, Oracle >= 12 and MSSQL (with different syntax
- and a subset of functionalities).
-
- .. change::
- :tags: feature, sql
- :tickets: 4753
-
- The :func:`_expression.select` construct and related constructs now allow for
- duplication of column labels and columns themselves in the columns clause,
- mirroring exactly how column expressions were passed in. This allows
- the tuples returned by an executed result to match what was SELECTed
- for in the first place, which is how the ORM :class:`_query.Query` works, so
- this establishes better cross-compatibility between the two constructs.
- Additionally, it allows column-positioning-sensitive structures such as
- UNIONs (i.e. :class:`_selectable.CompoundSelect`) to be more intuitively constructed
- in those cases where a particular column might appear in more than one
- place. To support this change, the :class:`_expression.ColumnCollection` has been
- revised to support duplicate columns as well as to allow integer index
- access.
-
- .. seealso::
-
- :ref:`change_4753`
-
-
- .. change::
- :tags: renamed, sql
- :tickets: 4617
-
- The :meth:`_expression.SelectBase.as_scalar` and :meth:`_query.Query.as_scalar` methods have
- been renamed to :meth:`_expression.SelectBase.scalar_subquery` and
- :meth:`_query.Query.scalar_subquery`, respectively. The old names continue to
- exist within 1.4 series with a deprecation warning. In addition, the
- implicit coercion of :class:`_expression.SelectBase`, :class:`_expression.Alias`, and other
- SELECT oriented objects into scalar subqueries when evaluated in a column
- context is also deprecated, and emits a warning that the
- :meth:`_expression.SelectBase.scalar_subquery` method should be called explicitly.
- This warning will in a later major release become an error, however the
- message will always be clear when :meth:`_expression.SelectBase.scalar_subquery` needs
- to be invoked. The latter part of the change is for clarity and to reduce
- the implicit decisionmaking by the query coercion system. The
- :meth:`.Subquery.as_scalar` method, which was previously
- ``Alias.as_scalar``, is also deprecated; ``.scalar_subquery()`` should be
- invoked directly from ` :func:`_expression.select` object or :class:`_query.Query` object.
-
- This change is part of the larger change to convert :func:`_expression.select` objects
- to no longer be directly part of the "from clause" class hierarchy, which
- also includes an overhaul of the clause coercion system.
-
-
- .. change::
- :tags: bug, mssql
- :tickets: 4980
-
- Fixed the base class of the :class:`_mssql.DATETIMEOFFSET` datatype to
- be based on the :class:`.DateTime` class hierarchy, as this is a
- datetime-holding datatype.
-
-
- .. change::
- :tags: bug, engine
- :tickets: 4712
-
- The :class:`_engine.Connection` object will now not clear a rolled-back
- transaction until the outermost transaction is explicitly rolled back.
- This is essentially the same behavior that the ORM :class:`.Session` has
- had for a long time, where an explicit call to ``.rollback()`` on all
- enclosing transactions is required for the transaction to logically clear,
- even though the DBAPI-level transaction has already been rolled back.
- The new behavior helps with situations such as the "ORM rollback test suite"
- pattern where the test suite rolls the transaction back within the ORM
- scope, but the test harness which seeks to control the scope of the
- transaction externally does not expect a new transaction to start
- implicitly.
-
- .. seealso::
-
- :ref:`change_4712`
-
-
- .. change::
- :tags: deprecated, orm
- :tickets: 4719
-
- Calling the :meth:`_query.Query.instances` method without passing a
- :class:`.QueryContext` is deprecated. The original use case for this was
- that a :class:`_query.Query` could yield ORM objects when given only the entities
- to be selected as well as a DBAPI cursor object. However, for this to work
- correctly there is essential metadata that is passed from a SQLAlchemy
- :class:`_engine.ResultProxy` that is derived from the mapped column expressions,
- which comes originally from the :class:`.QueryContext`. To retrieve ORM
- results from arbitrary SELECT statements, the :meth:`_query.Query.from_statement`
- method should be used.
-
-
- .. change::
- :tags: deprecated, sql
-
- The :class:`_schema.Table` class now raises a deprecation warning
- when columns with the same name are defined. To replace a column a new
- parameter :paramref:`_schema.Table.append_column.replace_existing` was
- added to the :meth:`_schema.Table.append_column` method.
-
- The :meth:`_expression.ColumnCollection.contains_column` will now
- raises an error when called with a string, suggesting the caller
- to use ``in`` instead.
-
- .. change::
- :tags: deprecated, engine
- :tickets: 4878
-
- The :paramref:`.case_sensitive` flag on :func:`_sa.create_engine` is
- deprecated; this flag was part of the transition of the result row object
- to allow case sensitive column matching as the default, while providing
- backwards compatibility for the former matching method. All string access
- for a row should be assumed to be case sensitive just like any other Python
- mapping.
-
-
- .. change::
- :tags: bug, sql
- :tickets: 5127
-
- Improved the :func:`_sql.tuple_` construct such that it behaves predictably
- when used in a columns-clause context. The SQL tuple is not supported as a
- "SELECT" columns clause element on most backends; on those that do
- (PostgreSQL, not surprisingly), the Python DBAPI does not have a "nested
- type" concept so there are still challenges in fetching rows for such an
- object. Use of :func:`_sql.tuple_` in a :func:`_sql.select` or
- :class:`_orm.Query` will now raise a :class:`_exc.CompileError` at the
- point at which the :func:`_sql.tuple_` object is seen as presenting itself
- for fetching rows (i.e., if the tuple is in the columns clause of a
- subquery, no error is raised). For ORM use,the :class:`_orm.Bundle` object
- is an explicit directive that a series of columns should be returned as a
- sub-tuple per row and is suggested by the error message. Additionally ,the
- tuple will now render with parenthesis in all contexts. Previously, the
- parenthesization would not render in a columns context leading to
- non-defined behavior.
-
- .. change::
- :tags: usecase, sql
- :tickets: 5576
-
- Add support to ``FETCH {FIRST | NEXT} [ count ]
- {ROW | ROWS} {ONLY | WITH TIES}`` in the select for the supported
- backends, currently PostgreSQL, Oracle and MSSQL.
-
- .. change::
- :tags: feature, engine, alchemy2
- :tickets: 4644
-
- Implemented the :paramref:`_sa.create_engine.future` parameter which
- enables forwards compatibility with SQLAlchemy 2. is used for forwards
- compatibility with SQLAlchemy 2. This engine features
- always-transactional behavior with autobegin.
-
- .. seealso::
-
- :ref:`migration_20_toplevel`
-
- .. change::
- :tags: usecase, sql
- :tickets: 4449
-
- Additional logic has been added such that certain SQL expressions which
- typically wrap a single database column will use the name of that column as
- their "anonymous label" name within a SELECT statement, potentially making
- key-based lookups in result tuples more intuitive. The primary example of
- this is that of a CAST expression, e.g. ``CAST(table.colname AS INTEGER)``,
- which will export its default name as "colname", rather than the usual
- "anon_1" label, that is, ``CAST(table.colname AS INTEGER) AS colname``.
- If the inner expression doesn't have a name, then the previous "anonymous
- label" logic is used. When using SELECT statements that make use of
- :meth:`_expression.Select.apply_labels`, such as those emitted by the ORM, the
- labeling logic will produce ``<tablename>_<inner column name>`` in the same
- was as if the column were named alone. The logic applies right now to the
- :func:`.cast` and :func:`.type_coerce` constructs as well as some
- single-element boolean expressions.
-
- .. seealso::
-
- :ref:`change_4449`
-
- .. change::
- :tags: feature, orm
- :tickets: 5508
-
- The ORM Declarative system is now unified into the ORM itself, with new
- import spaces under ``sqlalchemy.orm`` and new kinds of mappings. Support
- for decorator-based mappings without using a base class, support for
- classical style-mapper() calls that have access to the declarative class
- registry for relationships, and full integration of Declarative with 3rd
- party class attribute systems like ``dataclasses`` and ``attrs`` is now
- supported.
-
- .. seealso::
-
- :ref:`change_5508`
-
- :ref:`change_5027`
-
- .. change::
- :tags: removed, platform
- :tickets: 5094
-
- Removed all dialect code related to support for Jython and zxJDBC. Jython
- has not been supported by SQLAlchemy for many years and it is not expected
- that the current zxJDBC code is at all functional; for the moment it just
- takes up space and adds confusion by showing up in documentation. At the
- moment, it appears that Jython has achieved Python 2.7 support in its
- releases but not Python 3. If Jython were to be supported again, the form
- it should take is against the Python 3 version of Jython, and the various
- zxJDBC stubs for various backends should be implemented as a third party
- dialect.
-
-
- .. change::
- :tags: feature, sql
- :tickets: 5221
-
- Enhanced the disambiguating labels feature of the
- :func:`_expression.select` construct such that when a select statement
- is used in a subquery, repeated column names from different tables are now
- automatically labeled with a unique label name, without the need to use the
- full "apply_labels()" feature that combines tablename plus column name.
- The disambiguated labels are available as plain string keys in the .c
- collection of the subquery, and most importantly the feature allows an ORM
- :func:`_orm.aliased` construct against the combination of an entity and an
- arbitrary subquery to work correctly, targeting the correct columns despite
- same-named columns in the source tables, without the need for an "apply
- labels" warning.
-
-
- .. seealso::
-
- :ref:`migration_20_query_from_self` - Illustrates the new
- disambiguation feature as part of a strategy to migrate away from the
- :meth:`_query.Query.from_self` method.
-
- .. change::
- :tags: usecase, postgresql
- :tickets: 5549
-
- Added support for PostgreSQL "readonly" and "deferrable" flags for all of
- psycopg2, asyncpg and pg8000 dialects. This takes advantage of a newly
- generalized version of the "isolation level" API to support other kinds of
- session attributes set via execution options that are reliably reset
- when connections are returned to the connection pool.
-
- .. seealso::
-
- :ref:`postgresql_readonly_deferrable`
-
- .. change::
- :tags: mysql, feature
- :tickets: 5459
-
- Added support for MariaDB Connector/Python to the mysql dialect. Original
- pull request courtesy Georg Richter.
-
- .. change::
- :tags: usecase, orm
- :tickets: 5171
-
- Enhanced logic that tracks if relationships will be conflicting with each
- other when they write to the same column to include simple cases of two
- relationships that should have a "backref" between them. This means that
- if two relationships are not viewonly, are not linked with back_populates
- and are not otherwise in an inheriting sibling/overriding arrangement, and
- will populate the same foreign key column, a warning is emitted at mapper
- configuration time warning that a conflict may arise. A new parameter
- :paramref:`_orm.relationship.overlaps` is added to suit those very rare cases
- where such an overlapping persistence arrangement may be unavoidable.
-
-
- .. change::
- :tags: deprecated, orm
- :tickets: 4705, 5202
-
- Using strings to represent relationship names in ORM operations such as
- :meth:`_orm.Query.join`, as well as strings for all ORM attribute names
- in loader options like :func:`_orm.selectinload`
- is deprecated and will be removed in SQLAlchemy 2.0. The class-bound
- attribute should be passed instead. This provides much better specificity
- to the given method, allows for modifiers such as ``of_type()``, and
- reduces internal complexity.
-
- Additionally, the ``aliased`` and ``from_joinpoint`` parameters to
- :meth:`_orm.Query.join` are also deprecated. The :func:`_orm.aliased`
- construct now provides for a great deal of flexibility and capability
- and should be used directly.
-
- .. seealso::
-
- :ref:`migration_20_orm_query_join_strings`
-
- :ref:`migration_20_query_join_options`
-
- .. change::
- :tags: change, platform
- :tickets: 5404
-
- Installation has been modernized to use setup.cfg for most package
- metadata.
-
- .. change::
- :tags: bug, sql, postgresql
- :tickets: 5653
-
- Improved support for column names that contain percent signs in the string,
- including repaired issues involving anoymous labels that also embedded a
- column name with a percent sign in it, as well as re-established support
- for bound parameter names with percent signs embedded on the psycopg2
- dialect, using a late-escaping process similar to that used by the
- cx_Oracle dialect.
-
-
- .. change::
- :tags: orm, deprecated
- :tickets: 5134
-
- Deprecated logic in :meth:`_query.Query.distinct` that automatically adds
- columns in the ORDER BY clause to the columns clause; this will be removed
- in 2.0.
-
- .. seealso::
-
- :ref:`migration_20_query_distinct`
-
- .. change::
- :tags: orm, removed
- :tickets: 4642
-
- Remove the deprecated loader options ``joinedload_all``, ``subqueryload_all``,
- ``lazyload_all``, ``selectinload_all``. The normal version with method chaining
- should be used in their place.
-
- .. change::
- :tags: bug, sql
- :tickets: 4887
-
- Custom functions that are created as subclasses of
- :class:`.FunctionElement` will now generate an "anonymous label" based on
- the "name" of the function just like any other :class:`.Function` object,
- e.g. ``"SELECT myfunc() AS myfunc_1"``. While SELECT statements no longer
- require labels in order for the result proxy object to function, the ORM
- still targets columns in rows by using objects as mapping keys, which works
- more reliably when the column expressions have distinct names. In any
- case, the behavior is now made consistent between functions generated by
- :attr:`.func` and those generated as custom :class:`.FunctionElement`
- objects.
-
-
- .. change::
- :tags: usecase, extensions
- :tickets: 4887
-
- Custom compiler constructs created using the :mod:`sqlalchemy.ext.compiled`
- extension will automatically add contextual information to the compiler
- when a custom construct is interpreted as an element in the columns
- clause of a SELECT statement, such that the custom element will be
- targetable as a key in result row mappings, which is the kind of targeting
- that the ORM uses in order to match column elements into result tuples.
-
- .. change::
- :tags: engine, bug
- :tickets: 5497
-
- Adjusted the dialect initialization process such that the
- :meth:`_engine.Dialect.on_connect` is not called a second time
- on the first connection. The hook is called first, then the
- :meth:`_engine.Dialect.initialize` is called if that connection is the
- first for that dialect, then no more events are called. This eliminates
- the two calls to the "on_connect" function which can produce very
- difficult debugging situations.
-
- .. change::
- :tags: feature, engine, pyodbc
- :tickets: 5649
-
- Reworked the "setinputsizes()" set of dialect hooks to be correctly
- extensible for any arbirary DBAPI, by allowing dialects individual hooks
- that may invoke cursor.setinputsizes() in the appropriate style for that
- DBAPI. In particular this is intended to support pyodbc's style of usage
- which is fundamentally different from that of cx_Oracle. Added support
- for pyodbc.
-
-
- .. change::
- :tags: deprecated, engine
- :tickets: 4846
-
- "Implicit autocommit", which is the COMMIT that occurs when a DML or DDL
- statement is emitted on a connection, is deprecated and won't be part of
- SQLAlchemy 2.0. A 2.0-style warning is emitted when autocommit takes
- effect, so that the calling code may be adjusted to use an explicit
- transaction.
-
- As part of this change, DDL methods such as
- :meth:`_schema.MetaData.create_all` when used against an
- :class:`_engine.Engine` will run the operation in a BEGIN block if one is
- not started already.
-
- .. seealso::
-
- :ref:`deprecation_20_mode`
-
-
- .. change::
- :tags: deprecated, orm
- :tickets: 5573
-
- Passing keyword arguments to methods such as :meth:`_orm.Session.execute`
- to be passed into the :meth:`_orm.Session.get_bind` method is deprecated;
- the new :paramref:`_orm.Session.execute.bind_arguments` dictionary should
- be passed instead.
-
-
- .. change::
- :tags: renamed, schema
- :tickets: 5413
-
- Renamed the :meth:`_schema.Table.tometadata` method to
- :meth:`_schema.Table.to_metadata`. The previous name remains with a
- deprecation warning.
-
- .. change::
- :tags: bug, sql
- :tickets: 4336
-
- Reworked the :meth:`_expression.ClauseElement.compare` methods in terms of a new
- visitor-based approach, and additionally added test coverage ensuring that
- all :class:`_expression.ClauseElement` subclasses can be accurately compared
- against each other in terms of structure. Structural comparison
- capability is used to a small degree within the ORM currently, however
- it also may form the basis for new caching features.
-
- .. change::
- :tags: feature, orm
- :tickets: 1763
-
- Eager loaders, such as joined loading, SELECT IN loading, etc., when
- configured on a mapper or via query options will now be invoked during
- the refresh on an expired object; in the case of selectinload and
- subqueryload, since the additional load is for a single object only,
- the "immediateload" scheme is used in these cases which resembles the
- single-parent query emitted by lazy loading.
-
- .. seealso::
-
- :ref:`change_1763`
-
- .. change::
- :tags: usecase, orm
- :tickets: 5018, 3903
-
- The ORM bulk update and delete operations, historically available via the
- :meth:`_orm.Query.update` and :meth:`_orm.Query.delete` methods as well as
- via the :class:`_dml.Update` and :class:`_dml.Delete` constructs for
- :term:`2.0 style` execution, will now automatically accommodate for the
- additional WHERE criteria needed for a single-table inheritance
- discriminator in order to limit the statement to rows referring to the
- specific subtype requested. The new :func:`_orm.with_loader_criteria`
- construct is also supported for with bulk update/delete operations.
-
- .. change::
- :tags: engine, removed
- :tickets: 4643
-
- Remove deprecated method ``get_primary_keys`` in the :class:`.Dialect` and
- :class:`_reflection.Inspector` classes. Please refer to the
- :meth:`.Dialect.get_pk_constraint` and :meth:`_reflection.Inspector.get_primary_keys`
- methods.
-
- Remove deprecated event ``dbapi_error`` and the method
- ``ConnectionEvents.dbapi_error``. Please refer to the
- :meth:`_events.ConnectionEvents.handle_error` event.
- This change also removes the attributes ``ExecutionContext.is_disconnect``
- and ``ExecutionContext.exception``.
-
- .. change::
- :tags: removed, postgresql
- :tickets: 4643
-
- Remove support for deprecated engine URLs of the form ``postgres://``;
- this has emitted a warning for many years and projects should be
- using ``postgresql://``.
-
- .. change::
- :tags: removed, mysql
- :tickets: 4643
-
- Remove deprecated dialect ``mysql+gaerdbms`` that has been deprecated
- since version 1.0. Use the MySQLdb dialect directly.
-
- Remove deprecated parameter ``quoting`` from :class:`.mysql.ENUM`
- and :class:`.mysql.SET` in the ``mysql`` dialect. The values passed to the
- enum or the set are quoted by SQLAlchemy when needed automatically.
-
- .. change::
- :tags: removed, orm
- :tickets: 4643
-
- Remove deprecated function ``comparable_property``. Please refer to the
- :mod:`~sqlalchemy.ext.hybrid` extension. This also removes the function
- ``comparable_using`` in the declarative extension.
-
- Remove deprecated function ``compile_mappers``. Please use
- :func:`.configure_mappers`
-
- Remove deprecated method ``collection.linker``. Please refer to the
- :meth:`.AttributeEvents.init_collection` and
- :meth:`.AttributeEvents.dispose_collection` event handlers.
-
- Remove deprecated method ``Session.prune`` and parameter
- ``Session.weak_identity_map``. See the recipe at
- :ref:`session_referencing_behavior` for an event-based approach to
- maintaining strong identity references.
- This change also removes the class ``StrongInstanceDict``.
-
- Remove deprecated parameter ``mapper.order_by``. Use :meth:`_query.Query.order_by`
- to determine the ordering of a result set.
-
- Remove deprecated parameter ``Session._enable_transaction_accounting``.
-
- Remove deprecated parameter ``Session.is_modified.passive``.
-
- .. change::
- :tags: removed, schema
- :tickets: 4643
-
- Remove deprecated class ``Binary``. Please use :class:`.LargeBinary`.
-
- .. change::
- :tags: removed, sql
- :tickets: 4643
-
- Remove deprecated methods ``Compiled.compile``, ``ClauseElement.__and__`` and
- ``ClauseElement.__or__`` and attribute ``Over.func``.
-
- Remove deprecated ``FromClause.count`` method. Please use the
- :class:`_functions.count` function available from the
- :attr:`.func` namespace.
-
- .. change::
- :tags: removed, sql
- :tickets: 4643
-
- Remove deprecated parameters ``text.bindparams`` and ``text.typemap``.
- Please refer to the :meth:`_expression.TextClause.bindparams` and
- :meth:`_expression.TextClause.columns` methods.
-
- Remove deprecated parameter ``Table.useexisting``. Please use
- :paramref:`_schema.Table.extend_existing`.
-
- .. change::
- :tags: bug, orm
- :tickets: 4836
-
- An exception is now raised if the ORM loads a row for a polymorphic
- instance that has a primary key but the discriminator column is NULL, as
- discriminator columns should not be null.
-
-
-
- .. change::
- :tags: bug, sql
- :tickets: 4002
-
- Deprecate usage of ``DISTINCT ON`` in dialect other than PostgreSQL.
- Deprecate old usage of string distinct in MySQL dialect
-
- .. change::
- :tags: orm, usecase
- :tickets: 5237
-
- Update :paramref:`_orm.relationship.sync_backref` flag in a relationship
- to make it implicitly ``False`` in ``viewonly=True`` relationships,
- preventing synchronization events.
-
-
- .. seealso::
-
- :ref:`change_5237_14`
-
- .. change::
- :tags: deprecated, engine
- :tickets: 4877
-
- Deprecated the behavior by which a :class:`_schema.Column` can be used as the key
- in a result set row lookup, when that :class:`_schema.Column` is not part of the
- SQL selectable that is being selected; that is, it is only matched on name.
- A deprecation warning is now emitted for this case. Various ORM use
- cases, such as those involving :func:`_expression.text` constructs, have been improved
- so that this fallback logic is avoided in most cases.
-
-
- .. change::
- :tags: change, schema
- :tickets: 5367
-
- The :paramref:`.Enum.create_constraint` and
- :paramref:`.Boolean.create_constraint` parameters now default to False,
- indicating when a so-called "non-native" version of these two datatypes is
- created, a CHECK constraint will not be generated by default. These CHECK
- constraints present schema-management maintenance complexities that should
- be opted in to, rather than being turned on by default.
-
-
- .. change::
- :tags: feature, sql
- :tickets: 4645
-
- The "expanding IN" feature, which generates IN expressions at query
- execution time which are based on the particular parameters associated with
- the statement execution, is now used for all IN expressions made against
- lists of literal values. This allows IN expressions to be fully cacheable
- independently of the list of values being passed, and also includes support
- for empty lists. For any scenario where the IN expression contains
- non-literal SQL expressions, the old behavior of pre-rendering for each
- position in the IN is maintained. The change also completes support for
- expanding IN with tuples, where previously type-specific bind processors
- weren't taking effect.
-
- .. seealso::
-
- :ref:`change_4645`
-
- .. change::
- :tags: bug, mysql
- :tickets: 4189
-
- MySQL dialect's server_version_info tuple is now all numeric. String
- tokens like "MariaDB" are no longer present so that numeric comparison
- works in all cases. The .is_mariadb flag on the dialect should be
- consulted for whether or not mariadb was detected. Additionally removed
- structures meant to support extremely old MySQL versions 3.x and 4.x;
- the minimum MySQL version supported is now version 5.0.2.
-
-
- .. change::
- :tags: engine, feature
- :tickets: 2056
-
- Added new reflection method :meth:`.Inspector.get_sequence_names` which
- returns all the sequences defined and :meth:`.Inspector.has_sequence` to
- check if a particular sequence exits.
- Support for this method has been added to the backend that support
- :class:`.Sequence`: PostgreSQL, Oracle and MariaDB >= 10.3.
-
- .. change::
- :tags: usecase, postgresql
- :tickets: 4914
-
- The maximum buffer size for the :class:`.BufferedRowResultProxy`, which
- is used by dialects such as PostgreSQL when ``stream_results=True``, can
- now be set to a number greater than 1000 and the buffer will grow to
- that size. Previously, the buffer would not go beyond 1000 even if the
- value were set larger. The growth of the buffer is also now based
- on a simple multiplying factor currently set to 5. Pull request courtesy
- Soumaya Mauthoor.
-
-
- .. change::
- :tags: bug, orm
- :tickets: 4519
-
- Accessing a collection-oriented attribute on a newly created object no
- longer mutates ``__dict__``, but still returns an empty collection as has
- always been the case. This allows collection-oriented attributes to work
- consistently in comparison to scalar attributes which return ``None``, but
- also don't mutate ``__dict__``. In order to accommodate for the collection
- being mutated, the same empty collection is returned each time once
- initially created, and when it is mutated (e.g. an item appended, added,
- etc.) it is then moved into ``__dict__``. This removes the last of
- mutating side-effects on read-only attribute access within the ORM.
-
- .. seealso::
-
- :ref:`change_4519`
-
- .. change::
- :tags: change, sql
- :tickets: 4617
-
- As part of the SQLAlchemy 2.0 migration project, a conceptual change has
- been made to the role of the :class:`_expression.SelectBase` class hierarchy,
- which is the root of all "SELECT" statement constructs, in that they no
- longer serve directly as FROM clauses, that is, they no longer subclass
- :class:`_expression.FromClause`. For end users, the change mostly means that any
- placement of a :func:`_expression.select` construct in the FROM clause of another
- :func:`_expression.select` requires first that it be wrapped in a subquery first,
- which historically is through the use of the :meth:`_expression.SelectBase.alias`
- method, and is now also available through the use of
- :meth:`_expression.SelectBase.subquery`. This was usually a requirement in any
- case since several databases don't accept unnamed SELECT subqueries
- in their FROM clause in any case.
-
- .. seealso::
-
- :ref:`change_4617`
-
- .. change::
- :tags: change, sql
- :tickets: 4617
-
- Added a new Core class :class:`.Subquery`, which takes the place of
- :class:`_expression.Alias` when creating named subqueries against a :class:`_expression.SelectBase`
- object. :class:`.Subquery` acts in the same way as :class:`_expression.Alias`
- and is produced from the :meth:`_expression.SelectBase.subquery` method; for
- ease of use and backwards compatibility, the :meth:`_expression.SelectBase.alias`
- method is synonymous with this new method.
-
- .. seealso::
-
- :ref:`change_4617`
-
- .. change::
- :tags: change, orm
- :tickets: 4617
-
- The ORM will now warn when asked to coerce a :func:`_expression.select` construct into
- a subquery implicitly. This occurs within places such as the
- :meth:`_query.Query.select_entity_from` and :meth:`_query.Query.select_from` methods
- as well as within the :func:`.with_polymorphic` function. When a
- :class:`_expression.SelectBase` (which is what's produced by :func:`_expression.select`) or
- :class:`_query.Query` object is passed directly to these functions and others,
- the ORM is typically coercing them to be a subquery by calling the
- :meth:`_expression.SelectBase.alias` method automatically (which is now superseded by
- the :meth:`_expression.SelectBase.subquery` method). See the migration notes linked
- below for further details.
-
- .. seealso::
-
- :ref:`change_4617`
-
- .. change::
- :tags: bug, sql
- :tickets: 4617
-
- The ORDER BY clause of a :class:`_selectable.CompoundSelect`, e.g. UNION, EXCEPT, etc.
- will not render the table name associated with a given column when applying
- :meth:`_selectable.CompoundSelect.order_by` in terms of a :class:`_schema.Table` - bound
- column. Most databases require that the names in the ORDER BY clause be
- expressed as label names only which are matched to names in the first
- SELECT statement. The change is related to :ticket:`4617` in that a
- previous workaround was to refer to the ``.c`` attribute of the
- :class:`_selectable.CompoundSelect` in order to get at a column that has no table
- name. As the subquery is now named, this change allows both the workaround
- to continue to work, as well as allows table-bound columns as well as the
- :attr:`_selectable.CompoundSelect.selected_columns` collections to be usable in the
- :meth:`_selectable.CompoundSelect.order_by` method.
-
- .. change::
- :tags: bug, orm
- :tickets: 5226
-
- The refresh of an expired object will now trigger an autoflush if the list
- of expired attributes include one or more attributes that were explicitly
- expired or refreshed using the :meth:`.Session.expire` or
- :meth:`.Session.refresh` methods. This is an attempt to find a middle
- ground between the normal unexpiry of attributes that can happen in many
- cases where autoflush is not desirable, vs. the case where attributes are
- being explicitly expired or refreshed and it is possible that these
- attributes depend upon other pending state within the session that needs to
- be flushed. The two methods now also gain a new flag
- :paramref:`.Session.expire.autoflush` and
- :paramref:`.Session.refresh.autoflush`, defaulting to True; when set to
- False, this will disable the autoflush that occurs on unexpire for these
- attributes.
-
- .. change::
- :tags: feature, sql
- :tickets: 5380
-
- Along with the new transparent statement caching feature introduced as part
- of :ticket:`4369`, a new feature intended to decrease the Python overhead
- of creating statements is added, allowing lambdas to be used when
- indicating arguments being passed to a statement object such as select(),
- Query(), update(), etc., as well as allowing the construction of full
- statements within lambdas in a similar manner as that of the "baked query"
- system. The rationale of using lambdas is adapted from that of the "baked
- query" approach which uses lambdas to encapsulate any amount of Python code
- into a callable that only needs to be called when the statement is first
- constructed into a string. The new feature however is more sophisticated
- in that Python literal values that would be passed as parameters are
- automatically extracted, so that there is no longer a need to use
- bindparam() objects with such queries. Use of the feature is optional and
- can be used to as small or as great a degree as is desired, while still
- allowing statements to be fully cacheable.
-
- .. seealso::
-
- :ref:`engine_lambda_caching`
-
-
- .. change::
- :tags: feature, orm
- :tickets: 5027
-
- Added support for direct mapping of Python classes that are defined using
- the Python ``dataclasses`` decorator. Pull request courtesy Václav
- Klusák. The new feature integrates into new support at the Declarative
- level for systems such as ``dataclasses`` and ``attrs``.
-
- .. seealso::
-
- :ref:`change_5027`
-
- :ref:`change_5508`
-
-
- .. change::
- :tags: change, engine
- :tickets: 4710
-
- The ``RowProxy`` class is no longer a "proxy" object, and is instead
- directly populated with the post-processed contents of the DBAPI row tuple
- upon construction. Now named :class:`.Row`, the mechanics of how the
- Python-level value processors have been simplified, particularly as it impacts the
- format of the C code, so that a DBAPI row is processed into a result tuple
- up front. The object returned by the :class:`_engine.ResultProxy` is now the
- :class:`.LegacyRow` subclass, which maintains mapping/tuple hybrid behavior,
- however the base :class:`.Row` class now behaves more fully like a named
- tuple.
-
- .. seealso::
-
- :ref:`change_4710_core`
-
-
- .. change::
- :tags: change, orm
- :tickets: 4710
-
- The "KeyedTuple" class returned by :class:`_query.Query` is now replaced with the
- Core :class:`.Row` class, which behaves in the same way as KeyedTuple.
- In SQLAlchemy 2.0, both Core and ORM will return result rows using the same
- :class:`.Row` object. In the interim, Core uses a backwards-compatibility
- class :class:`.LegacyRow` that maintains the former mapping/tuple hybrid
- behavior used by "RowProxy".
-
- .. seealso::
-
- :ref:`change_4710_orm`
-
- .. change::
- :tags: feature, orm
- :tickets: 4826
-
- Added "raiseload" feature for ORM mapped columns via :paramref:`.orm.defer.raiseload`
- parameter on :func:`.defer` and :func:`.deferred`. This provides
- similar behavior for column-expression mapped attributes as the
- :func:`.raiseload` option does for relationship mapped attributes. The
- change also includes some behavioral changes to deferred columns regarding
- expiration; see the migration notes for details.
-
- .. seealso::
-
- :ref:`change_4826`
-
-
- .. change::
- :tags: bug, orm
- :tickets: 5150
-
- The behavior of the :paramref:`_orm.relationship.cascade_backrefs` flag
- will be reversed in 2.0 and set to ``False`` unconditionally, such that
- backrefs don't cascade save-update operations from a forwards-assignment to
- a backwards assignment. A 2.0 deprecation warning is emitted when the
- parameter is left at its default of ``True`` at the point at which such a
- cascade operation actually takes place. The new behavior can be
- established as always by setting the flag to ``False`` on a specific
- :func:`_orm.relationship`, or more generally can be set up across the board
- by setting the the :paramref:`_orm.Session.future` flag to True.
-
- .. seealso::
-
- :ref:`change_5150`
-
- .. change::
- :tags: deprecated, engine
- :tickets: 4755
-
- Deprecated remaining engine-level introspection and utility methods
- including :meth:`_engine.Engine.run_callable`, :meth:`_engine.Engine.transaction`,
- :meth:`_engine.Engine.table_names`, :meth:`_engine.Engine.has_table`. The utility
- methods are superseded by modern context-manager patterns, and the table
- introspection tasks are suited by the :class:`_reflection.Inspector` object.
-
- .. change::
- :tags: removed, engine
- :tickets: 4755
-
- The internal dialect method ``Dialect.reflecttable`` has been removed. A
- review of third party dialects has not found any making use of this method,
- as it was already documented as one that should not be used by external
- dialects. Additionally, the private ``Engine._run_visitor`` method
- is also removed.
-
-
- .. change::
- :tags: removed, engine
- :tickets: 4755
-
- The long-deprecated ``Inspector.get_table_names.order_by`` parameter has
- been removed.
-
- .. change::
- :tags: feature, engine
- :tickets: 4755
-
- The :paramref:`_schema.Table.autoload_with` parameter now accepts an :class:`_reflection.Inspector` object
- directly, as well as any :class:`_engine.Engine` or :class:`_engine.Connection` as was the case before.
-
-
- .. change::
- :tags: change, performance, engine, py3k
- :tickets: 5315
-
- Disabled the "unicode returns" check that runs on dialect startup when
- running under Python 3, which for many years has occurred in order to test
- the current DBAPI's behavior for whether or not it returns Python Unicode
- or Py2K strings for the VARCHAR and NVARCHAR datatypes. The check still
- occurs by default under Python 2, however the mechanism to test the
- behavior will be removed in SQLAlchemy 2.0 when Python 2 support is also
- removed.
-
- This logic was very effective when it was needed, however now that Python 3
- is standard, all DBAPIs are expected to return Python 3 strings for
- character datatypes. In the unlikely case that a third party DBAPI does
- not support this, the conversion logic within :class:`.String` is still
- available and the third party dialect may specify this in its upfront
- dialect flags by setting the dialect level flag ``returns_unicode_strings``
- to one of :attr:`.String.RETURNS_CONDITIONAL` or
- :attr:`.String.RETURNS_BYTES`, both of which will enable Unicode conversion
- even under Python 3.
-
- .. change::
- :tags: renamed, sql
- :tickets: 5435, 5429
-
- Several operators are renamed to achieve more consistent naming across
- SQLAlchemy.
-
- The operator changes are:
-
- * ``isfalse`` is now ``is_false``
- * ``isnot_distinct_from`` is now ``is_not_distinct_from``
- * ``istrue`` is now ``is_true``
- * ``notbetween`` is now ``not_between``
- * ``notcontains`` is now ``not_contains``
- * ``notendswith`` is now ``not_endswith``
- * ``notilike`` is now ``not_ilike``
- * ``notlike`` is now ``not_like``
- * ``notmatch`` is now ``not_match``
- * ``notstartswith`` is now ``not_startswith``
- * ``nullsfirst`` is now ``nulls_first``
- * ``nullslast`` is now ``nulls_last``
- * ``isnot`` is now ``is_not``
- * ``not_in_`` is now ``not_in``
-
- Because these are core operators, the internal migration strategy for this
- change is to support legacy terms for an extended period of time -- if not
- indefinitely -- but update all documentation, tutorials, and internal usage
- to the new terms. The new terms are used to define the functions, and
- the legacy terms have been deprecated into aliases of the new terms.
-
-
-
- .. change::
- :tags: orm, deprecated
- :tickets: 5192
-
- The :func:`.eagerload` and :func:`.relation` were old aliases and are
- now deprecated. Use :func:`_orm.joinedload` and :func:`_orm.relationship`
- respectively.
-
-
- .. change::
- :tags: bug, sql
- :tickets: 4621
-
- The :class:`_expression.Join` construct no longer considers the "onclause" as a source
- of additional FROM objects to be omitted from the FROM list of an enclosing
- :class:`_expression.Select` object as standalone FROM objects. This applies to an ON
- clause that includes a reference to another FROM object outside the JOIN;
- while this is usually not correct from a SQL perspective, it's also
- incorrect for it to be omitted, and the behavioral change makes the
- :class:`_expression.Select` / :class:`_expression.Join` behave a bit more intuitively.
-
+ :include_notes_from: unreleased_14
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
