0.6 Changelog
=============
+
.. changelog::
:version: 0.6.9
:released: Sat May 05 2012
.. include:: changelog_07.rst
:start-line: 5
+
.. changelog::
:version: 0.8.7
:released: July 22, 2014
.. change::
:tags: feature, sql
- Added :paramref:`.MetaData.reflect.**dialect_kwargs`
+ Added :paramref:`.MetaData.reflect.dialect_kwargs`
to support dialect-level reflection options for all :class:`_schema.Table`
objects reflected.
:start-line: 5
-
.. changelog::
:version: 1.1.18
:released: March 6, 2018
:tickets: 3842
Fixed bug where newly added warning for primary key on insert w/o
- autoincrement setting (see :ref:`change_3216`) would fail to emit
+ autoincrement setting (see :ticket:`3216`) would fail to emit
correctly when invoked upon a lower-case :func:`.table` construct.
.. change:: 3852
:tickets: 4352
The column conflict resolution technique discussed at
- :ref:`declarative_column_conflicts` is now functional for a :class:`_schema.Column`
+ :ref:`orm_inheritance_column_conflicts` is now functional for a :class:`_schema.Column`
that is also a primary key column. Previously, a check for primary key
columns declared on a single-inheritance subclass would occur before the
column copy were allowed to pass.
:tags: usecase, postgresql
:tickets: 5265
- Added support for columns or type :class:`.ARRAY` of :class:`.Enum`,
- :class:`.JSON` or :class:`_postgresql.JSONB` in PostgreSQL.
+ Added support for columns or type :class:`_sqltypes.ARRAY` of :class:`.Enum`,
+ :class:`_postgresql.JSON` or :class:`_postgresql.JSONB` in PostgreSQL.
Previously a workaround was required in these use cases.
:tickets: 5266
Raise an explicit :class:`.exc.CompileError` when adding a table with a
- column of type :class:`.ARRAY` of :class:`.Enum` configured with
+ column of type :class:`_sqltypes.ARRAY` of :class:`.Enum` configured with
:paramref:`.Enum.native_enum` set to ``False`` when
:paramref:`.Enum.create_constraint` is not set to ``False``
:class:`_types.JSON`
- :meth:`.JSON.Comparator.as_string`
+ :meth:`_sqltypes.JSON.Comparator.as_string`
- :meth:`.JSON.Comparator.as_boolean`
+ :meth:`_sqltypes.JSON.Comparator.as_boolean`
- :meth:`.JSON.Comparator.as_float`
+ :meth:`_sqltypes.JSON.Comparator.as_float`
- :meth:`.JSON.Comparator.as_integer`
+ :meth:`_sqltypes.JSON.Comparator.as_integer`
.. change::
:tags: usecase, oracle
Added support for the parameters in an ON DUPLICATE KEY UPDATE statement on
MySQL to be ordered, since parameter order in a MySQL UPDATE clause is
significant, in a similar manner as that described at
- :ref:`updates_order_parameters`. Pull request courtesy Maxim Bublis.
+ :ref:`tutorial_parameter_ordered_updates`. Pull request courtesy Maxim Bublis.
.. seealso::
:tickets: 7936
Fixed regression where the change made for :ticket:`7861`, released in
- version 1.4.33, that brought the :class:`.Insert` construct to be partially
+ version 1.4.33, that brought the :class:`_sql.Insert` construct to be partially
recognized as an ORM-enabled statement did not properly transfer the
correct mapper / mapped table state to the :class:`.Session`, causing the
:meth:`.Session.get_bind` method to fail for a :class:`.Session` that was
:tags: bug, postgresql
:tickets: 6515
- Fixed bug in :class:`.ARRAY` datatype in combination with :class:`.Enum` on
+ Fixed bug in :class:`_sqltypes.ARRAY` datatype in combination with :class:`.Enum` on
PostgreSQL where using the ``.any()`` or ``.all()`` methods to render SQL
ANY() or ALL(), given members of the Python enumeration as arguments, would
produce a type adaptation failure on all drivers.
:tickets: 7930
Fixed an issue in the psycopg2 dialect when using the
- :paramref:`.create_engine.pool_pre_ping` parameter which would cause
+ :paramref:`_sa.create_engine.pool_pre_ping` parameter which would cause
user-configured ``AUTOCOMMIT`` isolation level to be inadvertently reset by
the "ping" handler.
:tags: bug, engine
:tickets: 7953
- Added a warning regarding a bug which exists in the :meth:`.Result.columns`
- method when passing 0 for the index in conjunction with a :class:`.Result`
+ Added a warning regarding a bug which exists in the :meth:`_result.Result.columns`
+ method when passing 0 for the index in conjunction with a :class:`_result.Result`
that will return a single ORM entity, which indicates that the current
- behavior of :meth:`.Result.columns` is broken in this case as the
- :class:`.Result` object will yield scalar values and not :class:`.Row`
+ behavior of :meth:`_result.Result.columns` is broken in this case as the
+ :class:`_result.Result` object will yield scalar values and not :class:`.Row`
objects. The issue will be fixed in 2.0, which would be a
backwards-incompatible change for code that relies on the current broken
behavior. Code which wants to receive a collection of scalar values should
- use the :meth:`.Result.scalars` method, which will return a new
+ use the :meth:`_result.Result.scalars` method, which will return a new
:class:`.ScalarResult` object that yields non-row scalar objects.
:tickets: 7878
Fixed regression caused by :ticket:`7861` where invoking an
- :class:`.Insert` construct which contained ORM entities directly via
+ :class:`_sql.Insert` construct which contained ORM entities directly via
:meth:`_orm.Session.execute` would fail.
.. change::
and COMMIT log messages do not actually indicate a real transaction when
the AUTOCOMMIT isolation level is in use; messaging has been extended to
include the BEGIN message itself, and the messaging has also been fixed to
- accommodate when the :class:`.Engine` level
- :paramref:`.create_engine.isolation_level` parameter was used directly.
+ accommodate when the :class:`_engine.Engine` level
+ :paramref:`_sa.create_engine.isolation_level` parameter was used directly.
.. change::
:tags: bug, mssql, regression
:tags: usecase, engine
:tickets: 7877, 7815
- Added new parameter :paramref:`.Engine.dispose.close`, defaulting to True.
+ Added new parameter :paramref:`_engine.Engine.dispose.close`, defaulting to True.
When False, the engine disposal does not touch the connections in the old
pool at all, simply dropping the pool and replacing it. This use case is so
that when the original pool is transferred from a parent process, the
Added new attributes :attr:`.UpdateBase.returning_column_descriptions` and
:attr:`.UpdateBase.entity_description` to allow for inspection of ORM
- attributes and entities that are installed as part of an :class:`.Insert`,
+ attributes and entities that are installed as part of an :class:`_sql.Insert`,
:class:`.Update`, or :class:`.Delete` construct. The
:attr:`.Select.column_descriptions` accessor is also now implemented for
Core-only selectables.
:tags: bug, orm
:tickets: 7128
- Fixed bug where iterating a :class:`.Result` from a :class:`_orm.Session`
+ Fixed bug where iterating a :class:`_result.Result` from a :class:`_orm.Session`
after that :class:`_orm.Session` were closed would partially attach objects
to that session in an essentially invalid state. It now raises an exception
with a link to new documentation if an **un-buffered** result is iterated
from a :class:`_orm.Session` that was closed or otherwise had the
- :meth:`_orm.Session.expunge_all` method called after that :class:`.Result`
+ :meth:`_orm.Session.expunge_all` method called after that :class:`_result.Result`
was generated. The ``prebuffer_rows`` execution option, as is used
automatically by the asyncio extension for client-side result sets, may be
- used to produce a :class:`.Result` where the ORM objects are prebuffered,
+ used to produce a :class:`_result.Result` where the ORM objects are prebuffered,
and in this case iterating the result will produce a series of detached
objects.
:tickets: 6361
Fixed issue where usage of an explicit :class:`.Sequence` would produce
- inconsistent "inline" behavior for an :class:`.Insert` construct that
+ inconsistent "inline" behavior for an :class:`_sql.Insert` construct that
includes multiple values phrases; the first seq would be inline but
subsequent ones would be "pre-execute", leading to inconsistent sequence
ordering. The sequence expressions are now fully inline.
:tags: bug, engine, sqlite
:tickets: 5845
- Fixed bug in the 2.0 "future" version of :class:`.Engine` where emitting
+ Fixed bug in the 2.0 "future" version of :class:`_engine.Engine` where emitting
SQL during the :meth:`.EngineEvents.begin` event hook would cause a
re-entrant (recursive) condition due to autobegin, affecting among other
things the recipe documented for SQLite to allow for savepoints and
changelog_render_changeset = "https://www.sqlalchemy.org/trac/changeset/%s"
-exclude_patterns = ["build", "**/unreleased*/*", "*_include.rst"]
+exclude_patterns = ["build", "**/unreleased*/*", "**/*_include.rst"]
autodoc_class_signature = "separated"
autodoc_typehints_format = "short"
Result Set API
=================
-.. autoclass:: BaseCursorResult
+.. autoclass:: ChunkedIteratorResult
:members:
-.. autoclass:: ChunkedIteratorResult
+.. autoclass:: CursorResult
:members:
+ :inherited-members:
.. autoclass:: FrozenResult
:members:
.. autoclass:: Result
:members:
:inherited-members:
- :exclude-members: memoized_attribute, memoized_instancemethod
.. autoclass:: ScalarResult
:members:
:inherited-members:
- :exclude-members: memoized_attribute, memoized_instancemethod
.. autoclass:: MappingResult
:members:
:inherited-members:
- :exclude-members: memoized_attribute, memoized_instancemethod
-
-.. autoclass:: CursorResult
- :members:
- :inherited-members:
- :exclude-members: memoized_attribute, memoized_instancemethod
.. autoclass:: Row
:members:
Constraints API
---------------
+
.. autoclass:: Constraint
:members:
:inherited-members:
.. autoclass:: BaseDDLElement
:members:
-.. autoattr:: DDLElement
-
.. autoclass:: ExecutableDDLElement
:members:
.. toctree::
:hidden:
+
+ tutorial
\ No newline at end of file
:ref:`multipart_schema_names` - describes use of dotted schema names
with the SQL Server dialect.
- :ref:`schema_table_reflection`
+ :ref:`metadata_reflection_schemas`
.. _schema_metadata_schema_name:
>>> metadata_obj = MetaData(schema="project")
-The :method:`.MetaData.reflect` will then utilize that configured ``.schema``
+The :meth:`.MetaData.reflect` will then utilize that configured ``.schema``
for reflection::
>>> # uses `schema` configured in metadata_obj
Types which are specific to SQL Server, or have SQL Server-specific
construction arguments, are as follows:
+.. note: where :noindex: is used, indicates a type that is not redefined
+ in the dialect module, just imported from sqltypes. this avoids warnings
+ in the sphinx build
+
.. currentmodule:: sqlalchemy.dialects.mssql
.. autoclass:: BIT
.. autoclass:: CHAR
:members: __init__
+ :noindex:
.. autoclass:: DATETIME2
.. autoclass:: NCHAR
:members: __init__
+ :noindex:
.. autoclass:: NTEXT
.. autoclass:: NVARCHAR
:members: __init__
-
+ :noindex:
.. autoclass:: REAL
:members: __init__
.. autoclass:: TEXT
:members: __init__
-
+ :noindex:
.. autoclass:: TIME
:members: __init__
.. autoclass:: VARBINARY
:members: __init__
+ :noindex:
.. autoclass:: VARCHAR
:members: __init__
+ :noindex:
.. autoclass:: XML
Types which are specific to MySQL, or have MySQL-specific
construction arguments, are as follows:
+.. note: where :noindex: is used, indicates a type that is not redefined
+ in the dialect module, just imported from sqltypes. this avoids warnings
+ in the sphinx build
+
.. currentmodule:: sqlalchemy.dialects.mysql
.. autoclass:: BIGINT
.. autoclass:: BINARY
+ :noindex:
:members: __init__
.. autoclass:: BLOB
:members: __init__
+ :noindex:
.. autoclass:: BOOLEAN
:members: __init__
+ :noindex:
.. autoclass:: CHAR
.. autoclass:: DATE
:members: __init__
+ :noindex:
.. autoclass:: DATETIME
.. autoclass:: TEXT
:members: __init__
+ :noindex:
.. autoclass:: TIME
.. autoclass:: VARBINARY
:members: __init__
+ :noindex:
.. autoclass:: VARCHAR
Types which are specific to PostgreSQL, or have PostgreSQL-specific
construction arguments, are as follows:
+.. note: where :noindex: is used, indicates a type that is not redefined
+ in the dialect module, just imported from sqltypes. this avoids warnings
+ in the sphinx build
+
.. currentmodule:: sqlalchemy.dialects.postgresql
.. autoclass:: aggregate_order_by
.. autoclass:: REAL
:members: __init__
+ :noindex:
.. autoclass:: REGCLASS
:ref:`migration_20_toplevel`
+
+ imperative
+ declarative
+
+ In the SQLAlchemy ORM, these terms refer to two different styles of
+ mapping Python classes to database tables.
+
+ .. seealso::
+
+ :ref:`orm_declarative_mapping`
+
+ :ref:`orm_imperative_mapping`
+
facade
An object that serves as a front-facing interface masking more complex
:ref:`session_object_states`
+ attached
+ Indicates an ORM object that is presently associated with a specific
+ :term:`Session`.
+
+ .. seealso::
+
+ :ref:`session_object_states`
+
* :doc:`Error Message Guide <errors>` - Explainations of many SQLAlchemy Errors
* :doc:`Complete table of of contents <contents>`
* :doc:`Index <index>`
+
.. autofunction:: bulk_replace
-.. autoclass:: collection
-
.. autodata:: collection_adapter
.. autoclass:: CollectionAdapter
.. warning::
The :class:`.scoped_session` registry by default uses a Python
- `threading.local() <https://docs.python.org/3/library/threading.html#thread-local-data>`_
+ ``threading.local()``
in order to track :class:`_orm.Session` instances. **This is not
necessarily compatible with all application servers**, particularly those
which make use of greenlets or other alternative forms of concurrency
:members:
:inherited-members:
-.. autodata:: ASSOCIATION_PROXY
+.. autoclass:: AssociationProxyExtensionType
:members:
.. autoclass:: Comparator
-
-.. autodata:: HYBRID_METHOD
-.. autodata:: HYBRID_PROPERTY
+.. autoclass:: HybridExtensionType
.. autoclass:: ClassManager
:members:
- :inherited-members:
.. autoclass:: ColumnProperty
:members:
---------------------------------------------
As described in the section :ref:`orm_declarative_dataclasses`, the
-``@dataclass`` decorator and the attrs_ library both work as class
+``@dataclass`` decorator and the ``attrs`` library both work as class
decorators that are applied to a class first, before it is passed to
SQLAlchemy for mapping. Just like we can use the
:meth:`_orm.registry.mapped` decorator in order to apply declarative-style
Inspecting entities and columns from ORM-enabled SELECT and DML statements
==========================================================================
-The :func:`.select` construct, as well as the :func:`.insert`, :func:`.update`
-and :func:`.delete` constructs (for the latter DML constructs, as of SQLAlchemy
+The :func:`_sql.select` construct, as well as the :func:`_sql.insert`, :func:`_sql.update`
+and :func:`_sql.delete` constructs (for the latter DML constructs, as of SQLAlchemy
1.4.33), all support the ability to inspect the entities in which these
statements are created against, as well as the columns and datatypes that would
be returned in a result set.
this would raise ``NotImplementedError``.
-For :func:`.insert`, :func:`.update` and :func:`.delete` constructs, there are
+For :func:`_sql.insert`, :func:`.update` and :func:`.delete` constructs, there are
two separate attributes. One is :attr:`.UpdateBase.entity_description` which
returns information about the primary ORM entity and database table which the
DML construct would be affecting::
SET address.email_address=%s, user_account.fullname=%s
WHERE user_account.id = address.user_id AND address.email_address = %s
+.. _tutorial_parameter_ordered_updates:
Parameter Ordered Updates
~~~~~~~~~~~~~~~~~~~~~~~~~~
>>> sqlalchemy.__version__ # doctest: +SKIP
2.0.0
-.. rst-class:: core-header, orm-dependency
-
attribute set up.
The PostgreSQL dialect can reflect tables from any schema, as outlined in
-:ref:`schema_table_reflection`.
+:ref:`metadata_reflection_schemas`.
With regards to tables which these :class:`_schema.Table`
objects refer to via foreign key constraint, a decision must be made as to how
class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
"""Provides high-level functionality for a wrapped DB-API connection.
- The :class:`_engine.Connection` object is procured by calling
- the :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
+ The :class:`_engine.Connection` object is procured by calling the
+ :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
object, and provides services for execution of SQL statements as well
as transaction control.
- The Connection object is **not** thread-safe. While a Connection can be
+ The Connection object is **not** thread-safe. While a Connection can be
shared among threads using properly synchronized access, it is still
possible that the underlying DBAPI connection may not support shared
- access between threads. Check the DBAPI documentation for details.
+ access between threads. Check the DBAPI documentation for details.
The Connection object represents a single DBAPI connection checked out
- from the connection pool. In this state, the connection pool has no affect
- upon the connection, including its expiration or timeout state. For the
- connection pool to properly manage connections, connections should be
- returned to the connection pool (i.e. ``connection.close()``) whenever the
- connection is not in use.
+ from the connection pool. In this state, the connection pool has no
+ affect upon the connection, including its expiration or timeout state.
+ For the connection pool to properly manage connections, connections
+ should be returned to the connection pool (i.e. ``connection.close()``)
+ whenever the connection is not in use.
.. index::
single: thread safety; Connection
@property
def engine(self) -> Engine:
+ """Returns this :class:`.Engine`.
+
+ Used for legacy schemes that accept :class:`.Connection` /
+ :class:`.Engine` objects within the same variable.
+
+ """
return self
def clear_compiled_cache(self) -> None:
# mypy: allow-untyped-defs, allow-untyped-calls
"""Define cursor-specific result set constructs including
-:class:`.BaseCursorResult`, :class:`.CursorResult`."""
+:class:`.CursorResult`."""
from __future__ import annotations
This method may also be used to establish execution options for the
database connection used by the current transaction.
- .. versionadded:: 1.4.24 Added **kw arguments which are passed through
- to the underlying :meth:`_orm.Session.connection` method.
+ .. versionadded:: 1.4.24 Added \**kw arguments which are passed
+ through to the underlying :meth:`_orm.Session.connection` method.
.. seealso::
from .sql.schema import FetchedValue as FetchedValue
from .sql.schema import ForeignKey as ForeignKey
from .sql.schema import ForeignKeyConstraint as ForeignKeyConstraint
+from .sql.schema import HasConditionalDDL as HasConditionalDDL
from .sql.schema import Identity as Identity
from .sql.schema import Index as Index
from .sql.schema import MetaData as MetaData
from .sql.schema import PrimaryKeyConstraint as PrimaryKeyConstraint
+from .sql.schema import SchemaConst as SchemaConst
from .sql.schema import SchemaItem as SchemaItem
from .sql.schema import Sequence as Sequence
from .sql.schema import Table as Table
value automatically for this column, which will be accessible
after the statement is invoked via the
:attr:`.CursorResult.inserted_primary_key` attribute upon the
- :class:`.Result` object. This also applies towards use of the
+ :class:`_result.Result` object. This also applies towards use of the
ORM when ORM-mapped objects are persisted to the database,
indicating that a new integer primary key will be available to
become part of the :term:`identity key` for that object. This
Column('id', ForeignKey('other.id'),
primary_key=True, autoincrement='ignore_fk')
- It is typically not desirable to have "autoincrement" enabled on a
- column that refers to another via foreign key, as such a column is
- required to refer to a value that originates from elsewhere.
+ It is typically not desirable to have "autoincrement" enabled on a
+ column that refers to another via foreign key, as such a column is
+ required to refer to a value that originates from elsewhere.
The setting has these effects on columns that meet the
above criteria:
using a method specific to the database driver in use:
* MySQL, SQLite - calling upon ``cursor.lastrowid()``
- (see
- `https://www.python.org/dev/peps/pep-0249/#lastrowid
- <https://www.python.org/dev/peps/pep-0249/#lastrowid>`_)
+ (see
+ `https://www.python.org/dev/peps/pep-0249/#lastrowid
+ <https://www.python.org/dev/peps/pep-0249/#lastrowid>`_)
* PostgreSQL, SQL Server, Oracle - use RETURNING or an equivalent
construct when rendering an INSERT statement, and then retrieving
the newly generated primary key values after execution
"fast insertmany" feature. Such features are very new and
may not yet be well covered in documentation.
-
:param default: A scalar, Python callable, or
:class:`_expression.ColumnElement` expression representing the
*default value* for this column, which will be invoked upon insert
Below, all column names are given a label so that the two same-named
columns ``columna`` are disambiguated as ``table1_columna`` and
- ``table2_columna`::
+ ``table2_columna``::
>>> from sqlalchemy import table, column, select, true, LABEL_STYLE_TABLENAME_PLUS_COL
>>> table1 = table("table1", column("columna"), column("columnb"))
self._memoized_keys |= {key}
class memoized_attribute(memoized_property[_T]):
- """A read-only @property that is only evaluated once."""
+ """A read-only @property that is only evaluated once.
+
+ :meta private:
+
+ """
fget: Callable[..., _T]
__doc__: Optional[str]
@classmethod
def memoized_instancemethod(cls, fn: _F) -> _F:
- """Decorate a method memoize its return value."""
+ """Decorate a method memoize its return value.
+
+ :meta private:
+
+ """
def oneshot(self: Any, *args: Any, **kw: Any) -> Any:
result = fn(self, *args, **kw)
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
