U
|
¸ý°dé ã @ sô U d Z ddlmZ ddlZddlZddlZddlmZ ddlmZ ddlmZ ddlm Z ddlm
|
Z
|
dd lm Z dd
|
lm Z dd lm Z dd lmZ dd lmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddlmZ ddl m Z ddl m Z dd l m Z d d l m!Z! d d l m"Z" d d l m#Z# d d!l m Z d d"l$m%Z% d d!l$m Z& ej'rdd#l m(Z( dd$l m)Z) dd%lm*Z* dd&lm+Z+ dd'lm,Z, dd(lm-Z- dd)lm.Z. dd*lm/Z/ dd+lm0Z0 dd,lm1Z1 dd-lm2Z2 dd.lm3Z3 dd/lm4Z4 dd0lm5Z5 dd1l6m7Z7 dd2l8m9Z9 d d3l:m;Z; d d4l#m<Z< d d5l=m>Z> d d6l=m?Z? d d7l=m@Z@ d d8l$mAZA d d9lBmCZC d d:lDmEZE d d;lFmGZG d d<lFmHZH d d=lFmIZI d d>lJmKZK d d?lLmMZM d d@lLmNZN d dAlLmOZO d dBlPmQZQ edCedDZRe jSZTdEeUdF< e jSZVdGeUdH< G dIdJ dJee"jWdK ZXG dLdM dMeZYG dNdO dOe ZZG dPdQ dQeZZ[G dRdS dSeZZ\G dTdU dUe[Z]G dVdW dWee#j^e"jWdK Z_G dXdY dYe#j^Z`G dZd[ d[e`e_Zaeae__bdS )\zBDefines :class:`_engine.Connection` and :class:`_engine.Engine`.
|
|
é )Ú annotationsN)ÚAny)ÚCallable)Úcast)ÚIterable)ÚIterator)ÚList)ÚMapping)ÚNoReturn)ÚOptional)Úoverload)ÚTuple)ÚType)ÚTypeVar)ÚUnioné )Ú
|
BindTyping)ÚConnectionEventsTarget)Ú DBAPICursor)ÚExceptionContext)Ú ExecuteStyle)ÚExecutionContext)ÚIsolationLevel)Ú_distill_params_20)Ú_distill_raw_params)ÚTransactionalContexté )Úexc)Ú
|
inspection)Úlog)Úutil)Úcompiler)Ú CursorResult)Ú ScalarResult)Ú_AnyExecuteParams)Ú_AnyMultiExecuteParams)Ú_CoreAnyExecuteParams)Ú_CoreMultiExecuteParams)Ú_CoreSingleExecuteParams)Ú_DBAPIAnyExecuteParams)Ú_DBAPISingleExecuteParams)Ú_ExecuteOptions)ÚCompiledCacheType)ÚCoreExecuteOptionsParameter)ÚDialect)ÚSchemaTranslateMapType)Ú Inspector)ÚURL)Ú
|
dispatcher)Ú _EchoFlagType)Ú_ConnectionFairy)ÚPool)ÚPoolProxiedConnection)Ú
|
Executable)Ú _InfoType)ÚCompiled)ÚExecutableDDLElement)Ú SchemaDropper)ÚSchemaGenerator)ÚFunctionElement)ÚDefaultGenerator)Ú HasSchemaAttr)Ú
|
SchemaItem)ÚTypedReturnsRowsÚ_T)Úboundr+ Ú_EMPTY_EXECUTION_OPTSzMapping[str, Any]Ú
|
NO_OPTIONSc @ s" e Zd ZU dZded< dZdZded< dZd ed
|
< d ed < d ed< ded< dôdd ddddddZe j
|
ddddZ d ddd d d d Z d ddd d d!d"Z ed#dd$d%Zd&d'd(d)d*Zd dd+d,Zdddd d-d.d/Zed0d0d0ddd0d0d0d0d1 d2d d3ddd4d4d4d#dd d5 d6d7Zedd d8d9d7Zdd d8d:d7Zd dd;d<Zeddd=d>Zeddd?d@ZedddAdBZedCddDdEZd3ddFdGZedHddIdJZdKddLdMZ dCddNdOZ edPddQdRZ dõdSd dTdUdVZ d ddWdXZ d ddYdZZ!d[dd\d]Z"d^dd_d`Z#dödadbdcdddeZ$d ddfdgZ%d ddhdiZ&djddkdlZ'd÷ddd dmdndoZ(døddd dmdpdqZ)dddrdsZ*dddtduZ+dddvdwZ,d[ddxdyZ-d^ddzd{Z.d dd|d}Z/ddd~dZ0d[d dddZ1d dddZ2d dd
dZ3dùd'd dddZ4d d dddZ5d d dddZ6dbd dddZ7dd dcddZ8ddd dddZ9ddd dddZ:d dddZ;edúddddddddd Z<edûddd¡ddddd¢d Z<düddd¡ddddd£d Z<edýdddd¤dd¥dd¦d§Z=edþddd¡d¤dd¨dd©d§Z=dÿddd¡d¤dd¨ddªd§Z=ed ddd«d¤dd¬ddd®Z>edddd¡d¤dd¯dd°d®Z>dddd¡d¤dd¯dd±d®Z>d²d³d´d¯dµd¶d·Z?d¸d³d´dd¹dºd»Z@d¼d³d´d¯d½d¾d¿ZAdd³d dÀdÁdÂdÃZBd¡d³d´d¯dÄdÅdÆZCeDfdÇd³d´d¯dÈdÉdÊZEdd dËdd¯ddÌdÍZFdÎdÏdÐdÑd ddd¯dÒdÓdÔZGdÎdÕdÐdÑd¯dÖd×dØZHdÎdÕd¯dÙdÚdÛZIddÜd dÝdÞd dßdàdáZJdÜd dâdãdäZKdZLdZMddåd'dædçdÞddKdèdédêZNeOddådÎdëddddKdìdídîZPdïdðdd dñdòdóZQdS ( Ú
|
Connectiona: Provides high-level functionality for a wrapped DB-API connection.
|
|
The :class:`_engine.Connection` object is procured by calling the
|
:meth:`_engine.Engine.connect` method of the :class:`_engine.Engine`
|
object, and provides services for execution of SQL statements as well
|
as transaction control.
|
|
The Connection object is **not** thread-safe. While a Connection can be
|
shared among threads using properly synchronized access, it is still
|
possible that the underlying DBAPI connection may not support shared
|
access between threads. Check the DBAPI documentation for details.
|
|
The Connection object represents a single DBAPI connection checked out
|
from the connection pool. In this state, the connection pool has no
|
affect upon the connection, including its expiration or timeout state.
|
For the connection pool to properly manage connections, connections
|
should be returned to the connection pool (i.e. ``connection.close()``)
|
whenever the connection is not in use.
|
|
.. index::
|
single: thread safety; Connection
|
|
ú"dispatcher[ConnectionEventsTarget]Údispatchz sqlalchemy.engine.ConnectionNz Optional[TransactionalContext]Ú_trans_context_managerFz Optional[PoolProxiedConnection]Ú_dbapi_connectionr+ Ú_execution_optionszOptional[RootTransaction]Ú _transactionzOptional[NestedTransaction]Ú_nested_transactionTÚEnginezOptional[bool]Úbool)ÚengineÚ
|
connectionÚ _has_eventsÚ_allow_revalidateÚ_allow_autobeginc
|
C sê || _ |j | _}|dkrbz| ¡ | _W qh |jjk
|
r^ } zt |||¡ W 5 d}~X Y qhX n|| _d | _| _ d| _
|
d| _ || _ || _ | j ¡ | _|dkr°| j |j¡| _|pÀ|dkoÀ|j| _|j| _| jsÚ| j jræ| j | ¡ dS )zConstruct a new Connection.Nr F)rP ÚdialectÚraw_connectionrJ Ú loaded_dbapiÚErrorrF Ú$_handle_dbapi_exception_noconnectionrL rM Ú_Connection__savepoint_seqÚ_Connection__in_beginÚ_Connection__can_reconnectrT Ú_should_log_infoÚ_echorH Ú_joinrR rK Zengine_connect)ÚselfrP rQ rR rS rT rU Úerr© rb úMd:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\sqlalchemy/engine/base.pyÚ__init__ s6 ÿ ÿzConnection.__init__r ©Úreturnc s( d| j kr | j d fddS d S d S )NÚ logging_tokenc s d | f S )Nz[%s] %srb )Úmsg©Útokenrb rc Ú<lambda>´ ó z/Connection._message_formatter.<locals>.<lambda>©rK ©r` rb ri rc Ú_message_formatter° s
|
|
z Connection._message_formatterÚstrÚNone)ÚmessageÚargÚkwrf c O s@ | j }|r||}tjr&dtj |d< | jjj|f|| d S ©Nr Ú
|
stacklevel)ro r Ú
|
STACKLEVELÚSTACKLEVEL_OFFSETrP ÚloggerÚinfo©r` rr rs rt Úfmtrb rb rc Ú _log_info¸ s zConnection._log_infoc O s@ | j }|r||}tjr&dtj |d< | jjj|f|| d S ru )ro r rw rx rP ry Údebugr{ rb rb rc Ú
|
_log_debugà s zConnection._log_debugú Optional[SchemaTranslateMapType]c C s | j dd ¡S )NÚschema_translate_map)rK Úgetrn rb rb rc Ú_schema_translate_mapÎ s z Connection._schema_translate_mapr? ú Optional[str])Úobjrf c C s6 |j }| j dd¡}|r.||kr.|jr.|| S |S dS )ztReturn the schema name for the given schema item taking into
|
account current schema translate map.
|
|
r N)ZschemarK r Z_use_schema_map)r` r
Únamer rb rb rc Úschema_for_objectÒ s þÿþýz Connection.schema_for_objectc C s | S ©Nrb rn rb rb rc Ú __enter__æ s zConnection.__enter__)Útype_ÚvalueÚ tracebackrf c C s | ¡ d S r )Úclose)r` r r r rb rb rc Ú__exit__é s zConnection.__exit__.) Úcompiled_cacherg Úisolation_levelÚ no_parametersÚstream_resultsÚmax_row_bufferÚ yield_perÚinsertmanyvalues_page_sizer úOptional[CompiledCacheType]r Úint) r rg r r r r r r r Úoptrf c K s d S r rb ) r` r rg r r r r r r r r rb rb rc Úexecution_optionsì s z Connection.execution_options©r rf c K s d S r rb ©r` r rb rb rc r ý s c K s< | j s| jj r | j | |¡ | j |¡| _| j | |¡ | S )a3. Set non-SQL options for the connection which take effect
|
during execution.
|
|
This method modifies this :class:`_engine.Connection` **in-place**;
|
the return value is the same :class:`_engine.Connection` object
|
upon which the method is called. Note that this is in contrast
|
to the behavior of the ``execution_options`` methods on other
|
objects such as :meth:`_engine.Engine.execution_options` and
|
:meth:`_sql.Executable.execution_options`. The rationale is that many
|
such execution options necessarily modify the state of the base
|
DBAPI connection in any case so there is no feasible means of
|
keeping the effect of such an option localized to a "sub" connection.
|
|
.. versionchanged:: 2.0 The :meth:`_engine.Connection.execution_options`
|
method, in contrast to other objects with this method, modifies
|
the connection in-place without creating copy of it.
|
|
As discussed elsewhere, the :meth:`_engine.Connection.execution_options`
|
method accepts any arbitrary parameters including user defined names.
|
All parameters given are consumable in a number of ways including
|
by using the :meth:`_engine.Connection.get_execution_options` method.
|
See the examples at :meth:`_sql.Executable.execution_options`
|
and :meth:`_engine.Engine.execution_options`.
|
|
The keywords that are currently recognized by SQLAlchemy itself
|
include all those listed under :meth:`.Executable.execution_options`,
|
as well as others that are specific to :class:`_engine.Connection`.
|
|
:param compiled_cache: Available on: :class:`_engine.Connection`,
|
:class:`_engine.Engine`.
|
|
A dictionary where :class:`.Compiled` objects
|
will be cached when the :class:`_engine.Connection`
|
compiles a clause
|
expression into a :class:`.Compiled` object. This dictionary will
|
supersede the statement cache that may be configured on the
|
:class:`_engine.Engine` itself. If set to None, caching
|
is disabled, even if the engine has a configured cache size.
|
|
Note that the ORM makes use of its own "compiled" caches for
|
some operations, including flush operations. The caching
|
used by the ORM internally supersedes a cache dictionary
|
specified here.
|
|
:param logging_token: Available on: :class:`_engine.Connection`,
|
:class:`_engine.Engine`, :class:`_sql.Executable`.
|
|
Adds the specified string token surrounded by brackets in log
|
messages logged by the connection, i.e. the logging that's enabled
|
either via the :paramref:`_sa.create_engine.echo` flag or via the
|
``logging.getLogger("sqlalchemy.engine")`` logger. This allows a
|
per-connection or per-sub-engine token to be available which is
|
useful for debugging concurrent connection scenarios.
|
|
.. versionadded:: 1.4.0b2
|
|
.. seealso::
|
|
:ref:`dbengine_logging_tokens` - usage example
|
|
:paramref:`_sa.create_engine.logging_name` - adds a name to the
|
name used by the Python logger object itself.
|
|
:param isolation_level: Available on: :class:`_engine.Connection`,
|
:class:`_engine.Engine`.
|
|
Set the transaction isolation level for the lifespan of this
|
:class:`_engine.Connection` object.
|
Valid values include those string
|
values accepted by the :paramref:`_sa.create_engine.isolation_level`
|
parameter passed to :func:`_sa.create_engine`. These levels are
|
semi-database specific; see individual dialect documentation for
|
valid levels.
|
|
The isolation level option applies the isolation level by emitting
|
statements on the DBAPI connection, and **necessarily affects the
|
original Connection object overall**. The isolation level will remain
|
at the given setting until explicitly changed, or when the DBAPI
|
connection itself is :term:`released` to the connection pool, i.e. the
|
:meth:`_engine.Connection.close` method is called, at which time an
|
event handler will emit additional statements on the DBAPI connection
|
in order to revert the isolation level change.
|
|
.. note:: The ``isolation_level`` execution option may only be
|
established before the :meth:`_engine.Connection.begin` method is
|
called, as well as before any SQL statements are emitted which
|
would otherwise trigger "autobegin", or directly after a call to
|
:meth:`_engine.Connection.commit` or
|
:meth:`_engine.Connection.rollback`. A database cannot change the
|
isolation level on a transaction in progress.
|
|
.. note:: The ``isolation_level`` execution option is implicitly
|
reset if the :class:`_engine.Connection` is invalidated, e.g. via
|
the :meth:`_engine.Connection.invalidate` method, or if a
|
disconnection error occurs. The new connection produced after the
|
invalidation will **not** have the selected isolation level
|
re-applied to it automatically.
|
|
.. seealso::
|
|
:ref:`dbapi_autocommit`
|
|
:meth:`_engine.Connection.get_isolation_level`
|
- view current actual level
|
|
:param no_parameters: Available on: :class:`_engine.Connection`,
|
:class:`_sql.Executable`.
|
|
When ``True``, if the final parameter
|
list or dictionary is totally empty, will invoke the
|
statement on the cursor as ``cursor.execute(statement)``,
|
not passing the parameter collection at all.
|
Some DBAPIs such as psycopg2 and mysql-python consider
|
percent signs as significant only when parameters are
|
present; this option allows code to generate SQL
|
containing percent signs (and possibly other characters)
|
that is neutral regarding whether it's executed by the DBAPI
|
or piped into a script that's later invoked by
|
command line tools.
|
|
:param stream_results: Available on: :class:`_engine.Connection`,
|
:class:`_sql.Executable`.
|
|
Indicate to the dialect that results should be
|
"streamed" and not pre-buffered, if possible. For backends
|
such as PostgreSQL, MySQL and MariaDB, this indicates the use of
|
a "server side cursor" as opposed to a client side cursor.
|
Other backends such as that of Oracle may already use server
|
side cursors by default.
|
|
The usage of
|
:paramref:`_engine.Connection.execution_options.stream_results` is
|
usually combined with setting a fixed number of rows to to be fetched
|
in batches, to allow for efficient iteration of database rows while
|
at the same time not loading all result rows into memory at once;
|
this can be configured on a :class:`_engine.Result` object using the
|
:meth:`_engine.Result.yield_per` method, after execution has
|
returned a new :class:`_engine.Result`. If
|
:meth:`_engine.Result.yield_per` is not used,
|
the :paramref:`_engine.Connection.execution_options.stream_results`
|
mode of operation will instead use a dynamically sized buffer
|
which buffers sets of rows at a time, growing on each batch
|
based on a fixed growth size up until a limit which may
|
be configured using the
|
:paramref:`_engine.Connection.execution_options.max_row_buffer`
|
parameter.
|
|
When using the ORM to fetch ORM mapped objects from a result,
|
:meth:`_engine.Result.yield_per` should always be used with
|
:paramref:`_engine.Connection.execution_options.stream_results`,
|
so that the ORM does not fetch all rows into new ORM objects at once.
|
|
For typical use, the
|
:paramref:`_engine.Connection.execution_options.yield_per` execution
|
option should be preferred, which sets up both
|
:paramref:`_engine.Connection.execution_options.stream_results` and
|
:meth:`_engine.Result.yield_per` at once. This option is supported
|
both at a core level by :class:`_engine.Connection` as well as by the
|
ORM :class:`_engine.Session`; the latter is described at
|
:ref:`orm_queryguide_yield_per`.
|
|
.. seealso::
|
|
:ref:`engine_stream_results` - background on
|
:paramref:`_engine.Connection.execution_options.stream_results`
|
|
:paramref:`_engine.Connection.execution_options.max_row_buffer`
|
|
:paramref:`_engine.Connection.execution_options.yield_per`
|
|
:ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
describing the ORM version of ``yield_per``
|
|
:param max_row_buffer: Available on: :class:`_engine.Connection`,
|
:class:`_sql.Executable`. Sets a maximum
|
buffer size to use when the
|
:paramref:`_engine.Connection.execution_options.stream_results`
|
execution option is used on a backend that supports server side
|
cursors. The default value if not specified is 1000.
|
|
.. seealso::
|
|
:paramref:`_engine.Connection.execution_options.stream_results`
|
|
:ref:`engine_stream_results`
|
|
|
:param yield_per: Available on: :class:`_engine.Connection`,
|
:class:`_sql.Executable`. Integer value applied which will
|
set the :paramref:`_engine.Connection.execution_options.stream_results`
|
execution option and invoke :meth:`_engine.Result.yield_per`
|
automatically at once. Allows equivalent functionality as
|
is present when using this parameter with the ORM.
|
|
.. versionadded:: 1.4.40
|
|
.. seealso::
|
|
:ref:`engine_stream_results` - background and examples
|
on using server side cursors with Core.
|
|
:ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
|
describing the ORM version of ``yield_per``
|
|
:param insertmanyvalues_page_size: Available on: :class:`_engine.Connection`,
|
:class:`_engine.Engine`. Number of rows to format into an
|
INSERT statement when the statement uses "insertmanyvalues" mode,
|
which is a paged form of bulk insert that is used for many backends
|
when using :term:`executemany` execution typically in conjunction
|
with RETURNING. Defaults to 1000. May also be modified on a
|
per-engine basis using the
|
:paramref:`_sa.create_engine.insertmanyvalues_page_size` parameter.
|
|
.. versionadded:: 2.0
|
|
.. seealso::
|
|
:ref:`engine_insertmanyvalues`
|
|
:param schema_translate_map: Available on: :class:`_engine.Connection`,
|
:class:`_engine.Engine`, :class:`_sql.Executable`.
|
|
A dictionary mapping schema names to schema names, that will be
|
applied to the :paramref:`_schema.Table.schema` element of each
|
:class:`_schema.Table`
|
encountered when SQL or DDL expression elements
|
are compiled into strings; the resulting schema name will be
|
converted based on presence in the map of the original name.
|
|
.. seealso::
|
|
:ref:`schema_translating`
|
|
.. seealso::
|
|
:meth:`_engine.Engine.execution_options`
|
|
:meth:`.Executable.execution_options`
|
|
:meth:`_engine.Connection.get_execution_options`
|
|
:ref:`orm_queryguide_execution_options` - documentation on all
|
ORM-specific execution options
|
|
)rR rP rH Z set_connection_execution_optionsrK ÚunionrU r rb rb rc r s wc C s | j S )z¸Get the non-SQL options which will take effect during execution.
|
|
.. versionadded:: 1.3
|
|
.. seealso::
|
|
:meth:`_engine.Connection.execution_options`
|
rm rn rb rb rc Úget_execution_optionsý s z Connection.get_execution_optionsc C s | j }|d k o|jS r )rJ Úis_valid©r` Úpool_proxied_connectionrb rb rc Ú)_still_open_and_dbapi_connection_is_valid s þz4Connection._still_open_and_dbapi_connection_is_validc C s | j dko| j S )z)Return True if this connection is closed.N©rJ r\ rn rb rb rc Úclosed s zConnection.closedc C s | j }|dko| jS )zªReturn True if this connection was invalidated.
|
|
This does not indicate whether or not the connection was
|
invalidated at the pool level, however
|
|
Nr¢ r rb rb rc Ú invalidated s zConnection.invalidatedr6 c
|
C sr | j dkrhz
|
| ¡ W S tjtjfk
|
r2 Y qn tk
|
rd } z| |dddd¡ W 5 d}~X Y qnX n| j S dS )aV The underlying DB-API connection managed by this Connection.
|
|
This is a SQLAlchemy connection-pool proxied connection
|
which then has the attribute
|
:attr:`_pool._ConnectionFairy.dbapi_connection` that refers to the
|
actual driver connection.
|
|
.. seealso::
|
|
|
:ref:`dbapi_connections`
|
|
N)rJ Ú_revalidate_connectionr ÚPendingRollbackErrorÚResourceClosedErrorÚ BaseExceptionÚ_handle_dbapi_exception©r` Úerb rb rc rQ + s
|
|
&zConnection.connectionc
|
C s\ | j j}|dk stz| j |¡W S tk
|
rV } z| |dddd¡ W 5 d}~X Y nX dS )aÖ Return the current **actual** isolation level that's present on
|
the database within the scope of this connection.
|
|
This attribute will perform a live SQL operation against the database
|
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. This will be one of the four actual isolation
|
modes ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``,
|
``SERIALIZABLE``. It will **not** include the ``AUTOCOMMIT`` isolation
|
level setting. Third party dialects may also feature additional
|
isolation level settings.
|
|
.. note:: This method **will not report** on the ``AUTOCOMMIT``
|
isolation level, which is a separate :term:`dbapi` setting that's
|
independent of **actual** isolation level. When ``AUTOCOMMIT`` is
|
in use, the database connection still has a "traditional" isolation
|
mode in effect, that is typically one of the four values
|
``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE READ``,
|
``SERIALIZABLE``.
|
|
Compare to the :attr:`_engine.Connection.default_isolation_level`
|
accessor which returns the isolation level that is present on the
|
database at initial connection time.
|
|
.. seealso::
|
|
:attr:`_engine.Connection.default_isolation_level`
|
- view default level
|
|
:paramref:`_sa.create_engine.isolation_level`
|
- set per :class:`_engine.Engine` isolation level
|
|
:paramref:`.Connection.execution_options.isolation_level`
|
- set per :class:`_engine.Connection` isolation level
|
|
N)rQ Údbapi_connectionÚAssertionErrorrU Úget_isolation_levelr¨ r© )r` r¬ r« rb rb rc r® E s % z Connection.get_isolation_levelzOptional[IsolationLevel]c C s | j jS )aö The initial-connection time isolation level associated with the
|
:class:`_engine.Dialect` in use.
|
|
This value is independent of the
|
:paramref:`.Connection.execution_options.isolation_level` and
|
:paramref:`.Engine.execution_options.isolation_level` execution
|
options, and is determined by the :class:`_engine.Dialect` when the
|
first connection is created, by performing a SQL query against the
|
database for the current isolation level before any additional commands
|
have been emitted.
|
|
Calling this accessor does not invoke any new SQL queries.
|
|
.. seealso::
|
|
:meth:`_engine.Connection.get_isolation_level`
|
- view current actual isolation level
|
|
:paramref:`_sa.create_engine.isolation_level`
|
- set per :class:`_engine.Engine` isolation level
|
|
:paramref:`.Connection.execution_options.isolation_level`
|
- set per :class:`_engine.Connection` isolation level
|
|
)rU Údefault_isolation_levelrn rb rb rc r¯ q s z"Connection.default_isolation_levelr
|
c C s$ t jd| jd k rdnd ddd S )NzfCan't reconnect until invalid %stransaction is rolled back. Please rollback() fully before proceedingz
|
savepoint Ú Z8s2b)Úcode)r r¦ rM rn rb rb rc Ú_invalid_transaction s þüz Connection._invalid_transactionc C s> | j r0| jr0| jd k r | ¡ | j ¡ | _| jS t d¡d S )NúThis Connection is closed) r\ r¤ rL r² rP rV rJ r r§ rn rb rb rc r¥ s
|
z!Connection._revalidate_connectionr8 c C s | j jS )a Info dictionary associated with the underlying DBAPI connection
|
referred to by this :class:`_engine.Connection`, allowing user-defined
|
data to be associated with the connection.
|
|
The data here will follow along with the DBAPI connection including
|
after it is returned to the connection pool and used again
|
in subsequent instances of :class:`_engine.Connection`.
|
|
)rQ rz rn rb rb rc rz s zConnection.infozOptional[BaseException])Ú exceptionrf c C sF | j r
|
dS | jrt d¡| jr<| j}|dk s2t| |¡ d| _dS )aå Invalidate the underlying DBAPI connection associated with
|
this :class:`_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
|
:meth:`_engine.Connection.execute` method or similar),
|
this :class:`_engine.Connection` will attempt to
|
procure a new DBAPI connection using the services of the
|
:class:`_pool.Pool` as a source of connectivity (e.g.
|
a "reconnection").
|
|
If a transaction was in progress (e.g. the
|
:meth:`_engine.Connection.begin` method has been called) when
|
:meth:`_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 :class:`_engine.Connection`
|
will not allow a reconnection to proceed until the
|
:class:`.Transaction` object is ended, by calling the
|
:meth:`.Transaction.rollback` method; until that point, any attempt at
|
continuing to use the :class:`_engine.Connection` will raise an
|
:class:`~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 :meth:`_engine.Connection.invalidate` method,
|
just like auto-invalidation,
|
will at the connection pool level invoke the
|
:meth:`_events.PoolEvents.invalidate` event.
|
|
:param exception: an optional ``Exception`` instance that's the
|
reason for the invalidation. is passed along to event handlers
|
and logging functions.
|
|
.. seealso::
|
|
:ref:`pool_connection_invalidation`
|
|
Nr³ )r¤ r£ r r§ r¡ rJ r Ú
|
invalidate)r` r´ r rb rb rc rµ ¬ s .
|
|
zConnection.invalidatec C s4 | j rt d¡| j}|dkr(t d¡| ¡ dS )a2 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 :class:`_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).
|
|
r³ Nz&Can't detach an invalidated Connection)r£ r r§ rJ ÚInvalidRequestErrorÚdetachr rb rb rc r· ç s
|
ÿzConnection.detachc C s | j r| js| ¡ d S r )rT r[ Úbeginrn rb rb rc Ú
|
_autobegin s zConnection._autobeginÚRootTransactionc C s( | j dkrt| | _ | j S t d¡dS )a¥ Begin a transaction prior to autobegin occurring.
|
|
E.g.::
|
|
with engine.connect() as conn:
|
with conn.begin() as trans:
|
conn.execute(table.insert(), {"username": "sandy"})
|
|
|
The returned object is an instance of :class:`_engine.RootTransaction`.
|
This object represents the "scope" of the transaction,
|
which completes when either the :meth:`_engine.Transaction.rollback`
|
or :meth:`_engine.Transaction.commit` method is called; the object
|
also works as a context manager as illustrated above.
|
|
The :meth:`_engine.Connection.begin` method 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 :meth:`_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
|
:meth:`_engine.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 :meth:`_engine.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.
|
|
.. seealso::
|
|
:ref:`tutorial_working_with_transactions` - in the
|
:ref:`unified_tutorial`
|
|
:meth:`_engine.Connection.begin_nested` - use a SAVEPOINT
|
|
:meth:`_engine.Connection.begin_twophase` -
|
use a two phase /XID transaction
|
|
:meth:`_engine.Engine.begin` - context manager available from
|
:class:`_engine.Engine`
|
|
NzªThis connection has already initialized a SQLAlchemy Transaction() object via begin() or autobegin; can't call begin() here unless rollback() or commit() is called first.)rL rº r r¶ rn rb rb rc r¸ s A
|
|
ÿzConnection.beginÚNestedTransactionc C s | j dkr| ¡ t| S )aâ Begin a nested transaction (i.e. SAVEPOINT) and return a transaction
|
handle that controls the scope of the SAVEPOINT.
|
|
E.g.::
|
|
with engine.begin() as connection:
|
with connection.begin_nested():
|
connection.execute(table.insert(), {"username": "sandy"})
|
|
The returned object is an instance of
|
:class:`_engine.NestedTransaction`, which includes transactional
|
methods :meth:`_engine.NestedTransaction.commit` and
|
:meth:`_engine.NestedTransaction.rollback`; for a nested transaction,
|
these methods correspond to the operations "RELEASE SAVEPOINT <name>"
|
and "ROLLBACK TO SAVEPOINT <name>". The name of the savepoint is local
|
to the :class:`_engine.NestedTransaction` object and is generated
|
automatically. Like any other :class:`_engine.Transaction`, the
|
:class:`_engine.NestedTransaction` may be used as a context manager as
|
illustrated above which will "release" or "rollback" corresponding to
|
if the operation within the block were successful or raised an
|
exception.
|
|
Nested transactions require SAVEPOINT support in the underlying
|
database, else the behavior is undefined. SAVEPOINT is commonly used to
|
run operations within a transaction that may fail, while continuing the
|
outer transaction. E.g.::
|
|
from sqlalchemy import exc
|
|
with engine.begin() as connection:
|
trans = connection.begin_nested()
|
try:
|
connection.execute(table.insert(), {"username": "sandy"})
|
trans.commit()
|
except exc.IntegrityError: # catch for duplicate username
|
trans.rollback() # rollback to savepoint
|
|
# outer transaction continues
|
connection.execute( ... )
|
|
If :meth:`_engine.Connection.begin_nested` is called without first
|
calling :meth:`_engine.Connection.begin` or
|
:meth:`_engine.Engine.begin`, the :class:`_engine.Connection` object
|
will "autobegin" the outer transaction first. This outer transaction
|
may be committed using "commit-as-you-go" style, e.g.::
|
|
with engine.connect() as connection: # begin() wasn't called
|
|
with connection.begin_nested(): will auto-"begin()" first
|
connection.execute( ... )
|
# savepoint is released
|
|
connection.execute( ... )
|
|
# explicitly commit outer transaction
|
connection.commit()
|
|
# can continue working with connection here
|
|
.. versionchanged:: 2.0
|
|
:meth:`_engine.Connection.begin_nested` will now participate
|
in the connection "autobegin" behavior that is new as of
|
2.0 / "future" style connections in 1.4.
|
|
.. seealso::
|
|
:meth:`_engine.Connection.begin`
|
|
:ref:`session_begin_nested` - ORM support for SAVEPOINT
|
|
N)rL r¹ r» rn rb rb rc Ú begin_nested[ s I
|
zConnection.begin_nestedz Optional[Any]ÚTwoPhaseTransaction)Úxidrf c C s2 | j dk rt d¡|dkr(| jj ¡ }t| |S )a' Begin a two-phase or XA transaction and return a transaction
|
handle.
|
|
The returned object is an instance of :class:`.TwoPhaseTransaction`,
|
which in addition to the methods provided by
|
:class:`.Transaction`, also provides a
|
:meth:`~.TwoPhaseTransaction.prepare` method.
|
|
:param xid: the two phase transaction id. If not supplied, a
|
random id will be generated.
|
|
.. seealso::
|
|
:meth:`_engine.Connection.begin`
|
|
:meth:`_engine.Connection.begin_twophase`
|
|
NzOCannot start a two phase transaction when a transaction is already in progress.)rL r r¶ rP rU Z
|
create_xidr½ )r` r¾ rb rb rc Úbegin_twophase© s
|
ÿ zConnection.begin_twophasec C s | j r| j ¡ dS )a 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 :class:`_engine.Connection` automatically
|
whenever a statement is first executed, or when the
|
:meth:`_engine.Connection.begin` method is called.
|
|
.. note:: The :meth:`_engine.Connection.commit` method only acts upon
|
the primary database transaction that is linked to the
|
:class:`_engine.Connection` object. It does not operate upon a
|
SAVEPOINT that would have been invoked from the
|
:meth:`_engine.Connection.begin_nested` method; for control of a
|
SAVEPOINT, call :meth:`_engine.NestedTransaction.commit` on the
|
:class:`_engine.NestedTransaction` that is returned by the
|
:meth:`_engine.Connection.begin_nested` method itself.
|
|
|
N)rL Úcommitrn rb rb rc rÀ Æ s zConnection.commitc C s | j r| j ¡ dS )aY 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 :class:`_engine.Connection` automatically
|
whenever a statement is first executed, or when the
|
:meth:`_engine.Connection.begin` method is called.
|
|
.. note:: The :meth:`_engine.Connection.rollback` method only acts
|
upon the primary database transaction that is linked to the
|
:class:`_engine.Connection` object. It does not operate upon a
|
SAVEPOINT that would have been invoked from the
|
:meth:`_engine.Connection.begin_nested` method; for control of a
|
SAVEPOINT, call :meth:`_engine.NestedTransaction.rollback` on the
|
:class:`_engine.NestedTransaction` that is returned by the
|
:meth:`_engine.Connection.begin_nested` method itself.
|
|
|
N)rL Úrollbackrn rb rb rc rÁ ß s zConnection.rollbackz List[Any]c C s | j j | ¡S r )rP rU Zdo_recover_twophasern rb rb rc Úrecover_twophaseù s zConnection.recover_twophase)r¾ Úrecoverrf c C s | j jj| ||d d S ©N)rà )rP rU Údo_rollback_twophase©r` r¾ rà rb rb rc Úrollback_preparedü s z Connection.rollback_preparedc C s | j jj| ||d d S rÄ )rP rU Údo_commit_twophaserÆ rb rb rc Úcommit_preparedÿ s zConnection.commit_preparedc C s | j dk o| j jS ©z,Return True if a transaction is in progress.N)rL Ú is_activern rb rb rc Úin_transaction s zConnection.in_transactionc C s | j dk o| j jS rÊ )rM rË rn rb rb rc Úin_nested_transaction s
|
þz Connection.in_nested_transactionc C s0 | j dd ¡}t|dkp,|d ko,| jjjdkS )Nr Z
|
AUTOCOMMIT)rK r rO rP rU Z_on_connect_isolation_level)r` Zopt_isorb rb rc Ú_is_autocommit_isolation s ÿüz#Connection._is_autocommit_isolationc C s | j }|d krt d¡|S )Nz"connection is not in a transaction)rL r r¶ ©r` Ztransrb rb rc Ú_get_required_transaction s
|
z$Connection._get_required_transactionc C s | j }|d krt d¡|S )Nz)connection is not in a nested transaction)rM r r¶ rÏ rb rb rc Ú _get_required_nested_transaction s ÿz+Connection._get_required_nested_transactionc C s | j S )zaReturn the current root transaction in progress, if any.
|
|
.. versionadded:: 1.4
|
|
)rL rn rb rb rc Úget_transaction& s zConnection.get_transactionc C s | j S )zcReturn the current nested transaction in progress, if any.
|
|
.. versionadded:: 1.4
|
|
)rM rn rb rb rc Úget_nested_transaction/ s z!Connection.get_nested_transaction)Ú transactionrf c
|
C s | j r$| ¡ r| d¡ n
|
| d¡ d| _| js8| jjrD| j | ¡ zNz| jj | j
|
¡ W n4 t k
|
r } z| |d d d d ¡ W 5 d }~X Y nX W 5 d| _X d S )Nz?BEGIN (implicit; DBAPI should not BEGIN due to autocommit mode)zBEGIN (implicit)TF) r^ rÎ r} r[ rR rP rH r¸ rU Zdo_beginrQ r¨ r© ©r` rÔ r« rb rb rc Ú _begin_impl7 s ÿ
|
(zConnection._begin_implc
|
C s | j s| jj r| j | ¡ | jr| jrD| ¡ r:| d¡ n
|
| d¡ z| jj | j
|
¡ W n4 t k
|
r } z| |d d d d ¡ W 5 d }~X Y nX d S )NzVROLLBACK using DBAPI connection.rollback(), DBAPI should ignore due to autocommit modeZROLLBACK) rR rP rH rÁ r¡ r^ rÎ r} rU Z do_rollbackrQ r¨ r© rª rb rb rc Ú_rollback_implM s ÿ
|
zConnection._rollback_implc
|
C s | j s| jj r| j | ¡ | jr>| ¡ r4| d¡ n
|
| d¡ z| jj | j ¡ W n4 t
|
k
|
r } z| |d d d d ¡ W 5 d }~X Y nX d S )NzRCOMMIT using DBAPI connection.commit(), DBAPI should ignore due to autocommit modeZCOMMIT) rR rP rH rÀ r^ rÎ r} rU Z do_commitrQ r¨ r© rª rb rb rc Ú _commit_impl_ s ÿ
|
zConnection._commit_impl)r rf c C sP | j s| jj r | j | |¡ |d kr<| jd7 _d| j }| jj | |¡ |S )Nr zsa_savepoint_%s)rR rP rH Z savepointrZ rU Z do_savepoint©r` r rb rb rc Ú_savepoint_implq s
|
zConnection._savepoint_implc C s8 | j s| jj r | j | |d ¡ | jr4| jj | |¡ d S r )rR rP rH Zrollback_savepointr¡ rU Zdo_rollback_to_savepointrÙ rb rb rc Ú_rollback_to_savepoint_impl{ s z&Connection._rollback_to_savepoint_implc C s2 | j s| jj r | j | |d ¡ | jj | |¡ d S r )rR rP rH Zrelease_savepointrU Zdo_release_savepointrÙ rb rb rc Ú_release_savepoint_impl s z"Connection._release_savepoint_implc
|
C s | j r| d¡ | js | jjr.| j | |j¡ d| _zPz| jj | |j¡ W n4 t
|
k
|
r } z| |d d d d ¡ W 5 d }~X Y nX W 5 d| _X d S )NzBEGIN TWOPHASE (implicit)TF) r^ r} rR rP rH r¿ r¾ r[ rU Zdo_begin_twophaser¨ r© rÕ rb rb rc Ú_begin_twophase_impl s
|
(z Connection._begin_twophase_implc
|
C sz | j s| jj r | j | |¡ t| jts,tz| jj | |¡ W n4 t
|
k
|
rt } z| |d d d d ¡ W 5 d }~X Y nX d S r ) rR rP rH Zprepare_twophaseÚ
|
isinstancerL r½ r rU Zdo_prepare_twophaser¨ r© )r` r¾ r« rb rb rc Ú_prepare_twophase_impl s z!Connection._prepare_twophase_impl)r¾ Ú is_preparedrf c
|
C s | j s| jj r | j | ||¡ | jrt| jts4tz| jj
|
| ||¡ W n4 t k
|
r~ } z| |d d d d ¡ W 5 d }~X Y nX d S r ) rR rP rH Zrollback_twophaser¡ rÞ rL r½ r rU rÅ r¨ r© ©r` r¾ rà r« rb rb rc Ú_rollback_twophase_impl s ÿz"Connection._rollback_twophase_implc
|
C s~ | j s| jj r | j | ||¡ t| jts.tz| jj | ||¡ W n4 t
|
k
|
rx } z| |d d d d ¡ W 5 d }~X Y nX d S r ) rR rP rH Zcommit_twophaserÞ rL r½ r rU rÈ r¨ r© rá rb rb rc Ú_commit_twophase_impl s z Connection._commit_twophase_implc C sZ | j r| j ¡ d}nd}| jdk rP| j}|rBtd|jdd n| ¡ d| _d| _dS )aß Close this :class:`_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 :class:`_pool.Pool` referenced
|
by the :class:`_engine.Engine` that produced this
|
:class:`_engine.Connection`. Any transactional state present on
|
the DBAPI connection is also unconditionally released via
|
the DBAPI connection's ``rollback()`` method, regardless
|
of any :class:`.Transaction` object that may be
|
outstanding with regards to this :class:`_engine.Connection`.
|
|
This has the effect of also calling :meth:`_engine.Connection.rollback`
|
if any transaction is in place.
|
|
After :meth:`_engine.Connection.close` is called, the
|
:class:`_engine.Connection` is permanently in a closed state,
|
and will allow no further operations.
|
|
TFNr4 )Ztransaction_reset)rL r rJ r Z_close_specialr\ )r` Z
|
skip_resetÚconnrb rb rc r · s
|
|
|
ÿzConnection.close©r zTypedReturnsRows[Tuple[_T]]z"Optional[_CoreSingleExecuteParams]z%Optional[CoreExecuteOptionsParameter]z Optional[_T])Ú statementÚ
|
parametersr rf c C s d S r rb ©r` ræ rç r rb rb rc Úscalarç s zConnection.scalarr7 c C s d S r rb rè rb rb rc ré ñ s c
|
C sV t |}z
|
|j}W n. tk
|
r@ } zt |¡|W 5 d}~X Y nX || ||pNtS dS )au Executes a SQL statement construct and returns a scalar object.
|
|
This method is shorthand for invoking the
|
:meth:`_engine.Result.scalar` method after invoking the
|
:meth:`_engine.Connection.execute` method. Parameters are equivalent.
|
|
:return: a scalar Python value representing the first column of the
|
first row returned.
|
|
N)r Z_execute_on_scalarÚAttributeErrorr ÚObjectNotExecutableErrorrE ©r` ræ rç r Údistilled_parametersÚmethra rb rb rc ré û s
|
ýz Optional[_CoreAnyExecuteParams]zScalarResult[_T]c C s d S r rb rè rb rb rc Úscalars s zConnection.scalarszScalarResult[Any]c C s d S r rb rè rb rb rc rï " s c C s | j |||d ¡ S )aÐ Executes and returns a scalar result set, which yields scalar values
|
from the first column of each row.
|
|
This method is equivalent to calling :meth:`_engine.Connection.execute`
|
to receive a :class:`_result.Result` object, then invoking the
|
:meth:`_result.Result.scalars` method to produce a
|
:class:`_result.ScalarResult` instance.
|
|
:return: a :class:`_result.ScalarResult`
|
|
.. versionadded:: 1.4.24
|
|
rå )Úexecuterï rè rb rb rc rï , s
|
ÿzTypedReturnsRows[_T]zCursorResult[_T]c C s d S r rb rè rb rb rc rð E s zConnection.executezCursorResult[Any]c C s d S r rb rè rb rb rc rð O s c
|
C sV t |}z
|
|j}W n. tk
|
r@ } zt |¡|W 5 d}~X Y nX || ||pNtS dS )a¼ Executes a SQL statement construct and returns a
|
:class:`_engine.CursorResult`.
|
|
:param statement: The statement to be executed. This is always
|
an object that is in both the :class:`_expression.ClauseElement` and
|
:class:`_expression.Executable` hierarchies, including:
|
|
* :class:`_expression.Select`
|
* :class:`_expression.Insert`, :class:`_expression.Update`,
|
:class:`_expression.Delete`
|
* :class:`_expression.TextClause` and
|
:class:`_expression.TextualSelect`
|
* :class:`_schema.DDL` and objects which inherit from
|
:class:`_schema.ExecutableDDLElement`
|
|
:param parameters: parameters 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.
|
|
: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:`_engine.Connection.execution_options`.
|
|
:return: a :class:`_engine.Result` object.
|
|
N)r Z_execute_on_connectionrê r rë rE rì rb rb rc rð Y s &
|
ýzFunctionElement[Any]r' r- )Úfuncrí r rf c C s | | ¡ ||¡S )z%Execute a sql.FunctionElement object.)Ú_execute_clauseelementÚselect)r` rñ rí r rb rb rc Ú_execute_function s
|
ÿz Connection._execute_functionr> )Údefaultrí r rf c
|
C sô | j |¡}| js| jjr2| |||¡\}}}}nd }}z2| j}|dkrR| ¡ }| j}|j || ||¡}W nP t
|
j t
|
j fk
|
r Y n4 t k
|
r¼ } z| | dddd¡ W 5 d} ~ X Y nX | d|d¡}
|
| jsÚ| jjrð| j | |||||
|
¡ |
|
S )z&Execute a schema.ColumnDefault object.N)rK Ú
|
merge_withrR rP Ú_invoke_before_exec_eventrJ r¥ rU Úexecution_ctx_clsZ _init_defaultr r¦ r§ r¨ r© Z _exec_defaultrH Ú after_execute) r` rõ rí r Úevent_multiparamsÚ event_paramsrä rU Úctxr« Úretrb rb rc Ú_execute_default sT ÿ ÿûü ÿ$ú zConnection._execute_defaultr: )Úddlrí r rf c C sª |j | j |¡}| js | jjr6| |||¡\}}}}nd }}| j |¡}| dd¡}| j}|j||d} | ||j j
|
| d|| ¡}
|
| js| jjr¦| j | |||||
|
¡ |
|
S )z Execute a schema.DDL object.Nr )rU r ) rK rö rR rP r÷ r rU ÚcompileÚ_execute_contextrø Z _init_ddlrH rù ) r` rÿ rí r rú rû Z exec_optsr rU Úcompiledrý rb rb rc Ú _execute_ddlÒ sT ÿ ÿûü ÿúúzConnection._execute_ddlzVTuple[Any, _CoreMultiExecuteParams, _CoreMultiExecuteParams, _CoreSingleExecuteParams])ÚelemÚdistilled_paramsr rf c C s t |dkr g |d }}n
|
|i }}| jjD ]}|| ||||\}}}q.|rft|}|rvt d¡n|rr|g}ng }||||fS )Nr r zLEvent handler can't return non-empty multiparams and params at the same time)ÚlenrH Zbefore_executeÚlistr r¶ )r` r r r rú rû Úfnrb rb rc r÷ s*
|
û ÿz$Connection._invoke_before_exec_event)r rí r rf c C sæ |j | j |¡}| jp | jj}|r8| |||¡\}}}}|rVt|d }t|dk}ng }d}| j} | dd¡}
|
| d| jj ¡} |j
|
| | |||
|
| jj t j B d\} } }| j| | jj| ||| ||| |d
|
}|râ| j | |||||¡ |S ) z#Execute a sql.ClauseElement object.r r Fr Nr )rU r Z column_keysÚfor_executemanyr Zlinting)Ú cache_hit)rK rö rR rP r÷ Úsortedr rU r Ú_compiled_cacheZ_compile_w_cacheZcompiler_lintingr! Z WARN_LINTINGr rø Ú_init_compiledrH rù )r` r rí r Z
|
has_eventsrú rû Úkeysr rU r r Z compiled_sqlZextracted_paramsr
|
rý rb rb rc rò 3 sx ÿ ÿû ÿ ÿ ú ö úz!Connection._execute_clauseelementr9 )r rí r rf c C s |j | j|¡}| js | jjr4| |||¡\}}}}| j}| ||jj |||||dd¡ }| jsf| jjr|| j
|
| |||||¡ |S )ziExecute a sql.Compiled object.
|
|
TODO: why do we have this? likely deprecate or remove
|
|
N) r rö rK rR rP r÷ rU r rø r rH rù )r` r rí r rú rû rU rý rb rb rc Ú_execute_compiled| sJ ÿ ÿû÷ úz Connection._execute_compiledú Optional[_DBAPIAnyExecuteParams]c C s8 t |}| j |¡}| j}| ||jj|d|||¡}|S )a Executes a SQL statement construct and returns a
|
:class:`_engine.CursorResult`.
|
|
:param statement: The statement str to be executed. Bound parameters
|
must use the underlying DBAPI's paramstyle, such as "qmark",
|
"pyformat", "format", etc.
|
|
:param parameters: represent bound parameter values to be used in the
|
execution. The format is one of: a dictionary of named parameters,
|
a tuple of positional parameters, or a list containing either
|
dictionaries or tuples for multiple-execute support.
|
|
E.g. multiple dictionaries::
|
|
|
conn.exec_driver_sql(
|
"INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)",
|
[{"id":1, "value":"v1"}, {"id":2, "value":"v2"}]
|
)
|
|
Single dictionary::
|
|
conn.exec_driver_sql(
|
"INSERT INTO table (id, value) VALUES (%(id)s, %(value)s)",
|
dict(id=1, value="v1")
|
)
|
|
Single tuple::
|
|
conn.exec_driver_sql(
|
"INSERT INTO table (id, value) VALUES (?, ?)",
|
(1, 'v1')
|
)
|
|
.. note:: The :meth:`_engine.Connection.exec_driver_sql` method does
|
not participate in the
|
:meth:`_events.ConnectionEvents.before_execute` and
|
:meth:`_events.ConnectionEvents.after_execute` events. To
|
intercept calls to :meth:`_engine.Connection.exec_driver_sql`, use
|
:meth:`_events.ConnectionEvents.before_cursor_execute` and
|
:meth:`_events.ConnectionEvents.after_cursor_execute`.
|
|
.. seealso::
|
|
:pep:`249`
|
|
N)r rK rö rU r rø Z_init_statement)r` ræ rç r rí rU rý rb rb rc Úexec_driver_sql® s 6ÿù
|
zConnection.exec_driver_sqlr. z Callable[..., ExecutionContext]zUnion[str, Compiled]z Optional[_AnyMultiExecuteParams])rU Ú constructorræ rç r Úargsrt rf c
|
O s( |r$| dd¡}|r$| d|d¡}z0| j} | dkr<| ¡ } ||| | |f||}
|
W nT tjtjfk
|
rr Y n8 tk
|
r¨ } z| | t ||dd¡ W 5 d} ~ X Y nX | j
|
r¸| j
|
j rÆ| j rÐ| j j sÐ| ¡ n| jràt | ¡ | j
|
dkrò| ¡ |
|
¡ |
|
jtjkr| ||
|
¡S | ||
|
||¡S dS )zdCreate an :class:`.ExecutionContext` and execute, returning
|
a :class:`_engine.CursorResult`.r NT)r r )r r rJ r¥ r r¦ r§ r¨ r© rp rL rË rM r² rI r Ú_trans_ctx_checkr¹ Zpre_execÚ execute_styler ZINSERTMANYVALUESÚ_exec_insertmany_contextÚ_exec_single_context) r` rU r ræ rç r r rt Zyprä Úcontextr« rb rb rc r ÷ sn ÿ ÿÿÿ ÿÿþüû
|
|
|
þ ÿzConnection._execute_contextr )rU r ræ rç rf c
|
C s¬ |j tjkrf| ¡ }|rfz| |j||¡ W n8 tk
|
rd } z| |t||d|¡ W 5 d}~X Y nX |j|j |j
|
}}}|j s|d } n|} | j s| j j rÄ| jjD ] }
|
|
|
| ||| ||j \}} q¦| jr| |¡ | ¡ } | j js| d| tj| d|j d¡ n | d| ¡ d} zX|jtjkrtd| } | jj rh| jjjD ] }
|
|
|
||| |rFd } qhqF| s4| j ||| |¡ n²| sÜ|j rÜ| jj rÄ| jjj D ] }
|
|
|
|||r¤d } qÄq¤| s4| j |||¡ nXtd
|
| } | jj r | jjj D ] }
|
|
|
||| |rúd } q qú| s4| j ||| |¡ | j sF| j j r^| j | ||| ||j ¡ | ¡ | !¡ } W n6 tk
|
r¦ } z| ||| ||¡ W 5 d}~X Y nX | S ) zzcontinue the _execute_context() method for a single DBAPI
|
cursor.execute() or cursor.executemany() call.
|
|
Nr ú[%s] %ré
|
©ZbatchesÚismultiú8[%s] [SQL parameters hidden due to hide_parameters=True]Fr' Tr( )"Ú bind_typingr Ú SETINPUTSIZESÚ_prepare_set_input_sizesÚdo_set_input_sizesÚcursorr¨ r© rp ræ rç Ú executemanyrR rP rH Úbefore_cursor_executer^ r} Ú_get_cache_statsÚhide_parametersÚsql_utilÚ _repr_paramsr r Z EXECUTEMANYr rU Zdo_executemanyr Zdo_execute_no_paramsÚ
|
do_executeÚafter_cursor_executeÚ post_execÚ_setup_result_proxy)r` rU r ræ rç Úgeneric_setinputsizesr« r" Ú str_statementÚeffective_parametersr ÚstatsZ evt_handledÚresultrb rb rc r 5 s ÿ ÿý
|
|
ú
|
|
|
ýý
|
þ ÿ
|
ü
|
ü
|
|
ÿ ÿ
|
ü
|
ÿú ÿz Connection._exec_single_context)rU r rf c C s |j tjkr| ¡ }nd}|j|j|j }}}|}| jp@| jj}| j jrV| j j
|
j } nd} | j rl| ¡ d }
|
| |||||¡D ]Ì} | jràz| |j| j|¡ W n> tk
|
rÞ } z | | t | j¡| jd|¡ W 5 d} ~ X Y nX | j} | j}|r| j
|
jD ]}|| || ||d\} }qú| j r¸| t | ¡¡ d| j d| j d| jrLdnd | j r\d
|
nd d }| jd kr||
|
|7 }
|
n
|
d| }
|
| jj s¬| d|
|
tj |ddd¡ n | d|
|
¡ z6| D ] }||| ||r¾ qìq¾| || ||¡ W n@ tk
|
r. } z | j| t | ¡|||dd W 5 d} ~ X Y nX |r~| j
|
| |||||j ¡ q~z| !¡ | "¡ }W n6 tk
|
r } z| | ||||¡ W 5 d} ~ X Y nX |S )zÒcontinue the _execute_context() method for an "insertmanyvalues"
|
operation, which will invoke DBAPI
|
cursor.execute() one or more times with individual log and
|
event hook calls.
|
|
Nrb z (insertmanyvalues)Tú ú/z (ZorderedÚ unorderedz; batch not supportedr° ú)r Zinsertmanyvaluesr r Fr r )Ú is_sub_exec)#r r r r r" ræ rç rR rP rU rH r) r^ r% Z!_deliver_insertmanyvalues_batchesZprocessed_setinputsizesr! r¨ r© r' Z_long_statementZreplaced_statementZreplaced_parametersr$ r} ZbatchnumZ total_batchesZ rows_sortedZ is_downgradedr& r( r* r# r+ r, )r` rU r r- r" r. rç r/ Z engine_eventsZdo_execute_dispatchr0 Z imv_batchr« Zsub_stmtZ
|
sub_paramsr Z imv_statsr1 rb rb rc r Ä sü
|
ý
|
þ û
|
ý
|
û ú
|
ÿÿÿýÿù
|
|
|
|
ýý
|
ýü
|
üú ú ÿz#Connection._exec_insertmany_contextr r* úOptional[ExecutionContext])r" ræ rç r rf c
|
C sð | j s| jj r2| jjD ]}|| ||||d\}}q| jrN| |¡ | d|¡ zD| jj s\dn| jjjD ]}|||||rf qqf| j ||||¡ W n4 tk
|
rÆ } z| |||||¡ W 5 d}~X Y nX | j sÖ| jj rì| j
|
| ||||d¡ dS )a_ 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().
|
|
Fz [raw sql] %rrb N) rR rP rH r$ r^ r} rU r) r¨ r© r* )r` r" ræ rç r r r« rb rb rc Ú_cursor_executec sL ÿ
|
|
ÿý ÿ ÿzConnection._cursor_execute)r" rf c C s: z | ¡ W n( tk
|
r4 | jjjjddd Y nX dS )z\Close the given cursor, catching exceptions
|
and turning into log warnings.
|
|
zError closing cursorT)Úexc_infoN)r Ú ExceptionrP Úpoolry Úerror)r` r" rb rb rc Ú_safe_close_cursor s
|
ÿz Connection._safe_close_cursorr¨ zOptional[_AnyExecuteParams]úOptional[DBAPICursor])r« ræ rç r" r r6 rf c C sè t ¡ }t |¡}| jsZt|| jjjrL| j rL| j
|
|| j sD| j nd |¡pV|oV| j | _| } |d k rt| ov|j nd}
|
| jr°tjj|||| jjj| jj| j|
|
d |d ¡|d| _zÜt|| jjjpÞ|d k oÞ|d koÞ| } | rtjj||tt|| jjj| jj| j| j|
|
d} nd } d }| jjrð| j dd¡sðt || | j| j| ||||| j| d }| jj j D ]\}z ||}|d k r| |_!}W n4 tk
|
rÀ } z|}W Y ¢
|
qÆW 5 d }~X Y nX qh| j|j
|
krê|j
|
| _| rê|j
|
| _"|j#} | r|r| $|¡ | js0|r | %|¡ | &¡ s0| '¡ |rH| |d ¡|nJ| rn| d k s\t| |d ¡|n$|d d k st|d |d ¡W 5 | `| jrâ| `| j sâ| j } | d k sÂt| rØ| jj | |¡ | |¡ X d S )NF)r& rU r r T)r& Úconnection_invalidatedrU r Zskip_user_error_eventsr )(Úsysr9 r Úis_exit_exceptionÚ_is_disconnectrÞ rU rW rX r£ Ú is_disconnectr¤ rJ r# Ú_reentrant_errorr Ú
|
DBAPIErrorÚinstancerP r& Úwith_tracebackr r; Z _invalidaterµ r r: rR rK r ÚExceptionContextImplrH Ú handle_errorÚchained_exceptionr? Ú invalidate_pool_on_disconnectZhandle_dbapi_exceptionr= rÌ r× )r` r« ræ rç r" r r6 r9 rA rK r Zdbapi_conn_wrapperÚ should_wrapÚsqlalchemy_exceptionÚnewraiserü r Úper_fnÚ_raisedrb rb rc r© ¡ sÜ
|
ÿýý
|
ø
|
ÿýùøø ÿýø ÿô
|
"ÿÿ
|
|
|
z"Connection._handle_dbapi_exceptionúOptional[Engine])r« rU rP rC rK Ú is_pre_pingrf c C s t ¡ }|d kr,t||jjo*| |d d ¡}t||jj}|rrtjjd d t t
|
||jj|d k rd|j nd||d} nd } d }
|
|j r t || ||d d d d d ||| } |jjD ]T} z | | } | d k rÈ| | _}
|
W q¨ t
|
k
|
rú } z|}
|
W Y ¢ qþW 5 d }~X Y q¨X q¨| r || jkr | j | _}|
|
r4|
|
|d ¡|nJ|rZ| d k sHt| |d ¡|n$|d d k slt|d |d ¡d S )NF)r& r? rU r r )r@ r9 rÞ rW rX rC r rE rF r r: r& rR rH rH rI rJ r? rG r )Úclsr« rU rP rC rK rR r9 rL rM rN rü r rO rP rb rb rc rY 2 sr
|
ÿ þÿ÷ ô þz/Connection._handle_dbapi_exception_noconnectionú+Type[Union[SchemaGenerator, SchemaDropper]]r@ ©ÚvisitorcallableÚelementÚkwargsrf c K s || j | f| |¡ dS )z®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.
|
|
N)rU Ztraverse_single)r` rV rW rX rb rb rc Ú_run_ddl_visitor s zConnection._run_ddl_visitor)NNTT)N)N)F)F)N)N)N)N)N)N)N)N)N)N)NN)N)F)NNTF)RÚ__name__Ú
|
__module__Ú __qualname__Ú__doc__Ú__annotations__Ú_sqla_logger_namespacerI Zshould_close_with_resultrd r Zmemoized_propertyro r} r Úpropertyr r r r r r r r¡ r£ r¤ rQ r® r¯ r² r¥ rz rµ r· r¹ r¸ r¼ r¿ rÀ rÁ r rÇ rÉ rÌ rÍ rÎ rÐ rÑ rÒ rÓ rÖ r× rØ rÚ rÛ rÜ rÝ rß râ rã r ré rï rð rô rþ r r÷ rò rD r r r r r r8 r= rD rB r© Ú classmethodrY rY rb rb rb rc rF W s6
|
ú- õ( } , ;$LN
|
|
|
0 ýû ýû ýû ýû ýû ýûýû ýû ýû2 ;6+Mü5 üI > %û. ù ù LrF r0 c @ s8 e Zd ZdZdZddddddd d
|
d d d d d ddZdS )rH z3Implement the :class:`.ExceptionContext` interface.) rQ rP rU r" ræ rç Úoriginal_exceptionrM rJ Úexecution_contextrC rK rR r¨ z Optional[exc.StatementError]rQ r. úOptional[Connection]r> r r r7 rO ) r´ rM rP rU rQ r" ræ rç r rC rK rR c C sF || _ || _|| _|| _|| _| | _|| _|| _|
|
| _| | _ | | _
|
d S r ) rP rU rQ rM rb rc ræ rç rC rK rR ) r` r´ rM rP rU rQ r" ræ rç r rC rK rR rb rb rc rd ¡ s z ExceptionContextImpl.__init__N)rZ r[ r\ r] Ú __slots__rd rb rb rb rc rH s rH c @ sð e Zd ZU dZdZdZded< ded< ded< dd d
|
d Zedd d dZ dd ddZ
|
dd ddZ dd ddZ edd ddZ dd ddZdd ddZdd d d Zdd d d Zdd d d!Zdd d"d#Zdd d$d%Zd&S )'Ú Transactiona} Represent a database transaction in progress.
|
|
The :class:`.Transaction` object is procured by
|
calling the :meth:`_engine.Connection.begin` method of
|
:class:`_engine.Connection`::
|
|
from sqlalchemy import create_engine
|
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
|
connection = engine.connect()
|
trans = connection.begin()
|
connection.execute(text("insert into x (a, b) values (1, 2)"))
|
trans.commit()
|
|
The object provides :meth:`.rollback` and :meth:`.commit`
|
methods in order to control transaction boundaries. It
|
also implements a context manager interface so that
|
the Python ``with`` statement can be used with the
|
:meth:`_engine.Connection.begin` method::
|
|
with connection.begin():
|
connection.execute(text("insert into x (a, b) values (1, 2)"))
|
|
The Transaction object is **not** threadsafe.
|
|
.. seealso::
|
|
:meth:`_engine.Connection.begin`
|
|
:meth:`_engine.Connection.begin_twophase`
|
|
:meth:`_engine.Connection.begin_nested`
|
|
.. index::
|
single: thread safety; Transaction
|
rb FrO Ú_is_rootrË rF rQ ©rQ c C s
|
t d S r ©ÚNotImplementedError©r` rQ rb rb rc rd è s zTransaction.__init__re c C s
|
t dS )zTrue if this transaction is totally deactivated from the connection
|
and therefore can no longer affect its state.
|
|
Nri rn rb rb rc Ú _deactivated_from_connectionë s z(Transaction._deactivated_from_connectionrq c C s
|
t d S r ri rn rb rb rc Ú _do_closeó s zTransaction._do_closec C s
|
t d S r ri rn rb rb rc Ú _do_rollbackö s zTransaction._do_rollbackc C s
|
t d S r ri rn rb rb rc Ú
|
_do_commitù s zTransaction._do_commitc C s | j o| jj S r )rË rQ r¤ rn rb rb rc r ü s zTransaction.is_validc C s z | ¡ W 5 | j rtX dS )a; Close this :class:`.Transaction`.
|
|
If this transaction is the base transaction in a begin/commit
|
nesting, the transaction will rollback(). Otherwise, the
|
method returns.
|
|
This is used to cancel a Transaction without affecting the scope of
|
an enclosing transaction.
|
|
N)rË r rm rn rb rb rc r
|
s zTransaction.closec C s z | ¡ W 5 | j rtX dS )aí Roll back this :class:`.Transaction`.
|
|
The implementation of this may vary based on the type of transaction in
|
use:
|
|
* For a simple database transaction (e.g. :class:`.RootTransaction`),
|
it corresponds to a ROLLBACK.
|
|
* For a :class:`.NestedTransaction`, it corresponds to a
|
"ROLLBACK TO SAVEPOINT" operation.
|
|
* For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
|
phase transactions may be used.
|
|
|
N)rË r rn rn rb rb rc rÁ
|
s zTransaction.rollbackc C s z | ¡ W 5 | j rtX dS )aã Commit this :class:`.Transaction`.
|
|
The implementation of this may vary based on the type of transaction in
|
use:
|
|
* For a simple database transaction (e.g. :class:`.RootTransaction`),
|
it corresponds to a COMMIT.
|
|
* For a :class:`.NestedTransaction`, it corresponds to a
|
"RELEASE SAVEPOINT" operation.
|
|
* For a :class:`.TwoPhaseTransaction`, DBAPI-specific methods for two
|
phase transactions may be used.
|
|
N)rË r ro rn rb rb rc rÀ &
|
s zTransaction.commitc C s | j S r rh rn rb rb rc Ú _get_subject;
|
s zTransaction._get_subjectc C s | j S r )rË rn rb rb rc Ú_transaction_is_active>
|
s z"Transaction._transaction_is_activec C s | j S r )rl rn rb rb rc Ú_transaction_is_closedA
|
s z"Transaction._transaction_is_closedc C s dS ©NTrb rn rb rb rc Ú_rollback_can_be_calledD
|
s z#Transaction._rollback_can_be_calledN)rZ r[ r\ r] re rg r^ rd r` rl rm rn ro r r rÁ rÀ rp rq rr rt rb rb rb rc rf ½ s(
|
$ rf c @ s¬ e Zd ZdZdZdZddddZdd d
|
d Zed d d dZ dd ddZ
|
dd ddZ dd ddZ d d ddddZ dd ddZdd dd Zdd d d Zd S )!rº aý Represent the "root" transaction on a :class:`_engine.Connection`.
|
|
This corresponds to the current "BEGIN/COMMIT/ROLLBACK" that's occurring
|
for the :class:`_engine.Connection`. The :class:`_engine.RootTransaction`
|
is created by calling upon the :meth:`_engine.Connection.begin` method, and
|
remains associated with the :class:`_engine.Connection` throughout its
|
active span. The current :class:`_engine.RootTransaction` in use is
|
accessible via the :attr:`_engine.Connection.get_transaction` method of
|
:class:`_engine.Connection`.
|
|
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:`_engine.Connection.commit` and
|
:meth:`_engine.Connection.rollback` methods.
|
|
|
T)rQ rË rF rh c C s< |j d kst|jr t |¡ || _| ¡ | |_ d| _d S rs )rL r rI r r rQ Ú_connection_begin_implrË rk rb rb rc rd f
|
s
|
zRootTransaction.__init__rq re c C s8 | j r | jj| kstd| _ n| jj| k r4t d¡ d S )NFz0transaction already deassociated from connection)rË rQ rL r r Úwarnrn rb rb rc Ú_deactivate_from_connectionp
|
s
|
z+RootTransaction._deactivate_from_connectionrO c C s | j j| k S r )rQ rL rn rb rb rc rl x
|
s z,RootTransaction._deactivated_from_connectionc C s | j | ¡ d S r )rQ rÖ rn rb rb rc ru |
|
s z&RootTransaction._connection_begin_implc C s | j ¡ d S r )rQ r× rn rb rb rc Ú_connection_rollback_impl
|
s z)RootTransaction._connection_rollback_implc C s | j ¡ d S r )rQ rØ rn rb rb rc Ú_connection_commit_impl
|
s z'RootTransaction._connection_commit_implF)Útry_deactivaterf c C sn z&| j r| ¡ | jjr$| jj ¡ W 5 | j s2|r:| ¡ | jj| krNd | j_X | j rZt| jj| k sjtd S r )rË rw rQ rL rx rM Ú_cancelr )r` rz rb rb rc Ú _close_impl
|
s
|
|
|
zRootTransaction._close_implc C s | ¡ d S r ©r| rn rb rb rc rm
|
s zRootTransaction._do_closec C s | j dd d S )NT)rz r} rn rb rb rc rn
|
s z RootTransaction._do_rollbackc C s | j rL| jj| kstz | ¡ W 5 | jjr8| jj ¡ | ¡ X d | j_n"| jj| krd| j ¡ n
|
t
|
d¡| j rxt| jj| k std S )Nú This transaction is inactive) rË rQ rL r rM r{ rw ry r² r r¶ rn rb rb rc ro
|
s
|
|
|
|
zRootTransaction._do_commitN)F)rZ r[ r\ r] rg re rd rw r` rl ru rx ry r| rm rn ro rb rb rb rc rº L
|
s
|
rº c @ s e Zd ZU dZdZded< ddddZd d
|
d d d dZed
|
dddZ d dddZ
|
d
|
d
|
d dddZ d dddZ d dddZ d ddd Zd S ) r» a Represent a 'nested', or SAVEPOINT transaction.
|
|
The :class:`.NestedTransaction` object is created by calling the
|
:meth:`_engine.Connection.begin_nested` method of
|
:class:`_engine.Connection`.
|
|
When using :class:`.NestedTransaction`, the semantics of "begin" /
|
"commit" / "rollback" are as follows:
|
|
* the "begin" operation corresponds to the "BEGIN SAVEPOINT" command, where
|
the savepoint is given an explicit name that is part of the state
|
of this object.
|
|
* The :meth:`.NestedTransaction.commit` method corresponds to a
|
"RELEASE SAVEPOINT" operation, using the savepoint identifier associated
|
with this :class:`.NestedTransaction`.
|
|
* The :meth:`.NestedTransaction.rollback` method corresponds to a
|
"ROLLBACK TO SAVEPOINT" operation, using the savepoint identifier
|
associated with this :class:`.NestedTransaction`.
|
|
The rationale for mimicking the semantics of an outer transaction in
|
terms of savepoints so that code may deal with a "savepoint" transaction
|
and an "outer" transaction in an agnostic way.
|
|
.. seealso::
|
|
:ref:`session_begin_nested` - ORM version of the SAVEPOINT API.
|
|
)rQ rË Ú
|
_savepointÚ_previous_nestedrp r rF rh c C sH |j d k st|jr t |¡ || _| j ¡ | _d| _|j | _
|
| |_ d S rs ) rL r rI r r rQ rÚ r rË rM r rk rb rb rc rd Ü
|
s
|
zNestedTransaction.__init__TrO rq )rv rf c C s* | j j| kr| j| j _n|r&t d¡ d S )Nz7nested transaction already deassociated from connection)rQ rM r r rv )r` rv rb rb rc rw æ
|
s ÿz-NestedTransaction._deactivate_from_connectionre c C s | j j| k S r )rQ rM rn rb rb rc rl î
|
s z.NestedTransaction._deactivated_from_connectionc C s" d| _ | ¡ | jr | j ¡ d S ©NF)rË rw r r{ rn rb rb rc r{ ò
|
s zNestedTransaction._cancel)Údeactivate_from_connectionÚwarn_already_deactiverf c C sf z*| j r(| jjr(| jjj r(| j | j¡ W 5 d| _ |rB| j|d X | j rNt|rb| jj| k sbtd S )NF)rv )rË rw rQ rL rÛ r r rM )r` r r rb rb rc r| û
|
s ÿþý
|
z NestedTransaction._close_implc C s | dd¡ d S )NTFr} rn rb rb rc rm s zNestedTransaction._do_closec C s | dd¡ d S rs r} rn rb rb rc rn s z NestedTransaction._do_rollbackc C sR | j r,z| j | j¡ W 5 d| _ X | ¡ n"| jj| krD| j ¡ n
|
t d¡d S )NFz#This nested transaction is inactive) rË rQ rÜ r rw rM r² r r¶ rn rb rb rc ro s
|
ÿz NestedTransaction._do_commitN)T)rZ r[ r\ r] re r^ rd rw r` rl r{ r| rm rn ro rb rb rb rc r» ¸
|
s
|
|
r» c sn e Zd ZU dZdZded< ddd fdd Zd d
|
d d Zd d
|
d dZd d
|
ddZ d d
|
ddZ
|
Z S )r½ a Represent a two-phase transaction.
|
|
A new :class:`.TwoPhaseTransaction` object may be procured
|
using the :meth:`_engine.Connection.begin_twophase` method.
|
|
The interface is the same as that of :class:`.Transaction`
|
with the addition of the :meth:`prepare` method.
|
|
)r¾ Ú _is_preparedr r¾ rF )rQ r¾ c s d| _ || _t |¡ d S r )r r¾ Úsuperrd )r` rQ r¾ ©Ú __class__rb rc rd 9 s z TwoPhaseTransaction.__init__rq re c C s( | j st d¡| j | j¡ d| _dS )zqPrepare this :class:`.TwoPhaseTransaction`.
|
|
After a PREPARE, the transaction can be committed.
|
|
r~ TN)rË r r¶ rQ rß r¾ r rn rb rb rc Úprepare> s
|
zTwoPhaseTransaction.preparec C s | j | ¡ d S r )rQ rÝ rn rb rb rc ru I s z*TwoPhaseTransaction._connection_begin_implc C s | j | j| j¡ d S r )rQ râ r¾ r rn rb rb rc rx L s z-TwoPhaseTransaction._connection_rollback_implc C s | j | j| j¡ d S r )rQ rã r¾ r rn rb rb rc ry O s z+TwoPhaseTransaction._connection_commit_impl) rZ r[ r\ r] re r^ rd r ru rx ry Ú __classcell__rb rb r rc r½ * s
|
|
r½ c
|
@ sö e Zd ZU dZded< ded< eZded< dZd ed
|
< eZ d ed < d Z
|
ded< dZ d ed< dZ ded< ded< ded< ded< ded< d ed < dZdddd d d d!d d"d#d$Z d%d&d'd(d)Zed d*d+d,Zd&d*d-d.Zd/d&d0d1d2Zed3d3d3d3d3d4ddd5d dd/d6d7d8d9Zed/d6d0d:d9Zd/d6d0d;d9Zdd*d<d=Zedd*d>d?Zedd*d@dAZe ¡ Zdd*dBdCZd[d d&dEdFdGZ e j d\dHdIdJdKdLZ e j dId*dMdNZ dOdPd/d&dQdRdSZ!dTd*dUdVZ"dWd*dXdYZ#dS )]rN a
|
Connects a :class:`~sqlalchemy.pool.Pool` and
|
:class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a
|
source of database connectivity and behavior.
|
|
An :class:`_engine.Engine` object is instantiated publicly using the
|
:func:`~sqlalchemy.create_engine` function.
|
|
.. seealso::
|
|
:doc:`/core/engines`
|
|
:ref:`connections_toplevel`
|
|
rG rH r r r+ rK FrO rR zType[Connection]Ú_connection_clszsqlalchemy.engine.Enginerp r_ Ú
|
_is_futureNr r zType[OptionEngine]Ú _option_clsr. rU r5 r; r1 Úurlr& éô r zOptional[_EchoFlagType]r zOptional[Mapping[str, Any]])r; rU r Ú logging_nameÚechoÚquery_cache_sizer r& c C sl || _ || _|| _|r || _|| _|| _|dkrDtj|| jd| _ nd | _ t
|
j | |d |rh| j f | d S )Nr )Z
|
size_alert©Zechoflag) r; r rU r r r& r ZLRUCacheÚ_lru_size_alertr r Úinstance_loggerÚupdate_execution_options) r` r; rU r r r r r r& rb rb rc rd x s ÿ
|
zEngine.__init__zutil.LRUCache[Any, Any]rq )Úcacherf c C s" | ¡ r | j dt||j¡ d S )NziCompiled cache size pruning from %d items to %d. Increase cache size to reduce the frequency of pruning.)r] ry rz r Úcapacity)r` r rb rb rc r s üzEngine._lru_size_alertre c C s | S )z§Returns this :class:`.Engine`.
|
|
Used for legacy schemes that accept :class:`.Connection` /
|
:class:`.Engine` objects within the same variable.
|
|
rb rn rb rb rc rP s z Engine.enginec C s | j r| j ¡ dS )a 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
|
|
N)r Úclearrn rb rb rc Úclear_compiled_cache§ s zEngine.clear_compiled_cacher r c K s. | j | |¡ | j |¡| _| j | |¡ dS )aþ 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`
|
|
N)rH Z set_engine_execution_optionsrK r rU r rb rb rc r µ s z Engine.update_execution_options.)r rg r r r r Ú OptionEngine)r rg r r r r rf c K s d S r rb )r` r rg r r r r rb rb rc r Ê s zEngine.execution_optionsc K s d S r rb r rb rb rc r × s c K s | | |¡S )a* 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`
|
|
|
)r r rb rb rc r Û s Nc C s | j S )z³Get the non-SQL options which will take effect during execution.
|
|
.. versionadded: 1.3
|
|
.. seealso::
|
|
:meth:`_engine.Engine.execution_options`
|
rm rn rb rb rc r + s z Engine.get_execution_optionsc C s | j jS )zsString name of the :class:`~sqlalchemy.engine.interfaces.Dialect`
|
in use by this :class:`Engine`.
|
|
)rU r rn rb rb rc r 6 s z Engine.namec C s | j jS )zsDriver name of the :class:`~sqlalchemy.engine.interfaces.Dialect`
|
in use by this :class:`Engine`.
|
|
)rU Údriverrn rb rb rc r ? s z Engine.driverc C s d| j f S )Nz
|
Engine(%r))r rn rb rb rc Ú__repr__J s zEngine.__repr__T)r rf c C s* |r| j ¡ | j ¡ | _ | j | ¡ dS )a 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`
|
|
N)r; ÚdisposeZrecreaterH Zengine_disposed)r` r rb rb rc r M s %
|
zEngine.disposerd zIterator[Connection])rQ rf c c s. |d kr$| ¡ }|V W 5 Q R X n|V d S r )Úconnect)r` rQ rä rb rb rc Ú_optional_conn_ctx_managerw s
|
z!Engine._optional_conn_ctx_managerc
|
c s2 | ¡ }| ¡ |V W 5 Q R X W 5 Q R X dS )a7 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`.
|
|
N)r r¸ )r` rä rb rb rc r¸ s
|
|
z Engine.beginrT r@ rU c K s( | ¡ }|j||f| W 5 Q R X d S r )r¸ rY )r` rV rW rX rä rb rb rc rY s
|
zEngine._run_ddl_visitorrF c C s
|
| | ¡S )a< 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`
|
|
)r rn rb rb rc r © s zEngine.connectr6 c C s
|
| j ¡ S )aC 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`
|
|
)r; r rn rb rb rc rV Â s zEngine.raw_connection)NNr NF)T)N)$rZ r[ r\ r] r^ rD rK rR rF r r_ r r rd r r` rP r r r r r r r r Z echo_propertyr r r Ú
|
contextlibÚcontextmanagerr r¸ rY r rV rb rb rb rc rN S sf
|
÷ ù P * ÿ rN c @ sÀ e Zd ZU dZded< ded< ded< ded < d
|
ed < d ed < ded< dddddZdddddZejs¼e dddd Z
|
e
|
j ddd d d Z
|
e d dd d Z e j d dd!d"d Z d#S )$ÚOptionEngineMixinFrG rH r r r. rU r5 r; r1 r rO r& zlog.echo_propertyr rN r- )Úproxiedr c C sn || _ |j| _|j| _|j| _|j| _|j| _|j| _tj| | jd | j
|
|j ¡| _ |j | _ | j f | d S )Nr ) Ú_proxiedr rU r r r r& r r rH r_ rK r )r` r£ r rb rb rc rd æ s zOptionEngineMixin.__init__r rq r c K s
|
t d S r ri r rb rb rc r s z*OptionEngineMixin.update_execution_optionsre c C s | j jS r ©r¤ r; rn rb rb rc r; s zOptionEngineMixin.pool)r; rf c C s || j _d S r r¥ )r` r; rb rb rc r; s c C s | j jp| j dd¡S )NrR F)r¤ rR Ú__dict__r rn rb rb rc rR s ÿz OptionEngineMixin._has_events)r rf c C s || j d< d S )NrR )r¦ )r` r rb rb rc rR s N) rZ r[ r\ Z_sa_propagate_class_eventsr^ rd r ÚtypingÚ TYPE_CHECKINGr` r; ÚsetterrR rb rb rb rc r¢ Û s&
|
r¢ c @ s e Zd ZdddddZdS )r r rq r c K s t j| f| d S r )rN r r rb rb rc r s z%OptionEngine.update_execution_optionsN)rZ r[ r\ r rb rb rb rc r s r )cr] Ú
|
__future__r r r@ r§ r r r r r r r r
|
r r r r r r Z
|
interfacesr r r r r r r r r r r r° r r r Zsqlr! r' r¨ r" r# r$ r% r& r' r( r) r* r+ r, r- r. r/ Z
|
reflectionr0 r r1 Úeventr2 r3 r; r4 r5 r6 r7 Z sql._typingr8 Z sql.compilerr9 Zsql.ddlr: r; r< Z sql.functionsr= Z
|
sql.schemar> r? r@ Zsql.selectablerA rB Ú
|
EMPTY_DICTrD r^ rE Z InspectablerF rH rf rº r» r½ Z
|
IdentifiedrN r¢ r r rb rb rb rc Ú<module> sÔ I/ lr)
|
ÿ A
|
