:tags: bug, engine
:tickets: 7291
- Fixed issue in future :class:`_future.Connection` object where the
- :meth:`_future.Connection.execute` method would not accept a non-dict
+ Fixed issue in future :class:`_engine.Connection` object where the
+ :meth:`_engine.Connection.execute` method would not accept a non-dict
mapping object, such as SQLAlchemy's own :class:`.RowMapping` or other
``abc.collections.Mapping`` object as a parameter dictionary.
:tickets: 7272
:versions: 2.0.0b1
- Fixed issue in future :class:`_future.Engine` where calling upon
- :meth:`_future.Engine.begin` and entering the context manager would not
+ Fixed issue in future :class:`_engine.Engine` where calling upon
+ :meth:`_engine.Engine.begin` and entering the context manager would not
close the connection if the actual BEGIN operation failed for some reason,
such as an event handler raising an exception; this use case failed to be
tested for the future version of the engine. Note that the "future" context
autobegin a transaction but not commit it, which is a behavioral change.
When using a :term:`2.0 style` connection object, the behavior is unchanged
- from previous 1.4 versions; calling :meth:`_future.Connection.begin_nested`
+ from previous 1.4 versions; calling :meth:`_engine.Connection.begin_nested`
will "autobegin" the outer transaction if not already present, and then as
instructed emit a SAVEPOINT, returning the :class:`.NestedTransaction`
object. The outer transaction is committed by calling upon
- :meth:`_future.Connection.commit`, as is "commit-as-you-go" style usage.
+ :meth:`_engine.Connection.commit`, as is "commit-as-you-go" style usage.
In non-"future" mode, while the old behavior is restored, it also
emits a 2.0 deprecation warning as this is a legacy behavior.
by passing the flag ``future=True`` to the :func:`_sa.create_engine`
function.
-When the :paramref:`_sa.create_engine.future` flag is used, the :class:`_future.Engine`
-and :class:`_future.Connection` objects support the 2.0 API fully and not at all
-any legacy features, including the new argument format for :meth:`_future.Connection.execute`,
+When the :paramref:`_sa.create_engine.future` flag is used, the :class:`_engine.Engine`
+and :class:`_engine.Connection` objects support the 2.0 API fully and not at all
+any legacy features, including the new argument format for :meth:`_engine.Connection.execute`,
the removal of "implicit autocommit", string statements require the
-:func:`_sql.text` construct unless the :meth:`_future.Connection.exec_driver_sql`
-method is used, and connectionless execution from the :class:`_future.Engine`
+:func:`_sql.text` construct unless the :meth:`_engine.Connection.exec_driver_sql`
+method is used, and connectionless execution from the :class:`_engine.Engine`
is removed.
If all :class:`_exc.RemovedIn20Warning` warnings have been resolved regarding
:paramref:`_sa.create_engine.future` flag may be enabled and there should be
no errors raised.
-The new engine is described at :class:`_future.Engine` which delivers a new
-:class:`_future.Connection` object. In addition to the above changes, the,
-:class:`_future.Connection` object features
-:meth:`_future.Connection.commit` and
-:meth:`_future.Connection.rollback` methods, to support the new
+The new engine is described at :class:`_engine.Engine` which delivers a new
+:class:`_engine.Connection` object. In addition to the above changes, the,
+:class:`_engine.Connection` object features
+:meth:`_engine.Connection.commit` and
+:meth:`_engine.Connection.rollback` methods, to support the new
"commit-as-you-go" mode of operation::
When using :term:`2.0 style` with the :paramref:`_sa.create_engine.future`
flag, "commit as you go" style may also be used, as the
-:class:`_future.Connection` features **autobegin** behavior, which takes place
+:class:`_engine.Connection` features **autobegin** behavior, which takes place
when a statement is first invoked in the absence of an explicit call to
-:meth:`_future.Connection.begin`::
+:meth:`_engine.Connection.begin`::
with engine.connect() as conn:
conn.execute(some_table.insert().values(foo="bar"))
For "commit as you go, or rollback instead" usage, which resembles how the
:class:`_orm.Session` is normally used today, the "future" version of
-:class:`_future.Connection`, which is the one that is returned from an
-:class:`_future.Engine` that was created using the
+:class:`_engine.Connection`, which is the one that is returned from an
+:class:`_engine.Engine` that was created using the
:paramref:`_sa.create_engine.future` flag, includes new
-:meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback`
+:meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback`
methods, which act upon a transaction that is now begun automatically when
a statement is first invoked::
features **autobegin**, meaning the ``begin()`` event is emitted when the
execute method is first used (note however that there is no actual "BEGIN" in
the Python DBAPI). "autobegin" is a new pattern in SQLAlchemy 1.4 that
-is featured both by :class:`_future.Connection` as well as the ORM
-:class:`_orm.Session` object; autobegin allows that the :meth:`_future.Connection.begin`
+is featured both by :class:`_engine.Connection` as well as the ORM
+:class:`_orm.Session` object; autobegin allows that the :meth:`_engine.Connection.begin`
method may be called explicitly when the object is first acquired, for schemes
that wish to demarcate the beginning of the transaction, but if the method
is not called, then it occurs implicitly when work is first done on the object.
discussed at :ref:`dbapi_autocommit`. True autocommit is treated as an "isolation level"
so that the structure of application code does not change when autocommit is
used; the :meth:`_engine.Connection.begin` context manager as well as
-methods like :meth:`_future.Connection.commit` may still be used, they are
+methods like :meth:`_engine.Connection.commit` may still be used, they are
simply no-ops at the database driver level when DBAPI-level autocommit
is turned on.
The argument patterns that may be used with the :meth:`_engine.Connection`
execute method in SQLAlchemy 2.0 are highly simplified, removing many previously
available argument patterns. The new API in the 1.4 series is described at
-:meth:`_future.Connection`. The examples below illustrate the patterns that
+:meth:`_engine.Connection`. The examples below illustrate the patterns that
require modification::
**Migration to 2.0**
-The new :meth:`_future.Connection.execute` method now accepts a subset of the
+The new :meth:`_engine.Connection.execute` method now accepts a subset of the
argument styles that are accepted by the 1.x :meth:`_engine.Connection.execute`
method, so the following code is cross-compatible between 1.x and 2.0::
The use of ``*args`` and ``**kwargs`` has been removed both to remove the
complexity of guessing what kind of arguments were passed to the method, as
well as to make room for other options, namely the
-:paramref:`_future.Connection.execute.execution_options` dictionary that is now
+:paramref:`_engine.Connection.execute.execution_options` dictionary that is now
available to provide options on a per statement basis. The method is also
modified so that its use pattern matches that of the
:meth:`_orm.Session.execute` method, which is a much more prominent API in 2.0
When using future mode, there should be equivalent semantics between
the two packages, at the level of the :class:`_orm.sessionmaker` vs.
-the :class:`_future.Engine`, as well as the :class:`_orm.Session` vs.
-the :class:`_future.Connection`. The following sections detail
+the :class:`_engine.Engine`, as well as the :class:`_orm.Session` vs.
+the :class:`_engine.Connection`. The following sections detail
these scenarios based on the following scheme::
Commit as you go
~~~~~~~~~~~~~~~~
-Both :class:`_orm.Session` and :class:`_future.Connection` feature
-:meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback`
+Both :class:`_orm.Session` and :class:`_engine.Connection` feature
+:meth:`_engine.Connection.commit` and :meth:`_engine.Connection.rollback`
methods. Using SQLAlchemy 2.0-style operation, these methods affect the
**outermost** transaction in all cases.
Begin Once
~~~~~~~~~~
-Both :class:`_orm.sessionmaker` and :class:`_future.Engine` feature a
-:meth:`_future.Engine.begin` method that will both procure a new object
+Both :class:`_orm.sessionmaker` and :class:`_engine.Engine` feature a
+:meth:`_engine.Engine.begin` method that will both procure a new object
with which to execute SQL statements (the :class:`_orm.Session` and
-:class:`_future.Connection`, respectively) and then return a context manager
+:class:`_engine.Connection`, respectively) and then return a context manager
that will maintain a begin/commit/rollback context for that object.
Engine::
When using a SAVEPOINT via the :meth:`_orm.Session.begin_nested` or
:meth:`_engine.Connection.begin_nested` methods, the transaction object
returned must be used to commit or rollback the SAVEPOINT. Calling
-the :meth:`_orm.Session.commit` or :meth:`_future.Connection.commit` methods
+the :meth:`_orm.Session.commit` or :meth:`_engine.Connection.commit` methods
will always commit the **outermost** transaction; this is a SQLAlchemy 2.0
specific behavior that is reversed from the 1.x series.
one statement and insertion of SQL expressions. However the usual way that
:class:`_sql.Insert` is used is such that the VALUES clause is generated
automatically from the parameters passed to the
-:meth:`_future.Connection.execute` method; below we INSERT two more rows to
+:meth:`_engine.Connection.execute` method; below we INSERT two more rows to
illustrate this:
.. sourcecode:: pycon+sql
The execution above features "executemany" form first illustrated at
:ref:`tutorial_multiple_parameters`, however unlike when using the
:func:`_sql.text` construct, we didn't have to spell out any SQL.
-By passing a dictionary or list of dictionaries to the :meth:`_future.Connection.execute`
+By passing a dictionary or list of dictionaries to the :meth:`_engine.Connection.execute`
method in conjunction with the :class:`_sql.Insert` construct, the
-:class:`_future.Connection` ensures that the column names which are passed
+:class:`_engine.Connection` ensures that the column names which are passed
will be expressed in the VALUES clause of the :class:`_sql.Insert`
construct automatically.
For both Core and ORM, the :func:`_sql.select` function generates a
:class:`_sql.Select` construct which is used for all SELECT queries.
-Passed to methods like :meth:`_future.Connection.execute` in Core and
+Passed to methods like :meth:`_engine.Connection.execute` in Core and
:meth:`_orm.Session.execute` in ORM, a SELECT statement is emitted in the
current transaction and the result rows available via the returned
:class:`_engine.Result` object.
-With the :class:`_future.Engine` object ready to go, we may now proceed
-to dive into the basic operation of an :class:`_future.Engine` and
-its primary interactive endpoints, the :class:`_future.Connection` and
+With the :class:`_engine.Engine` object ready to go, we may now proceed
+to dive into the basic operation of an :class:`_engine.Engine` and
+its primary interactive endpoints, the :class:`_engine.Connection` and
:class:`_engine.Result`. We will additionally introduce the ORM's
:term:`facade` for these objects, known as the :class:`_orm.Session`.
**Note to ORM readers**
- When using the ORM, the :class:`_future.Engine` is managed by another
+ When using the ORM, the :class:`_engine.Engine` is managed by another
object called the :class:`_orm.Session`. The :class:`_orm.Session` in
modern SQLAlchemy emphasizes a transactional and SQL execution pattern that
- is largely identical to that of the :class:`_future.Connection` discussed
+ is largely identical to that of the :class:`_engine.Connection` discussed
below, so while this subsection is Core-centric, all of the concepts here
are essentially relevant to ORM use as well and is recommended for all ORM
- learners. The execution pattern used by the :class:`_future.Connection`
+ learners. The execution pattern used by the :class:`_engine.Connection`
will be contrasted with that of the :class:`_orm.Session` at the end
of this section.
Getting a Connection
---------------------
-The sole purpose of the :class:`_future.Engine` object from a user-facing
+The sole purpose of the :class:`_engine.Engine` object from a user-facing
perspective is to provide a unit of
-connectivity to the database called the :class:`_future.Connection`. When
-working with the Core directly, the :class:`_future.Connection` object
-is how all interaction with the database is done. As the :class:`_future.Connection`
+connectivity to the database called the :class:`_engine.Connection`. When
+working with the Core directly, the :class:`_engine.Connection` object
+is how all interaction with the database is done. As the :class:`_engine.Connection`
represents an open resource against the database, we want to always limit
the scope of our use of this object to a specific context, and the best
way to do that is by using Python context manager form, also known as
the Python DBAPI includes that a transaction is always in progress; when the
scope of the connection is :term:`released`, a ROLLBACK is emitted to end the
transaction. The transaction is **not committed automatically**; when we want
-to commit data we normally need to call :meth:`_future.Connection.commit`
+to commit data we normally need to call :meth:`_engine.Connection.commit`
as we'll see in the next section.
.. tip:: "autocommit" mode is available for special cases. The section
We just learned that the DBAPI connection is non-autocommitting. What if
we want to commit some data? We can alter our above example to create a
table and insert some data, and the transaction is then committed using
-the :meth:`_future.Connection.commit` method, invoked **inside** the block
-where we acquired the :class:`_future.Connection` object:
+the :meth:`_engine.Connection.commit` method, invoked **inside** the block
+where we acquired the :class:`_engine.Connection` object:
.. sourcecode:: pycon+sql
(the parameterization syntax above is discussed a few sections below in
:ref:`tutorial_multiple_parameters`). As we want the work we've done to be
committed within our block, we invoke the
-:meth:`_future.Connection.commit` method which commits the transaction. After
+:meth:`_engine.Connection.commit` method which commits the transaction. After
we call this method inside the block, we can continue to run more SQL
-statements and if we choose we may call :meth:`_future.Connection.commit`
+statements and if we choose we may call :meth:`_engine.Connection.commit`
again for subsequent statements. SQLAlchemy refers to this style as **commit as
you go**.
There is also another style of committing data, which is that we can declare
our "connect" block to be a transaction block up front. For this mode of
-operation, we use the :meth:`_future.Engine.begin` method to acquire the
-connection, rather than the :meth:`_future.Engine.connect` method. This method
-will both manage the scope of the :class:`_future.Connection` and also
+operation, we use the :meth:`_engine.Engine.begin` method to acquire the
+connection, rather than the :meth:`_engine.Engine.connect` method. This method
+will both manage the scope of the :class:`_engine.Connection` and also
enclose everything inside of a transaction with COMMIT at the end, assuming
a successful block, or ROLLBACK in case of exception raise. This style
may be referred towards as **begin once**:
-----------------------------
We have seen a few examples that run SQL statements against a database, making
-use of a method called :meth:`_future.Connection.execute`, in conjunction with
+use of a method called :meth:`_engine.Connection.execute`, in conjunction with
an object called :func:`_sql.text`, and returning an object called
:class:`_engine.Result`. In this section we'll illustrate more closely the
mechanics and interactions of these components.
Most of the content in this section applies equally well to modern ORM
use when using the :meth:`_orm.Session.execute` method, which works
- very similarly to that of :meth:`_future.Connection.execute`, including that
+ very similarly to that of :meth:`_engine.Connection.execute`, including that
ORM result rows are delivered using the same :class:`_engine.Result`
interface used by Core.
SQL statements are usually accompanied by data that is to be passed with the
statement itself, as we saw in the INSERT example previously. The
-:meth:`_future.Connection.execute` method therefore also accepts parameters,
+:meth:`_engine.Connection.execute` method therefore also accepts parameters,
which are referred towards as :term:`bound parameters`. A rudimentary example
might be if we wanted to limit our SELECT statement only to rows that meet a
certain criteria, such as rows where the "y" value were greater than a certain
our statement that names a new parameter called "y"; the :func:`_sql.text`
construct accepts these using a colon format "``:y``". The actual value for
"``:y``" is then passed as the second argument to
-:meth:`_future.Connection.execute` in the form of a dictionary:
+:meth:`_engine.Connection.execute` in the form of a dictionary:
.. sourcecode:: pycon+sql
database at once. For statements that **operate upon data, but do not return
result sets**, namely :term:`DML` statements such as "INSERT" which don't
include a phrase like "RETURNING", we can send **multi params** to the
-:meth:`_future.Connection.execute` method by passing a list of dictionaries
+:meth:`_engine.Connection.execute` method by passing a list of dictionaries
instead of a single dictionary, thus allowing the single SQL statement to
be invoked against each parameter set individually:
<sqlalchemy.engine.cursor.CursorResult object at 0x...>
COMMIT
-Behind the scenes, the :class:`_future.Connection` objects uses a DBAPI feature
+Behind the scenes, the :class:`_engine.Connection` objects uses a DBAPI feature
known as `cursor.executemany()
<https://www.python.org/dev/peps/pep-0249/#id18>`_. This method performs the
equivalent operation of invoking the given SQL statement against each parameter
The fundamental transactional / database interactive object when using the
ORM is called the :class:`_orm.Session`. In modern SQLAlchemy, this object
-is used in a manner very similar to that of the :class:`_future.Connection`,
+is used in a manner very similar to that of the :class:`_engine.Connection`,
and in fact as the :class:`_orm.Session` is used, it refers to a
-:class:`_future.Connection` internally which it uses to emit SQL.
+:class:`_engine.Connection` internally which it uses to emit SQL.
When the :class:`_orm.Session` is used with non-ORM constructs, it
passes through the SQL statements we give it and does not generally do things
-much differently from how the :class:`_future.Connection` does directly, so
+much differently from how the :class:`_engine.Connection` does directly, so
we can illustrate it here in terms of the simple textual SQL
operations we've already learned.
The :class:`_orm.Session` has a few different creational patterns, but
here we will illustrate the most basic one that tracks exactly with how
-the :class:`_future.Connection` is used which is to construct it within
+the :class:`_engine.Connection` is used which is to construct it within
a context manager:
.. sourcecode:: pycon+sql
in :ref:`tutorial_sending_parameters` - we directly replace the call to
``with engine.connect() as conn`` with ``with Session(engine) as session``,
and then make use of the :meth:`_orm.Session.execute` method just like we
-do with the :meth:`_future.Connection.execute` method.
+do with the :meth:`_engine.Connection.execute` method.
-Also, like the :class:`_future.Connection`, the :class:`_orm.Session` features
+Also, like the :class:`_engine.Connection`, the :class:`_orm.Session` features
"commit as you go" behavior using the :meth:`_orm.Session.commit` method,
illustrated below using a textual UPDATE statement to alter some of
our data:
the block with a "commit as you go" commit.
.. tip:: The :class:`_orm.Session` doesn't actually hold onto the
- :class:`_future.Connection` object after it ends the transaction. It
- gets a new :class:`_future.Connection` from the :class:`_future.Engine`
+ :class:`_engine.Connection` object after it ends the transaction. It
+ gets a new :class:`_engine.Connection` from the :class:`_engine.Engine`
when executing SQL against the database is next needed.
The :class:`_orm.Session` obviously has a lot more tricks up its sleeve
than that, however understanding that it has a :meth:`_orm.Session.execute`
-method that's used the same way as :meth:`_future.Connection.execute` will
+method that's used the same way as :meth:`_engine.Connection.execute` will
get us started with the examples that follow later.
.. seealso::
The start of any SQLAlchemy application is an object called the
-:class:`_future.Engine`. This object acts as a central source of connections
+:class:`_engine.Engine`. This object acts as a central source of connections
to a particular database, providing both a factory as well as a holding
space called a :ref:`connection pool <pooling_toplevel>` for these database
connections. The engine is typically a global object created just
For this tutorial we will use an in-memory-only SQLite database. This is an
easy way to test things without needing to have an actual pre-existing database
-set up. The :class:`_future.Engine` is created by using :func:`_sa.create_engine`, specifying
+set up. The :class:`_engine.Engine` is created by using :func:`_sa.create_engine`, specifying
the :paramref:`_sa.create_engine.future` flag set to ``True`` so that we make full use
of :term:`2.0 style` usage:
The main argument to :class:`_sa.create_engine`
is a string URL, above passed as the string ``"sqlite+pysqlite:///:memory:"``.
-This string indicates to the :class:`_future.Engine` three important
+This string indicates to the :class:`_engine.Engine` three important
facts:
1. What kind of database are we communicating with? This is the ``sqlite``
.. sidebar:: Lazy Connecting
- The :class:`_future.Engine`, when first returned by :func:`_sa.create_engine`,
+ The :class:`_engine.Engine`, when first returned by :func:`_sa.create_engine`,
has not actually tried to connect to the database yet; that happens
only the first time it is asked to perform a task against the database.
This is a software design pattern known as :term:`lazy initialization`.
We have also specified a parameter :paramref:`_sa.create_engine.echo`, which
-will instruct the :class:`_future.Engine` to log all of the SQL it emits to a
+will instruct the :class:`_engine.Engine` to log all of the SQL it emits to a
Python logger that will write to standard out. This flag is a shorthand way
of setting up
:ref:`Python logging more formally <dbengine_logging>` and is useful for
and query data from them. We have already all the tools needed to do so, by
invoking the
:meth:`_schema.MetaData.create_all` method on our :class:`_schema.MetaData`,
-sending it the :class:`_future.Engine` that refers to the target database:
+sending it the :class:`_engine.Engine` that refers to the target database:
.. sourcecode:: pycon+sql
:class:`_schema.Table` object, given the name of the table and a
:class:`_schema.MetaData` collection to which it will belong, then
instead of indicating individual :class:`_schema.Column` and
-:class:`_schema.Constraint` objects, pass it the target :class:`_future.Engine`
+:class:`_schema.Constraint` objects, pass it the target :class:`_engine.Engine`
using the :paramref:`_schema.Table.autoload_with` parameter:
.. sourcecode:: pycon+sql
accessible via the :attr:`_engine.Connection.get_transaction` method of
:class:`_engine.Connection`.
- In :term:`2.0 style` use, the :class:`_future.Connection` also employs
+ In :term:`2.0 style` use, the :class:`_engine.Connection` also employs
"autobegin" behavior that will create a new
:class:`_engine.RootTransaction` whenever a connection in a
non-transactional state is used to emit commands on the DBAPI connection.
The scope of the :class:`_engine.RootTransaction` in 2.0 style
- use can be controlled using the :meth:`_future.Connection.commit` and
- :meth:`_future.Connection.rollback` methods.
+ use can be controlled using the :meth:`_engine.Connection.commit` and
+ :meth:`_engine.Connection.rollback` methods.
"""
This is the **SQLAlchemy 1.x version** of :class:`_engine.Engine`. For
the :term:`2.0 style` version, which includes some API differences,
- see :class:`_future.Engine`.
+ see :class:`_engine.Engine`.
An :class:`_engine.Engine` object is instantiated publicly using the
:func:`~sqlalchemy.create_engine` function.
This returns this :class:`_asyncio.AsyncConnection` object with
the new options added.
- See :meth:`_future.Connection.execution_options` for full details
+ See :meth:`_engine.Connection.execution_options` for full details
on this method.
"""
If no transaction was started, the method has no effect, assuming
the connection is in a non-invalidated state.
- A transaction is begun on a :class:`_future.Connection` automatically
+ A transaction is begun on a :class:`_engine.Connection` automatically
whenever a statement is first executed, or when the
- :meth:`_future.Connection.begin` method is called.
+ :meth:`_engine.Connection.begin` method is called.
"""
await greenlet_spawn(self._proxied.commit)
transaction was started and the connection is in an invalidated state,
the transaction is cleared using this method.
- A transaction is begun on a :class:`_future.Connection` automatically
+ A transaction is begun on a :class:`_engine.Connection` automatically
whenever a statement is first executed, or when the
- :meth:`_future.Connection.begin` method is called.
+ :meth:`_engine.Connection.begin` method is called.
"""
:param execution_options: optional dictionary of execution options,
which will be associated with the statement execution. This
dictionary can provide a subset of the options that are accepted
- by :meth:`_future.Connection.execution_options`.
+ by :meth:`_engine.Connection.execution_options`.
:return: a :class:`_engine.Result` object.
This method is shorthand for invoking the
:meth:`_engine.Result.scalar` method after invoking the
- :meth:`_future.Connection.execute` method. Parameters are equivalent.
+ :meth:`_engine.Connection.execute` method. Parameters are equivalent.
:return: a scalar Python value representing the first column of the
first row returned.
This method is shorthand for invoking the
:meth:`_engine.Result.scalars` method after invoking the
- :meth:`_future.Connection.execute` method. Parameters are equivalent.
+ :meth:`_engine.Connection.execute` method. Parameters are equivalent.
:return: a :class:`_engine.ScalarResult` object.
This method is shorthand for invoking the
:meth:`_engine.AsyncResult.scalars` method after invoking the
- :meth:`_future.Connection.stream` method. Parameters are equivalent.
+ :meth:`_engine.Connection.stream` method. Parameters are equivalent.
:return: an :class:`_asyncio.AsyncScalarResult` object.
:class:`_asyncio.AsyncConnection` objects with the given execution
options.
- Proxied from :meth:`_future.Engine.execution_options`. See that
+ Proxied from :meth:`_engine.Engine.execution_options`. See that
method for details.
"""
return self._proxied.__iter__()
def add(self, instance: object, _warn: bool = True) -> None:
- r"""Place an object in the ``Session``.
+ r"""Place an object into this :class:`_orm.Session`.
.. container:: class_bases
Proxied for the :class:`_orm.Session` class on
behalf of the :class:`_asyncio.AsyncSession` class.
- Its state will be persisted to the database on the next flush
- operation.
+ Objects that are in the :term:`transient` state when passed to the
+ :meth:`_orm.Session.add` method will move to the
+ :term:`pending` state, until the next flush, at which point they
+ will move to the :term:`persistent` state.
- Repeated calls to ``add()`` will be ignored. The opposite of ``add()``
- is ``expunge()``.
+ Objects that are in the :term:`detached` state when passed to the
+ :meth:`_orm.Session.add` method will move to the :term:`persistent`
+ state directly.
+
+ If the transaction used by the :class:`_orm.Session` is rolled back,
+ objects which were transient when they were passed to
+ :meth:`_orm.Session.add` will be moved back to the
+ :term:`transient` state, and will no longer be present within this
+ :class:`_orm.Session`.
+
+ .. seealso::
+
+ :meth:`_orm.Session.add_all`
+
+ :ref:`session_adding` - at :ref:`session_basics`
return self._proxied.add(instance, _warn=_warn)
def add_all(self, instances: Iterable[object]) -> None:
- r"""Add the given collection of instances to this ``Session``.
+ r"""Add the given collection of instances to this :class:`_orm.Session`.
.. container:: class_bases
Proxied for the :class:`_orm.Session` class on
behalf of the :class:`_asyncio.AsyncSession` class.
+ See the documentation for :meth:`_orm.Session.add` for a general
+ behavioral description.
+
+ .. seealso::
+
+ :meth:`_orm.Session.add`
+
+ :ref:`session_adding` - at :ref:`session_basics`
+
+
""" # noqa: E501
For an ORM selection as would
be retrieved from :class:`_orm.Query`, this is an instance of
- :class:`_future.select` that was generated from the ORM query.
+ :class:`_sql.select` that was generated from the ORM query.
"""
parameters: Optional[_CoreAnyExecuteParams]
.. versionadded:: 1.4 - The :func:`_sql.select` function now accepts
column arguments positionally. The top-level :func:`_sql.select`
function will automatically use the 1.x or 2.x style API based on
- the incoming arguments; using :func:`_future.select` from the
+ the incoming arguments; using :func:`_sql.select` from the
``sqlalchemy.future`` module will enforce that only the 2.x style
constructor is used.
def filter(
self: SelfSelect, *criteria: _ColumnExpressionArgument[bool]
) -> SelfSelect:
- """A synonym for the :meth:`_future.Select.where` method."""
+ """A synonym for the :meth:`_sql.Select.where` method."""
return self.where(*criteria)
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
