sqlalchemy.engine.base.Connection

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Return a new Connection which references this Connection's engine and connection; but does not have close_with_result enabled, and also whose close() method does nothing.

The Core uses this very sparingly, only in the case of custom SQL default functions that are to be INSERTed as the primary key of a row where we need to get the value back, so we have to invoke it distinctly - this is a very uncommon case.

Userland code accesses _branch() when the connect() method is called. The branched connection acts as much as possible like the parent, except that it stays connected when a close() event occurs.

Undocumented

Undocumented

Execute a statement + params on the given cursor.

Adds appropriate logging and exception handling.

This method is used by DefaultDialect for special-case executions, such as for sequences and column defaults. The path of statement execution in the majority of cases terminates at _execute_context().

Undocumented

Undocumented

Execute a sql.Compiled object.

TODO: why do we have this? likely deprecate or remove

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

run a DDL visitor.

This method is only here so that the MockConnection can change the options given to the visitor so that "checkfirst" is skipped.

Undocumented

Undocumented

Begin a transaction and return a transaction handle.

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

Legacy use: nested calls to .begin on the same _engine.Connection will return new .Transaction objects that represent an emulated transaction within the scope of the enclosing transaction, that is:

trans = conn.begin()   # outermost transaction
trans2 = conn.begin()  # "nested"
trans2.commit()        # does nothing
trans.commit()         # actually commits

Calls to .Transaction.commit only have an effect when invoked via the outermost .Transaction object, though the .Transaction.rollback method of any of the .Transaction objects will roll back the transaction.

Begin a nested transaction (i.e. SAVEPOINT) and return a transaction handle, assuming an outer transaction is already established.

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.

The legacy form of _engine.Connection.begin_nested method has alternate behaviors based on whether or not the _engine.Connection.begin method was called previously. If _engine.Connection.begin was not called, then this method will behave the same as the _engine.Connection.begin method and return a .RootTransaction object that begins and commits a real transaction - no savepoint is invoked. If _engine.Connection.begin has been called, and a .RootTransaction is already established, then this method returns an instance of .NestedTransaction which will invoke and manage the scope of a SAVEPOINT.

Begin a two-phase or XA transaction and return a transaction handle.

The returned object is an instance of .TwoPhaseTransaction, which in addition to the methods provided by .Transaction, also provides a ~.TwoPhaseTransaction.prepare method.

Close this _engine.Connection.

This results in a release of the underlying database resources, that is, the DBAPI connection referenced internally. The DBAPI connection is typically restored back to the connection-holding _pool.Pool referenced by the _engine.Engine that produced this _engine.Connection. Any transactional state present on the DBAPI connection is also unconditionally released via the DBAPI connection's rollback() method, regardless of any .Transaction object that may be outstanding with regards to this _engine.Connection.

After _engine.Connection.close is called, the _engine.Connection is permanently in a closed state, and will allow no further operations.

Undocumented

Returns a branched version of this _engine.Connection.

The _engine.Connection.close method on the returned _engine.Connection can be called and this _engine.Connection will remain open.

This method provides usage symmetry with _engine.Engine.connect, including for usage with context managers.

Detach the underlying DB-API connection from its connection pool.

E.g.:

with engine.connect() as conn:
    conn.detach()
    conn.execute(text("SET search_path TO schema1, schema2"))

    # work with connection

# connection is fully closed (since we used "with:", can
# also call .close())

This _engine.Connection instance will remain usable. When closed (or exited from a context manager context as above), the DB-API connection will be literally closed and not returned to its originating pool.

This method can be used to insulate the rest of an application from a modified state on a connection (such as a transaction isolation level or similar).

Set non-SQL options for the connection which take effect during execution.

For a "future" style connection, this method returns this same _future.Connection object with the new options added.

For a legacy connection, this method returns a copy of this _engine.Connection which references the same underlying DBAPI connection, but also defines the given execution options which will take effect for a call to execute. As the new _engine.Connection references the same underlying resource, it's usually a good idea to ensure that the copies will be discarded immediately, which is implicit if used as in:

result = connection.execution_options(stream_results=True).\
                    execute(stmt)

Note that any key/value can be passed to _engine.Connection.execution_options, and it will be stored in the _execution_options dictionary of the _engine.Connection. It is suitable for usage by end-user schemes to communicate with event listeners, for example.

The keywords that are currently recognized by SQLAlchemy itself include all those listed under .Executable.execution_options, as well as others that are specific to _engine.Connection.

Get the non-SQL options which will take effect during execution.

Return the current isolation level assigned to this _engine.Connection.

This will typically be the default isolation level as determined by the dialect, unless if the :paramref:`.Connection.execution_options.isolation_level` feature has been used to alter the isolation level on a per-_engine.Connection basis.

This attribute will typically perform a live SQL operation in order to procure the current isolation level, so the value returned is the actual level on the underlying DBAPI connection regardless of how this state was set. Compare to the _engine.Connection.default_isolation_level accessor which returns the dialect-level setting without performing a SQL query.

Return the current nested transaction in progress, if any.

Return the current root transaction in progress, if any.

Invalidate the underlying DBAPI connection associated with this _engine.Connection.

An attempt will be made to close the underlying DBAPI connection immediately; however if this operation fails, the error is logged but not raised. The connection is then discarded whether or not close() succeeded.

Upon the next use (where "use" typically means using the _engine.Connection.execute method or similar), this _engine.Connection will attempt to procure a new DBAPI connection using the services of the _pool.Pool as a source of connectivity (e.g. a "reconnection").

If a transaction was in progress (e.g. the _engine.Connection.begin method has been called) when _engine.Connection.invalidate method is called, at the DBAPI level all state associated with this transaction is lost, as the DBAPI connection is closed. The _engine.Connection will not allow a reconnection to proceed until the .Transaction object is ended, by calling the .Transaction.rollback method; until that point, any attempt at continuing to use the _engine.Connection will raise an ~sqlalchemy.exc.InvalidRequestError. This is to prevent applications from accidentally continuing an ongoing transactional operations despite the fact that the transaction has been lost due to an invalidation.

The _engine.Connection.invalidate method, just like auto-invalidation, will at the connection pool level invoke the _events.PoolEvents.invalidate event.

Undocumented

Undocumented

Given a callable object or function, execute it, passing a _engine.Connection as the first argument.

The given *args and **kwargs are passed subsequent to the _engine.Connection argument.

This function, along with _engine.Engine.run_callable, allows a function to be run with a _engine.Connection or _engine.Engine object without the need to know which one is being dealt with.

Executes and returns the first column of the first row.

The underlying result/cursor is closed after execution.

Executes and returns a scalar result set, which yields scalar values from the first column of each row.

This method is equivalent to calling _engine.Connection.execute to receive a _result.Result object, then invoking the _result.Result.scalars method to produce a _result.ScalarResult instance.

Execute the given function within a transaction boundary.

The function is passed this _engine.Connection as the first argument, followed by the given *args and **kwargs, e.g.:

def do_something(conn, x, y):
    conn.execute(text("some statement"), {'x':x, 'y':y})

conn.transaction(do_something, 5, 10)

The operations inside the function are all invoked within the context of a single .Transaction. Upon success, the transaction is committed. If an exception is raised, the transaction is rolled back before propagating the exception.

with conn.begin():
    conn.execute(text("some statement"), {'x':5, 'y':10})

with engine.begin() as conn:
    conn.execute(text("some statement"), {'x':5, 'y':10})