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