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 .. seealso::
1264 :class:`.DialectKWArgs` - implementing base class which consumes
1265 :attr:`.DefaultDialect.construct_arguments`
1268 """
1270 reflection_options: Sequence[str] = ()
1271 """Sequence of string names indicating keyword arguments that can be
1272 established on a :class:`.Table` object which will be passed as
1273 "reflection options" when using :paramref:`.Table.autoload_with`.
1275 Current example is "oracle_resolve_synonyms" in the Oracle Database
1276 dialects.
1278 """
1280 dbapi_exception_translation_map: Mapping[str, str] = util.EMPTY_DICT
1281 """A dictionary of names that will contain as values the names of
1282 pep-249 exceptions ("IntegrityError", "OperationalError", etc)
1283 keyed to alternate class names, to support the case where a
1284 DBAPI has exception classes that aren't named as they are
1285 referred to (e.g. IntegrityError = MyException). In the vast
1286 majority of cases this dictionary is empty.
1287 """
1289 supports_comments: bool
1290 """Indicates the dialect supports comment DDL on tables and columns."""
1292 inline_comments: bool
1293 """Indicates the dialect supports comment DDL that's inline with the
1294 definition of a Table or Column. If False, this implies that ALTER must
1295 be used to set table and column comments."""
1297 supports_constraint_comments: bool
1298 """Indicates if the dialect supports comment DDL on constraints.
1300 .. versionadded:: 2.0
1301 """
1303 _has_events = False
1305 supports_statement_cache: bool = True
1306 """indicates if this dialect supports caching.
1308 All dialects that are compatible with statement caching should set this
1309 flag to True directly on each dialect class and subclass that supports
1310 it. SQLAlchemy tests that this flag is locally present on each dialect
1311 subclass before it will use statement caching. This is to provide
1312 safety for legacy or new dialects that are not yet fully tested to be
1313 compliant with SQL statement caching.
1315 .. versionadded:: 1.4.5
1317 .. seealso::
1319 :ref:`engine_thirdparty_caching`
1321 """
1323 _supports_statement_cache: bool
1324 """internal evaluation for supports_statement_cache"""
1326 bind_typing = BindTyping.NONE
1327 """define a means of passing typing information to the database and/or
1328 driver for bound parameters.
1330 See :class:`.BindTyping` for values.
1332 .. versionadded:: 2.0
1334 """
1336 is_async: bool
1337 """Whether or not this dialect is intended for asyncio use."""
1339 has_terminate: bool
1340 """Whether or not this dialect has a separate "terminate" implementation
1341 that does not block or require awaiting."""
1343 engine_config_types: Mapping[str, Any]
1344 """a mapping of string keys that can be in an engine config linked to
1345 type conversion functions.
1347 """
1349 label_length: Optional[int]
1350 """optional user-defined max length for SQL labels"""
1352 include_set_input_sizes: Optional[Set[Any]]
1353 """set of DBAPI type objects that should be included in
1354 automatic cursor.setinputsizes() calls.
1356 This is only used if bind_typing is BindTyping.SET_INPUT_SIZES
1358 """
1360 exclude_set_input_sizes: Optional[Set[Any]]
1361 """set of DBAPI type objects that should be excluded in
1362 automatic cursor.setinputsizes() calls.
1364 This is only used if bind_typing is BindTyping.SET_INPUT_SIZES
1366 """
1368 supports_simple_order_by_label: bool
1369 """target database supports ORDER BY <labelname>, where <labelname>
1370 refers to a label in the columns clause of the SELECT"""
1372 div_is_floordiv: bool
1373 """target database treats the / division operator as "floor division" """
1375 tuple_in_values: bool
1376 """target database supports tuple IN, i.e. (x, y) IN ((q, p), (r, z))"""
1378 requires_name_normalize: bool
1379 """Indicates symbol names are returned by the database in
1380 UPPERCASED if they are case insensitive within the database.
1381 If this is True, the methods normalize_name()
1382 and denormalize_name() must be provided.
1383 """
1385 _bind_typing_render_casts: bool
1387 _type_memos: MutableMapping[TypeEngine[Any], _TypeMemoDict]
1389 def _builtin_onconnect(self) -> Optional[_ListenerFnType]:
1390 raise NotImplementedError()
1392 def create_connect_args(self, url: URL) -> ConnectArgsType:
1393 """Build DB-API compatible connection arguments.
1395 Given a :class:`.URL` object, returns a tuple
1396 consisting of a ``(*args, **kwargs)`` suitable to send directly
1397 to the dbapi's connect function. The arguments are sent to the
1398 :meth:`.Dialect.connect` method which then runs the DBAPI-level
1399 ``connect()`` function.
1401 The method typically makes use of the
1402 :meth:`.URL.translate_connect_args`
1403 method in order to generate a dictionary of options.
1405 The default implementation is::
1407 def create_connect_args(self, url):
1408 opts = url.translate_connect_args()
1409 opts.update(url.query)
1410 return ([], opts)
1412 :param url: a :class:`.URL` object
1414 :return: a tuple of ``(*args, **kwargs)`` which will be passed to the
1415 :meth:`.Dialect.connect` method.
1417 .. seealso::
1419 :meth:`.URL.translate_connect_args`
1421 """
1423 raise NotImplementedError()
1425 @classmethod
1426 def import_dbapi(cls) -> DBAPIModule:
1427 """Import the DBAPI module that is used by this dialect.
1429 The Python module object returned here will be assigned as an
1430 instance variable to a constructed dialect under the name
1431 ``.dbapi``.
1433 .. versionchanged:: 2.0 The :meth:`.Dialect.import_dbapi` class
1434 method is renamed from the previous method ``.Dialect.dbapi()``,
1435 which would be replaced at dialect instantiation time by the
1436 DBAPI module itself, thus using the same name in two different ways.
1437 If a ``.Dialect.dbapi()`` classmethod is present on a third-party
1438 dialect, it will be used and a deprecation warning will be emitted.
1440 """
1441 raise NotImplementedError()
1443 def type_descriptor(self, typeobj: TypeEngine[_T]) -> TypeEngine[_T]:
1444 """Transform a generic type to a dialect-specific type.
1446 Dialect classes will usually use the
1447 :func:`_types.adapt_type` function in the types module to
1448 accomplish this.
1450 The returned result is cached *per dialect class* so can
1451 contain no dialect-instance state.
1453 """
1455 raise NotImplementedError()
1457 def initialize(self, connection: Connection) -> None:
1458 """Called during strategized creation of the dialect with a
1459 connection.
1461 Allows dialects to configure options based on server version info or
1462 other properties.
1464 The connection passed here is a SQLAlchemy Connection object,
1465 with full capabilities.
1467 The initialize() method of the base dialect should be called via
1468 super().
1470 .. note:: as of SQLAlchemy 1.4, this method is called **before**
1471 any :meth:`_engine.Dialect.on_connect` hooks are called.
1473 """
1475 if TYPE_CHECKING:
1477 def _overrides_default(self, method_name: str) -> bool: ...
1479 def get_columns(
1480 self,
1481 connection: Connection,
1482 table_name: str,
1483 schema: Optional[str] = None,
1484 **kw: Any,
1485 ) -> List[ReflectedColumn]:
1486 """Return information about columns in ``table_name``.
1488 Given a :class:`_engine.Connection`, a string
1489 ``table_name``, and an optional string ``schema``, return column
1490 information as a list of dictionaries
1491 corresponding to the :class:`.ReflectedColumn` dictionary.
1493 This is an internal dialect method. Applications should use
1494 :meth:`.Inspector.get_columns`.
1496 """
1498 raise NotImplementedError()
1500 def get_multi_columns(
1501 self,
1502 connection: Connection,
1503 *,
1504 schema: Optional[str] = None,
1505 filter_names: Optional[Collection[str]] = None,
1506 **kw: Any,
1507 ) -> Iterable[Tuple[TableKey, List[ReflectedColumn]]]:
1508 """Return information about columns in all tables in the
1509 given ``schema``.
1511 This is an internal dialect method. Applications should use
1512 :meth:`.Inspector.get_multi_columns`.
1514 .. note:: The :class:`_engine.DefaultDialect` provides a default
1515 implementation that will call the single table method for
1516 each object returned by :meth:`Dialect.get_table_names`,
1517 :meth:`Dialect.get_view_names` or
1518 :meth:`Dialect.get_materialized_view_names` depending on the
1519 provided ``kind``. Dialects that want to support a faster
1520 implementation should implement this method.
1522 .. versionadded:: 2.0
1524 """
1526 raise NotImplementedError()
1528 def get_pk_constraint(
1529 self,
1530 connection: Connection,
1531 table_name: str,
1532 schema: Optional[str] = None,
1533 **kw: Any,
1534 ) -> ReflectedPrimaryKeyConstraint:
1535 """Return information about the primary key constraint on
1536 table_name`.
1538 Given a :class:`_engine.Connection`, a string
1539 ``table_name``, and an optional string ``schema``, return primary
1540 key information as a dictionary corresponding to the
1541 :class:`.ReflectedPrimaryKeyConstraint` dictionary.
1543 This is an internal dialect method. Applications should use
1544 :meth:`.Inspector.get_pk_constraint`.
1546 """
1547 raise NotImplementedError()
1549 def get_multi_pk_constraint(
1550 self,
1551 connection: Connection,
1552 *,
1553 schema: Optional[str] = None,
1554 filter_names: Optional[Collection[str]] = None,
1555 **kw: Any,
1556 ) -> Iterable[Tuple[TableKey, ReflectedPrimaryKeyConstraint]]:
1557 """Return information about primary key constraints in
1558 all tables in the given ``schema``.
1560 This is an internal dialect method. Applications should use
1561 :meth:`.Inspector.get_multi_pk_constraint`.
1563 .. note:: The :class:`_engine.DefaultDialect` provides a default
1564 implementation that will call the single table method for
1565 each object returned by :meth:`Dialect.get_table_names`,
1566 :meth:`Dialect.get_view_names` or
1567 :meth:`Dialect.get_materialized_view_names` depending on the
1568 provided ``kind``. Dialects that want to support a faster
1569 implementation should implement this method.
1571 .. versionadded:: 2.0
1573 """
1574 raise NotImplementedError()
1576 def get_foreign_keys(
1577 self,
1578 connection: Connection,
1579 table_name: str,
1580 schema: Optional[str] = None,
1581 **kw: Any,
1582 ) -> List[ReflectedForeignKeyConstraint]:
1583 """Return information about foreign_keys in ``table_name``.
1585 Given a :class:`_engine.Connection`, a string
1586 ``table_name``, and an optional string ``schema``, return foreign
1587 key information as a list of dicts corresponding to the
1588 :class:`.ReflectedForeignKeyConstraint` dictionary.
1590 This is an internal dialect method. Applications should use
1591 :meth:`_engine.Inspector.get_foreign_keys`.
1592 """
1594 raise NotImplementedError()
1596 def get_multi_foreign_keys(
1597 self,
1598 connection: Connection,
1599 *,
1600 schema: Optional[str] = None,
1601 filter_names: Optional[Collection[str]] = None,
1602 **kw: Any,
1603 ) -> Iterable[Tuple[TableKey, List[ReflectedForeignKeyConstraint]]]:
1604 """Return information about foreign_keys in all tables
1605 in the given ``schema``.
1607 This is an internal dialect method. Applications should use
1608 :meth:`_engine.Inspector.get_multi_foreign_keys`.
1610 .. note:: The :class:`_engine.DefaultDialect` provides a default
1611 implementation that will call the single table method for
1612 each object returned by :meth:`Dialect.get_table_names`,
1613 :meth:`Dialect.get_view_names` or
1614 :meth:`Dialect.get_materialized_view_names` depending on the
1615 provided ``kind``. Dialects that want to support a faster
1616 implementation should implement this method.
1618 .. versionadded:: 2.0
1620 """
1622 raise NotImplementedError()
1624 def get_table_names(
1625 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1626 ) -> List[str]:
1627 """Return a list of table names for ``schema``.
1629 This is an internal dialect method. Applications should use
1630 :meth:`_engine.Inspector.get_table_names`.
1632 """
1634 raise NotImplementedError()
1636 def get_temp_table_names(
1637 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1638 ) -> List[str]:
1639 """Return a list of temporary table names on the given connection,
1640 if supported by the underlying backend.
1642 This is an internal dialect method. Applications should use
1643 :meth:`_engine.Inspector.get_temp_table_names`.
1645 """
1647 raise NotImplementedError()
1649 def get_view_names(
1650 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1651 ) -> List[str]:
1652 """Return a list of all non-materialized view names available in the
1653 database.
1655 This is an internal dialect method. Applications should use
1656 :meth:`_engine.Inspector.get_view_names`.
1658 :param schema: schema name to query, if not the default schema.
1660 """
1662 raise NotImplementedError()
1664 def get_materialized_view_names(
1665 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1666 ) -> List[str]:
1667 """Return a list of all materialized view names available in the
1668 database.
1670 This is an internal dialect method. Applications should use
1671 :meth:`_engine.Inspector.get_materialized_view_names`.
1673 :param schema: schema name to query, if not the default schema.
1675 .. versionadded:: 2.0
1677 """
1679 raise NotImplementedError()
1681 def get_sequence_names(
1682 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1683 ) -> List[str]:
1684 """Return a list of all sequence names available in the database.
1686 This is an internal dialect method. Applications should use
1687 :meth:`_engine.Inspector.get_sequence_names`.
1689 :param schema: schema name to query, if not the default schema.
1691 .. versionadded:: 1.4
1692 """
1694 raise NotImplementedError()
1696 def get_temp_view_names(
1697 self, connection: Connection, schema: Optional[str] = None, **kw: Any
1698 ) -> List[str]:
1699 """Return a list of temporary view names on the given connection,
1700 if supported by the underlying backend.
1702 This is an internal dialect method. Applications should use
1703 :meth:`_engine.Inspector.get_temp_view_names`.
1705 """
1707 raise NotImplementedError()
1709 def get_schema_names(self, connection: Connection, **kw: Any) -> List[str]:
1710 """Return a list of all schema names available in the database.
1712 This is an internal dialect method. Applications should use
1713 :meth:`_engine.Inspector.get_schema_names`.
1714 """
1715 raise NotImplementedError()
1717 def get_view_definition(
1718 self,
1719 connection: Connection,
1720 view_name: str,
1721 schema: Optional[str] = None,
1722 **kw: Any,
1723 ) -> str:
1724 """Return plain or materialized view definition.
1726 This is an internal dialect method. Applications should use
1727 :meth:`_engine.Inspector.get_view_definition`.
1729 Given a :class:`_engine.Connection`, a string
1730 ``view_name``, and an optional string ``schema``, return the view
1731 definition.
1732 """
1734 raise NotImplementedError()
1736 def get_indexes(
1737 self,
1738 connection: Connection,
1739 table_name: str,
1740 schema: Optional[str] = None,
1741 **kw: Any,
1742 ) -> List[ReflectedIndex]:
1743 """Return information about indexes in ``table_name``.
1745 Given a :class:`_engine.Connection`, a string
1746 ``table_name`` and an optional string ``schema``, return index
1747 information as a list of dictionaries corresponding to the
1748 :class:`.ReflectedIndex` dictionary.
1750 This is an internal dialect method. Applications should use
1751 :meth:`.Inspector.get_indexes`.
1752 """
1754 raise NotImplementedError()
1756 def get_multi_indexes(
1757 self,
1758 connection: Connection,
1759 *,
1760 schema: Optional[str] = None,
1761 filter_names: Optional[Collection[str]] = None,
1762 **kw: Any,
1763 ) -> Iterable[Tuple[TableKey, List[ReflectedIndex]]]:
1764 """Return information about indexes in in all tables
1765 in the given ``schema``.
1767 This is an internal dialect method. Applications should use
1768 :meth:`.Inspector.get_multi_indexes`.
1770 .. note:: The :class:`_engine.DefaultDialect` provides a default
1771 implementation that will call the single table method for
1772 each object returned by :meth:`Dialect.get_table_names`,
1773 :meth:`Dialect.get_view_names` or
1774 :meth:`Dialect.get_materialized_view_names` depending on the
1775 provided ``kind``. Dialects that want to support a faster
1776 implementation should implement this method.
1778 .. versionadded:: 2.0
1780 """
1782 raise NotImplementedError()
1784 def get_unique_constraints(
1785 self,
1786 connection: Connection,
1787 table_name: str,
1788 schema: Optional[str] = None,
1789 **kw: Any,
1790 ) -> List[ReflectedUniqueConstraint]:
1791 r"""Return information about unique constraints in ``table_name``.
1793 Given a string ``table_name`` and an optional string ``schema``, return
1794 unique constraint information as a list of dicts corresponding
1795 to the :class:`.ReflectedUniqueConstraint` dictionary.
1797 This is an internal dialect method. Applications should use
1798 :meth:`.Inspector.get_unique_constraints`.
1799 """
1801 raise NotImplementedError()
1803 def get_multi_unique_constraints(
1804 self,
1805 connection: Connection,
1806 *,
1807 schema: Optional[str] = None,
1808 filter_names: Optional[Collection[str]] = None,
1809 **kw: Any,
1810 ) -> Iterable[Tuple[TableKey, List[ReflectedUniqueConstraint]]]:
1811 """Return information about unique constraints in all tables
1812 in the given ``schema``.
1814 This is an internal dialect method. Applications should use
1815 :meth:`.Inspector.get_multi_unique_constraints`.
1817 .. note:: The :class:`_engine.DefaultDialect` provides a default
1818 implementation that will call the single table method for
1819 each object returned by :meth:`Dialect.get_table_names`,
1820 :meth:`Dialect.get_view_names` or
1821 :meth:`Dialect.get_materialized_view_names` depending on the
1822 provided ``kind``. Dialects that want to support a faster
1823 implementation should implement this method.
1825 .. versionadded:: 2.0
1827 """
1829 raise NotImplementedError()
1831 def get_check_constraints(
1832 self,
1833 connection: Connection,
1834 table_name: str,
1835 schema: Optional[str] = None,
1836 **kw: Any,
1837 ) -> List[ReflectedCheckConstraint]:
1838 r"""Return information about check constraints in ``table_name``.
1840 Given a string ``table_name`` and an optional string ``schema``, return
1841 check constraint information as a list of dicts corresponding
1842 to the :class:`.ReflectedCheckConstraint` dictionary.
1844 This is an internal dialect method. Applications should use
1845 :meth:`.Inspector.get_check_constraints`.
1847 """
1849 raise NotImplementedError()
1851 def get_multi_check_constraints(
1852 self,
1853 connection: Connection,
1854 *,
1855 schema: Optional[str] = None,
1856 filter_names: Optional[Collection[str]] = None,
1857 **kw: Any,
1858 ) -> Iterable[Tuple[TableKey, List[ReflectedCheckConstraint]]]:
1859 """Return information about check constraints in all tables
1860 in the given ``schema``.
1862 This is an internal dialect method. Applications should use
1863 :meth:`.Inspector.get_multi_check_constraints`.
1865 .. note:: The :class:`_engine.DefaultDialect` provides a default
1866 implementation that will call the single table method for
1867 each object returned by :meth:`Dialect.get_table_names`,
1868 :meth:`Dialect.get_view_names` or
1869 :meth:`Dialect.get_materialized_view_names` depending on the
1870 provided ``kind``. Dialects that want to support a faster
1871 implementation should implement this method.
1873 .. versionadded:: 2.0
1875 """
1877 raise NotImplementedError()
1879 def get_table_options(
1880 self,
1881 connection: Connection,
1882 table_name: str,
1883 schema: Optional[str] = None,
1884 **kw: Any,
1885 ) -> Dict[str, Any]:
1886 """Return a dictionary of options specified when ``table_name``
1887 was created.
1889 This is an internal dialect method. Applications should use
1890 :meth:`_engine.Inspector.get_table_options`.
1891 """
1892 raise NotImplementedError()
1894 def get_multi_table_options(
1895 self,
1896 connection: Connection,
1897 *,
1898 schema: Optional[str] = None,
1899 filter_names: Optional[Collection[str]] = None,
1900 **kw: Any,
1901 ) -> Iterable[Tuple[TableKey, Dict[str, Any]]]:
1902 """Return a dictionary of options specified when the tables in the
1903 given schema were created.
1905 This is an internal dialect method. Applications should use
1906 :meth:`_engine.Inspector.get_multi_table_options`.
1908 .. note:: The :class:`_engine.DefaultDialect` provides a default
1909 implementation that will call the single table method for
1910 each object returned by :meth:`Dialect.get_table_names`,
1911 :meth:`Dialect.get_view_names` or
1912 :meth:`Dialect.get_materialized_view_names` depending on the
1913 provided ``kind``. Dialects that want to support a faster
1914 implementation should implement this method.
1916 .. versionadded:: 2.0
1918 """
1919 raise NotImplementedError()
1921 def get_table_comment(
1922 self,
1923 connection: Connection,
1924 table_name: str,
1925 schema: Optional[str] = None,
1926 **kw: Any,
1927 ) -> ReflectedTableComment:
1928 r"""Return the "comment" for the table identified by ``table_name``.
1930 Given a string ``table_name`` and an optional string ``schema``, return
1931 table comment information as a dictionary corresponding to the
1932 :class:`.ReflectedTableComment` dictionary.
1934 This is an internal dialect method. Applications should use
1935 :meth:`.Inspector.get_table_comment`.
1937 :raise: ``NotImplementedError`` for dialects that don't support
1938 comments.
1940 """
1942 raise NotImplementedError()
1944 def get_multi_table_comment(
1945 self,
1946 connection: Connection,
1947 *,
1948 schema: Optional[str] = None,
1949 filter_names: Optional[Collection[str]] = None,
1950 **kw: Any,
1951 ) -> Iterable[Tuple[TableKey, ReflectedTableComment]]:
1952 """Return information about the table comment in all tables
1953 in the given ``schema``.
1955 This is an internal dialect method. Applications should use
1956 :meth:`_engine.Inspector.get_multi_table_comment`.
1958 .. note:: The :class:`_engine.DefaultDialect` provides a default
1959 implementation that will call the single table method for
1960 each object returned by :meth:`Dialect.get_table_names`,
1961 :meth:`Dialect.get_view_names` or
1962 :meth:`Dialect.get_materialized_view_names` depending on the
1963 provided ``kind``. Dialects that want to support a faster
1964 implementation should implement this method.
1966 .. versionadded:: 2.0
1968 """
1970 raise NotImplementedError()
1972 def normalize_name(self, name: str) -> str:
1973 """convert the given name to lowercase if it is detected as
1974 case insensitive.
1976 This method is only used if the dialect defines
1977 requires_name_normalize=True.
1979 """
1980 raise NotImplementedError()
1982 def denormalize_name(self, name: str) -> str:
1983 """convert the given name to a case insensitive identifier
1984 for the backend if it is an all-lowercase name.
1986 This method is only used if the dialect defines
1987 requires_name_normalize=True.
1989 """
1990 raise NotImplementedError()
1992 def has_table(
1993 self,
1994 connection: Connection,
1995 table_name: str,
1996 schema: Optional[str] = None,
1997 **kw: Any,
1998 ) -> bool:
1999 """For internal dialect use, check the existence of a particular table
2000 or view in the database.
2002 Given a :class:`_engine.Connection` object, a string table_name and
2003 optional schema name, return True if the given table exists in the
2004 database, False otherwise.
2006 This method serves as the underlying implementation of the
2007 public facing :meth:`.Inspector.has_table` method, and is also used
2008 internally to implement the "checkfirst" behavior for methods like
2009 :meth:`_schema.Table.create` and :meth:`_schema.MetaData.create_all`.
2011 .. note:: This method is used internally by SQLAlchemy, and is
2012 published so that third-party dialects may provide an
2013 implementation. It is **not** the public API for checking for table
2014 presence. Please use the :meth:`.Inspector.has_table` method.
2016 .. versionchanged:: 2.0:: :meth:`_engine.Dialect.has_table` now
2017 formally supports checking for additional table-like objects:
2019 * any type of views (plain or materialized)
2020 * temporary tables of any kind
2022 Previously, these two checks were not formally specified and
2023 different dialects would vary in their behavior. The dialect
2024 testing suite now includes tests for all of these object types,
2025 and dialects to the degree that the backing database supports views
2026 or temporary tables should seek to support locating these objects
2027 for full compliance.
2029 """
2031 raise NotImplementedError()
2033 def has_multi_table(
2034 self,
2035 connection: Connection,
2036 table_names: Sequence[str],
2037 schema: Optional[str] = None,
2038 **kw: Any,
2039 ) -> Iterable[Tuple[TableKey, bool]]:
2040 """For internal dialect use, check the existence of a particular list
2041 of tables or views in the database.
2043 This is an internal dialect method. Applications should use
2044 :meth:`.Inspector.has_multi_table`.
2046 .. note:: The :class:`_engine.DefaultDialect` provides a default
2047 implementation that will call the single table method for
2048 each table name provided. Dialects that want to support a faster
2049 implementation should implement this method.
2051 .. versionadded:: 2.1
2053 """
2055 raise NotImplementedError()
2057 def has_index(
2058 self,
2059 connection: Connection,
2060 table_name: str,
2061 index_name: str,
2062 schema: Optional[str] = None,
2063 **kw: Any,
2064 ) -> bool:
2065 """Check the existence of a particular index name in the database.
2067 Given a :class:`_engine.Connection` object, a string
2068 ``table_name`` and string index name, return ``True`` if an index of
2069 the given name on the given table exists, ``False`` otherwise.
2071 The :class:`.DefaultDialect` implements this in terms of the
2072 :meth:`.Dialect.has_table` and :meth:`.Dialect.get_indexes` methods,
2073 however dialects can implement a more performant version.
2075 This is an internal dialect method. Applications should use
2076 :meth:`_engine.Inspector.has_index`.
2078 .. versionadded:: 1.4
2080 """
2082 raise NotImplementedError()
2084 def has_sequence(
2085 self,
2086 connection: Connection,
2087 sequence_name: str,
2088 schema: Optional[str] = None,
2089 **kw: Any,
2090 ) -> bool:
2091 """Check the existence of a particular sequence in the database.
2093 Given a :class:`_engine.Connection` object and a string
2094 `sequence_name`, return ``True`` if the given sequence exists in
2095 the database, ``False`` otherwise.
2097 This is an internal dialect method. Applications should use
2098 :meth:`_engine.Inspector.has_sequence`.
2099 """
2101 raise NotImplementedError()
2103 def has_schema(
2104 self, connection: Connection, schema_name: str, **kw: Any
2105 ) -> bool:
2106 """Check the existence of a particular schema name in the database.
2108 Given a :class:`_engine.Connection` object, a string
2109 ``schema_name``, return ``True`` if a schema of the
2110 given exists, ``False`` otherwise.
2112 The :class:`.DefaultDialect` implements this by checking
2113 the presence of ``schema_name`` among the schemas returned by
2114 :meth:`.Dialect.get_schema_names`,
2115 however dialects can implement a more performant version.
2117 This is an internal dialect method. Applications should use
2118 :meth:`_engine.Inspector.has_schema`.
2120 .. versionadded:: 2.0
2122 """
2124 raise NotImplementedError()
2126 def _get_server_version_info(self, connection: Connection) -> Any:
2127 """Retrieve the server version info from the given connection.
2129 This is used by the default implementation to populate the
2130 "server_version_info" attribute and is called exactly
2131 once upon first connect.
2133 """
2135 raise NotImplementedError()
2137 def _get_default_schema_name(self, connection: Connection) -> str:
2138 """Return the string name of the currently selected schema from
2139 the given connection.
2141 This is used by the default implementation to populate the
2142 "default_schema_name" attribute and is called exactly
2143 once upon first connect.
2145 """
2147 raise NotImplementedError()
2149 def do_begin(self, dbapi_connection: PoolProxiedConnection) -> None:
2150 """Provide an implementation of ``connection.begin()``, given a
2151 DB-API connection.
2153 The DBAPI has no dedicated "begin" method and it is expected
2154 that transactions are implicit. This hook is provided for those
2155 DBAPIs that might need additional help in this area.
2157 :param dbapi_connection: a DBAPI connection, typically
2158 proxied within a :class:`.ConnectionFairy`.
2160 """
2162 raise NotImplementedError()
2164 def do_rollback(self, dbapi_connection: PoolProxiedConnection) -> None:
2165 """Provide an implementation of ``connection.rollback()``, given
2166 a DB-API connection.
2168 :param dbapi_connection: a DBAPI connection, typically
2169 proxied within a :class:`.ConnectionFairy`.
2171 """
2173 raise NotImplementedError()
2175 def do_commit(self, dbapi_connection: PoolProxiedConnection) -> None:
2176 """Provide an implementation of ``connection.commit()``, given a
2177 DB-API connection.
2179 :param dbapi_connection: a DBAPI connection, typically
2180 proxied within a :class:`.ConnectionFairy`.
2182 """
2184 raise NotImplementedError()
2186 def do_terminate(self, dbapi_connection: DBAPIConnection) -> None:
2187 """Provide an implementation of ``connection.close()`` that tries as
2188 much as possible to not block, given a DBAPI
2189 connection.
2191 In the vast majority of cases this just calls .close(), however
2192 for some asyncio dialects may call upon different API features.
2194 This hook is called by the :class:`_pool.Pool`
2195 when a connection is being recycled or has been invalidated.
2197 .. versionadded:: 1.4.41
2199 """
2201 raise NotImplementedError()
2203 def do_close(self, dbapi_connection: DBAPIConnection) -> None:
2204 """Provide an implementation of ``connection.close()``, given a DBAPI
2205 connection.
2207 This hook is called by the :class:`_pool.Pool`
2208 when a connection has been
2209 detached from the pool, or is being returned beyond the normal
2210 capacity of the pool.
2212 """
2214 raise NotImplementedError()
2216 def _do_ping_w_event(self, dbapi_connection: DBAPIConnection) -> bool:
2217 raise NotImplementedError()
2219 def do_ping(self, dbapi_connection: DBAPIConnection) -> bool:
2220 """ping the DBAPI connection and return True if the connection is
2221 usable."""
2222 raise NotImplementedError()
2224 def do_set_input_sizes(
2225 self,
2226 cursor: DBAPICursor,
2227 list_of_tuples: _GenericSetInputSizesType,
2228 context: ExecutionContext,
2229 ) -> Any:
2230 """invoke the cursor.setinputsizes() method with appropriate arguments
2232 This hook is called if the :attr:`.Dialect.bind_typing` attribute is
2233 set to the
2234 :attr:`.BindTyping.SETINPUTSIZES` value.
2235 Parameter data is passed in a list of tuples (paramname, dbtype,
2236 sqltype), where ``paramname`` is the key of the parameter in the
2237 statement, ``dbtype`` is the DBAPI datatype and ``sqltype`` is the
2238 SQLAlchemy type. The order of tuples is in the correct parameter order.
2240 .. versionadded:: 1.4
2242 .. versionchanged:: 2.0 - setinputsizes mode is now enabled by
2243 setting :attr:`.Dialect.bind_typing` to
2244 :attr:`.BindTyping.SETINPUTSIZES`. Dialects which accept
2245 a ``use_setinputsizes`` parameter should set this value
2246 appropriately.
2249 """
2250 raise NotImplementedError()
2252 def create_xid(self) -> Any:
2253 """Create a two-phase transaction ID.
2255 This id will be passed to do_begin_twophase(),
2256 do_rollback_twophase(), do_commit_twophase(). Its format is
2257 unspecified.
2258 """
2260 raise NotImplementedError()
2262 def do_savepoint(self, connection: Connection, name: str) -> None:
2263 """Create a savepoint with the given name.
2265 :param connection: a :class:`_engine.Connection`.
2266 :param name: savepoint name.
2268 """
2270 raise NotImplementedError()
2272 def do_rollback_to_savepoint(
2273 self, connection: Connection, name: str
2274 ) -> None:
2275 """Rollback a connection to the named savepoint.
2277 :param connection: a :class:`_engine.Connection`.
2278 :param name: savepoint name.
2280 """
2282 raise NotImplementedError()
2284 def do_release_savepoint(self, connection: Connection, name: str) -> None:
2285 """Release the named savepoint on a connection.
2287 :param connection: a :class:`_engine.Connection`.
2288 :param name: savepoint name.
2289 """
2291 raise NotImplementedError()
2293 def do_begin_twophase(self, connection: Connection, xid: Any) -> None:
2294 """Begin a two phase transaction on the given connection.
2296 :param connection: a :class:`_engine.Connection`.
2297 :param xid: xid
2299 """
2301 raise NotImplementedError()
2303 def do_prepare_twophase(self, connection: Connection, xid: Any) -> None:
2304 """Prepare a two phase transaction on the given connection.
2306 :param connection: a :class:`_engine.Connection`.
2307 :param xid: xid
2309 """
2311 raise NotImplementedError()
2313 def do_rollback_twophase(
2314 self,
2315 connection: Connection,
2316 xid: Any,
2317 is_prepared: bool = True,
2318 recover: bool = False,
2319 ) -> None:
2320 """Rollback a two phase transaction on the given connection.
2322 :param connection: a :class:`_engine.Connection`.
2323 :param xid: xid
2324 :param is_prepared: whether or not
2325 :meth:`.TwoPhaseTransaction.prepare` was called.
2326 :param recover: if the recover flag was passed.
2328 """
2330 raise NotImplementedError()
2332 def do_commit_twophase(
2333 self,
2334 connection: Connection,
2335 xid: Any,
2336 is_prepared: bool = True,
2337 recover: bool = False,
2338 ) -> None:
2339 """Commit a two phase transaction on the given connection.
2342 :param connection: a :class:`_engine.Connection`.
2343 :param xid: xid
2344 :param is_prepared: whether or not
2345 :meth:`.TwoPhaseTransaction.prepare` was called.
2346 :param recover: if the recover flag was passed.
2348 """
2350 raise NotImplementedError()
2352 def do_recover_twophase(self, connection: Connection) -> List[Any]:
2353 """Recover list of uncommitted prepared two phase transaction
2354 identifiers on the given connection.
2356 :param connection: a :class:`_engine.Connection`.
2358 """
2360 raise NotImplementedError()
2362 def _deliver_insertmanyvalues_batches(
2363 self,
2364 connection: Connection,
2365 cursor: DBAPICursor,
2366 statement: str,
2367 parameters: _DBAPIMultiExecuteParams,
2368 generic_setinputsizes: Optional[_GenericSetInputSizesType],
2369 context: ExecutionContext,
2370 ) -> Iterator[_InsertManyValuesBatch]:
2371 """convert executemany parameters for an INSERT into an iterator
2372 of statement/single execute values, used by the insertmanyvalues
2373 feature.
2375 """
2376 raise NotImplementedError()
2378 def do_executemany(
2379 self,
2380 cursor: DBAPICursor,
2381 statement: str,
2382 parameters: _DBAPIMultiExecuteParams,
2383 context: Optional[ExecutionContext] = None,
2384 ) -> None:
2385 """Provide an implementation of ``cursor.executemany(statement,
2386 parameters)``."""
2388 raise NotImplementedError()
2390 def do_execute(
2391 self,
2392 cursor: DBAPICursor,
2393 statement: str,
2394 parameters: Optional[_DBAPISingleExecuteParams],
2395 context: Optional[ExecutionContext] = None,
2396 ) -> None:
2397 """Provide an implementation of ``cursor.execute(statement,
2398 parameters)``."""
2400 raise NotImplementedError()
2402 def do_execute_no_params(
2403 self,
2404 cursor: DBAPICursor,
2405 statement: str,
2406 context: Optional[ExecutionContext] = None,
2407 ) -> None:
2408 """Provide an implementation of ``cursor.execute(statement)``.
2410 The parameter collection should not be sent.
2412 """
2414 raise NotImplementedError()
2416 def is_disconnect(
2417 self,
2418 e: DBAPIModule.Error,
2419 connection: Optional[Union[PoolProxiedConnection, DBAPIConnection]],
2420 cursor: Optional[DBAPICursor],
2421 ) -> bool:
2422 """Return True if the given DB-API error indicates an invalid
2423 connection"""
2425 raise NotImplementedError()
2427 def connect(self, *cargs: Any, **cparams: Any) -> DBAPIConnection:
2428 r"""Establish a connection using this dialect's DBAPI.
2430 The default implementation of this method is::
2432 def connect(self, *cargs, **cparams):
2433 return self.dbapi.connect(*cargs, **cparams)
2435 The ``*cargs, **cparams`` parameters are generated directly
2436 from this dialect's :meth:`.Dialect.create_connect_args` method.
2438 This method may be used for dialects that need to perform programmatic
2439 per-connection steps when a new connection is procured from the
2440 DBAPI.
2443 :param \*cargs: positional parameters returned from the
2444 :meth:`.Dialect.create_connect_args` method
2446 :param \*\*cparams: keyword parameters returned from the
2447 :meth:`.Dialect.create_connect_args` method.
2449 :return: a DBAPI connection, typically from the :pep:`249` module
2450 level ``.connect()`` function.
2452 .. seealso::
2454 :meth:`.Dialect.create_connect_args`
2456 :meth:`.Dialect.on_connect`
2458 """
2459 raise NotImplementedError()
2461 def on_connect_url(self, url: URL) -> Optional[Callable[[Any], Any]]:
2462 """return a callable which sets up a newly created DBAPI connection.
2464 This method is a new hook that supersedes the
2465 :meth:`_engine.Dialect.on_connect` method when implemented by a
2466 dialect. When not implemented by a dialect, it invokes the
2467 :meth:`_engine.Dialect.on_connect` method directly to maintain
2468 compatibility with existing dialects. There is no deprecation
2469 for :meth:`_engine.Dialect.on_connect` expected.
2471 The callable should accept a single argument "conn" which is the
2472 DBAPI connection itself. The inner callable has no
2473 return value.
2475 E.g.::
2477 class MyDialect(default.DefaultDialect):
2478 # ...
2480 def on_connect_url(self, url):
2481 def do_on_connect(connection):
2482 connection.execute("SET SPECIAL FLAGS etc")
2484 return do_on_connect
2486 This is used to set dialect-wide per-connection options such as
2487 isolation modes, Unicode modes, etc.
2489 This method differs from :meth:`_engine.Dialect.on_connect` in that
2490 it is passed the :class:`_engine.URL` object that's relevant to the
2491 connect args. Normally the only way to get this is from the
2492 :meth:`_engine.Dialect.on_connect` hook is to look on the
2493 :class:`_engine.Engine` itself, however this URL object may have been
2494 replaced by plugins.
2496 .. note::
2498 The default implementation of
2499 :meth:`_engine.Dialect.on_connect_url` is to invoke the
2500 :meth:`_engine.Dialect.on_connect` method. Therefore if a dialect
2501 implements this method, the :meth:`_engine.Dialect.on_connect`
2502 method **will not be called** unless the overriding dialect calls
2503 it directly from here.
2505 .. versionadded:: 1.4.3 added :meth:`_engine.Dialect.on_connect_url`
2506 which normally calls into :meth:`_engine.Dialect.on_connect`.
2508 :param url: a :class:`_engine.URL` object representing the
2509 :class:`_engine.URL` that was passed to the
2510 :meth:`_engine.Dialect.create_connect_args` method.
2512 :return: a callable that accepts a single DBAPI connection as an
2513 argument, or None.
2515 .. seealso::
2517 :meth:`_engine.Dialect.on_connect`
2519 """
2520 return self.on_connect()
2522 def on_connect(self) -> Optional[Callable[[Any], None]]:
2523 """return a callable which sets up a newly created DBAPI connection.
2525 The callable should accept a single argument "conn" which is the
2526 DBAPI connection itself. The inner callable has no
2527 return value.
2529 E.g.::
2531 class MyDialect(default.DefaultDialect):
2532 # ...
2534 def on_connect(self):
2535 def do_on_connect(connection):
2536 connection.execute("SET SPECIAL FLAGS etc")
2538 return do_on_connect
2540 This is used to set dialect-wide per-connection options such as
2541 isolation modes, Unicode modes, etc.
2543 The "do_on_connect" callable is invoked by using the
2544 :meth:`_events.PoolEvents.connect` event
2545 hook, then unwrapping the DBAPI connection and passing it into the
2546 callable.
2548 .. versionchanged:: 1.4 the on_connect hook is no longer called twice
2549 for the first connection of a dialect. The on_connect hook is still
2550 called before the :meth:`_engine.Dialect.initialize` method however.
2552 .. versionchanged:: 1.4.3 the on_connect hook is invoked from a new
2553 method on_connect_url that passes the URL that was used to create
2554 the connect args. Dialects can implement on_connect_url instead
2555 of on_connect if they need the URL object that was used for the
2556 connection in order to get additional context.
2558 If None is returned, no event listener is generated.
2560 :return: a callable that accepts a single DBAPI connection as an
2561 argument, or None.
2563 .. seealso::
2565 :meth:`.Dialect.connect` - allows the DBAPI ``connect()`` sequence
2566 itself to be controlled.
2568 :meth:`.Dialect.on_connect_url` - supersedes
2569 :meth:`.Dialect.on_connect` to also receive the
2570 :class:`_engine.URL` object in context.
2572 """
2573 return None
2575 def reset_isolation_level(self, dbapi_connection: DBAPIConnection) -> None:
2576 """Given a DBAPI connection, revert its isolation to the default.
2578 Note that this is a dialect-level method which is used as part
2579 of the implementation of the :class:`_engine.Connection` and
2580 :class:`_engine.Engine`
2581 isolation level facilities; these APIs should be preferred for
2582 most typical use cases.
2584 .. seealso::
2586 :meth:`_engine.Connection.get_isolation_level`
2587 - view current level
2589 :attr:`_engine.Connection.default_isolation_level`
2590 - view default level
2592 :paramref:`.Connection.execution_options.isolation_level` -
2593 set per :class:`_engine.Connection` isolation level
2595 :paramref:`_sa.create_engine.isolation_level` -
2596 set per :class:`_engine.Engine` isolation level
2598 """
2600 raise NotImplementedError()
2602 def set_isolation_level(
2603 self, dbapi_connection: DBAPIConnection, level: IsolationLevel
2604 ) -> None:
2605 """Given a DBAPI connection, set its isolation level.
2607 Note that this is a dialect-level method which is used as part
2608 of the implementation of the :class:`_engine.Connection` and
2609 :class:`_engine.Engine`
2610 isolation level facilities; these APIs should be preferred for
2611 most typical use cases.
2613 If the dialect also implements the
2614 :meth:`.Dialect.get_isolation_level_values` method, then the given
2615 level is guaranteed to be one of the string names within that sequence,
2616 and the method will not need to anticipate a lookup failure.
2618 .. seealso::
2620 :meth:`_engine.Connection.get_isolation_level`
2621 - view current level
2623 :attr:`_engine.Connection.default_isolation_level`
2624 - view default level
2626 :paramref:`.Connection.execution_options.isolation_level` -
2627 set per :class:`_engine.Connection` isolation level
2629 :paramref:`_sa.create_engine.isolation_level` -
2630 set per :class:`_engine.Engine` isolation level
2632 """
2634 raise NotImplementedError()
2636 def get_isolation_level(
2637 self, dbapi_connection: DBAPIConnection
2638 ) -> IsolationLevel:
2639 """Given a DBAPI connection, return its isolation level.
2641 When working with a :class:`_engine.Connection` object,
2642 the corresponding
2643 DBAPI connection may be procured using the
2644 :attr:`_engine.Connection.connection` accessor.
2646 Note that this is a dialect-level method which is used as part
2647 of the implementation of the :class:`_engine.Connection` and
2648 :class:`_engine.Engine` isolation level facilities;
2649 these APIs should be preferred for most typical use cases.
2652 .. seealso::
2654 :meth:`_engine.Connection.get_isolation_level`
2655 - view current level
2657 :attr:`_engine.Connection.default_isolation_level`
2658 - view default level
2660 :paramref:`.Connection.execution_options.isolation_level` -
2661 set per :class:`_engine.Connection` isolation level
2663 :paramref:`_sa.create_engine.isolation_level` -
2664 set per :class:`_engine.Engine` isolation level
2667 """
2669 raise NotImplementedError()
2671 def detect_autocommit_setting(self, dbapi_conn: DBAPIConnection) -> bool:
2672 """Detect the current autocommit setting for a DBAPI connection.
2674 :param dbapi_connection: a DBAPI connection object
2675 :return: True if autocommit is enabled, False if disabled
2676 :rtype: bool
2678 This method inspects the given DBAPI connection to determine
2679 whether autocommit mode is currently enabled. The specific
2680 mechanism for detecting autocommit varies by database dialect
2681 and DBAPI driver, however it should be done **without** network
2682 round trips.
2684 .. note::
2686 Not all dialects support autocommit detection. Dialects
2687 that do not support this feature will raise
2688 :exc:`NotImplementedError`.
2690 """
2691 raise NotImplementedError(
2692 "This dialect cannot detect autocommit on a DBAPI connection"
2693 )
2695 def get_default_isolation_level(
2696 self, dbapi_conn: DBAPIConnection
2697 ) -> IsolationLevel:
2698 """Given a DBAPI connection, return its isolation level, or
2699 a default isolation level if one cannot be retrieved.
2701 This method may only raise NotImplementedError and
2702 **must not raise any other exception**, as it is used implicitly upon
2703 first connect.
2705 The method **must return a value** for a dialect that supports
2706 isolation level settings, as this level is what will be reverted
2707 towards when a per-connection isolation level change is made.
2709 The method defaults to using the :meth:`.Dialect.get_isolation_level`
2710 method unless overridden by a dialect.
2712 """
2713 raise NotImplementedError()
2715 def get_isolation_level_values(
2716 self, dbapi_conn: DBAPIConnection
2717 ) -> Sequence[IsolationLevel]:
2718 """return a sequence of string isolation level names that are accepted
2719 by this dialect.
2721 The available names should use the following conventions:
2723 * use UPPERCASE names. isolation level methods will accept lowercase
2724 names but these are normalized into UPPERCASE before being passed
2725 along to the dialect.
2726 * separate words should be separated by spaces, not underscores, e.g.
2727 ``REPEATABLE READ``. isolation level names will have underscores
2728 converted to spaces before being passed along to the dialect.
2729 * The names for the four standard isolation names to the extent that
2730 they are supported by the backend should be ``READ UNCOMMITTED``,
2731 ``READ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``
2732 * if the dialect supports an autocommit option it should be provided
2733 using the isolation level name ``AUTOCOMMIT``.
2734 * Other isolation modes may also be present, provided that they
2735 are named in UPPERCASE and use spaces not underscores.
2737 This function is used so that the default dialect can check that
2738 a given isolation level parameter is valid, else raises an
2739 :class:`_exc.ArgumentError`.
2741 A DBAPI connection is passed to the method, in the unlikely event that
2742 the dialect needs to interrogate the connection itself to determine
2743 this list, however it is expected that most backends will return
2744 a hardcoded list of values. If the dialect supports "AUTOCOMMIT",
2745 that value should also be present in the sequence returned.
2747 The method raises ``NotImplementedError`` by default. If a dialect
2748 does not implement this method, then the default dialect will not
2749 perform any checking on a given isolation level value before passing
2750 it onto the :meth:`.Dialect.set_isolation_level` method. This is
2751 to allow backwards-compatibility with third party dialects that may
2752 not yet be implementing this method.
2754 .. versionadded:: 2.0
2756 """
2757 raise NotImplementedError()
2759 def _assert_and_set_isolation_level(
2760 self, dbapi_conn: DBAPIConnection, level: IsolationLevel
2761 ) -> None:
2762 raise NotImplementedError()
2764 @classmethod
2765 def get_dialect_cls(cls, url: URL) -> Type[Dialect]:
2766 """Given a URL, return the :class:`.Dialect` that will be used.
2768 This is a hook that allows an external plugin to provide functionality
2769 around an existing dialect, by allowing the plugin to be loaded
2770 from the url based on an entrypoint, and then the plugin returns
2771 the actual dialect to be used.
2773 By default this just returns the cls.
2775 """
2776 return cls
2778 @classmethod
2779 def get_async_dialect_cls(cls, url: URL) -> Type[Dialect]:
2780 """Given a URL, return the :class:`.Dialect` that will be used by
2781 an async engine.
2783 By default this is an alias of :meth:`.Dialect.get_dialect_cls` and
2784 just returns the cls. It may be used if a dialect provides
2785 both a sync and async version under the same name, like the
2786 ``psycopg`` driver.
2788 .. versionadded:: 2
2790 .. seealso::
2792 :meth:`.Dialect.get_dialect_cls`
2794 """
2795 return cls.get_dialect_cls(url)
2797 @classmethod
2798 def load_provisioning(cls) -> None:
2799 """set up the provision.py module for this dialect.
2801 For dialects that include a provision.py module that sets up
2802 provisioning followers, this method should initiate that process.
2804 A typical implementation would be::
2806 @classmethod
2807 def load_provisioning(cls):
2808 __import__("mydialect.provision")
2810 The default method assumes a module named ``provision.py`` inside
2811 the owning package of the current dialect, based on the ``__module__``
2812 attribute::
2814 @classmethod
2815 def load_provisioning(cls):
2816 package = ".".join(cls.__module__.split(".")[0:-1])
2817 try:
2818 __import__(package + ".provision")
2819 except ImportError:
2820 pass
2822 """
2824 @classmethod
2825 def engine_created(cls, engine: Engine) -> None:
2826 """A convenience hook called before returning the final
2827 :class:`_engine.Engine`.
2829 If the dialect returned a different class from the
2830 :meth:`.get_dialect_cls`
2831 method, then the hook is called on both classes, first on
2832 the dialect class returned by the :meth:`.get_dialect_cls` method and
2833 then on the class on which the method was called.
2835 The hook should be used by dialects and/or wrappers to apply special
2836 events to the engine or its components. In particular, it allows
2837 a dialect-wrapping class to apply dialect-level events.
2839 """
2841 def get_driver_connection(self, connection: DBAPIConnection) -> Any:
2842 """Returns the connection object as returned by the external driver
2843 package.
2845 For normal dialects that use a DBAPI compliant driver this call
2846 will just return the ``connection`` passed as argument.
2847 For dialects that instead adapt a non DBAPI compliant driver, like
2848 when adapting an asyncio driver, this call will return the
2849 connection-like object as returned by the driver.
2851 .. versionadded:: 1.4.24
2853 """
2854 raise NotImplementedError()
2856 def set_engine_execution_options(
2857 self, engine: Engine, opts: CoreExecuteOptionsParameter
2858 ) -> None:
2859 """Establish execution options for a given engine.
2861 This is implemented by :class:`.DefaultDialect` to establish
2862 event hooks for new :class:`.Connection` instances created
2863 by the given :class:`.Engine` which will then invoke the
2864 :meth:`.Dialect.set_connection_execution_options` method for that
2865 connection.
2867 """
2868 raise NotImplementedError()
2870 def set_connection_execution_options(
2871 self, connection: Connection, opts: CoreExecuteOptionsParameter
2872 ) -> None:
2873 """Establish execution options for a given connection.
2875 This is implemented by :class:`.DefaultDialect` in order to implement
2876 the :paramref:`_engine.Connection.execution_options.isolation_level`
2877 execution option. Dialects can intercept various execution options
2878 which may need to modify state on a particular DBAPI connection.
2880 .. versionadded:: 1.4
2882 """
2883 raise NotImplementedError()
2885 def get_dialect_pool_class(self, url: URL) -> Type[Pool]:
2886 """return a Pool class to use for a given URL"""
2887 raise NotImplementedError()
2889 def validate_identifier(self, ident: str) -> None:
2890 """Validates an identifier name, raising an exception if invalid"""
2893class CreateEnginePlugin:
2894 """A set of hooks intended to augment the construction of an
2895 :class:`_engine.Engine` object based on entrypoint names in a URL.
2897 The purpose of :class:`_engine.CreateEnginePlugin` is to allow third-party
2898 systems to apply engine, pool and dialect level event listeners without
2899 the need for the target application to be modified; instead, the plugin
2900 names can be added to the database URL. Target applications for
2901 :class:`_engine.CreateEnginePlugin` include:
2903 * connection and SQL performance tools, e.g. which use events to track
2904 number of checkouts and/or time spent with statements
2906 * connectivity plugins such as proxies
2908 A rudimentary :class:`_engine.CreateEnginePlugin` that attaches a logger
2909 to an :class:`_engine.Engine` object might look like::
2912 import logging
2914 from sqlalchemy.engine import CreateEnginePlugin
2915 from sqlalchemy import event
2918 class LogCursorEventsPlugin(CreateEnginePlugin):
2919 def __init__(self, url, kwargs):
2920 # consume the parameter "log_cursor_logging_name" from the
2921 # URL query
2922 logging_name = url.query.get(
2923 "log_cursor_logging_name", "log_cursor"
2924 )
2926 self.log = logging.getLogger(logging_name)
2928 def update_url(self, url):
2929 "update the URL to one that no longer includes our parameters"
2930 return url.difference_update_query(["log_cursor_logging_name"])
2932 def engine_created(self, engine):
2933 "attach an event listener after the new Engine is constructed"
2934 event.listen(engine, "before_cursor_execute", self._log_event)
2936 def _log_event(
2937 self,
2938 conn,
2939 cursor,
2940 statement,
2941 parameters,
2942 context,
2943 executemany,
2944 ):
2946 self.log.info("Plugin logged cursor event: %s", statement)
2948 Plugins are registered using entry points in a similar way as that
2949 of dialects::
2951 entry_points = {
2952 "sqlalchemy.plugins": [
2953 "log_cursor_plugin = myapp.plugins:LogCursorEventsPlugin"
2954 ]
2955 }
2957 A plugin that uses the above names would be invoked from a database
2958 URL as in::
2960 from sqlalchemy import create_engine
2962 engine = create_engine(
2963 "mysql+pymysql://scott:tiger@localhost/test?"
2964 "plugin=log_cursor_plugin&log_cursor_logging_name=mylogger"
2965 )
2967 The ``plugin`` URL parameter supports multiple instances, so that a URL
2968 may specify multiple plugins; they are loaded in the order stated
2969 in the URL::
2971 engine = create_engine(
2972 "mysql+pymysql://scott:tiger@localhost/test?"
2973 "plugin=plugin_one&plugin=plugin_twp&plugin=plugin_three"
2974 )
2976 The plugin names may also be passed directly to :func:`_sa.create_engine`
2977 using the :paramref:`_sa.create_engine.plugins` argument::
2979 engine = create_engine(
2980 "mysql+pymysql://scott:tiger@localhost/test", plugins=["myplugin"]
2981 )
2983 A plugin may consume plugin-specific arguments from the
2984 :class:`_engine.URL` object as well as the ``kwargs`` dictionary, which is
2985 the dictionary of arguments passed to the :func:`_sa.create_engine`
2986 call. "Consuming" these arguments includes that they must be removed
2987 when the plugin initializes, so that the arguments are not passed along
2988 to the :class:`_engine.Dialect` constructor, where they will raise an
2989 :class:`_exc.ArgumentError` because they are not known by the dialect.
2991 As of version 1.4 of SQLAlchemy, arguments should continue to be consumed
2992 from the ``kwargs`` dictionary directly, by removing the values with a
2993 method such as ``dict.pop``. Arguments from the :class:`_engine.URL` object
2994 should be consumed by implementing the
2995 :meth:`_engine.CreateEnginePlugin.update_url` method, returning a new copy
2996 of the :class:`_engine.URL` with plugin-specific parameters removed::
2998 class MyPlugin(CreateEnginePlugin):
2999 def __init__(self, url, kwargs):
3000 self.my_argument_one = url.query["my_argument_one"]
3001 self.my_argument_two = url.query["my_argument_two"]
3002 self.my_argument_three = kwargs.pop("my_argument_three", None)
3004 def update_url(self, url):
3005 return url.difference_update_query(
3006 ["my_argument_one", "my_argument_two"]
3007 )
3009 Arguments like those illustrated above would be consumed from a
3010 :func:`_sa.create_engine` call such as::
3012 from sqlalchemy import create_engine
3014 engine = create_engine(
3015 "mysql+pymysql://scott:tiger@localhost/test?"
3016 "plugin=myplugin&my_argument_one=foo&my_argument_two=bar",
3017 my_argument_three="bat",
3018 )
3020 .. versionchanged:: 1.4
3022 The :class:`_engine.URL` object is now immutable; a
3023 :class:`_engine.CreateEnginePlugin` that needs to alter the
3024 :class:`_engine.URL` should implement the newly added
3025 :meth:`_engine.CreateEnginePlugin.update_url` method, which
3026 is invoked after the plugin is constructed.
3028 For migration, construct the plugin in the following way, checking
3029 for the existence of the :meth:`_engine.CreateEnginePlugin.update_url`
3030 method to detect which version is running::
3032 class MyPlugin(CreateEnginePlugin):
3033 def __init__(self, url, kwargs):
3034 if hasattr(CreateEnginePlugin, "update_url"):
3035 # detect the 1.4 API
3036 self.my_argument_one = url.query["my_argument_one"]
3037 self.my_argument_two = url.query["my_argument_two"]
3038 else:
3039 # detect the 1.3 and earlier API - mutate the
3040 # URL directly
3041 self.my_argument_one = url.query.pop("my_argument_one")
3042 self.my_argument_two = url.query.pop("my_argument_two")
3044 self.my_argument_three = kwargs.pop("my_argument_three", None)
3046 def update_url(self, url):
3047 # this method is only called in the 1.4 version
3048 return url.difference_update_query(
3049 ["my_argument_one", "my_argument_two"]
3050 )
3052 .. seealso::
3054 :ref:`change_5526` - overview of the :class:`_engine.URL` change which
3055 also includes notes regarding :class:`_engine.CreateEnginePlugin`.
3058 When the engine creation process completes and produces the
3059 :class:`_engine.Engine` object, it is again passed to the plugin via the
3060 :meth:`_engine.CreateEnginePlugin.engine_created` hook. In this hook, additional
3061 changes can be made to the engine, most typically involving setup of
3062 events (e.g. those defined in :ref:`core_event_toplevel`).
3064 """ # noqa: E501
3066 def __init__(self, url: URL, kwargs: Dict[str, Any]):
3067 """Construct a new :class:`.CreateEnginePlugin`.
3069 The plugin object is instantiated individually for each call
3070 to :func:`_sa.create_engine`. A single :class:`_engine.
3071 Engine` will be
3072 passed to the :meth:`.CreateEnginePlugin.engine_created` method
3073 corresponding to this URL.
3075 :param url: the :class:`_engine.URL` object. The plugin may inspect
3076 the :class:`_engine.URL` for arguments. Arguments used by the
3077 plugin should be removed, by returning an updated :class:`_engine.URL`
3078 from the :meth:`_engine.CreateEnginePlugin.update_url` method.
3080 .. versionchanged:: 1.4
3082 The :class:`_engine.URL` object is now immutable, so a
3083 :class:`_engine.CreateEnginePlugin` that needs to alter the
3084 :class:`_engine.URL` object should implement the
3085 :meth:`_engine.CreateEnginePlugin.update_url` method.
3087 :param kwargs: The keyword arguments passed to
3088 :func:`_sa.create_engine`.
3090 """
3091 self.url = url
3093 def update_url(self, url: URL) -> URL:
3094 """Update the :class:`_engine.URL`.
3096 A new :class:`_engine.URL` should be returned. This method is
3097 typically used to consume configuration arguments from the
3098 :class:`_engine.URL` which must be removed, as they will not be
3099 recognized by the dialect. The
3100 :meth:`_engine.URL.difference_update_query` method is available
3101 to remove these arguments. See the docstring at
3102 :class:`_engine.CreateEnginePlugin` for an example.
3105 .. versionadded:: 1.4
3107 """
3108 raise NotImplementedError()
3110 def handle_dialect_kwargs(
3111 self, dialect_cls: Type[Dialect], dialect_args: Dict[str, Any]
3112 ) -> None:
3113 """parse and modify dialect kwargs"""
3115 def handle_pool_kwargs(
3116 self, pool_cls: Type[Pool], pool_args: Dict[str, Any]
3117 ) -> None:
3118 """parse and modify pool kwargs"""
3120 def engine_created(self, engine: Engine) -> None:
3121 """Receive the :class:`_engine.Engine`
3122 object when it is fully constructed.
3124 The plugin may make additional changes to the engine, such as
3125 registering engine or connection pool events.
3127 """
3130class ExecutionContext:
3131 """A messenger object for a Dialect that corresponds to a single
3132 execution.
3134 """
3136 engine: Engine
3137 """engine which the Connection is associated with"""
3139 connection: Connection
3140 """Connection object which can be freely used by default value
3141 generators to execute SQL. This Connection should reference the
3142 same underlying connection/transactional resources of
3143 root_connection."""
3145 root_connection: Connection
3146 """Connection object which is the source of this ExecutionContext."""
3148 dialect: Dialect
3149 """dialect which created this ExecutionContext."""
3151 cursor: DBAPICursor
3152 """DB-API cursor procured from the connection"""
3154 compiled: Optional[Compiled]
3155 """if passed to constructor, sqlalchemy.engine.base.Compiled object
3156 being executed"""
3158 statement: str
3159 """string version of the statement to be executed. Is either
3160 passed to the constructor, or must be created from the
3161 sql.Compiled object by the time pre_exec() has completed."""
3163 invoked_statement: Optional[Executable]
3164 """The Executable statement object that was given in the first place.
3166 This should be structurally equivalent to compiled.statement, but not
3167 necessarily the same object as in a caching scenario the compiled form
3168 will have been extracted from the cache.
3170 """
3172 parameters: _AnyMultiExecuteParams
3173 """bind parameters passed to the execute() or exec_driver_sql() methods.
3175 These are always stored as a list of parameter entries. A single-element
3176 list corresponds to a ``cursor.execute()`` call and a multiple-element
3177 list corresponds to ``cursor.executemany()``, except in the case
3178 of :attr:`.ExecuteStyle.INSERTMANYVALUES` which will use
3179 ``cursor.execute()`` one or more times.
3181 """
3183 no_parameters: bool
3184 """True if the execution style does not use parameters"""
3186 isinsert: bool
3187 """True if the statement is an INSERT."""
3189 isupdate: bool
3190 """True if the statement is an UPDATE."""
3192 execute_style: ExecuteStyle
3193 """the style of DBAPI cursor method that will be used to execute
3194 a statement.
3196 .. versionadded:: 2.0
3198 """
3200 executemany: bool
3201 """True if the context has a list of more than one parameter set.
3203 Historically this attribute links to whether ``cursor.execute()`` or
3204 ``cursor.executemany()`` will be used. It also can now mean that
3205 "insertmanyvalues" may be used which indicates one or more
3206 ``cursor.execute()`` calls.
3208 """
3210 prefetch_cols: util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]]
3211 """a list of Column objects for which a client-side default
3212 was fired off. Applies to inserts and updates."""
3214 postfetch_cols: util.generic_fn_descriptor[Optional[Sequence[Column[Any]]]]
3215 """a list of Column objects for which a server-side default or
3216 inline SQL expression value was fired off. Applies to inserts
3217 and updates."""
3219 execution_options: _ExecuteOptions
3220 """Execution options associated with the current statement execution"""
3222 @classmethod
3223 def _init_ddl(
3224 cls,
3225 dialect: Dialect,
3226 connection: Connection,
3227 dbapi_connection: PoolProxiedConnection,
3228 execution_options: _ExecuteOptions,
3229 compiled_ddl: DDLCompiler,
3230 ) -> ExecutionContext:
3231 raise NotImplementedError()
3233 @classmethod
3234 def _init_compiled(
3235 cls,
3236 dialect: Dialect,
3237 connection: Connection,
3238 dbapi_connection: PoolProxiedConnection,
3239 execution_options: _ExecuteOptions,
3240 compiled: SQLCompiler,
3241 parameters: _CoreMultiExecuteParams,
3242 invoked_statement: Executable,
3243 extracted_parameters: Optional[Sequence[BindParameter[Any]]],
3244 cache_hit: CacheStats = CacheStats.CACHING_DISABLED,
3245 ) -> ExecutionContext:
3246 raise NotImplementedError()
3248 @classmethod
3249 def _init_statement(
3250 cls,
3251 dialect: Dialect,
3252 connection: Connection,
3253 dbapi_connection: PoolProxiedConnection,
3254 execution_options: _ExecuteOptions,
3255 statement: str,
3256 parameters: _DBAPIMultiExecuteParams,
3257 ) -> ExecutionContext:
3258 raise NotImplementedError()
3260 @classmethod
3261 def _init_default(
3262 cls,
3263 dialect: Dialect,
3264 connection: Connection,
3265 dbapi_connection: PoolProxiedConnection,
3266 execution_options: _ExecuteOptions,
3267 ) -> ExecutionContext:
3268 raise NotImplementedError()
3270 def _exec_default(
3271 self,
3272 column: Optional[Column[Any]],
3273 default: DefaultGenerator,
3274 type_: Optional[TypeEngine[Any]],
3275 ) -> Any:
3276 raise NotImplementedError()
3278 def _prepare_set_input_sizes(
3279 self,
3280 ) -> Optional[List[Tuple[str, Any, TypeEngine[Any]]]]:
3281 raise NotImplementedError()
3283 def _get_cache_stats(self) -> str:
3284 raise NotImplementedError()
3286 def _setup_result_proxy(self) -> CursorResult[Any]:
3287 raise NotImplementedError()
3289 def fire_sequence(self, seq: Sequence_SchemaItem, type_: Integer) -> int:
3290 """given a :class:`.Sequence`, invoke it and return the next int
3291 value"""
3292 raise NotImplementedError()
3294 def create_cursor(self) -> DBAPICursor:
3295 """Return a new cursor generated from this ExecutionContext's
3296 connection.
3298 Some dialects may wish to change the behavior of
3299 connection.cursor(), such as postgresql which may return a PG
3300 "server side" cursor.
3301 """
3303 raise NotImplementedError()
3305 def pre_exec(self) -> None:
3306 """Called before an execution of a compiled statement.
3308 If a compiled statement was passed to this ExecutionContext,
3309 the `statement` and `parameters` datamembers must be
3310 initialized after this statement is complete.
3311 """
3313 raise NotImplementedError()
3315 def get_out_parameter_values(
3316 self, out_param_names: Sequence[str]
3317 ) -> Sequence[Any]:
3318 """Return a sequence of OUT parameter values from a cursor.
3320 For dialects that support OUT parameters, this method will be called
3321 when there is a :class:`.SQLCompiler` object which has the
3322 :attr:`.SQLCompiler.has_out_parameters` flag set. This flag in turn
3323 will be set to True if the statement itself has :class:`.BindParameter`
3324 objects that have the ``.isoutparam`` flag set which are consumed by
3325 the :meth:`.SQLCompiler.visit_bindparam` method. If the dialect
3326 compiler produces :class:`.BindParameter` objects with ``.isoutparam``
3327 set which are not handled by :meth:`.SQLCompiler.visit_bindparam`, it
3328 should set this flag explicitly.
3330 The list of names that were rendered for each bound parameter
3331 is passed to the method. The method should then return a sequence of
3332 values corresponding to the list of parameter objects. Unlike in
3333 previous SQLAlchemy versions, the values can be the **raw values** from
3334 the DBAPI; the execution context will apply the appropriate type
3335 handler based on what's present in self.compiled.binds and update the
3336 values. The processed dictionary will then be made available via the
3337 ``.out_parameters`` collection on the result object. Note that
3338 SQLAlchemy 1.4 has multiple kinds of result object as part of the 2.0
3339 transition.
3341 .. versionadded:: 1.4 - added
3342 :meth:`.ExecutionContext.get_out_parameter_values`, which is invoked
3343 automatically by the :class:`.DefaultExecutionContext` when there
3344 are :class:`.BindParameter` objects with the ``.isoutparam`` flag
3345 set. This replaces the practice of setting out parameters within
3346 the now-removed ``get_result_proxy()`` method.
3348 """
3349 raise NotImplementedError()
3351 def post_exec(self) -> None:
3352 """Called after the execution of a compiled statement.
3354 If a compiled statement was passed to this ExecutionContext,
3355 the `last_insert_ids`, `last_inserted_params`, etc.
3356 datamembers should be available after this method completes.
3357 """
3359 raise NotImplementedError()
3361 def handle_dbapi_exception(self, e: BaseException) -> None:
3362 """Receive a DBAPI exception which occurred upon execute, result
3363 fetch, etc."""
3365 raise NotImplementedError()
3367 def lastrow_has_defaults(self) -> bool:
3368 """Return True if the last INSERT or UPDATE row contained
3369 inlined or database-side defaults.
3370 """
3372 raise NotImplementedError()
3374 def get_rowcount(self) -> Optional[int]:
3375 """Return the DBAPI ``cursor.rowcount`` value, or in some
3376 cases an interpreted value.
3378 See :attr:`_engine.CursorResult.rowcount` for details on this.
3380 """
3382 raise NotImplementedError()
3384 def fetchall_for_returning(self, cursor: DBAPICursor) -> Sequence[Any]:
3385 """For a RETURNING result, deliver cursor.fetchall() from the
3386 DBAPI cursor.
3388 This is a dialect-specific hook for dialects that have special
3389 considerations when calling upon the rows delivered for a
3390 "RETURNING" statement. Default implementation is
3391 ``cursor.fetchall()``.
3393 This hook is currently used only by the :term:`insertmanyvalues`
3394 feature. Dialects that don't set ``use_insertmanyvalues=True``
3395 don't need to consider this hook.
3397 .. versionadded:: 2.0.10
3399 """
3400 raise NotImplementedError()
3403class ConnectionEventsTarget(EventTarget):
3404 """An object which can accept events from :class:`.ConnectionEvents`.
3406 Includes :class:`_engine.Connection` and :class:`_engine.Engine`.
3408 .. versionadded:: 2.0
3410 """
3412 dispatch: dispatcher[ConnectionEventsTarget]
3415Connectable = ConnectionEventsTarget
3418class ExceptionContext:
3419 """Encapsulate information about an error condition in progress.
3421 This object exists solely to be passed to the
3422 :meth:`_events.DialectEvents.handle_error` event,
3423 supporting an interface that
3424 can be extended without backwards-incompatibility.
3427 """
3429 __slots__ = ()
3431 dialect: Dialect
3432 """The :class:`_engine.Dialect` in use.
3434 This member is present for all invocations of the event hook.
3436 .. versionadded:: 2.0
3438 """
3440 connection: Optional[Connection]
3441 """The :class:`_engine.Connection` in use during the exception.
3443 This member is present, except in the case of a failure when
3444 first connecting.
3446 .. seealso::
3448 :attr:`.ExceptionContext.engine`
3451 """
3453 engine: Optional[Engine]
3454 """The :class:`_engine.Engine` in use during the exception.
3456 This member is present in all cases except for when handling an error
3457 within the connection pool "pre-ping" process.
3459 """
3461 cursor: Optional[DBAPICursor]
3462 """The DBAPI cursor object.
3464 May be None.
3466 """
3468 statement: Optional[str]
3469 """String SQL statement that was emitted directly to the DBAPI.
3471 May be None.
3473 """
3475 parameters: Optional[_DBAPIAnyExecuteParams]
3476 """Parameter collection that was emitted directly to the DBAPI.
3478 May be None.
3480 """
3482 original_exception: BaseException
3483 """The exception object which was caught.
3485 This member is always present.
3487 """
3489 sqlalchemy_exception: Optional[StatementError]
3490 """The :class:`sqlalchemy.exc.StatementError` which wraps the original,
3491 and will be raised if exception handling is not circumvented by the event.
3493 May be None, as not all exception types are wrapped by SQLAlchemy.
3494 For DBAPI-level exceptions that subclass the dbapi's Error class, this
3495 field will always be present.
3497 """
3499 chained_exception: Optional[BaseException]
3500 """The exception that was returned by the previous handler in the
3501 exception chain, if any.
3503 If present, this exception will be the one ultimately raised by
3504 SQLAlchemy unless a subsequent handler replaces it.
3506 May be None.
3508 """
3510 execution_context: Optional[ExecutionContext]
3511 """The :class:`.ExecutionContext` corresponding to the execution
3512 operation in progress.
3514 This is present for statement execution operations, but not for
3515 operations such as transaction begin/end. It also is not present when
3516 the exception was raised before the :class:`.ExecutionContext`
3517 could be constructed.
3519 Note that the :attr:`.ExceptionContext.statement` and
3520 :attr:`.ExceptionContext.parameters` members may represent a
3521 different value than that of the :class:`.ExecutionContext`,
3522 potentially in the case where a
3523 :meth:`_events.ConnectionEvents.before_cursor_execute` event or similar
3524 modified the statement/parameters to be sent.
3526 May be None.
3528 """
3530 is_disconnect: bool
3531 """Represent whether the exception as occurred represents a "disconnect"
3532 condition.
3534 This flag will always be True or False within the scope of the
3535 :meth:`_events.DialectEvents.handle_error` handler.
3537 SQLAlchemy will defer to this flag in order to determine whether or not
3538 the connection should be invalidated subsequently. That is, by
3539 assigning to this flag, a "disconnect" event which then results in
3540 a connection and pool invalidation can be invoked or prevented by
3541 changing this flag.
3544 .. note:: The pool "pre_ping" handler enabled using the
3545 :paramref:`_sa.create_engine.pool_pre_ping` parameter does **not**
3546 consult this event before deciding if the "ping" returned false,
3547 as opposed to receiving an unhandled error. For this use case, the
3548 :ref:`legacy recipe based on engine_connect() may be used
3549 <pool_disconnects_pessimistic_custom>`. A future API allow more
3550 comprehensive customization of the "disconnect" detection mechanism
3551 across all functions.
3553 """
3555 invalidate_pool_on_disconnect: bool
3556 """Represent whether all connections in the pool should be invalidated
3557 when a "disconnect" condition is in effect.
3559 Setting this flag to False within the scope of the
3560 :meth:`_events.DialectEvents.handle_error`
3561 event will have the effect such
3562 that the full collection of connections in the pool will not be
3563 invalidated during a disconnect; only the current connection that is the
3564 subject of the error will actually be invalidated.
3566 The purpose of this flag is for custom disconnect-handling schemes where
3567 the invalidation of other connections in the pool is to be performed
3568 based on other conditions, or even on a per-connection basis.
3570 """
3572 is_pre_ping: bool
3573 """Indicates if this error is occurring within the "pre-ping" step
3574 performed when :paramref:`_sa.create_engine.pool_pre_ping` is set to
3575 ``True``. In this mode, the :attr:`.ExceptionContext.engine` attribute
3576 will be ``None``. The dialect in use is accessible via the
3577 :attr:`.ExceptionContext.dialect` attribute.
3579 .. versionadded:: 2.0.5
3581 """
3584class AdaptedConnection:
3585 """Interface of an adapted connection object to support the DBAPI protocol.
3587 Used by asyncio dialects to provide a sync-style pep-249 facade on top
3588 of the asyncio connection/cursor API provided by the driver.
3590 .. versionadded:: 1.4.24
3592 """
3594 __slots__ = ("_connection",)
3596 _connection: AsyncIODBAPIConnection
3598 @property
3599 def driver_connection(self) -> Any:
3600 """The connection object as returned by the driver after a connect."""
3601 return self._connection
3603 def run_async(self, fn: Callable[[Any], Awaitable[_T]]) -> _T:
3604 """Run the awaitable returned by the given function, which is passed
3605 the raw asyncio driver connection.
3607 This is used to invoke awaitable-only methods on the driver connection
3608 within the context of a "synchronous" method, like a connection
3609 pool event handler.
3611 E.g.::
3613 engine = create_async_engine(...)
3616 @event.listens_for(engine.sync_engine, "connect")
3617 def register_custom_types(
3618 dbapi_connection, # ...
3619 ):
3620 dbapi_connection.run_async(
3621 lambda connection: connection.set_type_codec(
3622 "MyCustomType", encoder, decoder, ...
3623 )
3624 )
3626 .. versionadded:: 1.4.30
3628 .. seealso::
3630 :ref:`asyncio_events_run_async`
3632 """
3633 return await_(fn(self._connection))
3635 def __repr__(self) -> str:
3636 return "<AdaptedConnection %s>" % self._connection