sqlalchemy.future.engine.Connection

class documentation

class Connection(_LegacyConnection):

View In Hierarchy

Provides high-level functionality for a wrapped DB-API connection.

The _future.Connection object is procured by calling the _future.Engine.connect method of the _future.Engine object, and provides services for execution of SQL statements as well as transaction control.

This is the SQLAlchemy 2.0 version of the _engine.Connection class. The API and behavior of this object is largely the same, with the following differences in behavior:

  • The result object returned for results is the _engine.CursorResult object, which is a subclass of the _engine.Result. This object has a slightly different API and behavior than the _engine.LegacyCursorResult returned for 1.x style usage.
  • The object has _future.Connection.commit and _future.Connection.rollback methods which commit or roll back the current transaction in progress, if any.
  • The object features "autobegin" behavior, such that any call to _future.Connection.execute will unconditionally start a transaction which can be controlled using the above mentioned _future.Connection.commit and _future.Connection.rollback methods.
  • The object does not have any "autocommit" functionality. Any SQL statement or DDL statement will not be followed by any COMMIT until the transaction is explicitly committed, either via the _future.Connection.commit method, or if the connection is being used in a context manager that commits such as the one returned by _future.Engine.begin.
  • The SAVEPOINT method _future.Connection.begin_nested returns a _engine.NestedTransaction as was always the case, and the savepoint can be controlled by invoking _engine.NestedTransaction.commit or _engine.NestedTransaction.rollback as was the case before. However, this savepoint "transaction" is not associated with the transaction that is controlled by the connection itself; the overall transaction can be committed or rolled back directly which will not emit any special instructions for the SAVEPOINT (this will typically have the effect that one desires).
  • The _future.Connection object does not support "branching", which was a pattern by which a sub "connection" would be used that refers to this connection as a parent.
Method ​_branch Undocumented
Method begin Begin a transaction prior to autobegin occurring.
Method begin​_nested Begin a nested transaction (i.e. SAVEPOINT) and return a transaction handle.
Method close Close this _future.Connection.
Method commit Commit the transaction that is currently in progress.
Method execute Executes a SQL statement construct and returns a _engine.Result.
Method rollback Roll back the transaction that is currently in progress.
Method scalar Executes a SQL statement construct and returns a scalar object.
Class Variable ​_is​_future Undocumented
def _branch(self):

Undocumented

def begin(self):

Begin a transaction prior to autobegin occurring.

The returned object is an instance of _engine.RootTransaction. This object represents the "scope" of the transaction, which completes when either the _engine.Transaction.rollback or _engine.Transaction.commit method is called.

The _future.Connection.begin method in SQLAlchemy 2.0 begins a transaction that normally will be begun in any case when the connection is first used to execute a statement. The reason this method might be used would be to invoke the _events.ConnectionEvents.begin event at a specific time, or to organize code within the scope of a connection checkout in terms of context managed blocks, such as:

with engine.connect() as conn:
    with conn.begin():
        conn.execute(...)
        conn.execute(...)

    with conn.begin():
        conn.execute(...)
        conn.execute(...)

The above code is not fundamentally any different in its behavior than the following code which does not use _future.Connection.begin; the below style is referred towards as "commit as you go" style:

with engine.connect() as conn:
    conn.execute(...)
    conn.execute(...)
    conn.commit()

    conn.execute(...)
    conn.execute(...)
    conn.commit()

From a database point of view, the _future.Connection.begin method does not emit any SQL or change the state of the underlying DBAPI connection in any way; the Python DBAPI does not have any concept of explicit transaction begin.

See Also

:ref:`tutorial_working_with_transactions` - in the :ref:`unified_tutorial`

_future.Connection.begin_nested - use a SAVEPOINT

_engine.Connection.begin_twophase - use a two phase /XID transaction

_future.Engine.begin - context manager available from _future.Engine

def begin_nested(self):

Begin a nested transaction (i.e. SAVEPOINT) and return a transaction handle.

The returned object is an instance of _engine.NestedTransaction.

Nested transactions require SAVEPOINT support in the underlying database. Any transaction in the hierarchy may commit and rollback, however the outermost transaction still controls the overall commit or rollback of the transaction of a whole.

If an outer .RootTransaction is not present on this _future.Connection, a new one is created using "autobegin". This outer transaction may be completed using "commit-as-you-go" style usage, by calling upon _future.Connection.commit or _future.Connection.rollback.

Tip

The "autobegin" behavior of _future.Connection.begin_nested is specific to :term:`2.0 style` use; for legacy behaviors, see _engine.Connection.begin_nested.

The _engine.NestedTransaction remains independent of the _future.Connection object itself. Calling the _future.Connection.commit or _future.Connection.rollback will always affect the actual containing database transaction itself, and not the SAVEPOINT itself. When a database transaction is committed, any SAVEPOINTs that have been established are cleared and the data changes within their scope is also committed.

See Also

_future.Connection.begin

def close(self):

Close this _future.Connection.

This has the effect of also calling _future.Connection.rollback if any transaction is in place.

def commit(self):

Commit the transaction that is currently in progress.

This method commits the current transaction if one has been started. 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 _future.Connection automatically whenever a statement is first executed, or when the _future.Connection.begin method is called.

Note

The _future.Connection.commit method only acts upon the primary database transaction that is linked to the _future.Connection object. It does not operate upon a SAVEPOINT that would have been invoked from the _future.Connection.begin_nested method; for control of a SAVEPOINT, call _engine.NestedTransaction.commit on the _engine.NestedTransaction that is returned by the _future.Connection.begin_nested method itself.

def execute(self, statement, parameters=None, execution_options=None):
Executes a SQL statement construct and returns a _engine.Result.
Parameters
statement

The statement to be executed. This is always an object that is in both the _expression.ClauseElement and _expression.Executable hierarchies, including:

  • _expression.Select
  • _expression.Insert, _expression.Update, _expression.Delete
  • _expression.TextClause and _expression.TextualSelect
  • _schema.DDL and objects which inherit from _schema.DDLElement
parametersparameters which will be bound into the statement. This may be either a dictionary of parameter names to values, or a mutable sequence (e.g. a list) of dictionaries. When a list of dictionaries is passed, the underlying statement execution will make use of the DBAPI cursor.executemany() method. When a single dictionary is passed, the DBAPI cursor.execute() method will be used.
execution​_optionsoptional 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 _future.Connection.execution_options.
Returns
a _engine.Result object.
def rollback(self):

Roll back the transaction that is currently in progress.

This method rolls back the current transaction if one has been started. If no transaction was started, the method has no effect. If a transaction was started and the connection is in an invalidated state, the transaction is cleared using this method.

A transaction is begun on a _future.Connection automatically whenever a statement is first executed, or when the _future.Connection.begin method is called.

Note

The _future.Connection.rollback method only acts upon the primary database transaction that is linked to the _future.Connection object. It does not operate upon a SAVEPOINT that would have been invoked from the _future.Connection.begin_nested method; for control of a SAVEPOINT, call _engine.NestedTransaction.rollback on the _engine.NestedTransaction that is returned by the _future.Connection.begin_nested method itself.

def scalar(self, statement, parameters=None, execution_options=None):

Executes a SQL statement construct and returns a scalar object.

This method is shorthand for invoking the _engine.Result.scalar method after invoking the _future.Connection.execute method. Parameters are equivalent.

Returns
a scalar Python value representing the first column of the first row returned.
_is_future: bool =

Undocumented