sqlalchemy.engine.base.Engine

Undocumented

Undocumented

Return a context manager delivering a :class:`_engine.Connection` with a :class:`.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 :class:`.Transaction` is committed. If an error is raised, the :class:`.Transaction` is rolled back. .. seealso:: :meth:`_engine.Engine.connect` - procure a :class:`_engine.Connection` from an :class:`_engine.Engine`. :meth:`_engine.Connection.begin` - start a :class:`.Transaction` for a particular :class:`_engine.Connection`.

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. .. versionadded:: 1.4

Return a new :class:`_engine.Connection` object. The :class:`_engine.Connection` acts as a Python context manager, so the typical use of this method looks like:: with engine.connect() as connection: connection.execute(text("insert into table values ('foo')")) connection.commit() Where above, after the block is completed, the connection is "closed" and its underlying DBAPI resources are returned to the connection pool. This also has the effect of rolling back any transaction that was explicitly begun or was begun via autobegin, and will emit the :meth:`_events.ConnectionEvents.rollback` event if one was started and is still in progress. .. seealso:: :meth:`_engine.Engine.begin`

Dispose of the connection pool used by this :class:`_engine.Engine`. A new connection pool is created immediately after the old one has been disposed. The previous connection pool is disposed either actively, by closing out all currently checked-in connections in that pool, or passively, by losing references to it but otherwise not closing any connections. The latter strategy is more appropriate for an initializer in a forked Python process. :param close: if left at its default of ``True``, 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 :class:`_engine.Engine`, so when they are closed individually, eventually the :class:`_pool.Pool` which they are associated with will be garbage collected and they will be closed out fully, if not already closed on checkin. If set to ``False``, the previous connection pool is de-referenced, and otherwise not touched in any way. .. versionadded:: 1.4.33 Added the :paramref:`.Engine.dispose.close` parameter to allow the replacement of a connection pool in a child process without interfering with the connections used by the parent process. .. seealso:: :ref:`engine_disposal` :ref:`pooling_multiprocessing`

Return a new :class:`_engine.Engine` that will provide :class:`_engine.Connection` objects with the given execution options. The returned :class:`_engine.Engine` remains related to the original :class:`_engine.Engine` in that it shares the same connection pool and other state: * The :class:`_pool.Pool` used by the new :class:`_engine.Engine` is the same instance. The :meth:`_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 :class:`_engine.Engine` inherits the events of the parent, and new events can be associated with the new :class:`_engine.Engine` individually. * The logging configuration and logging_name is copied from the parent :class:`_engine.Engine`. The intent of the :meth:`_engine.Engine.execution_options` method is to implement schemes where multiple :class:`_engine.Engine` objects refer to the same connection pool, but are differentiated by options that affect some execution-level behavior for each engine. One such example is breaking into separate "reader" and "writer" :class:`_engine.Engine` instances, where one :class:`_engine.Engine` has a lower :term:`isolation level` setting configured or is even transaction-disabled using "autocommit". An example of this configuration is at :ref:`dbapi_autocommit_multiple`. Another example is one that uses a custom option ``shard_id`` which is consumed by an event to change the current schema on a database connection:: from sqlalchemy import event from sqlalchemy.engine import Engine primary_engine = create_engine("mysql+mysqldb://") shard1 = primary_engine.execution_options(shard_id="shard1") shard2 = primary_engine.execution_options(shard_id="shard2") 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.get_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 The above recipe illustrates two :class:`_engine.Engine` objects that will each serve as factories for :class:`_engine.Connection` objects that have pre-established "shard_id" execution options present. A :meth:`_events.ConnectionEvents.before_cursor_execute` event handler then interprets this execution option to emit a MySQL ``use`` statement to switch databases before a statement execution, while at the same time keeping track of which database we've established using the :attr:`_engine.Connection.info` dictionary. .. seealso:: :meth:`_engine.Connection.execution_options` - update execution options on a :class:`_engine.Connection` object. :meth:`_engine.Engine.update_execution_options` - update the execution options for a given :class:`_engine.Engine` in place. :meth:`_engine.Engine.get_execution_options`

Get the non-SQL options which will take effect during execution. .. versionadded: 1.3 .. seealso:: :meth:`_engine.Engine.execution_options`

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 :class:`_engine.Connection` is not needed. When a :class:`_engine.Connection` object is already present, the DBAPI connection is available using the :attr:`_engine.Connection.connection` accessor. .. seealso:: :ref:`dbapi_connections`

Update the default execution_options dictionary of this :class:`_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 :func:`_sa.create_engine`. .. seealso:: :meth:`_engine.Connection.execution_options` :meth:`_engine.Engine.execution_options`