sqlalchemy.engine.base.Engine

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Return a context manager delivering a _engine.Connection with a .Transaction established.

E.g.:

with engine.begin() as conn:
    conn.execute(
        text("insert into table (x, y, z) values (1, 2, 3)")
    )
    conn.execute(text("my_special_procedure(5)"))

Upon successful operation, the .Transaction is committed. If an error is raised, the .Transaction is rolled back.

Legacy use only: the close_with_result flag is normally False, and indicates that the _engine.Connection will be closed when the operation is complete. When set to True, it indicates the _engine.Connection is in "single use" mode, where the _engine.CursorResult returned by the first call to _engine.Connection.execute will close the _engine.Connection when that _engine.CursorResult has exhausted all result rows.

Clear the compiled cache associated with the dialect.

This applies only to the built-in cache that is established via the :paramref:`_engine.create_engine.query_cache_size` parameter. It will not impact any dictionary caches that were passed via the :paramref:`.Connection.execution_options.query_cache` parameter.

Return a new _engine.Connection object.

The _engine.Connection object is a facade that uses a DBAPI connection internally in order to communicate with the database. This connection is procured from the connection-holding _pool.Pool referenced by this _engine.Engine. When the _engine.Connection.close method of the _engine.Connection object is called, the underlying DBAPI connection is then returned to the connection pool, where it may be used again in a subsequent call to _engine.Engine.connect.

Dispose of the connection pool used by this _engine.Engine.

This has the effect of fully closing all currently checked in database connections. Connections that are still checked out will not be closed, however they will no longer be associated with this _engine.Engine, so when they are closed individually, eventually the _pool.Pool which they are associated with will be garbage collected and they will be closed out fully, if not already closed on checkin.

A new connection pool is created immediately after the old one has been disposed. This new pool, like all SQLAlchemy connection pools, does not make any actual connections to the database until one is first requested, so as long as the _engine.Engine isn't used again, no new connections will be made.

Executes the given construct and returns a _engine.CursorResult.

The arguments are the same as those used by _engine.Connection.execute.

Here, a _engine.Connection is acquired using the _engine.Engine.connect method, and the statement executed with that connection. The returned _engine.CursorResult is flagged such that when the _engine.CursorResult is exhausted and its underlying cursor is closed, the _engine.Connection created here will also be closed, which allows its associated DBAPI connection resource to be returned to the connection pool.

Return a new _engine.Engine that will provide _engine.Connection objects with the given execution options.

The returned _engine.Engine remains related to the original _engine.Engine in that it shares the same connection pool and other state:

• The _pool.Pool used by the new _engine.Engine is the same instance. The _engine.Engine.dispose method will replace the connection pool instance for the parent engine as well as this one.
• Event listeners are "cascaded" - meaning, the new _engine.Engine inherits the events of the parent, and new events can be associated with the new _engine.Engine individually.
• The logging configuration and logging_name is copied from the parent _engine.Engine.

The intent of the _engine.Engine.execution_options method is to implement "sharding" schemes where multiple _engine.Engine objects refer to the same connection pool, but are differentiated by options that would be consumed by a custom event:

primary_engine = create_engine("mysql://")
shard1 = primary_engine.execution_options(shard_id="shard1")
shard2 = primary_engine.execution_options(shard_id="shard2")

Above, the shard1 engine serves as a factory for _engine.Connection objects that will contain the execution option shard_id=shard1, and shard2 will produce _engine.Connection objects that contain the execution option shard_id=shard2.

An event handler can consume the above execution option to perform a schema switch or other operation, given a connection. Below we emit a MySQL use statement to switch databases, at the same time keeping track of which database we've established using the _engine.Connection.info dictionary, which gives us a persistent storage space that follows the DBAPI connection:

from sqlalchemy import event
from sqlalchemy.engine import Engine

shards = {"default": "base", shard_1: "db1", "shard_2": "db2"}

@event.listens_for(Engine, "before_cursor_execute")
def _switch_shard(conn, cursor, stmt,
        params, context, executemany):
    shard_id = conn._execution_options.get('shard_id', "default")
    current_shard = conn.info.get("current_shard", None)

    if current_shard != shard_id:
        cursor.execute("use %s" % shards[shard_id])
        conn.info["current_shard"] = shard_id

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

Return True if the given backend has a table of the given name.

Return a "raw" DBAPI connection from the connection pool.

The returned object is a proxied version of the DBAPI connection object used by the underlying driver in use. The object will have all the same behavior as the real DBAPI connection, except that its close() method will result in the connection being returned to the pool, rather than being closed for real.

This method provides direct DBAPI connection access for special situations when the API provided by _engine.Connection is not needed. When a _engine.Connection object is already present, the DBAPI connection is available using the _engine.Connection.connection accessor.

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.Connection.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.

Execute the given function within a transaction boundary.

The function is passed a _engine.Connection newly procured from _engine.Engine.connect 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})

engine.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 engine.begin() as conn:
    conn.execute(text("some statement"), {'x':5, 'y':10})

Update the default execution_options dictionary of this _engine.Engine.

The given keys/values in **opt are added to the default execution options that will be used for all connections. The initial contents of this dictionary can be sent via the execution_options parameter to _sa.create_engine.