Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# engine/interfaces.py
2# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
8"""Define core interfaces used by the engine system."""
10from __future__ import annotations
12from enum import Enum
13from typing import Any
14from typing import Awaitable
15from typing import Callable
16from typing import ClassVar
17from typing import Collection
18from typing import Dict
19from typing import Iterable
20from typing import Iterator
21from typing import List
22from typing import Literal
23from typing import Mapping
24from typing import MutableMapping
25from typing import Optional
26from typing import Protocol
27from typing import Sequence
28from typing import Set
29from typing import Tuple
30from typing import Type
31from typing import TYPE_CHECKING
32from typing import TypedDict
33from typing import TypeVar
34from typing import Union
36from .. import util
37from ..event import EventTarget
38from ..pool import Pool
39from ..pool import PoolProxiedConnection as PoolProxiedConnection
40from ..sql.compiler import Compiled as Compiled
41from ..sql.compiler import Compiled # noqa
42from ..sql.compiler import TypeCompiler as TypeCompiler
43from ..sql.compiler import TypeCompiler # noqa
44from ..util import immutabledict
45from ..util.concurrency import await_
46from ..util.typing import NotRequired
48if TYPE_CHECKING:
49 from .base import Connection
50 from .base import Engine
51 from .cursor import CursorResult
52 from .url import URL
53 from ..connectors.asyncio import AsyncIODBAPIConnection
54 from ..event import _ListenerFnType
55 from ..event import dispatcher
56 from ..exc import StatementError
57 from ..sql import Executable
58 from ..sql.compiler import _InsertManyValuesBatch
59 from ..sql.compiler import AggregateOrderByStyle
60 from ..sql.compiler import DDLCompiler
61 from ..sql.compiler import IdentifierPreparer
62 from ..sql.compiler import InsertmanyvaluesSentinelOpts
63 from ..sql.compiler import Linting
64 from ..sql.compiler import SQLCompiler
65 from ..sql.elements import BindParameter
66 from ..sql.elements import ClauseElement
67 from ..sql.schema import Column
68 from ..sql.schema import DefaultGenerator
69 from ..sql.schema import SchemaItem
70 from ..sql.schema import Sequence as Sequence_SchemaItem
71 from ..sql.sqltypes import _JSON_VALUE
72 from ..sql.sqltypes import Integer
73 from ..sql.type_api import _TypeMemoDict
74 from ..sql.type_api import TypeEngine
75 from ..util.langhelpers import generic_fn_descriptor
77ConnectArgsType = Tuple[Sequence[str], MutableMapping[str, Any]]
79_T = TypeVar("_T", bound="Any")
82class CacheStats(Enum):
83 CACHE_HIT = 0
84 CACHE_MISS = 1
85 CACHING_DISABLED = 2
86 NO_CACHE_KEY = 3
87 NO_DIALECT_SUPPORT = 4
90class ExecuteStyle(Enum):
91 """indicates the :term:`DBAPI` cursor method that will be used to invoke
92 a statement."""
94 EXECUTE = 0
95 """indicates cursor.execute() will be used"""
97 EXECUTEMANY = 1
98 """indicates cursor.executemany() will be used."""
100 INSERTMANYVALUES = 2
101 """indicates cursor.execute() will be used with an INSERT where the
102 VALUES expression will be expanded to accommodate for multiple
103 parameter sets
105 .. seealso::
107 :ref:`engine_insertmanyvalues`
109 """
112class DBAPIModule(Protocol):
113 class Error(Exception):
114 def __getattr__(self, key: str) -> Any: ...
116 class OperationalError(Error):
117 pass
119 class InterfaceError(Error):
120 pass
122 class IntegrityError(Error):
123 pass
125 def __getattr__(self, key: str) -> Any: ...
128class DBAPIConnection(Protocol):
129 """protocol representing a :pep:`249` database connection.
131 .. versionadded:: 2.0
133 .. seealso::
135 `Connection Objects <https://www.python.org/dev/peps/pep-0249/#connection-objects>`_
136 - in :pep:`249`
138 """ # noqa: E501
140 def close(self) -> None: ...
142 def commit(self) -> None: ...
144 def cursor(self, *args: Any, **kwargs: Any) -> DBAPICursor: ...
146 def rollback(self) -> None: ...
148 def __getattr__(self, key: str) -> Any: ...
150 def __setattr__(self, key: str, value: Any) -> None: ...
153class DBAPIType(Protocol):
154 """protocol representing a :pep:`249` database type.
156 .. versionadded:: 2.0
158 .. seealso::
160 `Type Objects <https://www.python.org/dev/peps/pep-0249/#type-objects>`_
161 - in :pep:`249`
163 """ # noqa: E501
166class DBAPICursor(Protocol):
167 """protocol representing a :pep:`249` database cursor.
169 .. versionadded:: 2.0
171 .. seealso::
173 `Cursor Objects <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_
174 - in :pep:`249`
176 """ # noqa: E501
178 @property
179 def description(
180 self,
181 ) -> _DBAPICursorDescription:
182 """The description attribute of the Cursor.
184 .. seealso::
186 `cursor.description <https://www.python.org/dev/peps/pep-0249/#description>`_
187 - in :pep:`249`
190 """ # noqa: E501
191 ...
193 @property
194 def rowcount(self) -> int: ...
196 arraysize: int
198 lastrowid: int
200 def close(self) -> None: ...
202 def execute(
203 self,
204 operation: Any,
205 parameters: Optional[_DBAPISingleExecuteParams] = None,
206 ) -> Any: ...
208 def executemany(
209 self,
210 operation: Any,
211 parameters: _DBAPIMultiExecuteParams,
212 ) -> Any: ...
214 def fetchone(self) -> Optional[Any]: ...
216 def fetchmany(self, size: int = ...) -> Sequence[Any]: ...
218 def fetchall(self) -> Sequence[Any]: ...
220 def setinputsizes(self, sizes: Sequence[Any]) -> None: ...
222 def setoutputsize(self, size: Any, column: Any) -> None: ...
224 def callproc(
225 self, procname: str, parameters: Sequence[Any] = ...
226 ) -> Any: ...
228 def nextset(self) -> Optional[bool]: ...
230 def __getattr__(self, key: str) -> Any: ...
233_CoreSingleExecuteParams = Mapping[str, Any]
234_MutableCoreSingleExecuteParams = MutableMapping[str, Any]
235_CoreMultiExecuteParams = Sequence[_CoreSingleExecuteParams]
236_CoreAnyExecuteParams = Union[
237 _CoreMultiExecuteParams, _CoreSingleExecuteParams
238]
240_DBAPISingleExecuteParams = Union[Sequence[Any], _CoreSingleExecuteParams]
242_DBAPIMultiExecuteParams = Union[
243 Sequence[Sequence[Any]], _CoreMultiExecuteParams
244]
245_DBAPIAnyExecuteParams = Union[
246 _DBAPIMultiExecuteParams, _DBAPISingleExecuteParams
247]
248_DBAPICursorDescription = Sequence[
249 Tuple[
250 str,
251 "DBAPIType",
252 Optional[int],
253 Optional[int],
254 Optional[int],
255 Optional[int],
256 Optional[bool],
257 ]
258]
260_AnySingleExecuteParams = _DBAPISingleExecuteParams
261_AnyMultiExecuteParams = _DBAPIMultiExecuteParams
262_AnyExecuteParams = _DBAPIAnyExecuteParams
264CompiledCacheType = MutableMapping[Any, "Compiled"]
265SchemaTranslateMapType = Mapping[Optional[str], Optional[str]]
267_ImmutableExecuteOptions = immutabledict[str, Any]
269_ParamStyle = Literal[
270 "qmark", "numeric", "named", "format", "pyformat", "numeric_dollar"
271]
273_GenericSetInputSizesType = List[Tuple[str, Any, "TypeEngine[Any]"]]
275IsolationLevel = Literal[
276 "SERIALIZABLE",
277 "REPEATABLE READ",
278 "READ COMMITTED",
279 "READ UNCOMMITTED",
280 "AUTOCOMMIT",
281]
284class _CoreKnownExecutionOptions(TypedDict, total=False):
285 compiled_cache: Optional[CompiledCacheType]
286 logging_token: str
287 isolation_level: IsolationLevel
288 no_parameters: bool
289 stream_results: bool
290 max_row_buffer: int
291 yield_per: int
292 insertmanyvalues_page_size: int
293 schema_translate_map: Optional[SchemaTranslateMapType]
294 preserve_rowcount: bool
295 driver_column_names: bool
298_ExecuteOptions = immutabledict[str, Any]
299CoreExecuteOptionsParameter = Union[
300 _CoreKnownExecutionOptions, Mapping[str, Any]
301]
304class ReflectedIdentity(TypedDict):
305 """represent the reflected IDENTITY structure of a column, corresponding
306 to the :class:`_schema.Identity` construct.
308 The :class:`.ReflectedIdentity` structure is part of the
309 :class:`.ReflectedColumn` structure, which is returned by the
310 :meth:`.Inspector.get_columns` method.
312 """
314 always: bool
315 """type of identity column"""
317 on_null: bool
318 """indicates ON NULL"""
320 start: int
321 """starting index of the sequence"""
323 increment: int
324 """increment value of the sequence"""
326 minvalue: int
327 """the minimum value of the sequence."""
329 maxvalue: int
330 """the maximum value of the sequence."""
332 nominvalue: bool
333 """no minimum value of the sequence."""
335 nomaxvalue: bool
336 """no maximum value of the sequence."""
338 cycle: bool
339 """allows the sequence to wrap around when the maxvalue
340 or minvalue has been reached."""
342 cache: Optional[int]
343 """number of future values in the
344 sequence which are calculated in advance."""
346 order: bool
347 """if true, renders the ORDER keyword."""
350class ReflectedComputed(TypedDict):
351 """Represent the reflected elements of a computed column, corresponding
352 to the :class:`_schema.Computed` construct.
354 The :class:`.ReflectedComputed` structure is part of the
355 :class:`.ReflectedColumn` structure, which is returned by the
356 :meth:`.Inspector.get_columns` method.
358 """
360 sqltext: str
361 """the expression used to generate this column returned
362 as a string SQL expression"""
364 persisted: NotRequired[bool]
365 """indicates if the value is stored in the table or computed on demand"""
368class ReflectedColumn(TypedDict):
369 """Dictionary representing the reflected elements corresponding to
370 a :class:`_schema.Column` object.
372 The :class:`.ReflectedColumn` structure is returned by the
373 :class:`.Inspector.get_columns` method.
375 """
377 name: str
378 """column name"""
380 type: TypeEngine[Any]
381 """column type represented as a :class:`.TypeEngine` instance."""
383 nullable: bool
384 """boolean flag if the column is NULL or NOT NULL"""
386 default: Optional[str]
387 """column default expression as a SQL string"""
389 autoincrement: NotRequired[bool]
390 """database-dependent autoincrement flag.
392 This flag indicates if the column has a database-side "autoincrement"
393 flag of some kind. Within SQLAlchemy, other kinds of columns may
394 also act as an "autoincrement" column without necessarily having
395 such a flag on them.
397 See :paramref:`_schema.Column.autoincrement` for more background on
398 "autoincrement".
400 """
402 comment: NotRequired[Optional[str]]
403 """comment for the column, if present.
404 Only some dialects return this key
405 """
407 computed: NotRequired[ReflectedComputed]
408 """indicates that this column is computed by the database.
409 Only some dialects return this key.
410 """
412 identity: NotRequired[ReflectedIdentity]
413 """indicates this column is an IDENTITY column.
414 Only some dialects return this key.
416 .. versionadded:: 1.4 - added support for identity column reflection.
417 """
419 dialect_options: NotRequired[Dict[str, Any]]
420 """Additional dialect-specific options detected for this reflected
421 object"""
424class ReflectedConstraint(TypedDict):
425 """Dictionary representing the reflected elements corresponding to
426 :class:`.Constraint`
428 A base class for all constraints
429 """
431 name: Optional[str]
432 """constraint name"""
434 comment: NotRequired[Optional[str]]
435 """comment for the constraint, if present"""
438class ReflectedCheckConstraint(ReflectedConstraint):
439 """Dictionary representing the reflected elements corresponding to
440 :class:`.CheckConstraint`.
442 The :class:`.ReflectedCheckConstraint` structure is returned by the
443 :meth:`.Inspector.get_check_constraints` method.
445 """
447 sqltext: str
448 """the check constraint's SQL expression"""
450 dialect_options: NotRequired[Dict[str, Any]]
451 """Additional dialect-specific options detected for this check constraint
452 """
455class ReflectedUniqueConstraint(ReflectedConstraint):
456 """Dictionary representing the reflected elements corresponding to
457 :class:`.UniqueConstraint`.
459 The :class:`.ReflectedUniqueConstraint` structure is returned by the
460 :meth:`.Inspector.get_unique_constraints` method.
462 """
464 column_names: List[str]
465 """column names which comprise the unique constraint"""
467 duplicates_index: NotRequired[Optional[str]]
468 "Indicates if this unique constraint duplicates an index with this name"
470 dialect_options: NotRequired[Dict[str, Any]]
471 """Additional dialect-specific options detected for this unique
472 constraint"""
475class ReflectedPrimaryKeyConstraint(ReflectedConstraint):
476 """Dictionary representing the reflected elements corresponding to
477 :class:`.PrimaryKeyConstraint`.
479 The :class:`.ReflectedPrimaryKeyConstraint` structure is returned by the
480 :meth:`.Inspector.get_pk_constraint` method.
482 """
484 constrained_columns: List[str]
485 """column names which comprise the primary key"""
487 dialect_options: NotRequired[Dict[str, Any]]
488 """Additional dialect-specific options detected for this primary key"""
491class ReflectedForeignKeyConstraint(ReflectedConstraint):
492 """Dictionary representing the reflected elements corresponding to
493 :class:`.ForeignKeyConstraint`.
495 The :class:`.ReflectedForeignKeyConstraint` structure is returned by
496 the :meth:`.Inspector.get_foreign_keys` method.
498 """
500 constrained_columns: List[str]
501 """local column names which comprise the foreign key"""
503 referred_schema: Optional[str]
504 """schema name of the table being referred"""
506 referred_table: str
507 """name of the table being referred"""
509 referred_columns: List[str]
510 """referred column names that correspond to ``constrained_columns``"""
512 options: NotRequired[Dict[str, Any]]
513 """Additional options detected for this foreign key constraint"""
516class ReflectedIndex(TypedDict):
517 """Dictionary representing the reflected elements corresponding to
518 :class:`.Index`.
520 The :class:`.ReflectedIndex` structure is returned by the
521 :meth:`.Inspector.get_indexes` method.
523 """
525 name: Optional[str]
526 """index name"""
528 column_names: List[Optional[str]]
529 """column names which the index references.
530 An element of this list is ``None`` if it's an expression and is
531 returned in the ``expressions`` list.
532 """
534 expressions: NotRequired[List[str]]
535 """Expressions that compose the index. This list, when present, contains
536 both plain column names (that are also in ``column_names``) and
537 expressions (that are ``None`` in ``column_names``).
538 """
540 unique: bool
541 """whether or not the index has a unique flag"""
543 duplicates_constraint: NotRequired[Optional[str]]
544 "Indicates if this index mirrors a constraint with this name"
546 include_columns: NotRequired[List[str]]
547 """columns to include in the INCLUDE clause for supporting databases.
549 .. deprecated:: 2.0
551 Legacy value, will be replaced with
552 ``index_dict["dialect_options"]["<dialect name>_include"]``
554 """
556 column_sorting: NotRequired[Dict[str, Tuple[str]]]
557 """optional dict mapping column names or expressions to tuple of sort
558 keywords, which may include ``asc``, ``desc``, ``nulls_first``,
559 ``nulls_last``.
560 """
562 dialect_options: NotRequired[Dict[str, Any]]
563 """Additional dialect-specific options detected for this index."""
566class ReflectedTableComment(TypedDict):
567 """Dictionary representing the reflected comment corresponding to
568 the :attr:`_schema.Table.comment` attribute.
570 The :class:`.ReflectedTableComment` structure is returned by the
571 :meth:`.Inspector.get_table_comment` method.
573 """
575 text: Optional[str]
576 """text of the comment"""
579class BindTyping(Enum):
580 """Define different methods of passing typing information for
581 bound parameters in a statement to the database driver.
583 .. versionadded:: 2.0
585 """
587 NONE = 1
588 """No steps are taken to pass typing information to the database driver.
590 This is the default behavior for databases such as SQLite, MySQL / MariaDB,
591 SQL Server.
593 """
595 SETINPUTSIZES = 2
596 """Use the pep-249 setinputsizes method.
598 This is only implemented for DBAPIs that support this method and for which
599 the SQLAlchemy dialect has the appropriate infrastructure for that dialect
600 set up. Current dialects include python-oracledb, cx_Oracle as well as
601 optional support for SQL Server using pyodbc.
603 When using setinputsizes, dialects also have a means of only using the
604 method for certain datatypes using include/exclude lists.
606 When SETINPUTSIZES is used, the :meth:`.Dialect.do_set_input_sizes` method
607 is called for each statement executed which has bound parameters.
609 """
611 RENDER_CASTS = 3
612 """Render casts or other directives in the SQL string.
614 This method is used for all PostgreSQL dialects, including asyncpg,
615 pg8000, psycopg, psycopg2. Dialects which implement this can choose
616 which kinds of datatypes are explicitly cast in SQL statements and which
617 aren't.
619 When RENDER_CASTS is used, the compiler will invoke the
620 :meth:`.SQLCompiler.render_bind_cast` method for the rendered
621 string representation of each :class:`.BindParameter` object whose
622 dialect-level type sets the :attr:`.TypeEngine.render_bind_cast` attribute.
624 The :meth:`.SQLCompiler.render_bind_cast` is also used to render casts
625 for one form of "insertmanyvalues" query, when both
626 :attr:`.InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT` and
627 :attr:`.InsertmanyvaluesSentinelOpts.RENDER_SELECT_COL_CASTS` are set,
628 where the casts are applied to the intermediary columns e.g.
629 "INSERT INTO t (a, b, c) SELECT p0::TYP, p1::TYP, p2::TYP "
630 "FROM (VALUES (?, ?), (?, ?), ...)".
632 .. versionadded:: 2.0.10 - :meth:`.SQLCompiler.render_bind_cast` is now
633 used within some elements of the "insertmanyvalues" implementation.
636 """
639ServerVersionInfoType = Tuple[Union[int, str], ...]
640"""The type of :attr:`.Dialect.server_version_info`.
642.. versionadded:: 2.1 Renamed from ``VersionInfoType``, which remains
643 present as a synonym. The version of the DBAPI, as opposed to that of
644 the database server, is instead a ``sqlalchemy.util.VersionInfo``; see
645 :attr:`.Dialect.dbapi_version`.
647"""
649VersionInfoType = ServerVersionInfoType
651TableKey = Tuple[Optional[str], str]
654class Dialect(EventTarget):
655 """Define the behavior of a specific database and DB-API combination.
657 Any aspect of metadata definition, SQL query generation,
658 execution, result-set handling, or anything else which varies
659 between databases is defined under the general category of the
660 Dialect. The Dialect acts as a factory for other
661 database-specific object implementations including
662 ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
664 .. note:: Third party dialects should not subclass :class:`.Dialect`
665 directly. Instead, subclass :class:`.default.DefaultDialect` or
666 descendant class.
668 """
670 CACHE_HIT = CacheStats.CACHE_HIT
671 CACHE_MISS = CacheStats.CACHE_MISS
672 CACHING_DISABLED = CacheStats.CACHING_DISABLED
673 NO_CACHE_KEY = CacheStats.NO_CACHE_KEY
674 NO_DIALECT_SUPPORT = CacheStats.NO_DIALECT_SUPPORT
676 dispatch: dispatcher[Dialect]
678 name: str
679 """identifying name for the dialect from a DBAPI-neutral point of view
680 (i.e. 'sqlite')
681 """
683 driver: str
684 """identifying name for the dialect's DBAPI"""
686 dialect_description: str
688 dbapi: Optional[DBAPIModule]
689 """A reference to the DBAPI module object itself.
691 SQLAlchemy dialects import DBAPI modules using the classmethod
692 :meth:`.Dialect.import_dbapi`. The rationale is so that any dialect
693 module can be imported and used to generate SQL statements without the
694 need for the actual DBAPI driver to be installed. Only when an
695 :class:`.Engine` is constructed using :func:`.create_engine` does the
696 DBAPI get imported; at that point, the creation process will assign
697 the DBAPI module to this attribute.
699 Dialects should therefore implement :meth:`.Dialect.import_dbapi`
700 which will import the necessary module and return it, and then refer
701 to ``self.dbapi`` in dialect code in order to refer to the DBAPI module
702 contents.
704 .. versionchanged:: The :attr:`.Dialect.dbapi` attribute is exclusively
705 used as the per-:class:`.Dialect`-instance reference to the DBAPI
706 module. The previous not-fully-documented ``.Dialect.dbapi()``
707 classmethod is deprecated and replaced by :meth:`.Dialect.import_dbapi`.
709 """
711 @util.non_memoized_property
712 def loaded_dbapi(self) -> DBAPIModule:
713 """same as .dbapi, but is never None; will raise an error if no
714 DBAPI was set up.
716 .. versionadded:: 2.0
718 """
719 raise NotImplementedError()
721 positional: bool
722 """True if the paramstyle for this Dialect is positional."""
724 paramstyle: str
725 """the paramstyle to be used (some DB-APIs support multiple
726 paramstyles).
727 """
729 compiler_linting: Linting
731 statement_compiler: Type[SQLCompiler]
732 """a :class:`.Compiled` class used to compile SQL statements"""
734 ddl_compiler: Type[DDLCompiler]
735 """a :class:`.Compiled` class used to compile DDL statements"""
737 type_compiler_cls: ClassVar[Type[TypeCompiler]]
738 """a :class:`.Compiled` class used to compile SQL type objects
740 .. versionadded:: 2.0
742 """
744 type_compiler_instance: TypeCompiler
745 """instance of a :class:`.Compiled` class used to compile SQL type
746 objects
748 .. versionadded:: 2.0
750 """
752 type_compiler: Any
753 """legacy; this is a TypeCompiler class at the class level, a
754 TypeCompiler instance at the instance level.
756 Refer to type_compiler_instance instead.
758 """
760 preparer: Type[IdentifierPreparer]
761 """a :class:`.IdentifierPreparer` class used to
762 quote identifiers.
763 """
765 identifier_preparer: IdentifierPreparer
766 """This element will refer to an instance of :class:`.IdentifierPreparer`
767 once a :class:`.DefaultDialect` has been constructed.
769 """
771 server_version_info: Optional[ServerVersionInfoType]
772 """a tuple containing a version number for the DB backend in use.
774 This value is only available for supporting dialects, and is
775 typically populated during the initial connection to the database.
776 """
778 minimum_dbapi_version: Optional[util.VersionInfo] = None
779 """The minimum version of the DBAPI which this dialect supports.
781 When present, :class:`.DefaultDialect` compares this against
782 :attr:`.Dialect.dbapi_version` as the dialect is constructed, raising
783 :class:`.exc.InvalidRequestError` if the DBAPI in use is older. A
784 dialect therefore does not need to implement this check itself::
786 class MyDialect(DefaultDialect):
787 minimum_dbapi_version = util.VersionInfo((2, 5))
789 No check takes place if the version of the DBAPI is not available, as
790 described at :attr:`.Dialect.dbapi_version`.
792 .. versionadded:: 2.1
794 """
796 @property
797 def dbapi_version(self) -> util.VersionInfo:
798 """the version number of the DBAPI in use.
800 In contrast to :attr:`.Dialect.server_version_info`, which refers to
801 the database server itself, this attribute refers to the version of
802 the Python DBAPI module which the dialect makes use of, and is
803 available without any database connection being established.
805 The value is a ``sqlalchemy.util.VersionInfo``, a tuple of integers
806 which additionally sorts pre-release versions such as ``2.0.0rc1``
807 as preceding the final release ``(2, 0, 0)``. It may be compared
808 against a plain tuple of integers directly::
810 if dialect.dbapi_version >= (2, 5):
811 ...
813 Dialects should implement
814 :meth:`.Dialect.retrieve_dbapi_version` only in order to provide
815 this value; this method in turn is used by the
816 :class:`.DefaultDialect` implementation of
817 :attr:`.DefaultDialect.dbapi_version`.
819 Two distinct conditions prevent a version from being available:
821 * :class:`.exc.NoDBAPILoaded` is raised if the dialect has no DBAPI
822 module loaded, as is the case for a dialect used only to compile
823 statements, or if its DBAPI publishes no version of its own.
824 Neither is an error on the part of the dialect.
826 * ``NotImplementedError`` is raised if the dialect does not
827 implement :meth:`.Dialect.retrieve_dbapi_version` at all. This
828 indicates the dialect itself needs to be fixed.
830 Consuming code which tolerates a dialect that has not loaded a
831 DBAPI should accommodate the former only, so that a dialect in need
832 of fixing continues to make itself known::
834 try:
835 dbapi_version = dialect.dbapi_version
836 except exc.NoDBAPILoaded:
837 dbapi_version = None
839 Note that ``hasattr()`` may **not** be used to test for support, as
840 it does not intercept ``NotImplementedError``. Note also that
841 reading this attribute does not cause a DBAPI module to be
842 imported; it reports upon the module already in use, if any.
844 A version, once determined, is memoized. As no memoization takes
845 place while the version remains unavailable, a DBAPI which is
846 established after the dialect was constructed is still detected.
848 .. versionadded:: 2.1
850 .. seealso::
852 :meth:`.Dialect.retrieve_dbapi_version`
854 """
855 raise NotImplementedError()
857 def retrieve_dbapi_version(self, dbapi: DBAPIModule) -> util.VersionInfo:
858 """Return the version of the given DBAPI module.
860 This is the dialect-implemented hook behind
861 :attr:`.Dialect.dbapi_version`. A dialect is responsible only for
862 locating where its particular DBAPI publishes a version and parsing
863 it, typically using ``sqlalchemy.util.parse_version_string()``::
865 def retrieve_dbapi_version(self, dbapi):
866 return util.parse_version_string(dbapi.__version__)
868 The ``dbapi`` argument is the module returned by
869 :meth:`.Dialect.import_dbapi`, which for asyncio dialects is
870 typically a wrapper object rather than the driver module itself.
872 This method is only invoked with a DBAPI actually loaded, and only
873 until a version has been determined; the surrounding conditions,
874 including memoization, are handled by :class:`.DefaultDialect`. An
875 empty version may be returned to indicate that no version could be
876 located, which :attr:`.Dialect.dbapi_version` translates into
877 :class:`.exc.NoDBAPILoaded`.
879 .. versionadded:: 2.1
881 """
882 raise NotImplementedError()
884 default_schema_name: Optional[str]
885 """the name of the default schema. This value is only available for
886 supporting dialects, and is typically populated during the
887 initial connection to the database.
889 """
891 # NOTE: this does not take into effect engine-level isolation level.
892 # not clear if this should be changed, seems like it should
893 default_isolation_level: Optional[IsolationLevel]
894 """the isolation that is implicitly present on new connections"""
896 skip_autocommit_rollback: bool
897 """Whether or not the :paramref:`.create_engine.skip_autocommit_rollback`
898 parameter was set.
900 .. versionadded:: 2.0.43
902 """
904 # create_engine() -> isolation_level currently goes here
905 _on_connect_isolation_level: Optional[IsolationLevel]
907 execution_ctx_cls: Type[ExecutionContext]
908 """a :class:`.ExecutionContext` class used to handle statement execution"""
910 execute_sequence_format: Union[
911 Type[Tuple[Any, ...]], Type[Tuple[List[Any]]]
912 ]
913 """either the 'tuple' or 'list' type, depending on what cursor.execute()
914 accepts for the second argument (they vary)."""
916 supports_alter: bool
917 """``True`` if the database supports ``ALTER TABLE`` - used only for
918 generating foreign key constraints in certain circumstances
919 """
921 max_identifier_length: int
922 """The maximum length of identifier names."""
923 max_index_name_length: Optional[int]
924 """The maximum length of index names if different from
925 ``max_identifier_length``."""
926 max_constraint_name_length: Optional[int]
927 """The maximum length of constraint names if different from
928 ``max_identifier_length``."""
930 supports_server_side_cursors: Union[generic_fn_descriptor[bool], bool]
931 """indicates if the dialect supports server side cursors"""
933 server_side_cursors: bool
934 """deprecated; indicates if the dialect should attempt to use server
935 side cursors by default"""
937 supports_sane_rowcount: bool
938 """Indicate whether the dialect properly implements rowcount for
939 ``UPDATE`` and ``DELETE`` statements.
940 """
942 supports_sane_multi_rowcount: bool
943 """Indicate whether the dialect properly implements rowcount for
944 ``UPDATE`` and ``DELETE`` statements when executed via
945 executemany.
946 """
948 supports_empty_insert: bool
949 """dialect supports INSERT () VALUES (), i.e. a plain INSERT with no
950 columns in it.
952 This is not usually supported; an "empty" insert is typically
953 suited using either "INSERT..DEFAULT VALUES" or
954 "INSERT ... (col) VALUES (DEFAULT)".
956 """
958 supports_default_values: bool
959 """dialect supports INSERT... DEFAULT VALUES syntax"""
961 supports_default_metavalue: bool
962 """dialect supports INSERT...(col) VALUES (DEFAULT) syntax.
964 Most databases support this in some way, e.g. SQLite supports it using
965 ``VALUES (NULL)``. MS SQL Server supports the syntax also however
966 is the only included dialect where we have this disabled, as
967 MSSQL does not support the field for the IDENTITY column, which is
968 usually where we like to make use of the feature.
970 """
972 default_metavalue_token: str = "DEFAULT"
973 """for INSERT... VALUES (DEFAULT) syntax, the token to put in the
974 parenthesis.
976 E.g. for SQLite this is the keyword "NULL".
978 """
980 supports_multivalues_insert: bool
981 """Target database supports INSERT...VALUES with multiple value
982 sets, i.e. INSERT INTO table (cols) VALUES (...), (...), (...), ...
984 """
986 _json_serializer: Callable[[_JSON_VALUE], str] | None
988 _json_deserializer: Callable[[str], _JSON_VALUE] | None
990 supports_native_json_serialization: bool
991 """target dialect includes a native JSON serializer, eliminating
992 the need to use json.dumps() for JSON data
994 .. versionadded:: 2.1
996 """
998 supports_native_json_deserialization: bool
999 """target dialect includes a native JSON deserializer, eliminating
1000 the need to use json.loads() for JSON data
1002 .. versionadded:: 2.1
1004 """
1006 dialect_injects_custom_json_deserializer: bool
1007 """target dialect, when given a custom _json_deserializer, needs to
1008 inject this handler at the connection/cursor level, rather than
1009 having JSON data returned as a string to be handled by the type
1011 ..versionadded:: 2.1
1013 """
1015 aggregate_order_by_style: AggregateOrderByStyle
1016 """Style of ORDER BY supported for arbitrary aggregate functions
1018 .. versionadded:: 2.1
1020 """
1022 insert_executemany_returning: bool
1023 """dialect / driver / database supports some means of providing
1024 INSERT...RETURNING support when dialect.do_executemany() is used.
1026 """
1028 insert_executemany_returning_sort_by_parameter_order: bool
1029 """dialect / driver / database supports some means of providing
1030 INSERT...RETURNING support when dialect.do_executemany() is used
1031 along with the :paramref:`_dml.Insert.returning.sort_by_parameter_order`
1032 parameter being set.
1034 """
1036 update_executemany_returning: bool
1037 """dialect supports UPDATE..RETURNING with executemany."""
1039 delete_executemany_returning: bool
1040 """dialect supports DELETE..RETURNING with executemany."""
1042 use_insertmanyvalues: bool
1043 """if True, indicates "insertmanyvalues" functionality should be used
1044 to allow for ``insert_executemany_returning`` behavior, if possible.
1046 In practice, setting this to True means:
1048 if ``supports_multivalues_insert``, ``insert_returning`` and
1049 ``use_insertmanyvalues`` are all True, the SQL compiler will produce
1050 an INSERT that will be interpreted by the :class:`.DefaultDialect`
1051 as an :attr:`.ExecuteStyle.INSERTMANYVALUES` execution that allows
1052 for INSERT of many rows with RETURNING by rewriting a single-row
1053 INSERT statement to have multiple VALUES clauses, also executing
1054 the statement multiple times for a series of batches when large numbers
1055 of rows are given.
1057 The parameter is False for the default dialect, and is set to True for
1058 SQLAlchemy internal dialects SQLite, MySQL/MariaDB, PostgreSQL, SQL Server.
1059 It remains at False for Oracle Database, which provides native "executemany
1060 with RETURNING" support and also does not support
1061 ``supports_multivalues_insert``. For MySQL/MariaDB, those MySQL dialects
1062 that don't support RETURNING will not report
1063 ``insert_executemany_returning`` as True.
1065 .. versionadded:: 2.0
1067 .. seealso::
1069 :ref:`engine_insertmanyvalues`
1071 """
1073 use_insertmanyvalues_wo_returning: bool
1074 """if True, and use_insertmanyvalues is also True, INSERT statements
1075 that don't include RETURNING will also use "insertmanyvalues".
1077 .. versionadded:: 2.0
1079 .. seealso::
1081 :ref:`engine_insertmanyvalues`
1083 """
1085 insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts
1086 """Options indicating the database supports a form of bulk INSERT where
1087 the autoincrement integer primary key can be reliably used as an ordering
1088 for INSERTed rows.
1090 .. versionadded:: 2.0.10
1092 .. seealso::
1094 :ref:`engine_insertmanyvalues_returning_order`
1096 """
1098 insertmanyvalues_page_size: int
1099 """Number of rows to render into an individual INSERT..VALUES() statement
1100 for :attr:`.ExecuteStyle.INSERTMANYVALUES` executions.
1102 The default dialect defaults this to 1000.
1104 .. versionadded:: 2.0
1106 .. seealso::
1108 :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size` -
1109 execution option available on :class:`_engine.Connection`, statements
1111 """ # noqa: E501
1113 insertmanyvalues_max_parameters: int
1114 """Alternate to insertmanyvalues_page_size, will additionally limit
1115 page size based on number of parameters total in the statement.
1118 """
1120 preexecute_autoincrement_sequences: bool
1121 """True if 'implicit' primary key functions must be executed separately
1122 in order to get their value, if RETURNING is not used.
1124 This is currently oriented towards PostgreSQL when the
1125 ``implicit_returning=False`` parameter is used on a :class:`.Table`
1126 object.
1128 """
1130 insert_returning: bool
1131 """if the dialect supports RETURNING with INSERT
1133 .. versionadded:: 2.0
1135 """
1137 update_returning: bool
1138 """if the dialect supports RETURNING with UPDATE
1140 .. versionadded:: 2.0
1142 """
1144 update_returning_multifrom: bool
1145 """if the dialect supports RETURNING with UPDATE..FROM
1147 .. versionadded:: 2.0
1149 """
1151 delete_returning: bool
1152 """if the dialect supports RETURNING with DELETE
1154 .. versionadded:: 2.0
1156 """
1158 delete_returning_multifrom: bool
1159 """if the dialect supports RETURNING with DELETE..FROM
1161 .. versionadded:: 2.0
1163 """
1165 favor_returning_over_lastrowid: bool
1166 """for backends that support both a lastrowid and a RETURNING insert
1167 strategy, favor RETURNING for simple single-int pk inserts.
1169 cursor.lastrowid tends to be more performant on most backends.
1171 """
1173 supports_identity_columns: bool
1174 """target database supports IDENTITY"""
1176 cte_follows_insert: bool
1177 """target database, when given a CTE with an INSERT statement, needs
1178 the CTE to be below the INSERT"""
1180 colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]]
1181 """A dictionary of TypeEngine classes from sqlalchemy.types mapped
1182 to subclasses that are specific to the dialect class. This
1183 dictionary is class-level only and is not accessed from the
1184 dialect instance itself.
1185 """
1187 supports_sequences: bool
1188 """Indicates if the dialect supports CREATE SEQUENCE or similar."""
1190 sequences_optional: bool
1191 """If True, indicates if the :paramref:`_schema.Sequence.optional`
1192 parameter on the :class:`_schema.Sequence` construct
1193 should signal to not generate a CREATE SEQUENCE. Applies only to
1194 dialects that support sequences. Currently used only to allow PostgreSQL
1195 SERIAL to be used on a column that specifies Sequence() for usage on
1196 other backends.
1197 """
1199 default_sequence_base: int
1200 """the default value that will be rendered as the "START WITH" portion of
1201 a CREATE SEQUENCE DDL statement.
1203 """
1205 supports_native_enum: bool
1206 """Indicates if the dialect supports a native ENUM construct.
1207 This will prevent :class:`_types.Enum` from generating a CHECK
1208 constraint when that type is used in "native" mode.
1209 """
1211 supports_native_boolean: bool
1212 """Indicates if the dialect supports a native boolean construct.
1213 This will prevent :class:`_types.Boolean` from generating a CHECK
1214 constraint when that type is used.
1215 """
1217 supports_native_decimal: bool
1218 """indicates if Decimal objects are handled and returned for precision
1219 numeric types, or if floats are returned"""
1221 supports_native_uuid: bool
1222 """indicates if Python UUID() objects are handled natively by the
1223 driver for SQL UUID datatypes.
1225 .. versionadded:: 2.0
1227 """
1229 returns_native_bytes: bool
1230 """indicates if Python bytes() objects are returned natively by the
1231 driver for SQL "binary" datatypes.
1233 .. versionadded:: 2.0.11
1235 """
1237 construct_arguments: Optional[
1238 List[Tuple[Type[Union[SchemaItem, ClauseElement]], Mapping[str, Any]]]
1239 ] = None
1240 """Optional set of argument specifiers for various SQLAlchemy
1241 constructs, typically schema items.
1243 To implement, establish as a series of tuples, as in::
1245 construct_arguments = [
1246 (schema.Index, {"using": False, "where": None, "ops": None}),
1247 ]
1249 If the above construct is established on the PostgreSQL dialect,
1250 the :class:`.Index` construct will now accept the keyword arguments
1251 ``postgresql_using``, ``postgresql_where``, and ``postgresql_ops``.
1252 Any other argument specified to the constructor of :class:`.Index`
1253 which is prefixed with ``postgresql_`` will raise :class:`.ArgumentError`.
1255 A dialect which does not include a ``construct_arguments`` member will
1256 not participate in the argument validation system. For such a dialect,
1257 any argument name is accepted by all participating constructs, within
1258 the namespace of arguments prefixed with that dialect name. The rationale
1259 here is so that third-party dialects that haven't yet implemented this
1260 feature continue to function in the old way.
1262 Arguments that represent database state without any corresponding DDL,
1263 but may nonetheless appear in a reflected set of arguments that should
1264 be ignored by the construct, may make use of the
1265 :attr:`.DialectKWArgConst.REFLECTED_ONLY` token as the default value.
1266 Arguments passed to the schema object on such a key will be passed along
1267 into the separate read-only collection
1268 :attr:`.DialectKWArgs.reflect_only_elements` and should be omitted from
1269 DDL rendering.
1271 .. versionadded:: 2.1 Added :class:`.DialectKWArgConst`.
1273 .. seealso::
1275 :class:`.DialectKWArgs` - implementing base class which consumes
1276 :attr:`.DefaultDialect.construct_arguments`
1279 """
1281 reflection_options: Sequence[str] = ()
1282 """Sequence of string names indicating keyword arguments that can be
1283 established on a :class:`.Table` object which will be passed as
1284 "reflection options" when using :paramref:`.Table.autoload_with`.
1286 Current example is "oracle_resolve_synonyms" in the Oracle Database
1287 dialects.
1289 """
1291 dbapi_exception_translation_map: Mapping[str, str] = util.EMPTY_DICT
1292 """A dictionary of names that will contain as values the names of
1293 pep-249 exceptions ("IntegrityError", "OperationalError", etc)
1294 keyed to alternate class names, to support the case where a
1295 DBAPI has exception classes that aren't named as they are
1296 referred to (e.g. IntegrityError = MyException). In the vast
1297 majority of cases this dictionary is empty.
1298 """
1300 supports_comments: bool
1301 """Indicates the dialect supports comment DDL on tables and columns."""
1303 inline_comments: bool
1304 """Indicates the dialect supports comment DDL that's inline with the
1305 definition of a Table or Column. If False, this implies that ALTER must
1306 be used to set table and column comments."""
1308 supports_constraint_comments: bool
1309 """Indicates if the dialect supports comment DDL on constraints.
1311 .. versionadded:: 2.0
1312 """
1314 _has_events = False
1316 supports_statement_cache: bool = True
1317 """indicates if this dialect supports caching.
1319 All dialects that are compatible with statement caching should set this
1320 flag to True directly on each dialect class and subclass that supports
1321 it. SQLAlchemy tests that this flag is locally present on each dialect
1322 subclass before it will use statement caching. This is to provide
1323 safety for legacy or new dialects that are not yet fully tested to be
1324 compliant with SQL statement caching.
1326 .. versionadded:: 1.4.5
1328 .. seealso::
1330 :ref:`engine_thirdparty_caching`
1332 """
1334 _supports_statement_cache: bool
1335 """internal evaluation for supports_statement_cache"""
1337 bind_typing = BindTyping.NONE
1338 """define a means of passing typing information to the database and/or
1339 driver for bound parameters.
1341 See :class:`.BindTyping` for values.
1343 .. versionadded:: 2.0
1345 """
1347 is_async: bool
1348 """Whether or not this dialect is intended for asyncio use."""
1350 has_terminate: bool
1351 """Whether or not this dialect has a separate "terminate" implementation
1352 that does not block or require awaiting."""
1354 engine_config_types: Mapping[str, Any]
1355 """a mapping of string keys that can be in an engine config linked to
1356 type conversion functions.
1358 """
1360 label_length: Optional[int]
1361 """optional user-defined max length for SQL labels"""
1363 include_set_input_sizes: Optional[Set[Any]]
1364 """set of DBAPI type objects that should be included in
1365 automatic cursor.setinputsizes() calls.
1367 This is only used if bind_typing is BindTyping.SET_INPUT_SIZES
1369 """
1371 exclude_set_input_sizes: Optional[Set[Any]]
1372 """set of DBAPI type objects that should be excluded in
1373 automatic cursor.setinputsizes() calls.
1375 This is only used if bind_typing is BindTyping.SET_INPUT_SIZES
1377 """
1379 supports_simple_order_by_label: bool
1380 """target database supports ORDER BY <labelname>, where <labelname>
1381 refers to a label in the columns clause of the SELECT"""
1383 div_is_floordiv: bool
1384 """target database treats the / division operator as "floor division" """
1386 tuple_in_values: bool
1387 """target database supports tuple IN, i.e. (x, y) IN ((q, p), (r, z))"""
1389 requires_name_normalize: bool
1390 """Indicates symbol names are returned by the database in
1391 UPPERCASED if they are case insensitive within the database.
1392 If this is True, the methods normalize_name()
1393 and denormalize_name() must be provided.
1394 """
1396 _bind_typing_render_casts: bool
1398 _type_memos: MutableMapping[TypeEngine[Any], _TypeMemoDict]
1400 def _builtin_onconnect(self) -> Optional[_ListenerFnType]:
1401 raise NotImplementedError()
1403 def create_connect_args(self, url: URL) -> ConnectArgsType:
1404 """Build DB-API compatible connection arguments.
1406 Given a :class:`.URL` object, returns a tuple
1407 consisting of a ``(*args, **kwargs)`` suitable to send directly
1408 to the dbapi's connect function. The arguments are sent to the
1409 :meth:`.Dialect.connect` method which then runs the DBAPI-level
1410 ``connect()`` function.
1412 The method typically makes use of the
1413 :meth:`.URL.translate_connect_args`
1414 method in order to generate a dictionary of options.
1416 The default implementation is::
1418 def create_connect_args(self, url):
1419 opts = url.translate_connect_args()
1420 opts.update(url.query)
1421 return ([], opts)
1423 :param url: a :class:`.URL` object
1425 :return: a tuple of ``(*args, **kwargs)`` which will be passed to the
1426 :meth:`.Dialect.connect` method.
1428 .. seealso::
1430 :meth:`.URL.translate_connect_args`
1432 """
1434 raise NotImplementedError()
1436 @classmethod
1437 def import_dbapi(cls) -> DBAPIModule:
1438 """Import the DBAPI module that is used by this dialect.
1440 The Python module object returned here will be assigned as an
1441 instance variable to a constructed dialect under the name
1442 ``.dbapi``.
1444 .. versionchanged:: 2.0 The :meth:`.Dialect.import_dbapi` class
1445 method is renamed from the previous method ``.Dialect.dbapi()``,
1446 which would be replaced at dialect instantiation time by the
1447 DBAPI module itself, thus using the same name in two different ways.
1448 If a ``.Dialect.dbapi()`` classmethod is present on a third-party
1449 dialect, it will be used and a deprecation warning will be emitted.
1451 """
1452 raise NotImplementedError()
1454 def type_descriptor(self, typeobj: TypeEngine[_T]) -> TypeEngine[_T]:
1455 """Transform a generic type to a dialect-specific type.
1457 Dialect classes will usually use the
1458 :func:`_types.adapt_type` function in the types module to
1459 accomplish this.
1461 The returned result is cached *per dialect class* so can
1462 contain no dialect-instance state.
1464 """
1466 raise NotImplementedError()
1468 def min_year_for_type(self, typeobj: TypeEngine[Any]) -> int:
1469 """Return the earliest year the database accepts for the given
1470 date or datetime type.
1472 The type may be a generic type such as :class:`.DateTime`, in
1473 which case the limit is that of the database type the dialect
1474 renders for it. Dialects whose date or datetime types don't
1475 accept all years from ``datetime.MINYEAR`` forward override this
1476 method; e.g. SQL Server's ``DATETIME`` type, which the dialect
1477 renders for :class:`.DateTime`, accepts years from 1753 forward.
1479 .. versionadded:: 2.0.55
1481 """
1483 raise NotImplementedError()
1485 def initialize(self, connection: Connection) -> None:
1486 """Called during strategized creation of the dialect with a
1487 connection.
1489 Allows dialects to configure options based on server version info or
1490 other properties.
1492 The connection passed here is a SQLAlchemy Connection object,
1493 with full capabilities.
1495 The initialize() method of the base dialect should be called via
1496 super().
1498 .. note:: as of SQLAlchemy 1.4, this method is called **before**
1499 any :meth:`_engine.Dialect.on_connect` hooks are called.
1501 """
1503 if TYPE_CHECKING:
1505 def _overrides_default(self, method_name: str) -> bool: ...
1507 def get_columns(
1508 self,
1509 connection: Connection,
1510 table_name: str,
1511 schema: Optional[str] = None,
1512 **kw: Any,
1513 ) -> List[ReflectedColumn]:
1514 """Return information about columns in ``table_name``.
1516 Given a :class:`_engine.Connection`, a string
1517 ``table_name``, and an optional string ``schema``, return column
1518 information as a list of dictionaries
1519 corresponding to the :class:`.ReflectedColumn` dictionary.
1521 This is an internal dialect method. Applications should use
1522 :meth:`.Inspector.get_columns`.
1524 """
1526 raise NotImplementedError()
1528 def get_multi_columns(
1529 self,
1530 connection: Connection,
1531 *,
1532 schema: Optional[str] = None,
1533 filter_names: Optional[Collection[str]] = None,
1534 **kw: Any,
1535 ) -> Iterable[Tuple[TableKey, List[ReflectedColumn]]]:
1536 """Return information about columns in all tables in the
1537 given ``schema``.
1539 This is an internal dialect method. Applications should use
1540 :meth:`.Inspector.get_multi_columns`.
1542 .. note:: The :class:`_engine.DefaultDialect` provides a default
1543 implementation that will call the single table method for
1544 each object returned by :meth:`Dialect.get_table_names`,
1545 :meth:`Dialect.get_view_names` or
1546 :meth:`Dialect.get_materialized_view_names` depending on the
1547 provided ``kind``. Dialects that want to support a faster
1548 implementation should implement this method.
1550 .. versionadded:: 2.0
1552 """
1554 raise NotImplementedError()
1556 def get_pk_constraint(
1557 self,
1558 connection: Connection,
1559 table_name: str,
1560 schema: Optional[str] = None,
1561 **kw: Any,
1562 ) -> ReflectedPrimaryKeyConstraint:
1563 """Return information about the primary key constraint on
1564 table_name`.
1566 Given a :class:`_engine.Connection`, a string
1567 ``table_name``, and an optional string ``schema``, return primary
1568 key information as a dictionary corresponding to the
1569 :class:`.ReflectedPrimaryKeyConstraint` dictionary.
1571 This is an internal dialect method. Applications should use
1572 :meth:`.Inspector.get_pk_constraint`.
1574 """
1575 raise NotImplementedError()
1577 def get_multi_pk_constraint(
1578 self,
1579 connection: Connection,
1580 *,
1581 schema: Optional[str] = None,
1582 filter_names: Optional[Collection[str]] = None,
1583 **kw: Any,
1584 ) -> Iterable[Tuple[TableKey, ReflectedPrimaryKeyConstraint]]:
1585 """Return information about primary key constraints in
1586 all tables in the given ``schema``.
1588 This is an internal dialect method. Applications should use
1589 :meth:`.Inspector.get_multi_pk_constraint`.
1591 .. note:: The :class:`_engine.DefaultDialect` provides a default
1592 implementation that will call the single table method for
1593 each object returned by :meth:`Dialect.get_table_names`,
1594 :meth:`Dialect.get_view_names` or
1595 :meth:`Dialect.get_materialized_view_names` depending on the
1596 provided ``kind``. Dialects that want to support a faster
1597 implementation should implement this method.
1599 .. versionadded:: 2.0
1601 """
1602 raise NotImplementedError()
1604 def get_foreign_keys(
1605 self,
1606 connection: Connection,
1607 table_name: str,
1608 schema: Optional[str] = None,
1609 **kw: Any,
1610 ) -> List[ReflectedForeignKeyConstraint]:
1611 """Return information about foreign_keys in ``table_name``.
1613 Given a :class:`_engine.Connection`, a string
1614 ``table_name``, and an optional string ``schema``, return foreign
1615 key information as a list of dicts corresponding to the
1616 :class:`.ReflectedForeignKeyConstraint` dictionary.
1618 This is an internal dialect method. Applications should use
1619 :meth:`_engine.Inspector.get_foreign_keys`.
1620 """
1622 raise NotImplementedError()
1624 def get_multi_foreign_keys(
1625 self,
1626 connection: Connection,
1627 *,
1628 schema: Optional[str] = None,
1629 filter_names: Optional[Collection[str]] = None,
1630 **kw: Any,
1631 ) -> Iterable[Tuple[TableKey, List[ReflectedForeignKeyConstraint]]]:
1632 """Return information about foreign_keys in all tables
1633 in the given ``schema``.
1635 This is an internal dialect method. Applications should use
1636 :meth:`_engine.Inspector.get_multi_foreign_keys`.
1638 .. note:: The :class:`_engine.DefaultDialect` provides a default
1639 implementation that will call the single table method for
1640 each object returned by :meth:`Dialect.get_table_names`,
1641 :meth:`Dialect.get_view_names` or
1642 :meth:`Dialect.get_materialized_view_names` depending on the
1643 provided ``kind``. Dialects that want to support a faster
1644 implementation should implement this method.
1646 .. versionadded:: 2.0
1648 """
1650 raise NotImplementedError()
1652 def get_table_names(
1653 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1654 ) -> List[str]:
1655 """Return a list of table names for ``schema``.
1657 This is an internal dialect method. Applications should use
1658 :meth:`_engine.Inspector.get_table_names`.
1660 """
1662 raise NotImplementedError()
1664 def get_temp_table_names(
1665 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1666 ) -> List[str]:
1667 """Return a list of temporary table names on the given connection,
1668 if supported by the underlying backend.
1670 This is an internal dialect method. Applications should use
1671 :meth:`_engine.Inspector.get_temp_table_names`.
1673 """
1675 raise NotImplementedError()
1677 def get_view_names(
1678 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1679 ) -> List[str]:
1680 """Return a list of all non-materialized view names available in the
1681 database.
1683 This is an internal dialect method. Applications should use
1684 :meth:`_engine.Inspector.get_view_names`.
1686 :param schema: schema name to query, if not the default schema.
1688 """
1690 raise NotImplementedError()
1692 def get_materialized_view_names(
1693 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1694 ) -> List[str]:
1695 """Return a list of all materialized view names available in the
1696 database.
1698 This is an internal dialect method. Applications should use
1699 :meth:`_engine.Inspector.get_materialized_view_names`.
1701 :param schema: schema name to query, if not the default schema.
1703 .. versionadded:: 2.0
1705 """
1707 raise NotImplementedError()
1709 def get_sequence_names(
1710 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1711 ) -> List[str]:
1712 """Return a list of all sequence names available in the database.
1714 This is an internal dialect method. Applications should use
1715 :meth:`_engine.Inspector.get_sequence_names`.
1717 :param schema: schema name to query, if not the default schema.
1719 .. versionadded:: 1.4
1720 """
1722 raise NotImplementedError()
1724 def get_temp_view_names(
1725 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1726 ) -> List[str]:
1727 """Return a list of temporary view names on the given connection,
1728 if supported by the underlying backend.
1730 This is an internal dialect method. Applications should use
1731 :meth:`_engine.Inspector.get_temp_view_names`.
1733 """
1735 raise NotImplementedError()
1737 def get_schema_names(self, connection: Connection, **kw: Any) -> List[str]:
1738 """Return a list of all schema names available in the database.
1740 This is an internal dialect method. Applications should use
1741 :meth:`_engine.Inspector.get_schema_names`.
1742 """
1743 raise NotImplementedError()
1745 def get_view_definition(
1746 self,
1747 connection: Connection,
1748 view_name: str,
1749 schema: Optional[str] = None,
1750 **kw: Any,
1751 ) -> str:
1752 """Return plain or materialized view definition.
1754 This is an internal dialect method. Applications should use
1755 :meth:`_engine.Inspector.get_view_definition`.
1757 Given a :class:`_engine.Connection`, a string
1758 ``view_name``, and an optional string ``schema``, return the view
1759 definition.
1760 """
1762 raise NotImplementedError()
1764 def get_indexes(
1765 self,
1766 connection: Connection,
1767 table_name: str,
1768 schema: Optional[str] = None,
1769 **kw: Any,
1770 ) -> List[ReflectedIndex]:
1771 """Return information about indexes in ``table_name``.
1773 Given a :class:`_engine.Connection`, a string
1774 ``table_name`` and an optional string ``schema``, return index
1775 information as a list of dictionaries corresponding to the
1776 :class:`.ReflectedIndex` dictionary.
1778 This is an internal dialect method. Applications should use
1779 :meth:`.Inspector.get_indexes`.
1780 """
1782 raise NotImplementedError()
1784 def get_multi_indexes(
1785 self,
1786 connection: Connection,
1787 *,
1788 schema: Optional[str] = None,
1789 filter_names: Optional[Collection[str]] = None,
1790 **kw: Any,
1791 ) -> Iterable[Tuple[TableKey, List[ReflectedIndex]]]:
1792 """Return information about indexes in in all tables
1793 in the given ``schema``.
1795 This is an internal dialect method. Applications should use
1796 :meth:`.Inspector.get_multi_indexes`.
1798 .. note:: The :class:`_engine.DefaultDialect` provides a default
1799 implementation that will call the single table method for
1800 each object returned by :meth:`Dialect.get_table_names`,
1801 :meth:`Dialect.get_view_names` or
1802 :meth:`Dialect.get_materialized_view_names` depending on the
1803 provided ``kind``. Dialects that want to support a faster
1804 implementation should implement this method.
1806 .. versionadded:: 2.0
1808 """
1810 raise NotImplementedError()
1812 def get_unique_constraints(
1813 self,
1814 connection: Connection,
1815 table_name: str,
1816 schema: Optional[str] = None,
1817 **kw: Any,
1818 ) -> List[ReflectedUniqueConstraint]:
1819 r"""Return information about unique constraints in ``table_name``.
1821 Given a string ``table_name`` and an optional string ``schema``, return
1822 unique constraint information as a list of dicts corresponding
1823 to the :class:`.ReflectedUniqueConstraint` dictionary.
1825 This is an internal dialect method. Applications should use
1826 :meth:`.Inspector.get_unique_constraints`.
1827 """
1829 raise NotImplementedError()
1831 def get_multi_unique_constraints(
1832 self,
1833 connection: Connection,
1834 *,
1835 schema: Optional[str] = None,
1836 filter_names: Optional[Collection[str]] = None,
1837 **kw: Any,
1838 ) -> Iterable[Tuple[TableKey, List[ReflectedUniqueConstraint]]]:
1839 """Return information about unique constraints in all tables
1840 in the given ``schema``.
1842 This is an internal dialect method. Applications should use
1843 :meth:`.Inspector.get_multi_unique_constraints`.
1845 .. note:: The :class:`_engine.DefaultDialect` provides a default
1846 implementation that will call the single table method for
1847 each object returned by :meth:`Dialect.get_table_names`,
1848 :meth:`Dialect.get_view_names` or
1849 :meth:`Dialect.get_materialized_view_names` depending on the
1850 provided ``kind``. Dialects that want to support a faster
1851 implementation should implement this method.
1853 .. versionadded:: 2.0
1855 """
1857 raise NotImplementedError()
1859 def get_check_constraints(
1860 self,
1861 connection: Connection,
1862 table_name: str,
1863 schema: Optional[str] = None,
1864 **kw: Any,
1865 ) -> List[ReflectedCheckConstraint]:
1866 r"""Return information about check constraints in ``table_name``.
1868 Given a string ``table_name`` and an optional string ``schema``, return
1869 check constraint information as a list of dicts corresponding
1870 to the :class:`.ReflectedCheckConstraint` dictionary.
1872 This is an internal dialect method. Applications should use
1873 :meth:`.Inspector.get_check_constraints`.
1875 """
1877 raise NotImplementedError()
1879 def get_multi_check_constraints(
1880 self,
1881 connection: Connection,
1882 *,
1883 schema: Optional[str] = None,
1884 filter_names: Optional[Collection[str]] = None,
1885 **kw: Any,
1886 ) -> Iterable[Tuple[TableKey, List[ReflectedCheckConstraint]]]:
1887 """Return information about check constraints in all tables
1888 in the given ``schema``.
1890 This is an internal dialect method. Applications should use
1891 :meth:`.Inspector.get_multi_check_constraints`.
1893 .. note:: The :class:`_engine.DefaultDialect` provides a default
1894 implementation that will call the single table method for
1895 each object returned by :meth:`Dialect.get_table_names`,
1896 :meth:`Dialect.get_view_names` or
1897 :meth:`Dialect.get_materialized_view_names` depending on the
1898 provided ``kind``. Dialects that want to support a faster
1899 implementation should implement this method.
1901 .. versionadded:: 2.0
1903 """
1905 raise NotImplementedError()
1907 def get_table_options(
1908 self,
1909 connection: Connection,
1910 table_name: str,
1911 schema: Optional[str] = None,
1912 **kw: Any,
1913 ) -> Dict[str, Any]:
1914 """Return a dictionary of options specified when ``table_name``
1915 was created.
1917 This is an internal dialect method. Applications should use
1918 :meth:`_engine.Inspector.get_table_options`.
1919 """
1920 raise NotImplementedError()
1922 def get_multi_table_options(
1923 self,
1924 connection: Connection,
1925 *,
1926 schema: Optional[str] = None,
1927 filter_names: Optional[Collection[str]] = None,
1928 **kw: Any,
1929 ) -> Iterable[Tuple[TableKey, Dict[str, Any]]]:
1930 """Return a dictionary of options specified when the tables in the
1931 given schema were created.
1933 This is an internal dialect method. Applications should use
1934 :meth:`_engine.Inspector.get_multi_table_options`.
1936 .. note:: The :class:`_engine.DefaultDialect` provides a default
1937 implementation that will call the single table method for
1938 each object returned by :meth:`Dialect.get_table_names`,
1939 :meth:`Dialect.get_view_names` or
1940 :meth:`Dialect.get_materialized_view_names` depending on the
1941 provided ``kind``. Dialects that want to support a faster
1942 implementation should implement this method.
1944 .. versionadded:: 2.0
1946 """
1947 raise NotImplementedError()
1949 def get_table_comment(
1950 self,
1951 connection: Connection,
1952 table_name: str,
1953 schema: Optional[str] = None,
1954 **kw: Any,
1955 ) -> ReflectedTableComment:
1956 r"""Return the "comment" for the table identified by ``table_name``.
1958 Given a string ``table_name`` and an optional string ``schema``, return
1959 table comment information as a dictionary corresponding to the
1960 :class:`.ReflectedTableComment` dictionary.
1962 This is an internal dialect method. Applications should use
1963 :meth:`.Inspector.get_table_comment`.
1965 :raise: ``NotImplementedError`` for dialects that don't support
1966 comments.
1968 """
1970 raise NotImplementedError()
1972 def get_multi_table_comment(
1973 self,
1974 connection: Connection,
1975 *,
1976 schema: Optional[str] = None,
1977 filter_names: Optional[Collection[str]] = None,
1978 **kw: Any,
1979 ) -> Iterable[Tuple[TableKey, ReflectedTableComment]]:
1980 """Return information about the table comment in all tables
1981 in the given ``schema``.
1983 This is an internal dialect method. Applications should use
1984 :meth:`_engine.Inspector.get_multi_table_comment`.
1986 .. note:: The :class:`_engine.DefaultDialect` provides a default
1987 implementation that will call the single table method for
1988 each object returned by :meth:`Dialect.get_table_names`,
1989 :meth:`Dialect.get_view_names` or
1990 :meth:`Dialect.get_materialized_view_names` depending on the
1991 provided ``kind``. Dialects that want to support a faster
1992 implementation should implement this method.
1994 .. versionadded:: 2.0
1996 """
1998 raise NotImplementedError()
2000 def normalize_name(self, name: str) -> str:
2001 """convert the given name to lowercase if it is detected as
2002 case insensitive.
2004 This method is only used if the dialect defines
2005 requires_name_normalize=True.
2007 """
2008 raise NotImplementedError()
2010 def denormalize_name(self, name: str) -> str:
2011 """convert the given name to a case insensitive identifier
2012 for the backend if it is an all-lowercase name.
2014 This method is only used if the dialect defines
2015 requires_name_normalize=True.
2017 """
2018 raise NotImplementedError()
2020 def has_table(
2021 self,
2022 connection: Connection,
2023 table_name: str,
2024 schema: Optional[str] = None,
2025 **kw: Any,
2026 ) -> bool:
2027 """For internal dialect use, check the existence of a particular table
2028 or view in the database.
2030 Given a :class:`_engine.Connection` object, a string table_name and
2031 optional schema name, return True if the given table exists in the
2032 database, False otherwise.
2034 This method serves as the underlying implementation of the
2035 public facing :meth:`.Inspector.has_table` method, and is also used
2036 internally to implement the "checkfirst" behavior for methods like
2037 :meth:`_schema.Table.create` and :meth:`_schema.MetaData.create_all`.
2039 .. note:: This method is used internally by SQLAlchemy, and is
2040 published so that third-party dialects may provide an
2041 implementation. It is **not** the public API for checking for table
2042 presence. Please use the :meth:`.Inspector.has_table` method.
2044 .. versionchanged:: 2.0:: :meth:`_engine.Dialect.has_table` now
2045 formally supports checking for additional table-like objects:
2047 * any type of views (plain or materialized)
2048 * temporary tables of any kind
2050 Previously, these two checks were not formally specified and
2051 different dialects would vary in their behavior. The dialect
2052 testing suite now includes tests for all of these object types,
2053 and dialects to the degree that the backing database supports views
2054 or temporary tables should seek to support locating these objects
2055 for full compliance.
2057 """
2059 raise NotImplementedError()
2061 def has_multi_table(
2062 self,
2063 connection: Connection,
2064 table_names: Sequence[str],
2065 schema: Optional[str] = None,
2066 **kw: Any,
2067 ) -> Iterable[Tuple[TableKey, bool]]:
2068 """For internal dialect use, check the existence of a particular list
2069 of tables or views in the database.
2071 This is an internal dialect method. Applications should use
2072 :meth:`.Inspector.has_multi_table`.
2074 .. note:: The :class:`_engine.DefaultDialect` provides a default
2075 implementation that will call the single table method for
2076 each table name provided. Dialects that want to support a faster
2077 implementation should implement this method.
2079 .. versionadded:: 2.1
2081 """
2083 raise NotImplementedError()
2085 def has_index(
2086 self,
2087 connection: Connection,
2088 table_name: str,
2089 index_name: str,
2090 schema: Optional[str] = None,
2091 **kw: Any,
2092 ) -> bool:
2093 """Check the existence of a particular index name in the database.
2095 Given a :class:`_engine.Connection` object, a string
2096 ``table_name`` and string index name, return ``True`` if an index of
2097 the given name on the given table exists, ``False`` otherwise.
2099 The :class:`.DefaultDialect` implements this in terms of the
2100 :meth:`.Dialect.has_table` and :meth:`.Dialect.get_indexes` methods,
2101 however dialects can implement a more performant version.
2103 This is an internal dialect method. Applications should use
2104 :meth:`_engine.Inspector.has_index`.
2106 .. versionadded:: 1.4
2108 """
2110 raise NotImplementedError()
2112 def has_sequence(
2113 self,
2114 connection: Connection,
2115 sequence_name: str,
2116 schema: Optional[str] = None,
2117 **kw: Any,
2118 ) -> bool:
2119 """Check the existence of a particular sequence in the database.
2121 Given a :class:`_engine.Connection` object and a string
2122 `sequence_name`, return ``True`` if the given sequence exists in
2123 the database, ``False`` otherwise.
2125 This is an internal dialect method. Applications should use
2126 :meth:`_engine.Inspector.has_sequence`.
2127 """
2129 raise NotImplementedError()
2131 def has_schema(
2132 self, connection: Connection, schema_name: str, **kw: Any
2133 ) -> bool:
2134 """Check the existence of a particular schema name in the database.
2136 Given a :class:`_engine.Connection` object, a string
2137 ``schema_name``, return ``True`` if a schema of the
2138 given exists, ``False`` otherwise.
2140 The :class:`.DefaultDialect` implements this by checking
2141 the presence of ``schema_name`` among the schemas returned by
2142 :meth:`.Dialect.get_schema_names`,
2143 however dialects can implement a more performant version.
2145 This is an internal dialect method. Applications should use
2146 :meth:`_engine.Inspector.has_schema`.
2148 .. versionadded:: 2.0
2150 """
2152 raise NotImplementedError()
2154 def _get_server_version_info(self, connection: Connection) -> Any:
2155 """Retrieve the server version info from the given connection.
2157 This is used by the default implementation to populate the
2158 "server_version_info" attribute and is called exactly
2159 once upon first connect.
2161 """
2163 raise NotImplementedError()
2165 def _get_default_schema_name(self, connection: Connection) -> str:
2166 """Return the string name of the currently selected schema from
2167 the given connection.
2169 This is used by the default implementation to populate the
2170 "default_schema_name" attribute and is called exactly
2171 once upon first connect.
2173 """
2175 raise NotImplementedError()
2177 def do_begin(self, dbapi_connection: PoolProxiedConnection) -> None:
2178 """Provide an implementation of ``connection.begin()``, given a
2179 DB-API connection.
2181 The DBAPI has no dedicated "begin" method and it is expected
2182 that transactions are implicit. This hook is provided for those
2183 DBAPIs that might need additional help in this area.
2185 :param dbapi_connection: a DBAPI connection, typically
2186 proxied within a :class:`.ConnectionFairy`.
2188 """
2190 raise NotImplementedError()
2192 def do_rollback(self, dbapi_connection: PoolProxiedConnection) -> None:
2193 """Provide an implementation of ``connection.rollback()``, given
2194 a DB-API connection.
2196 :param dbapi_connection: a DBAPI connection, typically
2197 proxied within a :class:`.ConnectionFairy`.
2199 """
2201 raise NotImplementedError()
2203 def do_commit(self, dbapi_connection: PoolProxiedConnection) -> None:
2204 """Provide an implementation of ``connection.commit()``, given a
2205 DB-API connection.
2207 :param dbapi_connection: a DBAPI connection, typically
2208 proxied within a :class:`.ConnectionFairy`.
2210 """
2212 raise NotImplementedError()
2214 def do_terminate(self, dbapi_connection: DBAPIConnection) -> None:
2215 """Provide an implementation of ``connection.close()`` that tries as
2216 much as possible to not block, given a DBAPI
2217 connection.
2219 In the vast majority of cases this just calls .close(), however
2220 for some asyncio dialects may call upon different API features.
2222 This hook is called by the :class:`_pool.Pool`
2223 when a connection is being recycled or has been invalidated.
2225 .. versionadded:: 1.4.41
2227 """
2229 raise NotImplementedError()
2231 def do_close(self, dbapi_connection: DBAPIConnection) -> None:
2232 """Provide an implementation of ``connection.close()``, given a DBAPI
2233 connection.
2235 This hook is called by the :class:`_pool.Pool`
2236 when a connection has been
2237 detached from the pool, or is being returned beyond the normal
2238 capacity of the pool.
2240 """
2242 raise NotImplementedError()
2244 def _do_ping_w_event(self, dbapi_connection: DBAPIConnection) -> bool:
2245 raise NotImplementedError()
2247 def do_ping(self, dbapi_connection: DBAPIConnection) -> bool:
2248 """ping the DBAPI connection and return True if the connection is
2249 usable."""
2250 raise NotImplementedError()
2252 def do_set_input_sizes(
2253 self,
2254 cursor: DBAPICursor,
2255 list_of_tuples: _GenericSetInputSizesType,
2256 context: ExecutionContext,
2257 ) -> Any:
2258 """invoke the cursor.setinputsizes() method with appropriate arguments
2260 This hook is called if the :attr:`.Dialect.bind_typing` attribute is
2261 set to the
2262 :attr:`.BindTyping.SETINPUTSIZES` value.
2263 Parameter data is passed in a list of tuples (paramname, dbtype,
2264 sqltype), where ``paramname`` is the key of the parameter in the
2265 statement, ``dbtype`` is the DBAPI datatype and ``sqltype`` is the
2266 SQLAlchemy type. The order of tuples is in the correct parameter order.
2268 .. versionadded:: 1.4
2270 .. versionchanged:: 2.0 - setinputsizes mode is now enabled by
2271 setting :attr:`.Dialect.bind_typing` to
2272 :attr:`.BindTyping.SETINPUTSIZES`. Dialects which accept
2273 a ``use_setinputsizes`` parameter should set this value
2274 appropriately.
2277 """
2278 raise NotImplementedError()
2280 def create_xid(self) -> Any:
2281 """Create a two-phase transaction ID.
2283 This id will be passed to do_begin_twophase(),
2284 do_rollback_twophase(), do_commit_twophase(). Its format is
2285 unspecified.
2286 """
2288 raise NotImplementedError()
2290 def do_savepoint(self, connection: Connection, name: str) -> None:
2291 """Create a savepoint with the given name.
2293 :param connection: a :class:`_engine.Connection`.
2294 :param name: savepoint name.
2296 """
2298 raise NotImplementedError()
2300 def do_rollback_to_savepoint(
2301 self, connection: Connection, name: str
2302 ) -> None:
2303 """Rollback a connection to the named savepoint.
2305 :param connection: a :class:`_engine.Connection`.
2306 :param name: savepoint name.
2308 """
2310 raise NotImplementedError()
2312 def do_release_savepoint(self, connection: Connection, name: str) -> None:
2313 """Release the named savepoint on a connection.
2315 :param connection: a :class:`_engine.Connection`.
2316 :param name: savepoint name.
2317 """
2319 raise NotImplementedError()
2321 def do_begin_twophase(self, connection: Connection, xid: Any) -> None:
2322 """Begin a two phase transaction on the given connection.
2324 :param connection: a :class:`_engine.Connection`.
2325 :param xid: xid
2327 """
2329 raise NotImplementedError()
2331 def do_prepare_twophase(self, connection: Connection, xid: Any) -> None:
2332 """Prepare a two phase transaction on the given connection.
2334 :param connection: a :class:`_engine.Connection`.
2335 :param xid: xid
2337 """
2339 raise NotImplementedError()
2341 def do_rollback_twophase(
2342 self,
2343 connection: Connection,
2344 xid: Any,
2345 is_prepared: bool = True,
2346 recover: bool = False,
2347 ) -> None:
2348 """Rollback a two phase transaction on the given connection.
2350 :param connection: a :class:`_engine.Connection`.
2351 :param xid: xid
2352 :param is_prepared: whether or not
2353 :meth:`.TwoPhaseTransaction.prepare` was called.
2354 :param recover: if the recover flag was passed.
2356 """
2358 raise NotImplementedError()
2360 def do_commit_twophase(
2361 self,
2362 connection: Connection,
2363 xid: Any,
2364 is_prepared: bool = True,
2365 recover: bool = False,
2366 ) -> None:
2367 """Commit a two phase transaction on the given connection.
2370 :param connection: a :class:`_engine.Connection`.
2371 :param xid: xid
2372 :param is_prepared: whether or not
2373 :meth:`.TwoPhaseTransaction.prepare` was called.
2374 :param recover: if the recover flag was passed.
2376 """
2378 raise NotImplementedError()
2380 def do_recover_twophase(self, connection: Connection) -> List[Any]:
2381 """Recover list of uncommitted prepared two phase transaction
2382 identifiers on the given connection.
2384 :param connection: a :class:`_engine.Connection`.
2386 """
2388 raise NotImplementedError()
2390 def _deliver_insertmanyvalues_batches(
2391 self,
2392 connection: Connection,
2393 cursor: DBAPICursor,
2394 statement: str,
2395 parameters: _DBAPIMultiExecuteParams,
2396 generic_setinputsizes: Optional[_GenericSetInputSizesType],
2397 context: ExecutionContext,
2398 ) -> Iterator[_InsertManyValuesBatch]:
2399 """convert executemany parameters for an INSERT into an iterator
2400 of statement/single execute values, used by the insertmanyvalues
2401 feature.
2403 """
2404 raise NotImplementedError()
2406 def do_executemany(
2407 self,
2408 cursor: DBAPICursor,
2409 statement: str,
2410 parameters: _DBAPIMultiExecuteParams,
2411 context: Optional[ExecutionContext] = None,
2412 ) -> None:
2413 """Provide an implementation of ``cursor.executemany(statement,
2414 parameters)``."""
2416 raise NotImplementedError()
2418 def do_execute(
2419 self,
2420 cursor: DBAPICursor,
2421 statement: str,
2422 parameters: Optional[_DBAPISingleExecuteParams],
2423 context: Optional[ExecutionContext] = None,
2424 ) -> None:
2425 """Provide an implementation of ``cursor.execute(statement,
2426 parameters)``."""
2428 raise NotImplementedError()
2430 def do_execute_no_params(
2431 self,
2432 cursor: DBAPICursor,
2433 statement: str,
2434 context: Optional[ExecutionContext] = None,
2435 ) -> None:
2436 """Provide an implementation of ``cursor.execute(statement)``.
2438 The parameter collection should not be sent.
2440 """
2442 raise NotImplementedError()
2444 def is_disconnect(
2445 self,
2446 e: DBAPIModule.Error,
2447 connection: Optional[Union[PoolProxiedConnection, DBAPIConnection]],
2448 cursor: Optional[DBAPICursor],
2449 ) -> bool:
2450 """Return True if the given DB-API error indicates an invalid
2451 connection"""
2453 raise NotImplementedError()
2455 def connect(self, *cargs: Any, **cparams: Any) -> DBAPIConnection:
2456 r"""Establish a connection using this dialect's DBAPI.
2458 The default implementation of this method is::
2460 def connect(self, *cargs, **cparams):
2461 return self.dbapi.connect(*cargs, **cparams)
2463 The ``*cargs, **cparams`` parameters are generated directly
2464 from this dialect's :meth:`.Dialect.create_connect_args` method.
2466 This method may be used for dialects that need to perform programmatic
2467 per-connection steps when a new connection is procured from the
2468 DBAPI.
2471 :param \*cargs: positional parameters returned from the
2472 :meth:`.Dialect.create_connect_args` method
2474 :param \*\*cparams: keyword parameters returned from the
2475 :meth:`.Dialect.create_connect_args` method.
2477 :return: a DBAPI connection, typically from the :pep:`249` module
2478 level ``.connect()`` function.
2480 .. seealso::
2482 :meth:`.Dialect.create_connect_args`
2484 :meth:`.Dialect.on_connect`
2486 """
2487 raise NotImplementedError()
2489 def on_connect_url(self, url: URL) -> Optional[Callable[[Any], Any]]:
2490 """return a callable which sets up a newly created DBAPI connection.
2492 This method is a new hook that supersedes the
2493 :meth:`_engine.Dialect.on_connect` method when implemented by a
2494 dialect. When not implemented by a dialect, it invokes the
2495 :meth:`_engine.Dialect.on_connect` method directly to maintain
2496 compatibility with existing dialects. There is no deprecation
2497 for :meth:`_engine.Dialect.on_connect` expected.
2499 The callable should accept a single argument "conn" which is the
2500 DBAPI connection itself. The inner callable has no
2501 return value.
2503 E.g.::
2505 class MyDialect(default.DefaultDialect):
2506 # ...
2508 def on_connect_url(self, url):
2509 def do_on_connect(connection):
2510 connection.execute("SET SPECIAL FLAGS etc")
2512 return do_on_connect
2514 This is used to set dialect-wide per-connection options such as
2515 isolation modes, Unicode modes, etc.
2517 This method differs from :meth:`_engine.Dialect.on_connect` in that
2518 it is passed the :class:`_engine.URL` object that's relevant to the
2519 connect args. Normally the only way to get this is from the
2520 :meth:`_engine.Dialect.on_connect` hook is to look on the
2521 :class:`_engine.Engine` itself, however this URL object may have been
2522 replaced by plugins.
2524 .. note::
2526 The default implementation of
2527 :meth:`_engine.Dialect.on_connect_url` is to invoke the
2528 :meth:`_engine.Dialect.on_connect` method. Therefore if a dialect
2529 implements this method, the :meth:`_engine.Dialect.on_connect`
2530 method **will not be called** unless the overriding dialect calls
2531 it directly from here.
2533 .. versionadded:: 1.4.3 added :meth:`_engine.Dialect.on_connect_url`
2534 which normally calls into :meth:`_engine.Dialect.on_connect`.
2536 :param url: a :class:`_engine.URL` object representing the
2537 :class:`_engine.URL` that was passed to the
2538 :meth:`_engine.Dialect.create_connect_args` method.
2540 :return: a callable that accepts a single DBAPI connection as an
2541 argument, or None.
2543 .. seealso::
2545 :meth:`_engine.Dialect.on_connect`
2547 """
2548 return self.on_connect()
2550 def on_connect(self) -> Optional[Callable[[Any], None]]:
2551 """return a callable which sets up a newly created DBAPI connection.
2553 The callable should accept a single argument "conn" which is the
2554 DBAPI connection itself. The inner callable has no
2555 return value.
2557 E.g.::
2559 class MyDialect(default.DefaultDialect):
2560 # ...
2562 def on_connect(self):
2563 def do_on_connect(connection):
2564 connection.execute("SET SPECIAL FLAGS etc")
2566 return do_on_connect
2568 This is used to set dialect-wide per-connection options such as
2569 isolation modes, Unicode modes, etc.
2571 The "do_on_connect" callable is invoked by using the
2572 :meth:`_events.PoolEvents.connect` event
2573 hook, then unwrapping the DBAPI connection and passing it into the
2574 callable.
2576 .. versionchanged:: 1.4 the on_connect hook is no longer called twice
2577 for the first connection of a dialect. The on_connect hook is still
2578 called before the :meth:`_engine.Dialect.initialize` method however.
2580 .. versionchanged:: 1.4.3 the on_connect hook is invoked from a new
2581 method on_connect_url that passes the URL that was used to create
2582 the connect args. Dialects can implement on_connect_url instead
2583 of on_connect if they need the URL object that was used for the
2584 connection in order to get additional context.
2586 If None is returned, no event listener is generated.
2588 :return: a callable that accepts a single DBAPI connection as an
2589 argument, or None.
2591 .. seealso::
2593 :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence
2594 itself to be controlled.
2596 :meth:`.Dialect.on_connect_url` - supersedes
2597 :meth:`.Dialect.on_connect` to also receive the
2598 :class:`_engine.URL` object in context.
2600 """
2601 return None
2603 def reset_isolation_level(self, dbapi_connection: DBAPIConnection) -> None:
2604 """Given a DBAPI connection, revert its isolation to the default.
2606 Note that this is a dialect-level method which is used as part
2607 of the implementation of the :class:`_engine.Connection` and
2608 :class:`_engine.Engine`
2609 isolation level facilities; these APIs should be preferred for
2610 most typical use cases.
2612 .. seealso::
2614 :meth:`_engine.Connection.get_isolation_level`
2615 - view current level
2617 :attr:`_engine.Connection.default_isolation_level`
2618 - view default level
2620 :paramref:`.Connection.execution_options.isolation_level` -
2621 set per :class:`_engine.Connection` isolation level
2623 :paramref:`_sa.create_engine.isolation_level` -
2624 set per :class:`_engine.Engine` isolation level
2626 """
2628 raise NotImplementedError()
2630 def set_isolation_level(
2631 self, dbapi_connection: DBAPIConnection, level: IsolationLevel
2632 ) -> None:
2633 """Given a DBAPI connection, set its isolation level.
2635 Note that this is a dialect-level method which is used as part
2636 of the implementation of the :class:`_engine.Connection` and
2637 :class:`_engine.Engine`
2638 isolation level facilities; these APIs should be preferred for
2639 most typical use cases.
2641 If the dialect also implements the
2642 :meth:`.Dialect.get_isolation_level_values` method, then the given
2643 level is guaranteed to be one of the string names within that sequence,
2644 and the method will not need to anticipate a lookup failure.
2646 .. seealso::
2648 :meth:`_engine.Connection.get_isolation_level`
2649 - view current level
2651 :attr:`_engine.Connection.default_isolation_level`
2652 - view default level
2654 :paramref:`.Connection.execution_options.isolation_level` -
2655 set per :class:`_engine.Connection` isolation level
2657 :paramref:`_sa.create_engine.isolation_level` -
2658 set per :class:`_engine.Engine` isolation level
2660 """
2662 raise NotImplementedError()
2664 def get_isolation_level(
2665 self, dbapi_connection: DBAPIConnection
2666 ) -> IsolationLevel:
2667 """Given a DBAPI connection, return its isolation level.
2669 When working with a :class:`_engine.Connection` object,
2670 the corresponding
2671 DBAPI connection may be procured using the
2672 :attr:`_engine.Connection.connection` accessor.
2674 Note that this is a dialect-level method which is used as part
2675 of the implementation of the :class:`_engine.Connection` and
2676 :class:`_engine.Engine` isolation level facilities;
2677 these APIs should be preferred for most typical use cases.
2680 .. seealso::
2682 :meth:`_engine.Connection.get_isolation_level`
2683 - view current level
2685 :attr:`_engine.Connection.default_isolation_level`
2686 - view default level
2688 :paramref:`.Connection.execution_options.isolation_level` -
2689 set per :class:`_engine.Connection` isolation level
2691 :paramref:`_sa.create_engine.isolation_level` -
2692 set per :class:`_engine.Engine` isolation level
2695 """
2697 raise NotImplementedError()
2699 def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
2700 """Detect the current autocommit setting for a DBAPI connection.
2702 :param dbapi_connection: a DBAPI connection object
2703 :return: True if autocommit is enabled, False if disabled
2704 :rtype: bool
2706 This method inspects the given DBAPI connection to determine
2707 whether autocommit mode is currently enabled. The specific
2708 mechanism for detecting autocommit varies by database dialect
2709 and DBAPI driver, however it should be done **without** network
2710 round trips.
2712 .. note::
2714 Not all dialects support autocommit detection. Dialects
2715 that do not support this feature will raise
2716 :exc:`NotImplementedError`.
2718 """
2719 raise NotImplementedError(
2720 "This dialect cannot detect autocommit on a DBAPI connection"
2721 )
2723 def get_default_isolation_level(
2724 self, dbapi_conn: DBAPIConnection
2725 ) -> IsolationLevel:
2726 """Given a DBAPI connection, return its isolation level, or
2727 a default isolation level if one cannot be retrieved.
2729 This method may only raise NotImplementedError and
2730 **must not raise any other exception**, as it is used implicitly upon
2731 first connect.
2733 The method **must return a value** for a dialect that supports
2734 isolation level settings, as this level is what will be reverted
2735 towards when a per-connection isolation level change is made.
2737 The method defaults to using the :meth:`.Dialect.get_isolation_level`
2738 method unless overridden by a dialect.
2740 """
2741 raise NotImplementedError()
2743 def get_isolation_level_values(
2744 self, dbapi_conn: DBAPIConnection
2745 ) -> Sequence[IsolationLevel]:
2746 """return a sequence of string isolation level names that are accepted
2747 by this dialect.
2749 The available names should use the following conventions:
2751 * use UPPERCASE names. isolation level methods will accept lowercase
2752 names but these are normalized into UPPERCASE before being passed
2753 along to the dialect.
2754 * separate words should be separated by spaces, not underscores, e.g.
2755 ``REPEATABLE READ``. isolation level names will have underscores
2756 converted to spaces before being passed along to the dialect.
2757 * The names for the four standard isolation names to the extent that
2758 they are supported by the backend should be ``READ UNCOMMITTED``,
2759 ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``
2760 * if the dialect supports an autocommit option it should be provided
2761 using the isolation level name ``AUTOCOMMIT``.
2762 * Other isolation modes may also be present, provided that they
2763 are named in UPPERCASE and use spaces not underscores.
2765 This function is used so that the default dialect can check that
2766 a given isolation level parameter is valid, else raises an
2767 :class:`_exc.ArgumentError`.
2769 A DBAPI connection is passed to the method, in the unlikely event that
2770 the dialect needs to interrogate the connection itself to determine
2771 this list, however it is expected that most backends will return
2772 a hardcoded list of values. If the dialect supports "AUTOCOMMIT",
2773 that value should also be present in the sequence returned.
2775 The method raises ``NotImplementedError`` by default. If a dialect
2776 does not implement this method, then the default dialect will not
2777 perform any checking on a given isolation level value before passing
2778 it onto the :meth:`.Dialect.set_isolation_level` method. This is
2779 to allow backwards-compatibility with third party dialects that may
2780 not yet be implementing this method.
2782 .. versionadded:: 2.0
2784 """
2785 raise NotImplementedError()
2787 def _assert_and_set_isolation_level(
2788 self, dbapi_conn: DBAPIConnection, level: IsolationLevel
2789 ) -> None:
2790 raise NotImplementedError()
2792 @classmethod
2793 def get_dialect_cls(cls, url: URL) -> Type[Dialect]:
2794 """Given a URL, return the :class:`.Dialect` that will be used.
2796 This is a hook that allows an external plugin to provide functionality
2797 around an existing dialect, by allowing the plugin to be loaded
2798 from the url based on an entrypoint, and then the plugin returns
2799 the actual dialect to be used.
2801 By default this just returns the cls.
2803 """
2804 return cls
2806 @classmethod
2807 def get_async_dialect_cls(cls, url: URL) -> Type[Dialect]:
2808 """Given a URL, return the :class:`.Dialect` that will be used by
2809 an async engine.
2811 By default this is an alias of :meth:`.Dialect.get_dialect_cls` and
2812 just returns the cls. It may be used if a dialect provides
2813 both a sync and async version under the same name, like the
2814 ``psycopg`` driver.
2816 .. versionadded:: 2
2818 .. seealso::
2820 :meth:`.Dialect.get_dialect_cls`
2822 """
2823 return cls.get_dialect_cls(url)
2825 @classmethod
2826 def load_provisioning(cls) -> None:
2827 """set up the provision.py module for this dialect.
2829 For dialects that include a provision.py module that sets up
2830 provisioning followers, this method should initiate that process.
2832 A typical implementation would be::
2834 @classmethod
2835 def load_provisioning(cls):
2836 __import__("mydialect.provision")
2838 The default method assumes a module named ``provision.py`` inside
2839 the owning package of the current dialect, based on the ``__module__``
2840 attribute::
2842 @classmethod
2843 def load_provisioning(cls):
2844 package = ".".join(cls.__module__.split(".")[0:-1])
2845 try:
2846 __import__(package + ".provision")
2847 except ImportError:
2848 pass
2850 """
2852 @classmethod
2853 def engine_created(cls, engine: Engine) -> None:
2854 """A convenience hook called before returning the final
2855 :class:`_engine.Engine`.
2857 If the dialect returned a different class from the
2858 :meth:`.get_dialect_cls`
2859 method, then the hook is called on both classes, first on
2860 the dialect class returned by the :meth:`.get_dialect_cls` method and
2861 then on the class on which the method was called.
2863 The hook should be used by dialects and/or wrappers to apply special
2864 events to the engine or its components. In particular, it allows
2865 a dialect-wrapping class to apply dialect-level events.
2867 """
2869 def get_driver_connection(self, connection: DBAPIConnection) -> Any:
2870 """Returns the connection object as returned by the external driver
2871 package.
2873 For normal dialects that use a DBAPI compliant driver this call
2874 will just return the ``connection`` passed as argument.
2875 For dialects that instead adapt a non DBAPI compliant driver, like
2876 when adapting an asyncio driver, this call will return the
2877 connection-like object as returned by the driver.
2879 .. versionadded:: 1.4.24
2881 """
2882 raise NotImplementedError()
2884 def set_engine_execution_options(
2885 self, engine: Engine, opts: CoreExecuteOptionsParameter
2886 ) -> None:
2887 """Establish execution options for a given engine.
2889 This is implemented by :class:`.DefaultDialect` to establish
2890 event hooks for new :class:`.Connection` instances created
2891 by the given :class:`.Engine` which will then invoke the
2892 :meth:`.Dialect.set_connection_execution_options` method for that
2893 connection.
2895 """
2896 raise NotImplementedError()
2898 def set_connection_execution_options(
2899 self, connection: Connection, opts: CoreExecuteOptionsParameter
2900 ) -> None:
2901 """Establish execution options for a given connection.
2903 This is implemented by :class:`.DefaultDialect` in order to implement
2904 the :paramref:`_engine.Connection.execution_options.isolation_level`
2905 execution option. Dialects can intercept various execution options
2906 which may need to modify state on a particular DBAPI connection.
2908 .. versionadded:: 1.4
2910 """
2911 raise NotImplementedError()
2913 def get_dialect_pool_class(self, url: URL) -> Type[Pool]:
2914 """return a Pool class to use for a given URL"""
2915 raise NotImplementedError()
2917 def validate_identifier(self, ident: str) -> None:
2918 """Validates an identifier name, raising an exception if invalid"""
2921class CreateEnginePlugin:
2922 """A set of hooks intended to augment the construction of an
2923 :class:`_engine.Engine` object based on entrypoint names in a URL.
2925 The purpose of :class:`_engine.CreateEnginePlugin` is to allow third-party
2926 systems to apply engine, pool and dialect level event listeners without
2927 the need for the target application to be modified; instead, the plugin
2928 names can be added to the database URL. Target applications for
2929 :class:`_engine.CreateEnginePlugin` include:
2931 * connection and SQL performance tools, e.g. which use events to track
2932 number of checkouts and/or time spent with statements
2934 * connectivity plugins such as proxies
2936 A rudimentary :class:`_engine.CreateEnginePlugin` that attaches a logger
2937 to an :class:`_engine.Engine` object might look like::
2940 import logging
2942 from sqlalchemy.engine import CreateEnginePlugin
2943 from sqlalchemy import event
2946 class LogCursorEventsPlugin(CreateEnginePlugin):
2947 def __init__(self, url, kwargs):
2948 # consume the parameter "log_cursor_logging_name" from the
2949 # URL query
2950 logging_name = url.query.get(
2951 "log_cursor_logging_name", "log_cursor"
2952 )
2954 self.log = logging.getLogger(logging_name)
2956 def update_url(self, url):
2957 "update the URL to one that no longer includes our parameters"
2958 return url.difference_update_query(["log_cursor_logging_name"])
2960 def engine_created(self, engine):
2961 "attach an event listener after the new Engine is constructed"
2962 event.listen(engine, "before_cursor_execute", self._log_event)
2964 def _log_event(
2965 self,
2966 conn,
2967 cursor,
2968 statement,
2969 parameters,
2970 context,
2971 executemany,
2972 ):
2974 self.log.info("Plugin logged cursor event: %s", statement)
2976 Plugins are registered using entry points in a similar way as that
2977 of dialects::
2979 entry_points = {
2980 "sqlalchemy.plugins": [
2981 "log_cursor_plugin = myapp.plugins:LogCursorEventsPlugin"
2982 ]
2983 }
2985 A plugin that uses the above names would be invoked from a database
2986 URL as in::
2988 from sqlalchemy import create_engine
2990 engine = create_engine(
2991 "mysql+pymysql://scott:tiger@localhost/test?"
2992 "plugin=log_cursor_plugin&log_cursor_logging_name=mylogger"
2993 )
2995 The ``plugin`` URL parameter supports multiple instances, so that a URL
2996 may specify multiple plugins; they are loaded in the order stated
2997 in the URL::
2999 engine = create_engine(
3000 "mysql+pymysql://scott:tiger@localhost/test?"
3001 "plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three"
3002 )
3004 The plugin names may also be passed directly to :func:`_sa.create_engine`
3005 using the :paramref:`_sa.create_engine.plugins` argument::
3007 engine = create_engine(
3008 "mysql+pymysql://scott:tiger@localhost/test", plugins=["myplugin"]
3009 )
3011 A plugin may consume plugin-specific arguments from the
3012 :class:`_engine.URL` object as well as the ``kwargs`` dictionary, which is
3013 the dictionary of arguments passed to the :func:`_sa.create_engine`
3014 call. "Consuming" these arguments includes that they must be removed
3015 when the plugin initializes, so that the arguments are not passed along
3016 to the :class:`_engine.Dialect` constructor, where they will raise an
3017 :class:`_exc.ArgumentError` because they are not known by the dialect.
3019 As of version 1.4 of SQLAlchemy, arguments should continue to be consumed
3020 from the ``kwargs`` dictionary directly, by removing the values with a
3021 method such as ``dict.pop``. Arguments from the :class:`_engine.URL` object
3022 should be consumed by implementing the
3023 :meth:`_engine.CreateEnginePlugin.update_url` method, returning a new copy
3024 of the :class:`_engine.URL` with plugin-specific parameters removed::
3026 class MyPlugin(CreateEnginePlugin):
3027 def __init__(self, url, kwargs):
3028 self.my_argument_one = url.query["my_argument_one"]
3029 self.my_argument_two = url.query["my_argument_two"]
3030 self.my_argument_three = kwargs.pop("my_argument_three", None)
3032 def update_url(self, url):
3033 return url.difference_update_query(
3034 ["my_argument_one", "my_argument_two"]
3035 )
3037 Arguments like those illustrated above would be consumed from a
3038 :func:`_sa.create_engine` call such as::
3040 from sqlalchemy import create_engine
3042 engine = create_engine(
3043 "mysql+pymysql://scott:tiger@localhost/test?"
3044 "plugin=myplugin&my_argument_one=foo&my_argument_two=bar",
3045 my_argument_three="bat",
3046 )
3048 .. versionchanged:: 1.4
3050 The :class:`_engine.URL` object is now immutable; a
3051 :class:`_engine.CreateEnginePlugin` that needs to alter the
3052 :class:`_engine.URL` should implement the newly added
3053 :meth:`_engine.CreateEnginePlugin.update_url` method, which
3054 is invoked after the plugin is constructed.
3056 For migration, construct the plugin in the following way, checking
3057 for the existence of the :meth:`_engine.CreateEnginePlugin.update_url`
3058 method to detect which version is running::
3060 class MyPlugin(CreateEnginePlugin):
3061 def __init__(self, url, kwargs):
3062 if hasattr(CreateEnginePlugin, "update_url"):
3063 # detect the 1.4 API
3064 self.my_argument_one = url.query["my_argument_one"]
3065 self.my_argument_two = url.query["my_argument_two"]
3066 else:
3067 # detect the 1.3 and earlier API - mutate the
3068 # URL directly
3069 self.my_argument_one = url.query.pop("my_argument_one")
3070 self.my_argument_two = url.query.pop("my_argument_two")
3072 self.my_argument_three = kwargs.pop("my_argument_three", None)
3074 def update_url(self, url):
3075 # this method is only called in the 1.4 version
3076 return url.difference_update_query(
3077 ["my_argument_one", "my_argument_two"]
3078 )
3080 .. seealso::
3082 :ref:`change_5526` - overview of the :class:`_engine.URL` change which
3083 also includes notes regarding :class:`_engine.CreateEnginePlugin`.
3086 When the engine creation process completes and produces the
3087 :class:`_engine.Engine` object, it is again passed to the plugin via the
3088 :meth:`_engine.CreateEnginePlugin.engine_created` hook. In this hook, additional
3089 changes can be made to the engine, most typically involving setup of
3090 events (e.g. those defined in :ref:`core_event_toplevel`).
3092 """ # noqa: E501
3094 def __init__(self, url: URL, kwargs: Dict[str, Any]):
3095 """Construct a new :class:`.CreateEnginePlugin`.
3097 The plugin object is instantiated individually for each call
3098 to :func:`_sa.create_engine`. A single :class:`_engine.
3099 Engine` will be
3100 passed to the :meth:`.CreateEnginePlugin.engine_created` method
3101 corresponding to this URL.
3103 :param url: the :class:`_engine.URL` object. The plugin may inspect
3104 the :class:`_engine.URL` for arguments. Arguments used by the
3105 plugin should be removed, by returning an updated :class:`_engine.URL`
3106 from the :meth:`_engine.CreateEnginePlugin.update_url` method.
3108 .. versionchanged:: 1.4
3110 The :class:`_engine.URL` object is now immutable, so a
3111 :class:`_engine.CreateEnginePlugin` that needs to alter the
3112 :class:`_engine.URL` object should implement the
3113 :meth:`_engine.CreateEnginePlugin.update_url` method.
3115 :param kwargs: The keyword arguments passed to
3116 :func:`_sa.create_engine`.
3118 """
3119 self.url = url
3121 def update_url(self, url: URL) -> URL:
3122 """Update the :class:`_engine.URL`.
3124 A new :class:`_engine.URL` should be returned. This method is
3125 typically used to consume configuration arguments from the
3126 :class:`_engine.URL` which must be removed, as they will not be
3127 recognized by the dialect. The
3128 :meth:`_engine.URL.difference_update_query` method is available
3129 to remove these arguments. See the docstring at
3130 :class:`_engine.CreateEnginePlugin` for an example.
3133 .. versionadded:: 1.4
3135 """
3136 raise NotImplementedError()
3138 def handle_dialect_kwargs(
3139 self, dialect_cls: Type[Dialect], dialect_args: Dict[str, Any]
3140 ) -> None:
3141 """parse and modify dialect kwargs"""
3143 def handle_pool_kwargs(
3144 self, pool_cls: Type[Pool], pool_args: Dict[str, Any]
3145 ) -> None:
3146 """parse and modify pool kwargs"""
3148 def engine_created(self, engine: Engine) -> None:
3149 """Receive the :class:`_engine.Engine`
3150 object when it is fully constructed.
3152 The plugin may make additional changes to the engine, such as
3153 registering engine or connection pool events.
3155 """
3158class ExecutionContext:
3159 """A messenger object for a Dialect that corresponds to a single
3160 execution.
3162 """
3164 engine: Engine
3165 """engine which the Connection is associated with"""
3167 connection: Connection
3168 """Connection object which can be freely used by default value
3169 generators to execute SQL. This Connection should reference the
3170 same underlying connection/transactional resources of
3171 root_connection."""
3173 root_connection: Connection
3174 """Connection object which is the source of this ExecutionContext."""
3176 dialect: Dialect
3177 """dialect which created this ExecutionContext."""
3179 cursor: DBAPICursor
3180 """DB-API cursor procured from the connection"""
3182 compiled: Optional[Compiled]
3183 """if passed to constructor, sqlalchemy.engine.base.Compiled object
3184 being executed"""
3186 statement: str
3187 """string version of the statement to be executed. Is either
3188 passed to the constructor, or must be created from the
3189 sql.Compiled object by the time pre_exec() has completed."""
3191 invoked_statement: Optional[Executable]
3192 """The Executable statement object that was given in the first place.
3194 This should be structurally equivalent to compiled.statement, but not
3195 necessarily the same object as in a caching scenario the compiled form
3196 will have been extracted from the cache.
3198 """
3200 parameters: _AnyMultiExecuteParams
3201 """bind parameters passed to the execute() or exec_driver_sql() methods.
3203 These are always stored as a list of parameter entries. A single-element
3204 list corresponds to a ``cursor.execute()`` call and a multiple-element
3205 list corresponds to ``cursor.executemany()``, except in the case
3206 of :attr:`.ExecuteStyle.INSERTMANYVALUES` which will use
3207 ``cursor.execute()`` one or more times.
3209 """
3211 no_parameters: bool
3212 """True if the execution style does not use parameters"""
3214 isinsert: bool
3215 """True if the statement is an INSERT."""
3217 isupdate: bool
3218 """True if the statement is an UPDATE."""
3220 execute_style: ExecuteStyle
3221 """the style of DBAPI cursor method that will be used to execute
3222 a statement.
3224 .. versionadded:: 2.0
3226 """
3228 executemany: bool
3229 """True if the context has a list of more than one parameter set.
3231 Historically this attribute links to whether ``cursor.execute()`` or
3232 ``cursor.executemany()`` will be used. It also can now mean that
3233 "insertmanyvalues" may be used which indicates one or more
3234 ``cursor.execute()`` calls.
3236 """
3238 prefetch_cols: util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]]
3239 """a list of Column objects for which a client-side default
3240 was fired off. Applies to inserts and updates."""
3242 postfetch_cols: util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]]
3243 """a list of Column objects for which a server-side default or
3244 inline SQL expression value was fired off. Applies to inserts
3245 and updates."""
3247 execution_options: _ExecuteOptions
3248 """Execution options associated with the current statement execution"""
3250 @classmethod
3251 def _init_ddl(
3252 cls,
3253 dialect: Dialect,
3254 connection: Connection,
3255 dbapi_connection: PoolProxiedConnection,
3256 execution_options: _ExecuteOptions,
3257 compiled_ddl: DDLCompiler,
3258 ) -> ExecutionContext:
3259 raise NotImplementedError()
3261 @classmethod
3262 def _init_compiled(
3263 cls,
3264 dialect: Dialect,
3265 connection: Connection,
3266 dbapi_connection: PoolProxiedConnection,
3267 execution_options: _ExecuteOptions,
3268 compiled: SQLCompiler,
3269 parameters: _CoreMultiExecuteParams,
3270 invoked_statement: Executable,
3271 extracted_parameters: Optional[Sequence[BindParameter[Any]]],
3272 cache_hit: CacheStats = CacheStats.CACHING_DISABLED,
3273 ) -> ExecutionContext:
3274 raise NotImplementedError()
3276 @classmethod
3277 def _init_statement(
3278 cls,
3279 dialect: Dialect,
3280 connection: Connection,
3281 dbapi_connection: PoolProxiedConnection,
3282 execution_options: _ExecuteOptions,
3283 statement: str,
3284 parameters: _DBAPIMultiExecuteParams,
3285 ) -> ExecutionContext:
3286 raise NotImplementedError()
3288 @classmethod
3289 def _init_default(
3290 cls,
3291 dialect: Dialect,
3292 connection: Connection,
3293 dbapi_connection: PoolProxiedConnection,
3294 execution_options: _ExecuteOptions,
3295 ) -> ExecutionContext:
3296 raise NotImplementedError()
3298 def _exec_default(
3299 self,
3300 column: Optional[Column[Any]],
3301 default: DefaultGenerator,
3302 type_: Optional[TypeEngine[Any]],
3303 ) -> Any:
3304 raise NotImplementedError()
3306 def _prepare_set_input_sizes(
3307 self,
3308 ) -> Optional[List[Tuple[str, Any, TypeEngine[Any]]]]:
3309 raise NotImplementedError()
3311 def _get_cache_stats(self) -> str:
3312 raise NotImplementedError()
3314 def _setup_result_proxy(self) -> CursorResult[Any]:
3315 raise NotImplementedError()
3317 def fire_sequence(self, seq: Sequence_SchemaItem, type_: Integer) -> int:
3318 """given a :class:`.Sequence`, invoke it and return the next int
3319 value"""
3320 raise NotImplementedError()
3322 def create_cursor(self) -> DBAPICursor:
3323 """Return a new cursor generated from this ExecutionContext's
3324 connection.
3326 Some dialects may wish to change the behavior of
3327 connection.cursor(), such as postgresql which may return a PG
3328 "server side" cursor.
3329 """
3331 raise NotImplementedError()
3333 def pre_exec(self) -> None:
3334 """Called before an execution of a compiled statement.
3336 If a compiled statement was passed to this ExecutionContext,
3337 the `statement` and `parameters` datamembers must be
3338 initialized after this statement is complete.
3339 """
3341 raise NotImplementedError()
3343 def get_out_parameter_values(
3344 self, out_param_names: Sequence[str]
3345 ) -> Sequence[Any]:
3346 """Return a sequence of OUT parameter values from a cursor.
3348 For dialects that support OUT parameters, this method will be called
3349 when there is a :class:`.SQLCompiler` object which has the
3350 :attr:`.SQLCompiler.has_out_parameters` flag set. This flag in turn
3351 will be set to True if the statement itself has :class:`.BindParameter`
3352 objects that have the ``.isoutparam`` flag set which are consumed by
3353 the :meth:`.SQLCompiler.visit_bindparam` method. If the dialect
3354 compiler produces :class:`.BindParameter` objects with ``.isoutparam``
3355 set which are not handled by :meth:`.SQLCompiler.visit_bindparam`, it
3356 should set this flag explicitly.
3358 The list of names that were rendered for each bound parameter
3359 is passed to the method. The method should then return a sequence of
3360 values corresponding to the list of parameter objects. Unlike in
3361 previous SQLAlchemy versions, the values can be the **raw values** from
3362 the DBAPI; the execution context will apply the appropriate type
3363 handler based on what's present in self.compiled.binds and update the
3364 values. The processed dictionary will then be made available via the
3365 ``.out_parameters`` collection on the result object. Note that
3366 SQLAlchemy 1.4 has multiple kinds of result object as part of the 2.0
3367 transition.
3369 .. versionadded:: 1.4 - added
3370 :meth:`.ExecutionContext.get_out_parameter_values`, which is invoked
3371 automatically by the :class:`.DefaultExecutionContext` when there
3372 are :class:`.BindParameter` objects with the ``.isoutparam`` flag
3373 set. This replaces the practice of setting out parameters within
3374 the now-removed ``get_result_proxy()`` method.
3376 """
3377 raise NotImplementedError()
3379 def post_exec(self) -> None:
3380 """Called after the execution of a compiled statement.
3382 If a compiled statement was passed to this ExecutionContext,
3383 the `last_insert_ids`, `last_inserted_params`, etc.
3384 datamembers should be available after this method completes.
3385 """
3387 raise NotImplementedError()
3389 def handle_dbapi_exception(self, e: BaseException) -> None:
3390 """Receive a DBAPI exception which occurred upon execute, result
3391 fetch, etc."""
3393 raise NotImplementedError()
3395 def lastrow_has_defaults(self) -> bool:
3396 """Return True if the last INSERT or UPDATE row contained
3397 inlined or database-side defaults.
3398 """
3400 raise NotImplementedError()
3402 def get_rowcount(self) -> Optional[int]:
3403 """Return the DBAPI ``cursor.rowcount`` value, or in some
3404 cases an interpreted value.
3406 See :attr:`_engine.CursorResult.rowcount` for details on this.
3408 """
3410 raise NotImplementedError()
3412 def fetchall_for_returning(self, cursor: DBAPICursor) -> Sequence[Any]:
3413 """For a RETURNING result, deliver cursor.fetchall() from the
3414 DBAPI cursor.
3416 This is a dialect-specific hook for dialects that have special
3417 considerations when calling upon the rows delivered for a
3418 "RETURNING" statement. Default implementation is
3419 ``cursor.fetchall()``.
3421 This hook is currently used only by the :term:`insertmanyvalues`
3422 feature. Dialects that don't set ``use_insertmanyvalues=True``
3423 don't need to consider this hook.
3425 .. versionadded:: 2.0.10
3427 """
3428 raise NotImplementedError()
3431class ConnectionEventsTarget(EventTarget):
3432 """An object which can accept events from :class:`.ConnectionEvents`.
3434 Includes :class:`_engine.Connection` and :class:`_engine.Engine`.
3436 .. versionadded:: 2.0
3438 """
3440 dispatch: dispatcher[ConnectionEventsTarget]
3443Connectable = ConnectionEventsTarget
3446class ExceptionContext:
3447 """Encapsulate information about an error condition in progress.
3449 This object exists solely to be passed to the
3450 :meth:`_events.DialectEvents.handle_error` event,
3451 supporting an interface that
3452 can be extended without backwards-incompatibility.
3455 """
3457 if not TYPE_CHECKING:
3458 __slots__ = ()
3460 dialect: Dialect
3461 """The :class:`_engine.Dialect` in use.
3463 This member is present for all invocations of the event hook.
3465 .. versionadded:: 2.0
3467 """
3469 connection: Optional[Connection]
3470 """The :class:`_engine.Connection` in use during the exception.
3472 This member is present, except in the case of a failure when
3473 first connecting.
3475 .. seealso::
3477 :attr:`.ExceptionContext.engine`
3480 """
3482 engine: Optional[Engine]
3483 """The :class:`_engine.Engine` in use during the exception.
3485 This member is present in all cases except for when handling an error
3486 within the connection pool "pre-ping" process.
3488 """
3490 cursor: Optional[DBAPICursor]
3491 """The DBAPI cursor object.
3493 May be None.
3495 """
3497 statement: Optional[str]
3498 """String SQL statement that was emitted directly to the DBAPI.
3500 May be None.
3502 """
3504 parameters: Optional[_DBAPIAnyExecuteParams]
3505 """Parameter collection that was emitted directly to the DBAPI.
3507 May be None.
3509 """
3511 original_exception: BaseException
3512 """The exception object which was caught.
3514 This member is always present.
3516 """
3518 sqlalchemy_exception: Optional[StatementError]
3519 """The :class:`sqlalchemy.exc.StatementError` which wraps the original,
3520 and will be raised if exception handling is not circumvented by the event.
3522 May be None, as not all exception types are wrapped by SQLAlchemy.
3523 For DBAPI-level exceptions that subclass the dbapi's Error class, this
3524 field will always be present.
3526 """
3528 chained_exception: Optional[BaseException]
3529 """The exception that was returned by the previous handler in the
3530 exception chain, if any.
3532 If present, this exception will be the one ultimately raised by
3533 SQLAlchemy unless a subsequent handler replaces it.
3535 May be None.
3537 """
3539 execution_context: Optional[ExecutionContext]
3540 """The :class:`.ExecutionContext` corresponding to the execution
3541 operation in progress.
3543 This is present for statement execution operations, but not for
3544 operations such as transaction begin/end. It also is not present when
3545 the exception was raised before the :class:`.ExecutionContext`
3546 could be constructed.
3548 Note that the :attr:`.ExceptionContext.statement` and
3549 :attr:`.ExceptionContext.parameters` members may represent a
3550 different value than that of the :class:`.ExecutionContext`,
3551 potentially in the case where a
3552 :meth:`_events.ConnectionEvents.before_cursor_execute` event or similar
3553 modified the statement/parameters to be sent.
3555 May be None.
3557 """
3559 is_disconnect: bool
3560 """Represent whether the exception as occurred represents a "disconnect"
3561 condition.
3563 This flag will always be True or False within the scope of the
3564 :meth:`_events.DialectEvents.handle_error` handler.
3566 SQLAlchemy will defer to this flag in order to determine whether or not
3567 the connection should be invalidated subsequently. That is, by
3568 assigning to this flag, a "disconnect" event which then results in
3569 a connection and pool invalidation can be invoked or prevented by
3570 changing this flag.
3573 .. note:: The pool "pre_ping" handler enabled using the
3574 :paramref:`_sa.create_engine.pool_pre_ping` parameter does **not**
3575 consult this event before deciding if the "ping" returned false,
3576 as opposed to receiving an unhandled error. For this use case, the
3577 :ref:`legacy recipe based on engine_connect() may be used
3578 <pool_disconnects_pessimistic_custom>`. A future API allow more
3579 comprehensive customization of the "disconnect" detection mechanism
3580 across all functions.
3582 """
3584 invalidate_pool_on_disconnect: bool
3585 """Represent whether all connections in the pool should be invalidated
3586 when a "disconnect" condition is in effect.
3588 Setting this flag to False within the scope of the
3589 :meth:`_events.DialectEvents.handle_error`
3590 event will have the effect such
3591 that the full collection of connections in the pool will not be
3592 invalidated during a disconnect; only the current connection that is the
3593 subject of the error will actually be invalidated.
3595 The purpose of this flag is for custom disconnect-handling schemes where
3596 the invalidation of other connections in the pool is to be performed
3597 based on other conditions, or even on a per-connection basis.
3599 """
3601 is_pre_ping: bool
3602 """Indicates if this error is occurring within the "pre-ping" step
3603 performed when :paramref:`_sa.create_engine.pool_pre_ping` is set to
3604 ``True``. In this mode, the :attr:`.ExceptionContext.engine` attribute
3605 will be ``None``. The dialect in use is accessible via the
3606 :attr:`.ExceptionContext.dialect` attribute.
3608 .. versionadded:: 2.0.5
3610 """
3613class AdaptedConnection:
3614 """Interface of an adapted connection object to support the DBAPI protocol.
3616 Used by asyncio dialects to provide a sync-style pep-249 facade on top
3617 of the asyncio connection/cursor API provided by the driver.
3619 .. versionadded:: 1.4.24
3621 """
3623 __slots__ = ("_connection",)
3625 _connection: AsyncIODBAPIConnection
3627 @property
3628 def driver_connection(self) -> Any:
3629 """The connection object as returned by the driver after a connect."""
3630 return self._connection
3632 def run_async(self, fn: Callable[[Any], Awaitable[_T]]) -> _T:
3633 """Run the awaitable returned by the given function, which is passed
3634 the raw asyncio driver connection.
3636 This is used to invoke awaitable-only methods on the driver connection
3637 within the context of a "synchronous" method, like a connection
3638 pool event handler.
3640 E.g.::
3642 engine = create_async_engine(...)
3645 @event.listens_for(engine.sync_engine, "connect")
3646 def register_custom_types(
3647 dbapi_connection, # ...
3648 ):
3649 dbapi_connection.run_async(
3650 lambda connection: connection.set_type_codec(
3651 "MyCustomType", encoder, decoder, ...
3652 )
3653 )
3655 .. versionadded:: 1.4.30
3657 .. seealso::
3659 :ref:`asyncio_events_run_async`
3661 """
3662 return await_(fn(self._connection))
3664 def __repr__(self) -> str:
3665 return "<AdaptedConnection %s>" % self._connection