codekingpro/portable-devtools
115k
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
7
8"""Define core interfaces used by the engine system."""
9
10from __future__ import annotations
11
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 Mapping
23from typing import MutableMapping
24from typing import Optional
25from typing import Sequence
26from typing import Set
27from typing import Tuple
28from typing import Type
29from typing import TYPE_CHECKING
30from typing import TypeVar
31from typing import Union
32
33from .. import util
34from ..event import EventTarget
35from ..pool import Pool
36from ..pool import PoolProxiedConnection as PoolProxiedConnection
37from ..sql.compiler import Compiled as Compiled
38from ..sql.compiler import Compiled # noqa
39from ..sql.compiler import TypeCompiler as TypeCompiler
40from ..sql.compiler import TypeCompiler # noqa
41from ..util import immutabledict
42from ..util.concurrency import await_only
43from ..util.typing import Literal
44from ..util.typing import NotRequired
45from ..util.typing import Protocol
46from ..util.typing import TypedDict
47
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 DDLCompiler
60 from ..sql.compiler import IdentifierPreparer
61 from ..sql.compiler import InsertmanyvaluesSentinelOpts
62 from ..sql.compiler import Linting
63 from ..sql.compiler import SQLCompiler
64 from ..sql.elements import BindParameter
65 from ..sql.elements import ClauseElement
66 from ..sql.schema import Column
67 from ..sql.schema import DefaultGenerator
68 from ..sql.schema import SchemaItem
69 from ..sql.schema import Sequence as Sequence_SchemaItem
70 from ..sql.sqltypes import Integer
71 from ..sql.type_api import _TypeMemoDict
72 from ..sql.type_api import TypeEngine
73 from ..util.langhelpers import generic_fn_descriptor
74
75ConnectArgsType = Tuple[Sequence[str], MutableMapping[str, Any]]
76
77_T = TypeVar("_T", bound="Any")
78
79
80class CacheStats(Enum):
81 CACHE_HIT = 0
82 CACHE_MISS = 1
83 CACHING_DISABLED = 2
84 NO_CACHE_KEY = 3
85 NO_DIALECT_SUPPORT = 4
86
87
88class ExecuteStyle(Enum):
89 """indicates the :term:`DBAPI` cursor method that will be used to invoke
90 a statement."""
91
92 EXECUTE = 0
93 """indicates cursor.execute() will be used"""
94
95 EXECUTEMANY = 1
96 """indicates cursor.executemany() will be used."""
97
98 INSERTMANYVALUES = 2
99 """indicates cursor.execute() will be used with an INSERT where the
100 VALUES expression will be expanded to accommodate for multiple
101 parameter sets
102
103 .. seealso::
104
105 :ref:`engine_insertmanyvalues`
106
107 """
108
109
110class DBAPIModule(Protocol):
111 class Error(Exception):
112 def __getattr__(self, key: str) -> Any: ...
113
114 class OperationalError(Error):
115 pass
116
117 class InterfaceError(Error):
118 pass
119
120 class IntegrityError(Error):
121 pass
122
123 def __getattr__(self, key: str) -> Any: ...
124
125
126class DBAPIConnection(Protocol):
127 """protocol representing a :pep:`249` database connection.
128
129 .. versionadded:: 2.0
130
131 .. seealso::
132
133 `Connection Objects <https://www.python.org/dev/peps/pep-0249/#connection-objects>`_
134 - in :pep:`249`
135
136 """ # noqa: E501
137
138 def close(self) -> None: ...
139
140 def commit(self) -> None: ...
141
142 def cursor(self, *args: Any, **kwargs: Any) -> DBAPICursor: ...
143
144 def rollback(self) -> None: ...
145
146 def __getattr__(self, key: str) -> Any: ...
147
148 def __setattr__(self, key: str, value: Any) -> None: ...
149
150
151class DBAPIType(Protocol):
152 """protocol representing a :pep:`249` database type.
153
154 .. versionadded:: 2.0
155
156 .. seealso::
157
158 `Type Objects <https://www.python.org/dev/peps/pep-0249/#type-objects>`_
159 - in :pep:`249`
160
161 """ # noqa: E501
162
163
164class DBAPICursor(Protocol):
165 """protocol representing a :pep:`249` database cursor.
166
167 .. versionadded:: 2.0
168
169 .. seealso::
170
171 `Cursor Objects <https://www.python.org/dev/peps/pep-0249/#cursor-objects>`_
172 - in :pep:`249`
173
174 """ # noqa: E501
175
176 @property
177 def description(
178 self,
179 ) -> _DBAPICursorDescription:
180 """The description attribute of the Cursor.
181
182 .. seealso::
183
184 `cursor.description <https://www.python.org/dev/peps/pep-0249/#description>`_
185 - in :pep:`249`
186
187
188 """ # noqa: E501
189 ...
190
191 @property
192 def rowcount(self) -> int: ...
193
194 arraysize: int
195
196 lastrowid: int
197
198 def close(self) -> None: ...
199
200 def execute(
201 self,
202 operation: Any,
203 parameters: Optional[_DBAPISingleExecuteParams] = None,
204 ) -> Any: ...
205
206 def executemany(
207 self,
208 operation: Any,
209 parameters: _DBAPIMultiExecuteParams,
210 ) -> Any: ...
211
212 def fetchone(self) -> Optional[Any]: ...
213
214 def fetchmany(self, size: int = ...) -> Sequence[Any]: ...
215
216 def fetchall(self) -> Sequence[Any]: ...
217
218 def setinputsizes(self, sizes: Sequence[Any]) -> None: ...
219
220 def setoutputsize(self, size: Any, column: Any) -> None: ...
221
222 def callproc(
223 self, procname: str, parameters: Sequence[Any] = ...
224 ) -> Any: ...
225
226 def nextset(self) -> Optional[bool]: ...
227
228 def __getattr__(self, key: str) -> Any: ...
229
230
231_CoreSingleExecuteParams = Mapping[str, Any]
232_MutableCoreSingleExecuteParams = MutableMapping[str, Any]
233_CoreMultiExecuteParams = Sequence[_CoreSingleExecuteParams]
234_CoreAnyExecuteParams = Union[
235 _CoreMultiExecuteParams, _CoreSingleExecuteParams
236]
237
238_DBAPISingleExecuteParams = Union[Sequence[Any], _CoreSingleExecuteParams]
239
240_DBAPIMultiExecuteParams = Union[
241 Sequence[Sequence[Any]], _CoreMultiExecuteParams
242]
243_DBAPIAnyExecuteParams = Union[
244 _DBAPIMultiExecuteParams, _DBAPISingleExecuteParams
245]
246_DBAPICursorDescription = Sequence[
247 Tuple[
248 str,
249 "DBAPIType",
250 Optional[int],
251 Optional[int],
252 Optional[int],
253 Optional[int],
254 Optional[bool],
255 ]
256]
257
258_AnySingleExecuteParams = _DBAPISingleExecuteParams
259_AnyMultiExecuteParams = _DBAPIMultiExecuteParams
260_AnyExecuteParams = _DBAPIAnyExecuteParams
261
262CompiledCacheType = MutableMapping[Any, "Compiled"]
263SchemaTranslateMapType = Mapping[Optional[str], Optional[str]]
264
265_ImmutableExecuteOptions = immutabledict[str, Any]
266
267_ParamStyle = Literal[
268 "qmark", "numeric", "named", "format", "pyformat", "numeric_dollar"
269]
270
271_GenericSetInputSizesType = List[Tuple[str, Any, "TypeEngine[Any]"]]
272
273IsolationLevel = Literal[
274 "SERIALIZABLE",
275 "REPEATABLE READ",
276 "READ COMMITTED",
277 "READ UNCOMMITTED",
278 "AUTOCOMMIT",
279]
280
281
282class _CoreKnownExecutionOptions(TypedDict, total=False):
283 compiled_cache: Optional[CompiledCacheType]
284 logging_token: str
285 isolation_level: IsolationLevel
286 no_parameters: bool
287 stream_results: bool
288 max_row_buffer: int
289 yield_per: int
290 insertmanyvalues_page_size: int
291 schema_translate_map: Optional[SchemaTranslateMapType]
292 preserve_rowcount: bool
293
294
295_ExecuteOptions = immutabledict[str, Any]
296CoreExecuteOptionsParameter = Union[
297 _CoreKnownExecutionOptions, Mapping[str, Any]
298]
299
300
301class ReflectedIdentity(TypedDict):
302 """represent the reflected IDENTITY structure of a column, corresponding
303 to the :class:`_schema.Identity` construct.
304
305 The :class:`.ReflectedIdentity` structure is part of the
306 :class:`.ReflectedColumn` structure, which is returned by the
307 :meth:`.Inspector.get_columns` method.
308
309 """
310
311 always: bool
312 """type of identity column"""
313
314 on_null: bool
315 """indicates ON NULL"""
316
317 start: int
318 """starting index of the sequence"""
319
320 increment: int
321 """increment value of the sequence"""
322
323 minvalue: int
324 """the minimum value of the sequence."""
325
326 maxvalue: int
327 """the maximum value of the sequence."""
328
329 nominvalue: bool
330 """no minimum value of the sequence."""
331
332 nomaxvalue: bool
333 """no maximum value of the sequence."""
334
335 cycle: bool
336 """allows the sequence to wrap around when the maxvalue
337 or minvalue has been reached."""
338
339 cache: Optional[int]
340 """number of future values in the
341 sequence which are calculated in advance."""
342
343 order: bool
344 """if true, renders the ORDER keyword."""
345
346
347class ReflectedComputed(TypedDict):
348 """Represent the reflected elements of a computed column, corresponding
349 to the :class:`_schema.Computed` construct.
350
351 The :class:`.ReflectedComputed` structure is part of the
352 :class:`.ReflectedColumn` structure, which is returned by the
353 :meth:`.Inspector.get_columns` method.
354
355 """
356
357 sqltext: str
358 """the expression used to generate this column returned
359 as a string SQL expression"""
360
361 persisted: NotRequired[bool]
362 """indicates if the value is stored in the table or computed on demand"""
363
364
365class ReflectedColumn(TypedDict):
366 """Dictionary representing the reflected elements corresponding to
367 a :class:`_schema.Column` object.
368
369 The :class:`.ReflectedColumn` structure is returned by the
370 :class:`.Inspector.get_columns` method.
371
372 """
373
374 name: str
375 """column name"""
376
377 type: TypeEngine[Any]
378 """column type represented as a :class:`.TypeEngine` instance."""
379
380 nullable: bool
381 """boolean flag if the column is NULL or NOT NULL"""
382
383 default: Optional[str]
384 """column default expression as a SQL string"""
385
386 autoincrement: NotRequired[bool]
387 """database-dependent autoincrement flag.
388
389 This flag indicates if the column has a database-side "autoincrement"
390 flag of some kind. Within SQLAlchemy, other kinds of columns may
391 also act as an "autoincrement" column without necessarily having
392 such a flag on them.
393
394 See :paramref:`_schema.Column.autoincrement` for more background on
395 "autoincrement".
396
397 """
398
399 comment: NotRequired[Optional[str]]
400 """comment for the column, if present.
401 Only some dialects return this key
402 """
403
404 computed: NotRequired[ReflectedComputed]
405 """indicates that this column is computed by the database.
406 Only some dialects return this key.
407
408 .. versionadded:: 1.3.16 - added support for computed reflection.
409 """
410
411 identity: NotRequired[ReflectedIdentity]
412 """indicates this column is an IDENTITY column.
413 Only some dialects return this key.
414
415 .. versionadded:: 1.4 - added support for identity column reflection.
416 """
417
418 dialect_options: NotRequired[Dict[str, Any]]
419 """Additional dialect-specific options detected for this reflected
420 object"""
421
422
423class ReflectedConstraint(TypedDict):
424 """Dictionary representing the reflected elements corresponding to
425 :class:`.Constraint`
426
427 A base class for all constraints
428 """
429
430 name: Optional[str]
431 """constraint name"""
432
433 comment: NotRequired[Optional[str]]
434 """comment for the constraint, if present"""
435
436
437class ReflectedCheckConstraint(ReflectedConstraint):
438 """Dictionary representing the reflected elements corresponding to
439 :class:`.CheckConstraint`.
440
441 The :class:`.ReflectedCheckConstraint` structure is returned by the
442 :meth:`.Inspector.get_check_constraints` method.
443
444 """
445
446 sqltext: str
447 """the check constraint's SQL expression"""
448
449 dialect_options: NotRequired[Dict[str, Any]]
450 """Additional dialect-specific options detected for this check constraint
451
452 .. versionadded:: 1.3.8
453 """
454
455
456class ReflectedUniqueConstraint(ReflectedConstraint):
457 """Dictionary representing the reflected elements corresponding to
458 :class:`.UniqueConstraint`.
459
460 The :class:`.ReflectedUniqueConstraint` structure is returned by the
461 :meth:`.Inspector.get_unique_constraints` method.
462
463 """
464
465 column_names: List[str]
466 """column names which comprise the unique constraint"""
467
468 duplicates_index: NotRequired[Optional[str]]
469 "Indicates if this unique constraint duplicates an index with this name"
470
471 dialect_options: NotRequired[Dict[str, Any]]
472 """Additional dialect-specific options detected for this unique
473 constraint"""
474
475
476class ReflectedPrimaryKeyConstraint(ReflectedConstraint):
477 """Dictionary representing the reflected elements corresponding to
478 :class:`.PrimaryKeyConstraint`.
479
480 The :class:`.ReflectedPrimaryKeyConstraint` structure is returned by the
481 :meth:`.Inspector.get_pk_constraint` method.
482
483 """
484
485 constrained_columns: List[str]
486 """column names which comprise the primary key"""
487
488 dialect_options: NotRequired[Dict[str, Any]]
489 """Additional dialect-specific options detected for this primary key"""
490
491
492class ReflectedForeignKeyConstraint(ReflectedConstraint):
493 """Dictionary representing the reflected elements corresponding to
494 :class:`.ForeignKeyConstraint`.
495
496 The :class:`.ReflectedForeignKeyConstraint` structure is returned by
497 the :meth:`.Inspector.get_foreign_keys` method.
498
499 """
500
501 constrained_columns: List[str]
502 """local column names which comprise the foreign key"""
503
504 referred_schema: Optional[str]
505 """schema name of the table being referred"""
506
507 referred_table: str
508 """name of the table being referred"""
509
510 referred_columns: List[str]
511 """referred column names that correspond to ``constrained_columns``"""
512
513 options: NotRequired[Dict[str, Any]]
514 """Additional options detected for this foreign key constraint"""
515
516
517class ReflectedIndex(TypedDict):
518 """Dictionary representing the reflected elements corresponding to
519 :class:`.Index`.
520
521 The :class:`.ReflectedIndex` structure is returned by the
522 :meth:`.Inspector.get_indexes` method.
523
524 """
525
526 name: Optional[str]
527 """index name"""
528
529 column_names: List[Optional[str]]
530 """column names which the index references.
531 An element of this list is ``None`` if it's an expression and is
532 returned in the ``expressions`` list.
533 """
534
535 expressions: NotRequired[List[str]]
536 """Expressions that compose the index. This list, when present, contains
537 both plain column names (that are also in ``column_names``) and
538 expressions (that are ``None`` in ``column_names``).
539 """
540
541 unique: bool
542 """whether or not the index has a unique flag"""
543
544 duplicates_constraint: NotRequired[Optional[str]]
545 "Indicates if this index mirrors a constraint with this name"
546
547 include_columns: NotRequired[List[str]]
548 """columns to include in the INCLUDE clause for supporting databases.
549
550 .. deprecated:: 2.0
551
552 Legacy value, will be replaced with
553 ``index_dict["dialect_options"]["<dialect name>_include"]``
554
555 """
556
557 column_sorting: NotRequired[Dict[str, Tuple[str]]]
558 """optional dict mapping column names or expressions to tuple of sort
559 keywords, which may include ``asc``, ``desc``, ``nulls_first``,
560 ``nulls_last``.
561
562 .. versionadded:: 1.3.5
563 """
564
565 dialect_options: NotRequired[Dict[str, Any]]
566 """Additional dialect-specific options detected for this index"""
567
568
569class ReflectedTableComment(TypedDict):
570 """Dictionary representing the reflected comment corresponding to
571 the :attr:`_schema.Table.comment` attribute.
572
573 The :class:`.ReflectedTableComment` structure is returned by the
574 :meth:`.Inspector.get_table_comment` method.
575
576 """
577
578 text: Optional[str]
579 """text of the comment"""
580
581
582class BindTyping(Enum):
583 """Define different methods of passing typing information for
584 bound parameters in a statement to the database driver.
585
586 .. versionadded:: 2.0
587
588 """
589
590 NONE = 1
591 """No steps are taken to pass typing information to the database driver.
592
593 This is the default behavior for databases such as SQLite, MySQL / MariaDB,
594 SQL Server.
595
596 """
597
598 SETINPUTSIZES = 2
599 """Use the pep-249 setinputsizes method.
600
601 This is only implemented for DBAPIs that support this method and for which
602 the SQLAlchemy dialect has the appropriate infrastructure for that dialect
603 set up. Current dialects include python-oracledb, cx_Oracle as well as
604 optional support for SQL Server using pyodbc.
605
606 When using setinputsizes, dialects also have a means of only using the
607 method for certain datatypes using include/exclude lists.
608
609 When SETINPUTSIZES is used, the :meth:`.Dialect.do_set_input_sizes` method
610 is called for each statement executed which has bound parameters.
611
612 """
613
614 RENDER_CASTS = 3
615 """Render casts or other directives in the SQL string.
616
617 This method is used for all PostgreSQL dialects, including asyncpg,
618 pg8000, psycopg, psycopg2. Dialects which implement this can choose
619 which kinds of datatypes are explicitly cast in SQL statements and which
620 aren't.
621
622 When RENDER_CASTS is used, the compiler will invoke the
623 :meth:`.SQLCompiler.render_bind_cast` method for the rendered
624 string representation of each :class:`.BindParameter` object whose
625 dialect-level type sets the :attr:`.TypeEngine.render_bind_cast` attribute.
626
627 The :meth:`.SQLCompiler.render_bind_cast` is also used to render casts
628 for one form of "insertmanyvalues" query, when both
629 :attr:`.InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT` and
630 :attr:`.InsertmanyvaluesSentinelOpts.RENDER_SELECT_COL_CASTS` are set,
631 where the casts are applied to the intermediary columns e.g.
632 "INSERT INTO t (a, b, c) SELECT p0::TYP, p1::TYP, p2::TYP "
633 "FROM (VALUES (?, ?), (?, ?), ...)".
634
635 .. versionadded:: 2.0.10 - :meth:`.SQLCompiler.render_bind_cast` is now
636 used within some elements of the "insertmanyvalues" implementation.
637
638
639 """
640
641
642VersionInfoType = Tuple[Union[int, str], ...]
643TableKey = Tuple[Optional[str], str]
644
645
646class Dialect(EventTarget):
647 """Define the behavior of a specific database and DB-API combination.
648
649 Any aspect of metadata definition, SQL query generation,
650 execution, result-set handling, or anything else which varies
651 between databases is defined under the general category of the
652 Dialect. The Dialect acts as a factory for other
653 database-specific object implementations including
654 ExecutionContext, Compiled, DefaultGenerator, and TypeEngine.
655
656 .. note:: Third party dialects should not subclass :class:`.Dialect`
657 directly. Instead, subclass :class:`.default.DefaultDialect` or
658 descendant class.
659
660 """
661
662 CACHE_HIT = CacheStats.CACHE_HIT
663 CACHE_MISS = CacheStats.CACHE_MISS
664 CACHING_DISABLED = CacheStats.CACHING_DISABLED
665 NO_CACHE_KEY = CacheStats.NO_CACHE_KEY
666 NO_DIALECT_SUPPORT = CacheStats.NO_DIALECT_SUPPORT
667
668 dispatch: dispatcher[Dialect]
669
670 name: str
671 """identifying name for the dialect from a DBAPI-neutral point of view
672 (i.e. 'sqlite')
673 """
674
675 driver: str
676 """identifying name for the dialect's DBAPI"""
677
678 dialect_description: str
679
680 dbapi: Optional[DBAPIModule]
681 """A reference to the DBAPI module object itself.
682
683 SQLAlchemy dialects import DBAPI modules using the classmethod
684 :meth:`.Dialect.import_dbapi`. The rationale is so that any dialect
685 module can be imported and used to generate SQL statements without the
686 need for the actual DBAPI driver to be installed. Only when an
687 :class:`.Engine` is constructed using :func:`.create_engine` does the
688 DBAPI get imported; at that point, the creation process will assign
689 the DBAPI module to this attribute.
690
691 Dialects should therefore implement :meth:`.Dialect.import_dbapi`
692 which will import the necessary module and return it, and then refer
693 to ``self.dbapi`` in dialect code in order to refer to the DBAPI module
694 contents.
695
696 .. versionchanged:: The :attr:`.Dialect.dbapi` attribute is exclusively
697 used as the per-:class:`.Dialect`-instance reference to the DBAPI
698 module. The previous not-fully-documented ``.Dialect.dbapi()``
699 classmethod is deprecated and replaced by :meth:`.Dialect.import_dbapi`.
700
701 """
702
703 @util.non_memoized_property
704 def loaded_dbapi(self) -> DBAPIModule:
705 """same as .dbapi, but is never None; will raise an error if no
706 DBAPI was set up.
707
708 .. versionadded:: 2.0
709
710 """
711 raise NotImplementedError()
712
713 positional: bool
714 """True if the paramstyle for this Dialect is positional."""
715
716 paramstyle: str
717 """the paramstyle to be used (some DB-APIs support multiple
718 paramstyles).
719 """
720
721 compiler_linting: Linting
722
723 statement_compiler: Type[SQLCompiler]
724 """a :class:`.Compiled` class used to compile SQL statements"""
725
726 ddl_compiler: Type[DDLCompiler]
727 """a :class:`.Compiled` class used to compile DDL statements"""
728
729 type_compiler_cls: ClassVar[Type[TypeCompiler]]
730 """a :class:`.Compiled` class used to compile SQL type objects
731
732 .. versionadded:: 2.0
733
734 """
735
736 type_compiler_instance: TypeCompiler
737 """instance of a :class:`.Compiled` class used to compile SQL type
738 objects
739
740 .. versionadded:: 2.0
741
742 """
743
744 type_compiler: Any
745 """legacy; this is a TypeCompiler class at the class level, a
746 TypeCompiler instance at the instance level.
747
748 Refer to type_compiler_instance instead.
749
750 """
751
752 preparer: Type[IdentifierPreparer]
753 """a :class:`.IdentifierPreparer` class used to
754 quote identifiers.
755 """
756
757 identifier_preparer: IdentifierPreparer
758 """This element will refer to an instance of :class:`.IdentifierPreparer`
759 once a :class:`.DefaultDialect` has been constructed.
760
761 """
762
763 server_version_info: Optional[Tuple[Any, ...]]
764 """a tuple containing a version number for the DB backend in use.
765
766 This value is only available for supporting dialects, and is
767 typically populated during the initial connection to the database.
768 """
769
770 default_schema_name: Optional[str]
771 """the name of the default schema. This value is only available for
772 supporting dialects, and is typically populated during the
773 initial connection to the database.
774
775 """
776
777 # NOTE: this does not take into effect engine-level isolation level.
778 # not clear if this should be changed, seems like it should
779 default_isolation_level: Optional[IsolationLevel]
780 """the isolation that is implicitly present on new connections"""
781
782 skip_autocommit_rollback: bool
783 """Whether or not the :paramref:`.create_engine.skip_autocommit_rollback`
784 parameter was set.
785
786 .. versionadded:: 2.0.43
787
788 """
789
790 # create_engine() -> isolation_level currently goes here
791 _on_connect_isolation_level: Optional[IsolationLevel]
792
793 execution_ctx_cls: Type[ExecutionContext]
794 """a :class:`.ExecutionContext` class used to handle statement execution"""
795
796 execute_sequence_format: Union[
797 Type[Tuple[Any, ...]], Type[Tuple[List[Any]]]
798 ]
799 """either the 'tuple' or 'list' type, depending on what cursor.execute()
800 accepts for the second argument (they vary)."""
801
802 supports_alter: bool
803 """``True`` if the database supports ``ALTER TABLE`` - used only for
804 generating foreign key constraints in certain circumstances
805 """
806
807 max_identifier_length: int
808 """The maximum length of identifier names."""
809 max_index_name_length: Optional[int]
810 """The maximum length of index names if different from
811 ``max_identifier_length``."""
812 max_constraint_name_length: Optional[int]
813 """The maximum length of constraint names if different from
814 ``max_identifier_length``."""
815
816 supports_server_side_cursors: Union[generic_fn_descriptor[bool], bool]
817 """indicates if the dialect supports server side cursors"""
818
819 server_side_cursors: bool
820 """deprecated; indicates if the dialect should attempt to use server
821 side cursors by default"""
822
823 supports_sane_rowcount: bool
824 """Indicate whether the dialect properly implements rowcount for
825 ``UPDATE`` and ``DELETE`` statements.
826 """
827
828 supports_sane_multi_rowcount: bool
829 """Indicate whether the dialect properly implements rowcount for
830 ``UPDATE`` and ``DELETE`` statements when executed via
831 executemany.
832 """
833
834 supports_empty_insert: bool
835 """dialect supports INSERT () VALUES (), i.e. a plain INSERT with no
836 columns in it.
837
838 This is not usually supported; an "empty" insert is typically
839 suited using either "INSERT..DEFAULT VALUES" or
840 "INSERT ... (col) VALUES (DEFAULT)".
841
842 """
843
844 supports_default_values: bool
845 """dialect supports INSERT... DEFAULT VALUES syntax"""
846
847 supports_default_metavalue: bool
848 """dialect supports INSERT...(col) VALUES (DEFAULT) syntax.
849
850 Most databases support this in some way, e.g. SQLite supports it using
851 ``VALUES (NULL)``. MS SQL Server supports the syntax also however
852 is the only included dialect where we have this disabled, as
853 MSSQL does not support the field for the IDENTITY column, which is
854 usually where we like to make use of the feature.
855
856 """
857
858 default_metavalue_token: str = "DEFAULT"
859 """for INSERT... VALUES (DEFAULT) syntax, the token to put in the
860 parenthesis.
861
862 E.g. for SQLite this is the keyword "NULL".
863
864 """
865
866 supports_multivalues_insert: bool
867 """Target database supports INSERT...VALUES with multiple value
868 sets, i.e. INSERT INTO table (cols) VALUES (...), (...), (...), ...
869
870 """
871
872 insert_executemany_returning: bool
873 """dialect / driver / database supports some means of providing
874 INSERT...RETURNING support when dialect.do_executemany() is used.
875
876 """
877
878 insert_executemany_returning_sort_by_parameter_order: bool
879 """dialect / driver / database supports some means of providing
880 INSERT...RETURNING support when dialect.do_executemany() is used
881 along with the :paramref:`_dml.Insert.returning.sort_by_parameter_order`
882 parameter being set.
883
884 """
885
886 update_executemany_returning: bool
887 """dialect supports UPDATE..RETURNING with executemany."""
888
889 delete_executemany_returning: bool
890 """dialect supports DELETE..RETURNING with executemany."""
891
892 use_insertmanyvalues: bool
893 """if True, indicates "insertmanyvalues" functionality should be used
894 to allow for ``insert_executemany_returning`` behavior, if possible.
895
896 In practice, setting this to True means:
897
898 if ``supports_multivalues_insert``, ``insert_returning`` and
899 ``use_insertmanyvalues`` are all True, the SQL compiler will produce
900 an INSERT that will be interpreted by the :class:`.DefaultDialect`
901 as an :attr:`.ExecuteStyle.INSERTMANYVALUES` execution that allows
902 for INSERT of many rows with RETURNING by rewriting a single-row
903 INSERT statement to have multiple VALUES clauses, also executing
904 the statement multiple times for a series of batches when large numbers
905 of rows are given.
906
907 The parameter is False for the default dialect, and is set to True for
908 SQLAlchemy internal dialects SQLite, MySQL/MariaDB, PostgreSQL, SQL Server.
909 It remains at False for Oracle Database, which provides native "executemany
910 with RETURNING" support and also does not support
911 ``supports_multivalues_insert``. For MySQL/MariaDB, those MySQL dialects
912 that don't support RETURNING will not report
913 ``insert_executemany_returning`` as True.
914
915 .. versionadded:: 2.0
916
917 .. seealso::
918
919 :ref:`engine_insertmanyvalues`
920
921 """
922
923 use_insertmanyvalues_wo_returning: bool
924 """if True, and use_insertmanyvalues is also True, INSERT statements
925 that don't include RETURNING will also use "insertmanyvalues".
926
927 .. versionadded:: 2.0
928
929 .. seealso::
930
931 :ref:`engine_insertmanyvalues`
932
933 """
934
935 insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts
936 """Options indicating the database supports a form of bulk INSERT where
937 the autoincrement integer primary key can be reliably used as an ordering
938 for INSERTed rows.
939
940 .. versionadded:: 2.0.10
941
942 .. seealso::
943
944 :ref:`engine_insertmanyvalues_returning_order`
945
946 """
947
948 insertmanyvalues_page_size: int
949 """Number of rows to render into an individual INSERT..VALUES() statement
950 for :attr:`.ExecuteStyle.INSERTMANYVALUES` executions.
951
952 The default dialect defaults this to 1000.
953
954 .. versionadded:: 2.0
955
956 .. seealso::
957
958 :paramref:`_engine.Connection.execution_options.insertmanyvalues_page_size` -
959 execution option available on :class:`_engine.Connection`, statements
960
961 """ # noqa: E501
962
963 insertmanyvalues_max_parameters: int
964 """Alternate to insertmanyvalues_page_size, will additionally limit
965 page size based on number of parameters total in the statement.
966
967
968 """
969
970 preexecute_autoincrement_sequences: bool
971 """True if 'implicit' primary key functions must be executed separately
972 in order to get their value, if RETURNING is not used.
973
974 This is currently oriented towards PostgreSQL when the
975 ``implicit_returning=False`` parameter is used on a :class:`.Table`
976 object.
977
978 """
979
980 insert_returning: bool
981 """if the dialect supports RETURNING with INSERT
982
983 .. versionadded:: 2.0
984
985 """
986
987 update_returning: bool
988 """if the dialect supports RETURNING with UPDATE
989
990 .. versionadded:: 2.0
991
992 """
993
994 update_returning_multifrom: bool
995 """if the dialect supports RETURNING with UPDATE..FROM
996
997 .. versionadded:: 2.0
998
999 """
1000
1001 delete_returning: bool
1002 """if the dialect supports RETURNING with DELETE
1003
1004 .. versionadded:: 2.0
1005
1006 """
1007
1008 delete_returning_multifrom: bool
1009 """if the dialect supports RETURNING with DELETE..FROM
1010
1011 .. versionadded:: 2.0
1012
1013 """
1014
1015 favor_returning_over_lastrowid: bool
1016 """for backends that support both a lastrowid and a RETURNING insert
1017 strategy, favor RETURNING for simple single-int pk inserts.
1018
1019 cursor.lastrowid tends to be more performant on most backends.
1020
1021 """
1022
1023 supports_identity_columns: bool
1024 """target database supports IDENTITY"""
1025
1026 cte_follows_insert: bool
1027 """target database, when given a CTE with an INSERT statement, needs
1028 the CTE to be below the INSERT"""
1029
1030 colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]]
1031 """A dictionary of TypeEngine classes from sqlalchemy.types mapped
1032 to subclasses that are specific to the dialect class. This
1033 dictionary is class-level only and is not accessed from the
1034 dialect instance itself.
1035 """
1036
1037 supports_sequences: bool
1038 """Indicates if the dialect supports CREATE SEQUENCE or similar."""
1039
1040 sequences_optional: bool
1041 """If True, indicates if the :paramref:`_schema.Sequence.optional`
1042 parameter on the :class:`_schema.Sequence` construct
1043 should signal to not generate a CREATE SEQUENCE. Applies only to
1044 dialects that support sequences. Currently used only to allow PostgreSQL
1045 SERIAL to be used on a column that specifies Sequence() for usage on
1046 other backends.
1047 """
1048
1049 default_sequence_base: int
1050 """the default value that will be rendered as the "START WITH" portion of
1051 a CREATE SEQUENCE DDL statement.
1052
1053 """
1054
1055 supports_native_enum: bool
1056 """Indicates if the dialect supports a native ENUM construct.
1057 This will prevent :class:`_types.Enum` from generating a CHECK
1058 constraint when that type is used in "native" mode.
1059 """
1060
1061 supports_native_boolean: bool
1062 """Indicates if the dialect supports a native boolean construct.
1063 This will prevent :class:`_types.Boolean` from generating a CHECK
1064 constraint when that type is used.
1065 """
1066
1067 supports_native_decimal: bool
1068 """indicates if Decimal objects are handled and returned for precision
1069 numeric types, or if floats are returned"""
1070
1071 supports_native_uuid: bool
1072 """indicates if Python UUID() objects are handled natively by the
1073 driver for SQL UUID datatypes.
1074
1075 .. versionadded:: 2.0
1076
1077 """
1078
1079 returns_native_bytes: bool
1080 """indicates if Python bytes() objects are returned natively by the
1081 driver for SQL "binary" datatypes.
1082
1083 .. versionadded:: 2.0.11
1084
1085 """
1086
1087 construct_arguments: Optional[
1088 List[Tuple[Type[Union[SchemaItem, ClauseElement]], Mapping[str, Any]]]
1089 ] = None
1090 """Optional set of argument specifiers for various SQLAlchemy
1091 constructs, typically schema items.
1092
1093 To implement, establish as a series of tuples, as in::
1094
1095 construct_arguments = [
1096 (schema.Index, {"using": False, "where": None, "ops": None}),
1097 ]
1098
1099 If the above construct is established on the PostgreSQL dialect,
1100 the :class:`.Index` construct will now accept the keyword arguments
1101 ``postgresql_using``, ``postgresql_where``, nad ``postgresql_ops``.
1102 Any other argument specified to the constructor of :class:`.Index`
1103 which is prefixed with ``postgresql_`` will raise :class:`.ArgumentError`.
1104
1105 A dialect which does not include a ``construct_arguments`` member will
1106 not participate in the argument validation system. For such a dialect,
1107 any argument name is accepted by all participating constructs, within
1108 the namespace of arguments prefixed with that dialect name. The rationale
1109 here is so that third-party dialects that haven't yet implemented this
1110 feature continue to function in the old way.
1111
1112 .. seealso::
1113
1114 :class:`.DialectKWArgs` - implementing base class which consumes
1115 :attr:`.DefaultDialect.construct_arguments`
1116
1117
1118 """
1119
1120 reflection_options: Sequence[str] = ()
1121 """Sequence of string names indicating keyword arguments that can be
1122 established on a :class:`.Table` object which will be passed as
1123 "reflection options" when using :paramref:`.Table.autoload_with`.
1124
1125 Current example is "oracle_resolve_synonyms" in the Oracle Database
1126 dialects.
1127
1128 """
1129
1130 dbapi_exception_translation_map: Mapping[str, str] = util.EMPTY_DICT
1131 """A dictionary of names that will contain as values the names of
1132 pep-249 exceptions ("IntegrityError", "OperationalError", etc)
1133 keyed to alternate class names, to support the case where a
1134 DBAPI has exception classes that aren't named as they are
1135 referred to (e.g. IntegrityError = MyException). In the vast
1136 majority of cases this dictionary is empty.
1137 """
1138
1139 supports_comments: bool
1140 """Indicates the dialect supports comment DDL on tables and columns."""
1141
1142 inline_comments: bool
1143 """Indicates the dialect supports comment DDL that's inline with the
1144 definition of a Table or Column. If False, this implies that ALTER must
1145 be used to set table and column comments."""
1146
1147 supports_constraint_comments: bool
1148 """Indicates if the dialect supports comment DDL on constraints.
1149
1150 .. versionadded:: 2.0
1151 """
1152
1153 _has_events = False
1154
1155 supports_statement_cache: bool = True
1156 """indicates if this dialect supports caching.
1157
1158 All dialects that are compatible with statement caching should set this
1159 flag to True directly on each dialect class and subclass that supports
1160 it. SQLAlchemy tests that this flag is locally present on each dialect
1161 subclass before it will use statement caching. This is to provide
1162 safety for legacy or new dialects that are not yet fully tested to be
1163 compliant with SQL statement caching.
1164
1165 .. versionadded:: 1.4.5
1166
1167 .. seealso::
1168
1169 :ref:`engine_thirdparty_caching`
1170
1171 """
1172
1173 _supports_statement_cache: bool
1174 """internal evaluation for supports_statement_cache"""
1175
1176 bind_typing = BindTyping.NONE
1177 """define a means of passing typing information to the database and/or
1178 driver for bound parameters.
1179
1180 See :class:`.BindTyping` for values.
1181
1182 .. versionadded:: 2.0
1183
1184 """
1185
1186 is_async: bool
1187 """Whether or not this dialect is intended for asyncio use."""
1188
1189 has_terminate: bool
1190 """Whether or not this dialect has a separate "terminate" implementation
1191 that does not block or require awaiting."""
1192
1193 engine_config_types: Mapping[str, Any]
1194 """a mapping of string keys that can be in an engine config linked to
1195 type conversion functions.
1196
1197 """
1198
1199 label_length: Optional[int]
1200 """optional user-defined max length for SQL labels"""