SqlAlchemy 2.0 中文文档（四十七）

原文：docs.sqlalchemy.org/en/20/contents.html

核心 API 基础

原文：docs.sqlalchemy.org/en/20/core/api_basics.html

• 事件
  • 事件注册
  • 命名参数风格
  • 目标
  • 修饰符
  • 事件和多进程
  • 事件参考
  • API 参考
• 运行时检查 API
  • inspect()
  • 可用的检查目标
• 核心异常
  • AmbiguousForeignKeysError
  • ArgumentError
  • AwaitRequired
  • Base20DeprecationWarning
  • CircularDependencyError
  • CompileError
  • ConstraintColumnNotFoundError
  • DBAPIError
  • DataError
  • DatabaseError
  • DisconnectionError
  • DontWrapMixin
  • DuplicateColumnError
  • HasDescriptionCode
  • IdentifierError
  • IllegalStateChangeError
  • IntegrityError
  • InterfaceError
  • InternalError
  • InvalidRequestError
  • InvalidatePoolError
  • LegacyAPIWarning
  • MissingGreenlet
  • MovedIn20Warning
  • MultipleResultsFound
  • NoForeignKeysError
  • NoInspectionAvailable
  • NoReferenceError
  • NoReferencedColumnError
  • NoReferencedTableError
  • NoResultFound
  • NoSuchColumnError
  • NoSuchModuleError
  • NoSuchTableError
  • NotSupportedError
  • ObjectNotExecutableError
  • OperationalError
  • PendingRollbackError
  • ProgrammingError
  • ResourceClosedError
  • SADeprecationWarning
  • SAPendingDeprecationWarning
  • SATestSuiteWarning
  • SAWarning
  • SQLAlchemyError
  • StatementError
  • TimeoutError
  • UnboundExecutionError
  • UnreflectableTableError
  • UnsupportedCompilationError
• 核心内部
  • BindTyping
  • Compiled
  • DBAPIConnection
  • DBAPICursor
  • DBAPIType
  • DDLCompiler
  • DefaultDialect
  • Dialect
  • DefaultExecutionContext
  • ExecutionContext
  • ExpandedState
  • GenericTypeCompiler
  • Identified
  • IdentifierPreparer
  • SQLCompiler
  • StrSQLCompiler
  • AdaptedConnection

事件

原文：docs.sqlalchemy.org/en/20/core/event.html

SQLAlchemy 包括一个事件 API，它发布了一系列钩子，可以进入 SQLAlchemy 核心和 ORM 的内部。

事件注册

订阅事件通过单个 API 点完成，即listen() 函数，或者可以使用listens_for() 装饰器。这些函数接受一个目标，一个字符串标识符，用于标识要拦截的事件，以及一个用户定义的监听函数。这两个函数的额外位置参数和关键字参数可能会被特定类型的事件支持，这些事件可能会指定给定事件函数的备用接口，或者根据给定目标提供有关次要事件目标的指令。

事件的名称和相应监听函数的参数签名是从绑定到文档中描述的标记类的绑定规范方法派生的。例如，对于PoolEvents.connect() 的文档表明，事件名称为"connect"，并且用户定义的监听函数应接收两个位置参数：

from sqlalchemy.event import listen
from sqlalchemy.pool import Pool

def my_on_connect(dbapi_con, connection_record):
    print("New DBAPI connection:", dbapi_con)

listen(Pool, "connect", my_on_connect)

使用 listens_for() 装饰器进行监听如下所示：

from sqlalchemy.event import listens_for
from sqlalchemy.pool import Pool

@listens_for(Pool, "connect")
def my_on_connect(dbapi_con, connection_record):
    print("New DBAPI connection:", dbapi_con)

命名参数样式

监听函数可以接受一些参数样式的变化。以PoolEvents.connect() 为例，此函数被记录为接收dbapi_connection 和 connection_record 参数。我们可以选择通过名称接收这些参数，通过建立一个接受 **keyword 参数的监听函数，或通过向 listen() 或 listens_for() 传递 named=True 来实现：

from sqlalchemy.event import listens_for
from sqlalchemy.pool import Pool

@listens_for(Pool, "connect", named=True)
def my_on_connect(**kw):
    print("New DBAPI connection:", kw["dbapi_connection"])

使用命名参数传递时，函数参数规范中列出的名称将用作字典中的键。

命名样式通过名称传递所有参数，而不考虑函数签名，因此特定参数也可以以任何顺序列出，只要名称匹配即可：

from sqlalchemy.event import listens_for
from sqlalchemy.pool import Pool

@listens_for(Pool, "connect", named=True)
def my_on_connect(dbapi_connection, **kw):
    print("New DBAPI connection:", dbapi_connection)
    print("Connection record:", kw["connection_record"])

上面，存在 **kw 告诉 listens_for() 参数应该通过名称而不是位置传递给函数。

目标

listen() 函数在目标方面非常灵活。它通常接受类、这些类的实例以及相关类或对象，可以从中派生适当的目标。例如，上述提到的 "connect" 事件接受 Engine 类和对象，以及 Pool 类和对象：

from sqlalchemy.event import listen
from sqlalchemy.pool import Pool, QueuePool
from sqlalchemy import create_engine
from sqlalchemy.engine import Engine
import psycopg2

def connect():
    return psycopg2.connect(user="ed", host="127.0.0.1", dbname="test")

my_pool = QueuePool(connect)
my_engine = create_engine("postgresql+psycopg2://ed@localhost/test")

# associate listener with all instances of Pool
listen(Pool, "connect", my_on_connect)

# associate listener with all instances of Pool
# via the Engine class
listen(Engine, "connect", my_on_connect)

# associate listener with my_pool
listen(my_pool, "connect", my_on_connect)

# associate listener with my_engine.pool
listen(my_engine, "connect", my_on_connect)

修饰符

一些监听器允许传递修饰符给 listen()。这些修饰符有时会为监听器提供替代的调用签名。例如，在 ORM 事件中，一些事件监听器可以具有修改后续处理的返回值。默认情况下，没有监听器需要返回值，但通过传递 retval=True 可以支持此值：

def validate_phone(target, value, oldvalue, initiator):
  """Strip non-numeric characters from a phone number"""

    return re.sub(r"\D", "", value)

# setup listener on UserContact.phone attribute, instructing
# it to use the return value
listen(UserContact.phone, "set", validate_phone, retval=True)

事件和多进程

SQLAlchemy 的事件钩子是用 Python 函数和对象实现的，因此事件通过 Python 函数调用进行传播。Python 的多进程遵循我们对操作系统多进程的思考方式，例如父进程派生子进程，因此我们可以使用相同的模型描述 SQLAlchemy 事件系统的行为。

在父进程中注册的事件钩子将存在于从注册这些钩子后派生的新子进程中，因为在生成子进程时，子进程会以父进程的所有现有 Python 结构的副本开始。在注册钩子之前已存在的子进程将不会接收到这些新的事件钩子，因为父进程中对 Python 结构的更改不会传播到子进程。

对于事件本身，这些都是 Python 函数调用，没有任何能力在进程之间传播。SQLAlchemy 的事件系统不实现任何进程间通信。可以实现使用 Python 进程间消息传递的事件钩子，但这需要用户自己实现。

事件参考

SQLAlchemy Core 和 SQLAlchemy ORM 都提供了各种各样的事件钩子：

• 核心事件 - 这些事件在 核心事件 中描述，包括特定于连接池生命周期、SQL 语句执行、事务生命周期和模式创建和拆除的事件钩子。
• ORM 事件 - 这些事件在 ORM 事件 中描述，包括特定于类和属性检测、对象初始化钩子、属性更改钩子、会话状态、刷新和提交钩子、映射器初始化、对象/结果填充和每个实例持久性钩子的事件钩子。

API 参考

function sqlalchemy.event.listen(target: Any, identifier: str, fn: Callable[[...], Any], *args: Any, **kw: Any) → None

为给定目标注册监听器函数。

listen() 函数是 SQLAlchemy 事件系统的主要接口之一，在 Events 中有文档说明。

例如：

from sqlalchemy import event
from sqlalchemy.schema import UniqueConstraint

def unique_constraint_name(const, table):
    const.name = "uq_%s_%s" % (
        table.name,
        list(const.columns)[0].name
    )
event.listen(
        UniqueConstraint,
        "after_parent_attach",
        unique_constraint_name)

参数：

• insert（bool） - 事件处理程序的默认行为是在发现时将装饰的用户定义函数附加到注册的事件监听器的内部列表中。如果用户使用 insert=True 注册函数，则 SQLAlchemy 将在发现时将函数插入（前置）到内部列表中。此功能通常不由 SQLAlchemy 维护者使用或推荐使用，但提供此功能是为了确保某些用户定义的函数可以在其他函数之前运行，例如在 修改 MySQL 中的 sql_mode 时。
• named（bool） - 使用命名参数传递时，函数参数规范中列出的名称将用作字典中的键。参见 命名参数风格。
• once（bool） - 私有/内部 API 使用。已弃用。该参数将确保事件函数仅在给定目标上运行一次。但这并不意味着自动取消注册监听器函数；如果不显式地移除监听器函数，即使指定了 once=True，也会导致内存无限增长。
• propagate（bool） - 在使用 ORM 仪表化和映射事件时可用 propagate kwarg。参见 MapperEvents 和 MapperEvents.before_mapper_configured() 以获取示例。
• retval（bool） - 此标志仅适用于特定的事件监听器，每个监听器都包含解释何时应使用它的文档。默认情况下，没有监听器需要返回值。但是，一些监听器支持返回值的特殊行为，并在其文档中包含 retval=True 标志是必要的信息。 利用 listen.retval 的事件监听器套件包括 ConnectionEvents 和 AttributeEvents。

注意

listen() 函数不能在目标事件正在运行时调用。这对线程安全性有影响，并且意味着无法从监听器函数内部添加事件本身。在可变集合中存在要运行的事件列表，在迭代过程中不能更改。

事件注册和移除不打算是“高速”操作；这是一个配置操作。对于需要在高比例上快速关联和取消关联事件的系统，请使用从单个监听器内部处理的可变结构。

另见

listens_for()

remove()

function sqlalchemy.event.listens_for(target: Any, identifier: str, *args: Any, **kw: Any) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

将函数装饰为给定目标 + 标识符的监听器。

listens_for() 装饰器是 SQLAlchemy 事件系统的主要接口的一部分，文档位于 Events。

此函数通常与 listens() 共享相同的 kwargs。

例如：

from sqlalchemy import event
from sqlalchemy.schema import UniqueConstraint

@event.listens_for(UniqueConstraint, "after_parent_attach")
def unique_constraint_name(const, table):
    const.name = "uq_%s_%s" % (
        table.name,
        list(const.columns)[0].name
    )

通过使用 once 参数，也可以仅调用给定函数的事件的第一次调用：

@event.listens_for(Mapper, "before_configure", once=True)
def on_config():
    do_config()

警告

once 参数并不意味着在第一次调用后自动注销监听器函数；监听器条目将保留与目标对象的关联。即使指定了 once=True，如果不明确删除，关联任意数量的监听器将导致内存无限增长。

另见

listen() - 事件监听的概述

function sqlalchemy.event.remove(target: Any, identifier: str, fn: Callable[[...], Any]) → None

移除事件监听器。

此处的参数应与发送到 listen() 的参数完全匹配；通过使用相同的参数调用 remove() 将撤消由此调用导致的所有事件注册。

例如：

# if a function was registered like this...
@event.listens_for(SomeMappedClass, "before_insert", propagate=True)
def my_listener_function(*arg):
    pass

# ... it's removed like this
event.remove(SomeMappedClass, "before_insert", my_listener_function)

在上面的示例中，与 SomeMappedClass 关联的监听器函数也被传播到 SomeMappedClass 的子类；remove() 函数将撤消所有这些操作。

注意

remove() 函数不能在目标事件正在运行时调用。这对线程安全性有影响，并且意味着无法从监听器函数内部删除事件本身。在可变集合中存在要运行的事件列表，在迭代过程中不能更改。

事件注册和移除不打算是“高速”操作；这是一个配置操作。对于需要在高比例上快速关联和取消关联事件的系统，请使用从单个监听器内部处理的可变结构。

另见

listen()

function sqlalchemy.event.contains(target: Any, identifier: str, fn: Callable[[...], Any]) → bool

如果给定的目标/标识/函数设置为监听，则返回 True。

事件注册

通过单个 API 点进行事件订阅，即listen()函数，或者选择使用listens_for()装饰器。这些函数接受一个目标，一个字符串标识符，用于识别要拦截的事件，并且接受一个用户定义的监听函数。这两个函数的其他位置参数和关键字参数可能会被特定类型的事件支持，这些事件可能会指定给定事件函数的替代接口，或者根据给定目标提供关于次要事件目标的说明。

事件的名称和相应监听函数的参数签名是从绑定到在文档中描述的标记类的类绑定规范方法派生的。例如，PoolEvents.connect() 的文档指示事件名称是"connect"，并且用户定义的监听函数应该接收两个位置参数：

from sqlalchemy.event import listen
from sqlalchemy.pool import Pool

def my_on_connect(dbapi_con, connection_record):
    print("New DBAPI connection:", dbapi_con)

listen(Pool, "connect", my_on_connect)

使用listens_for()装饰器进行监听如下所示：

from sqlalchemy.event import listens_for
from sqlalchemy.pool import Pool

@listens_for(Pool, "connect")
def my_on_connect(dbapi_con, connection_record):
    print("New DBAPI connection:", dbapi_con)

命名参数风格

有一些论证风格的变体可以被监听函数接受。以PoolEvents.connect()为例，该函数被记录为接收dbapi_connection和connection_record参数。我们可以选择通过名称接收这些参数，通过建立一个接受**keyword参数的监听函数，或者通过将named=True传递给listen()或listens_for()来接收：

from sqlalchemy.event import listens_for
from sqlalchemy.pool import Pool

@listens_for(Pool, "connect", named=True)
def my_on_connect(**kw):
    print("New DBAPI connection:", kw["dbapi_connection"])

使用命名参数传递时，函数参数规范中列出的名称将用作字典中的键。

Named 风格通过名称传递所有参数，而不管函数签名如何，因此特定参数也可以列出，以任何顺序，只要名称匹配即可：

from sqlalchemy.event import listens_for
from sqlalchemy.pool import Pool

@listens_for(Pool, "connect", named=True)
def my_on_connect(dbapi_connection, **kw):
    print("New DBAPI connection:", dbapi_connection)
    print("Connection record:", kw["connection_record"])

上述代码中的 **kw 告诉listens_for()应该按名称而不是按位置传递参数给函数。

目标

listen() 函数在目标方面非常灵活。它通常接受类、这些类的实例以及相关类或对象，从中可以派生出适当的目标。例如，上述提到的 "connect" 事件也接受 Engine 类和对象，以及 Pool 类和对象：

from sqlalchemy.event import listen
from sqlalchemy.pool import Pool, QueuePool
from sqlalchemy import create_engine
from sqlalchemy.engine import Engine
import psycopg2

def connect():
    return psycopg2.connect(user="ed", host="127.0.0.1", dbname="test")

my_pool = QueuePool(connect)
my_engine = create_engine("postgresql+psycopg2://ed@localhost/test")

# associate listener with all instances of Pool
listen(Pool, "connect", my_on_connect)

# associate listener with all instances of Pool
# via the Engine class
listen(Engine, "connect", my_on_connect)

# associate listener with my_pool
listen(my_pool, "connect", my_on_connect)

# associate listener with my_engine.pool
listen(my_engine, "connect", my_on_connect)

修饰符

一些监听器允许传递修饰符给 listen()。这些修饰符有时会为监听器提供替代的调用签名。例如，对于 ORM 事件，一些事件监听器可以有一个返回值，该返回值修改了后续的处理方式。默认情况下，没有任何监听器需要返回值，但是通过传递 retval=True，可以支持该值：

def validate_phone(target, value, oldvalue, initiator):
  """Strip non-numeric characters from a phone number"""

    return re.sub(r"\D", "", value)

# setup listener on UserContact.phone attribute, instructing
# it to use the return value
listen(UserContact.phone, "set", validate_phone, retval=True)

事件和多处理

SQLAlchemy 的事件钩子是通过 Python 函数和对象实现的，因此事件通过 Python 函数调用传播。Python 多进程遵循与我们所思考的操作系统多进程相同的方式，例如父进程分叉出子进程，因此我们可以使用相同的模型描述 SQLAlchemy 事件系统的行为。

在父进程中注册的事件钩子将存在于从该父进程分叉出的新子进程中，因为子进程在生成时从父进程开始时具有所有现有 Python 结构的副本。在注册钩子之前存在的子进程将不会接收到这些新的事件钩子，因为在父进程中对 Python 结构所做的更改不会传播到子进程。

对于事件本身，这些是 Python 函数调用，它们没有任何传播到进程之间的能力。SQLAlchemy 的事件系统不实现任何进程间通信。可能会实现在其中使用 Python 进程间消息传递的事件钩子，但这需要用户实现。

事件参考

SQLAlchemy 核心和 SQLAlchemy ORM 都具有各种各样的事件钩子：

• 核心事件 - 这些在 核心事件 中描述，包括特定于连接池生命周期、SQL 语句执行、事务生命周期和架构创建和拆除的事件钩子。
• ORM 事件 - 这些在 ORM 事件 中描述，包括特定于类和属性检测、对象初始化钩子、属性变更钩子、会话状态、刷新和提交钩子、映射器初始化、对象/结果填充和每个实例持久性钩子的事件钩子。

API 参考

function sqlalchemy.event.listen(target: Any, identifier: str, fn: Callable[[...], Any], *args: Any, **kw: Any) → None

为给定的目标注册一个侦听器函数。

listen()函数是 SQLAlchemy 事件系统的主要接口之一，在事件中有文档说明。

例如：

from sqlalchemy import event
from sqlalchemy.schema import UniqueConstraint

def unique_constraint_name(const, table):
    const.name = "uq_%s_%s" % (
        table.name,
        list(const.columns)[0].name
    )
event.listen(
        UniqueConstraint,
        "after_parent_attach",
        unique_constraint_name)

参数：

• insert (bool) – 事件处理程序的默认行为是在发现时将装饰的用户定义函数追加到已注册的事件侦听器的内部列表中。如果用户使用 insert=True 注册一个函数，SQLAlchemy 将在发现时将函数插入（预置）到内部列表中。这个功能通常不被 SQLAlchemy 维护者使用或推荐，但为了确保某些用户定义的函数可以在其他函数之前运行，比如更改 MySQL 中的 sql_mode 时，提供了此功能。
• named (bool) – 在使用命名参数传递时，函数参数规范中列出的名称将用作字典中的键。请参阅命名参数风格。
• once (bool) – 私有/内部 API 使用。已弃用。此参数将提供事件函数仅在给定目标上运行一次。但是，这并不意味着侦听器函数会自动取消注册；如果未显式删除关联的任意数量的侦听器，则即使指定了 once=True，内存也会无限增长。
• propagate (bool) – 在使用 ORM 仪器和映射事件时，propagate 关键字参数是可用的。参见MapperEvents和MapperEvents.before_mapper_configured()进行示例。
• retval (bool) – 此标志仅适用于特定的事件侦听器，每个事件侦听器都包含说明何时应该使用它的文档。默认情况下，没有侦听器需要返回值。但是，一些侦听器确实支持返回值的特殊行为，并在其文档中包含了必须使用 retval=True 标志才能处理返回值的说明。 利用listen.retval的事件侦听器套件包括ConnectionEvents和AttributeEvents。

注意

listen() 函数不能在目标事件正在运行时调用。这对线程安全性有影响，并且还意味着无法从监听器函数内部为自身添加事件。要运行的事件列表存在于一个可变集合内，在迭代期间不能更改。

事件注册和移除并不意味着是“高速”操作；它是一种配置操作。对于需要在高比例下快速关联和取消关联事件的系统，请使用可变结构，并且从单个监听器内部处理。

另请参阅

listens_for()

remove()

function sqlalchemy.event.listens_for(target: Any, identifier: str, *args: Any, **kw: Any) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

将函数装饰为给定目标 + 标识符的监听器。

listens_for() 装饰器是 SQLAlchemy 事件系统的主要接口之一，在事件文档中有说明。

此函数通常具有与 listens() 相同的 kwargs。

例如：

from sqlalchemy import event
from sqlalchemy.schema import UniqueConstraint

@event.listens_for(UniqueConstraint, "after_parent_attach")
def unique_constraint_name(const, table):
    const.name = "uq_%s_%s" % (
        table.name,
        list(const.columns)[0].name
    )

使用 once 参数，给定函数还可以仅在事件的第一次调用时被调用：

@event.listens_for(Mapper, "before_configure", once=True)
def on_config():
    do_config()

警告

once 参数不意味着在第一次调用后自动取消注册监听器函数；监听器条目将保持与目标对象的关联。如果不显式移除，关联任意数量的监听器将导致内存无限增长，即使指定了 once=True。

另请参阅

listen() - 事件监听的一般描述

function sqlalchemy.event.remove(target: Any, identifier: str, fn: Callable[[...], Any]) → None

移除事件监听器。

此处的参数应与发送到 listen() 的参数完全匹配；通过使用相同的参数调用 remove() 将撤消此调用结果的所有事件注册。

例如：

# if a function was registered like this...
@event.listens_for(SomeMappedClass, "before_insert", propagate=True)
def my_listener_function(*arg):
    pass

# ... it's removed like this
event.remove(SomeMappedClass, "before_insert", my_listener_function)

上述中，与 SomeMappedClass 关联的监听器函数也传播到了 SomeMappedClass 的子类；remove() 函数将撤销所有这些操作。

注意

remove() 函数不能在目标事件正在运行时调用。这对线程安全性有影响，并且还意味着无法从监听器函数内部移除事件本身。要运行的事件列表存在于一个可变集合内，在迭代期间不能更改。

事件注册和移除并不意味着是“高速”操作；它是一种配置操作。对于需要在高比例下快速关联和取消关联事件的系统，请使用可变结构，并且从单个监听器内部处理。

另请参阅

listen()

function sqlalchemy.event.contains(target: Any, identifier: str, fn: Callable[[...], Any]) → bool

如果给定的目标/标识符/函数已设置为监听，则返回 True。

运行时检查 API

原文：docs.sqlalchemy.org/en/20/core/inspection.html

检查模块提供了inspect()函数，该函数提供了关于 SQLAlchemy 对象的运行时信息，包括核心部分和 ORM 部分。

inspect()函数是访问 SQLAlchemy 公共 API 以查看内存对象配置和构建的入口点。根据传递给inspect()的对象类型，返回值将是提供已知接口的相关对象，或者在许多情况下将返回对象本身。

inspect()的理由是双重的。一是它取代了需要了解 SQLAlchemy 中大量“获取信息”的函数的需求，例如Inspector.from_engine()（在 1.4 中已弃用）、instance_state()、class_mapper()等。另一个是inspect()的返回值保证遵守文档化的 API，从而允许基于 SQLAlchemy 配置构建的第三方工具以向前兼容的方式构建。

function sqlalchemy.inspect(subject: Any, raiseerr: bool = True) → Any

为给定目标生成一个检查对象。

在某些情况下，返回的值可能与给定的对象相同，例如如果传递了一个Mapper对象。在其他情况下，它将是给定对象的注册检查类型的实例，例如如果传递了一个Engine，则返回一个Inspector对象。

参数：

• subject – 要检查的主题。
• raiseerr – 当为True时，如果给定主题不对应于已知的 SQLAlchemy 检查类型，则引发sqlalchemy.exc.NoInspectionAvailable。如果为False，则返回None。

可检查的目标

下面是许多常见检查目标的列表。

• Connectable（即 Engine、Connection） - 返回一个 Inspector 对象。
• ClauseElement - 所有 SQL 表达式组件，包括 Table、Column，都作为自己的检查对象，这意味着传递给 inspect() 的这些对象返回它们自身。
• object - 给定一个对象，ORM 将检查其映射 - 如果是这样，将返回一个表示对象的映射状态的 InstanceState。InstanceState 还通过 AttributeState 接口提供对每个属性状态的访问，以及通过 History 对象提供对任何属性的每次 flush 的“历史”访问。 请参见 映射实例的检查
• type（即类） - 由 ORM 给定的类将被检查映射 - 如果是这样，将返回该类的 Mapper。 请参见 Mapper 对象的检查
• 映射属性 - 将映射属性传递给 inspect()，例如 inspect(MyClass.some_attribute)，将返回一个 QueryableAttribute 对象，它是与映射类关联的 描述符。该描述符指的是一个 MapperProperty，通常是 ColumnProperty 或 RelationshipProperty 的实例，通过其 QueryableAttribute.property 属性。
• AliasedClass - 返回一个 AliasedInsp 对象。

可用的检查目标

以下是许多常见检查目标的列表。

• Connectable（即Engine，Connection） - 返回一个Inspector对象。
• ClauseElement - 所有 SQL 表达式组件，包括Table，Column，都作为自己的检查对象，这意味着任何这些对象传递给inspect()都会返回它们自己。
• object - 给定的对象将由 ORM 检查映射 - 如果是这样，将返回一个表示对象映射状态的InstanceState。InstanceState还通过AttributeState接口提供对每个属性状态的访问，以及通过History对象提供对任何属性的每次刷新“历史”的访问。 另请参见 映射实例的检查
• type（即一个类） - 将给定的类检查 ORM 是否有映射 - 如果有，将返回该类的Mapper。 另请参见 Mapper 对象的检查
• 传递映射属性 - 将映射属性传递给inspect()，例如inspect(MyClass.some_attribute)，将返回一个QueryableAttribute对象，该对象是与映射类相关联的描述符。此描述符指向一个MapperProperty，通常是ColumnProperty或RelationshipProperty的实例，通过其QueryableAttribute.property属性。
• AliasedClass - 返回一个 AliasedInsp 对象。

核心异常

原文：docs.sqlalchemy.org/en/20/core/exceptions.html

与 SQLAlchemy 一起使用的异常。

基础异常类是 SQLAlchemyError。作为 DBAPI 异常的结果引发的异常都是 DBAPIError 的子类。

exception sqlalchemy.exc.AmbiguousForeignKeysError

当在联接过程中无法定位两个可选择项之间的多个匹配外键时引发。

类签名

类 sqlalchemy.exc.AmbiguousForeignKeysError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.ArgumentError

当提供了无效或冲突的函数参数时引发。

此错误通常对应于构建时状态错误。

类签名

类 sqlalchemy.exc.ArgumentError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.AwaitRequired

如果在需要异步操作但没有等待时调用了异步 greenlet spawn，则会引发错误。

类签名

类 sqlalchemy.exc.AwaitRequired (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.Base20DeprecationWarning

用于特定于 SQLAlchemy 2.0 中已弃用或传统的 API 的使用。

另请参阅

在 SQLAlchemy 2.0 中 将不再 。

SQLAlchemy 2.0 弃用模式

类签名

类 sqlalchemy.exc.Base20DeprecationWarning (sqlalchemy.exc.SADeprecationWarning)

attribute deprecated_since: str | None = '1.4'

表明开始引发此废弃警告的版本

exception sqlalchemy.exc.CircularDependencyError

当检测到循环依赖时，通过拓扑排序解决。

出现此错误的两种情况如下：

• 在会话刷新操作中，如果两个对象相互依赖，它们不能仅通过 INSERT 或 DELETE 语句进行插入或删除；需要使用 UPDATE 来后关联或先取消关联其中一个外键约束值。在 指向自身的行 / 相互依赖的行 中描述的 post_update 标志可以解决这种循环。
• 在 MetaData.sorted_tables 操作中，两个 ForeignKey 或 ForeignKeyConstraint 对象相互引用。对其中一个或两个应用 use_alter=True 标志，参见 通过 ALTER 创建/删除外键约束。

类签名

类 sqlalchemy.exc.CircularDependencyError (sqlalchemy.exc.SQLAlchemyError)

method __init__(message: str, cycles: Any, edges: Any, msg: str | None = None, code: str | None = None)

exception sqlalchemy.exc.CompileError

在 SQL 编译期间发生错误时引发

类签名

类 sqlalchemy.exc.CompileError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.ConstraintColumnNotFoundError

当约束引用不存在于被约束表中的字符串列名称时引发。

在版本 2.0 中新增。

类签名

类 sqlalchemy.exc.ConstraintColumnNotFoundError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.DBAPIError

当数据库操作执行失败时引发。

封装由 DB-API 底层数据库操作引发的异常。可能的情况下，SQLAlchemy 的 DBAPIError 匹配 DB-API 标准异常类型的特定驱动程序实现被封装为相应的子类型。DB-API 的 Error 类型映射到 SQLAlchemy 中的 DBAPIError，否则名称相同。请注意，不能保证不同的 DB-API 实现将为任何给定的错误条件引发相同的异常类型。

DBAPIError 包含 StatementError.statement 和 StatementError.params 属性，提供有关出现问题的语句的上下文信息，典型情况下，错误是在发出 SQL 语句的上下文中引发的。

封装的异常对象在 StatementError.orig 属性中可用。其类型和属性是特定于 DB-API 实现的。

类签名

类 sqlalchemy.exc.DBAPIError (sqlalchemy.exc.StatementError)

method __init__(statement: str | None, params: _AnyExecuteParams | None, orig: BaseException, hide_parameters: bool = False, connection_invalidated: bool = False, code: str | None = None, ismulti: bool | None = None)

exception sqlalchemy.exc.DataError

包装一个 DB-API DataError。

类签名

类 sqlalchemy.exc.DataError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.DatabaseError

包装一个 DB-API DatabaseError。

类签名

类 sqlalchemy.exc.DatabaseError (sqlalchemy.exc.DBAPIError)

exception sqlalchemy.exc.DisconnectionError

在原始 DB-API 连接上检测到断开连接。

此错误由连接池内部引发并消耗。它可以由 PoolEvents.checkout() 事件引发，以便主机池强制重试；在池放弃并引发关于连接尝试的 InvalidRequestError 之前，该异常将被连续捕获三次。

类签名

类 sqlalchemy.exc.DisconnectionError (sqlalchemy.exc.SQLAlchemyError)

class sqlalchemy.exc.DontWrapMixin

一个混合类，当应用于用户定义的异常类时，在执行语句过程中发出错误时不会被包装在 StatementError 内。

例如：

from sqlalchemy.exc import DontWrapMixin

class MyCustomException(Exception, DontWrapMixin):
    pass

class MySpecialType(TypeDecorator):
    impl = String

    def process_bind_param(self, value, dialect):
        if value == 'invalid':
            raise MyCustomException("invalid!")

exception sqlalchemy.exc.DuplicateColumnError

正在向表添加列，该列将替换另一列，但没有适当的参数允许此操作。

版本 2.0.0b4 中新增。

类签名

类 sqlalchemy.exc.DuplicateColumnError (sqlalchemy.exc.ArgumentError)

class sqlalchemy.exc.HasDescriptionCode

添加 ‘code’ 作为属性和 ‘_code_str’ 作为方法的助手

exception sqlalchemy.exc.IdentifierError

当模式名称超出最大字符限制时引发

类签名

类 sqlalchemy.exc.IdentifierError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.IllegalStateChangeError

追踪状态的对象遇到了某种类型的非法状态改变。

版本 2.0 中新增。

类签名

类sqlalchemy.exc.IllegalStateChangeError（sqlalchemy.exc.InvalidRequestError）

exception sqlalchemy.exc.IntegrityError

包装了一个 DB-API IntegrityError。

类签名

类sqlalchemy.exc.IntegrityError（sqlalchemy.exc.DatabaseError）

exception sqlalchemy.exc.InterfaceError

包装了一个 DB-API InterfaceError。

类签名

类sqlalchemy.exc.InterfaceError（sqlalchemy.exc.DBAPIError）

exception sqlalchemy.exc.InternalError

包装了一个 DB-API InternalError。

类签名

类sqlalchemy.exc.InternalError（sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.InvalidRequestError

SQLAlchemy 被要求执行一些它无法执行的操作。

此错误通常对应于运行时状态错误。

类签名

类sqlalchemy.exc.InvalidRequestError（sqlalchemy.exc.SQLAlchemyError）

exception sqlalchemy.exc.InvalidatePoolError

当连接池应该使所有陈旧连接无效时引发。

一个DisconnectionError的子类，表示在连接上遇到的断开情况可能意味着整个池应该无效，因为数据库已重新启动。

此异常将以与DisconnectionError相同的方式处理，允许在放弃之前尝试三次重新连接。

1.2 版本中的新功能。

类签名

类sqlalchemy.exc.InvalidatePoolError（sqlalchemy.exc.DisconnectionError）

exception sqlalchemy.exc.LegacyAPIWarning

表示处于“遗留”状态的 API，长期弃用。

类签名

类sqlalchemy.exc.LegacyAPIWarning（sqlalchemy.exc.Base20DeprecationWarning）

exception sqlalchemy.exc.MissingGreenlet

如果在不在 greenlet spawn 上下文中调用 async greenlet await_ 时引发的错误。

类签名

类sqlalchemy.exc.MissingGreenlet（sqlalchemy.exc.InvalidRequestError）

exception sqlalchemy.exc.MovedIn20Warning

用于指示仅移动的 API 的 RemovedIn20Warning 子类型。

类签名

class sqlalchemy.exc.MovedIn20Warning (sqlalchemy.exc.Base20DeprecationWarning)

exception sqlalchemy.exc.MultipleResultsFound

需要单个数据库结果，但找到多个结果。

从版本 1.4 开始更改：此异常现在是 Core 中sqlalchemy.exc模块的一部分，已从 ORM 中移动。该符号仍然可以从sqlalchemy.orm.exc中导入。

类签名

class sqlalchemy.exc.MultipleResultsFound (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoForeignKeysError

在连接期间无法找到两个可选择对象之间的外键时引发。

类签名

class sqlalchemy.exc.NoForeignKeysError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.NoInspectionAvailable

传递给sqlalchemy.inspection.inspect()的主题未产生检查的上下文。

类签名

class sqlalchemy.exc.NoInspectionAvailable (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoReferenceError

由ForeignKey引发，表示无法解析引用。

类签名

class sqlalchemy.exc.NoReferenceError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoReferencedColumnError

当所引用的Column无法找到时，由ForeignKey引发。

类签名

class sqlalchemy.exc.NoReferencedColumnError (sqlalchemy.exc.NoReferenceError)

method __init__(message: str, tname: str, cname: str)

exception sqlalchemy.exc.NoReferencedTableError

当所引用的Table无法找到时，由ForeignKey引发。

类签名

class sqlalchemy.exc.NoReferencedTableError (sqlalchemy.exc.NoReferenceError)

method __init__(message: str, tname: str)

exception sqlalchemy.exc.NoResultFound

需要数据库结果，但未找到任何结果。

从版本 1.4 开始更改：此异常现在是 Core 中sqlalchemy.exc模块的一部分，已从 ORM 中移动。该符号仍然可以从sqlalchemy.orm.exc中导入。

类签名

class sqlalchemy.exc.NoResultFound (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoSuchColumnError

请求了Row中不存在的列。

类签名

类 sqlalchemy.exc.NoSuchColumnError (sqlalchemy.exc.InvalidRequestError, builtins.KeyError)

exception sqlalchemy.exc.NoSuchModuleError

当找不到特定名称的动态加载模块（通常是数据库方言）时引发。

类签名

类 sqlalchemy.exc.NoSuchModuleError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.NoSuchTableError

表不存在或对连接不可见。

类签名

类 sqlalchemy.exc.NoSuchTableError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NotSupportedError

封装了一个 DB-API NotSupportedError。

类签名

类 sqlalchemy.exc.NotSupportedError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.ObjectNotExecutableError

当传递给 .execute() 的对象无法作为 SQL 执行时引发。

类签名

类 sqlalchemy.exc.ObjectNotExecutableError (sqlalchemy.exc.ArgumentError)

method __init__(target: Any)

exception sqlalchemy.exc.OperationalError

封装了一个 DB-API OperationalError。

类签名

类 sqlalchemy.exc.OperationalError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.PendingRollbackError

事务失败，需要在继续之前回滚。

自版本 1.4 新增。

类签名

类 sqlalchemy.exc.PendingRollbackError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.ProgrammingError

封装了一个 DB-API ProgrammingError。

类签名

类 sqlalchemy.exc.ProgrammingError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.ResourceClosedError

从已关闭状态的连接、游标或其他对象请求了操作。

类签名

类 sqlalchemy.exc.ResourceClosedError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.SADeprecationWarning

用于废弃的 API 的使用。

类签名

类sqlalchemy.exc.SADeprecationWarning（sqlalchemy.exc.HasDescriptionCode，builtins.DeprecationWarning）

attribute deprecated_since: str | None = None

表明开始引发此弃用警告的版本

exception sqlalchemy.exc.SAPendingDeprecationWarning

与SADeprecationWarning类似的警告，此警告在现代版本的 SQLAlchemy 中不使用。

类签名

类sqlalchemy.exc.SAPendingDeprecationWarning（builtins.PendingDeprecationWarning）

attribute deprecated_since: str | None = None

表明开始引发此弃用警告的版本

exception sqlalchemy.exc.SATestSuiteWarning

在测试期间检测到的非致命条件的警告

目前不在 SAWarning 之外，以便我们可以解决像 Alembic 这样的工具在警告方面做错事的问题。

类签名

类sqlalchemy.exc.SATestSuiteWarning（builtins.Warning）

exception sqlalchemy.exc.SAWarning

在运行时发出。

类签名

类sqlalchemy.exc.SAWarning（sqlalchemy.exc.HasDescriptionCode，builtins.RuntimeWarning）

exception sqlalchemy.exc.SQLAlchemyError

通用错误类。

类签名

类sqlalchemy.exc.SQLAlchemyError（sqlalchemy.exc.HasDescriptionCode，builtins.Exception）

exception sqlalchemy.exc.StatementError

在执行 SQL 语句期间发生错误。

StatementError封装了执行过程中引发的异常，并具有statement和params属性，提供有关出现问题的语句的具体情况的上下文。

封装的异常对象可在orig属性中找到。

类签名

类sqlalchemy.exc.StatementError（sqlalchemy.exc.SQLAlchemyError）

method __init__(message: str, statement: str | None, params: _AnyExecuteParams | None, orig: BaseException | None, hide_parameters: bool = False, code: str | None = None, ismulti: bool | None = None)

attribute ismulti: bool | None = None

传递给repr_params()的多个参数。None是有意义的。

attribute orig: BaseException | None = None

被抛出的原始异常。

attribute params: _AnyExecuteParams | None = None

在发生此异常时使用的参数列表。

attribute statement: str | None = None

在发生此异常时调用的字符串 SQL 语句。

exception sqlalchemy.exc.TimeoutError

在连接池在获取连接时超时时引发。

类签名

类 sqlalchemy.exc.TimeoutError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.UnboundExecutionError

尝试执行 SQL 但没有数据库连接。

类签名

类 sqlalchemy.exc.UnboundExecutionError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.UnreflectableTableError

表存在，但由于某种原因无法反映。

自 1.2 版本新增。

类签名

类 sqlalchemy.exc.UnreflectableTableError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.UnsupportedCompilationError

当操作不受给定编译器支持时引发。

另请参见

如何将 SQL 表达式渲染为字符串，可能包含内联的绑定参数？

编译器 StrSQLCompiler 无法渲染类型为 的元素

类签名

类 sqlalchemy.exc.UnsupportedCompilationError (sqlalchemy.exc.CompileError)

method __init__(compiler: Compiled | TypeCompiler, element_type: Type[ClauseElement], message: str | None = None)

核心内部

原文：docs.sqlalchemy.org/en/20/core/internals.html

这里列出了一些关键的内部结构。

class sqlalchemy.engine.BindTyping

定义了在语句中传递绑定参数的不同方法以传递到数据库驱动程序。

从版本 2.0 开始。

成员

NONE, RENDER_CASTS, SETINPUTSIZES

类签名

类sqlalchemy.engine.BindTyping (enum.Enum)

attribute NONE = 1

没有采取任何步骤将类型信息传递给数据库驱动程序。

这是 SQLite、MySQL/MariaDB、SQL Server 等数据库的默认行为。

attribute RENDER_CASTS = 3

在 SQL 字符串中渲染转换或其他指令。

此方法适用于所有 PostgreSQL 方言，包括 asyncpg、pg8000、psycopg、psycopg2。实现此方法的方言可以选择在 SQL 语句中明确转换哪些类型的数据类型，哪些不转换。

使用 RENDER_CASTS 时，编译器将为渲染的字符串表示形式中的每个 BindParameter 对象调用 SQLCompiler.render_bind_cast() 方法，该对象的方言级类型设置了 TypeEngine.render_bind_cast 属性。

SQLCompiler.render_bind_cast() 也用于渲染一种形式的 “insertmanyvalues” 查询的转换，当同时设置了 InsertmanyvaluesSentinelOpts.USE_INSERT_FROM_SELECT 和 InsertmanyvaluesSentinelOpts.RENDER_SELECT_COL_CASTS 时，转换应用于中间列，例如 “INSERT INTO t (a, b, c) SELECT p0::TYP, p1::TYP, p2::TYP ” “FROM (VALUES (?, ?), (?, ?), …)”。

2.0.10 版本中的新内容：- 现在在 “insertmanyvalues” 实现的某些部分中使用了 SQLCompiler.render_bind_cast()。

attribute SETINPUTSIZES = 2

使用 pep-249 的 setinputsizes 方法。

仅对支持此方法的 DBAPIs 实现了此功能，并且对于 SQLAlchemy 方言已经设置了适当的基础架构的情况下才实现了。当前的方言包括 cx_Oracle，以及对使用 pyodbc 的 SQL Server 的可选支持。

使用 setinputsizes 时，方言还可以通过包含/排除列表的方式只对某些数据类型使用该方法。

使用 SETINPUTSIZES 时，对于每个执行的语句，具有绑定参数的语句都会调用 Dialect.do_set_input_sizes() 方法。

class sqlalchemy.engine.Compiled

表示已编译的 SQL 或 DDL 表达式。

成员

init(), cache_key, compile_state, construct_params(), dml_compile_state, execution_options, params, sql_compiler, state, statement, string

Compiled对象的__str__方法应生成语句的实际文本。Compiled对象特定于其底层数据库方言，并且可能特定于在特定绑定参数集中引用的列。在任何情况下，Compiled对象都不应依赖于这些绑定参数的实际值，即使它可能引用这些值作为默认值。

method __init__(dialect: Dialect, statement: ClauseElement | None, schema_translate_map: SchemaTranslateMapType | None = None, render_schema_translate: bool = False, compile_kwargs: Mapping[str, Any] = {})

构造一个新的Compiled对象。

参数：

• dialect – 编译的Dialect。
• statement – 要编译的ClauseElement。
• schema_translate_map – 模式名称的字典，用于在形成结果 SQL 时进行翻译 另请参阅 模式名称的翻译
• compile_kwargs – 将传递给初始调用Compiled.process()的额外 kwargs。

attribute cache_key: CacheKey | None = None

创建此Compiled对象之前生成的CacheKey。

用于需要访问在首次缓存Compiled实例时生成的原始CacheKey实例的例程，通常是为了将原始的BindParameter对象列表与在每次调用时生成的每个语句列表进行对比。

attribute compile_state: CompileState | None = None

可选的CompileState对象，用于维护编译器使用的其他状态。

主要的可执行对象，例如Insert、Update、Delete、Select在编译时会生成此状态，以计算关于对象的其他信息。对于要执行的顶级对象，可以将状态存储在此处，也可以适用于结果集处理。

版本 1.4 中的新功能。

method construct_params(params: _CoreSingleExecuteParams | None = None, extracted_parameters: Sequence[BindParameter[Any]] | None = None, escape_names: bool = True) → _MutableCoreSingleExecuteParams | None

返回此编译对象的绑定参数。

参数：

params – 一个字符串/对象对的字典，其值将覆盖编译到语句中的绑定值。

attribute dml_compile_state: CompileState | None = None

可选的CompileState在分配.isinsert、.isupdate或.isdelete时分配。

这通常将是与.compile_state相同的对象，但有一种例外情况，例如ORMFromStatementCompileState对象。

版本 1.4.40 中的新功能。

attribute execution_options: _ExecuteOptions = {}

从语句传播的执行选项。在某些情况下，语句的子元素可以修改这些选项。

attribute params

返回此已编译对象的绑定参数。

attribute sql_compiler

返回一个能够处理 SQL 表达式的已编译对象。

如果此编译器是一个，那么它很可能只返回‘self’。

attribute state: CompilerState

编译器状态的描述

attribute statement: ClauseElement | None = None

要编译的语句。

attribute string: str = ''

statement的字符串表示

class sqlalchemy.engine.interfaces.DBAPIConnection

表示PEP 249数据库连接的协议。

版本 2.0 中的新内容。

另请参见

连接对象 - 在PEP 249中

成员

自动提交，close()，commit()，cursor()，rollback()

类签名

类sqlalchemy.engine.interfaces.DBAPIConnection（typing_extensions.Protocol）

attribute autocommit: bool

method close() → None

method commit() → None

method cursor() → DBAPICursor

method rollback() → None

class sqlalchemy.engine.interfaces.DBAPICursor

表示PEP 249数据库游标的协议。

版本 2.0 中的新内容。

另请参见

游标对象 - 在PEP 249中

成员

数组大小，callproc()，close()，description，execute()，executemany()，fetchall()，fetchmany()，fetchone()，lastrowid，nextset()，rowcount，setinputsizes()，setoutputsize()

类签名

类sqlalchemy.engine.interfaces.DBAPICursor（typing_extensions.Protocol）

attribute arraysize: int

method callproc(procname: str, parameters: Sequence[Any] = Ellipsis) → Any

method close() → None

attribute description

游标的描述属性。

另请参见

cursor.description - 在PEP 249中

method execute(operation: Any, parameters: Sequence[Any] | Mapping[str, Any] | None = None) → Any

method executemany(operation: Any, parameters: Sequence[Sequence[Any]] | Sequence[Mapping[str, Any]]) → Any

method fetchall() → Sequence[Any]

method fetchmany(size: int = Ellipsis) → Sequence[Any]

method fetchone() → Any | None

attribute lastrowid: int

method nextset() → bool | None

attribute rowcount

method setinputsizes(sizes: Sequence[Any]) → None

method setoutputsize(size: Any, column: Any) → None

class sqlalchemy.engine.interfaces.DBAPIType

表示PEP 249数据库类型的协议。

版本 2.0 中的新内容。

另请参见

类型对象 - 在 PEP 249

类签名

类 sqlalchemy.engine.interfaces.DBAPIType (typing_extensions.Protocol) 的定义

class sqlalchemy.sql.compiler.DDLCompiler

成员

__init__(), cache_key, compile_state, construct_params(), define_constraint_remote_table(), dml_compile_state, execution_options, params, sql_compiler, state, statement, string

类签名

类 sqlalchemy.sql.compiler.DDLCompiler（sqlalchemy.sql.compiler.Compiled的一个子类）

method __init__(dialect: Dialect, statement: ClauseElement | None, schema_translate_map: SchemaTranslateMapType | None = None, render_schema_translate: bool = False, compile_kwargs: Mapping[str, Any] = {})

继承自 Compiled 的 sqlalchemy.sql.compiler.Compiled.__init__ 方法

构造一个新的 Compiled 对象。

参数:

• dialect – 要编译的 Dialect。
• statement – 待编译的 ClauseElement。
• schema_translate_map – 用于形成生成 SQL 时要翻译的模式名称字典 另请参见 模式名称的翻译
• compile_kwargs – 将传递给初始调用 Compiled.process() 的额外 kwargs。

attribute cache_key: CacheKey | None = None

继承自 Compiled 的 Compiled.cache_key 属性

生成此 Compiled 对象之前生成的 CacheKey。

这用于需要访问在首次缓存Compiled实例时生成的原始CacheKey实例的例程，通常是为了调和原始的BindParameter对象列表与每次调用时生成的每个语句列表。

attribute compile_state: CompileState | None = None

继承自 Compiled 的 Compiled.compile_state 属性

可选的 CompileState 对象，用于维护编译器使用的其他状态。

主要的可执行对象，如Insert、Update、Delete、Select，在编译时会生成此状态，以计算有关对象的其他信息。对于要执行的顶级对象，该状态可以存储在这里，也可以适用于结果集处理。

1.4 版中的新功能。

method construct_params(params: _CoreSingleExecuteParams | None = None, extracted_parameters: Sequence[BindParameter[Any]] | None = None, escape_names: bool = True) → _MutableCoreSingleExecuteParams | None

返回此编译对象的绑定参数。

参数：

params – 一个字符串/对象对的字典，其值将覆盖编译到语句中的绑定值。

method define_constraint_remote_table(constraint, table, preparer)

格式化 CREATE CONSTRAINT 语句的远程表子句。

attribute dml_compile_state: CompileState | None = None

继承自 Compiled 的 Compiled.dml_compile_state 属性

在分配 .isinsert、.isupdate 或 .isdelete 的相同点分配的可选的 CompileState。

这通常是与 .compile_state 相同的对象，但有一些例外情况，比如 ORMFromStatementCompileState 对象。

1.4.40 版中的新功能。

attribute execution_options: _ExecuteOptions = {}

继承自 Compiled 的 Compiled.execution_options 属性

语句中传播的执行选项。在某些情况下，语句的子元素可以修改这些选项。

attribute params

继承自 Compiled 的 Compiled.params 属性

返回此编译对象的绑定参数。

attribute sql_compiler

attribute state: CompilerState

编译器状态的描述

attribute statement: ClauseElement | None = None

继承自 Compiled 的 Compiled.statement 属性

要编译的语句。

attribute string: str = ''

继承自 Compiled 的 Compiled.string 属性

statement 的字符串表示

class sqlalchemy.engine.default.DefaultDialect

Dialect 的默认实现

成员

bind_typing, colspecs, connect(), construct_arguments, create_connect_args(), create_xid(), cte_follows_insert, dbapi, dbapi_exception_translation_map, ddl_compiler, default_isolation_level, default_metavalue_token, default_schema_name, default_sequence_base, delete_executemany_returning, delete_returning, delete_returning_multifrom, denormalize_name(), div_is_floordiv, do_begin(), do_begin_twophase(), do_close(), do_commit(), do_commit_twophase(), do_execute(), do_execute_no_params(), do_executemany(), do_ping(), do_prepare_twophase(), do_recover_twophase(), do_release_savepoint(), do_rollback(), do_rollback_to_savepoint(), do_rollback_twophase(), do_savepoint(), do_set_input_sizes(), do_terminate(), driver, engine_config_types, engine_created(), exclude_set_input_sizes, execute_sequence_format, execution_ctx_cls, favor_returning_over_lastrowid, full_returning, get_async_dialect_cls(), get_check_constraints(), get_columns(), get_default_isolation_level(), get_dialect_cls(), get_dialect_pool_class(), get_driver_connection(), get_foreign_keys(), get_indexes(), get_isolation_level(), get_isolation_level_values(), get_materialized_view_names(), get_multi_check_constraints(), get_multi_columns(), get_multi_foreign_keys(), get_multi_indexes(), get_multi_pk_constraint(), get_multi_table_comment(), get_multi_table_options(), get_multi_unique_constraints(), get_pk_constraint(), get_schema_names(), get_sequence_names(), get_table_comment(), get_table_names(), get_table_options(), get_temp_table_names(), get_temp_view_names(), get_unique_constraints(), get_view_definition(), get_view_names(), has_index(), has_schema(), has_sequence(), has_table(), has_terminate, identifier_preparer, import_dbapi(), include_set_input_sizes, initialize(), inline_comments, insert_executemany_returning, insert_executemany_returning_sort_by_parameter_order, insert_returning, insertmanyvalues_implicit_sentinel, insertmanyvalues_max_parameters, insertmanyvalues_page_size, is_async, is_disconnect(), label_length, load_provisioning(), loaded_dbapi, max_identifier_length, name, normalize_name(), on_connect(), on_connect_url(), paramstyle, positional, preexecute_autoincrement_sequences, preparer, reflection_options, reset_isolation_level(), returns_native_bytes, sequences_optional, server_side_cursors, server_version_info, set_connection_execution_options(), set_engine_execution_options(), set_isolation_level(), statement_compiler, supports_alter, supports_comments, supports_constraint_comments, supports_default_metavalue, supports_default_values, supports_empty_insert, supports_identity_columns, supports_multivalues_insert, supports_native_boolean, supports_native_decimal, supports_native_enum, supports_native_uuid, supports_sane_multi_rowcount, supports_sane_rowcount, supports_sane_rowcount_returning, supports_sequences, supports_server_side_cursors, supports_simple_order_by_label, supports_statement_cache, tuple_in_values, type_compiler, type_compiler_cls, type_compiler_instance, type_descriptor(), update_executemany_returning, update_returning, update_returning_multifrom, use_insertmanyvalues, use_insertmanyvalues_wo_returning

类签名

sqlalchemy.engine.default.DefaultDialect 类 (sqlalchemy.engine.interfaces.Dialect)

attribute bind_typing = 1

定义将类型信息传递给绑定参数的数据库和/或驱动程序的方法。

有关值，请参阅 BindTyping。

2.0 版本中新增。

attribute colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]] = {}

从 sqlalchemy.types 映射到特定于方言类的子类的 TypeEngine 类字典。该字典仅适用于类级别，并且不是从方言实例本身访问的。

method connect(*cargs, **cparams)

使用此方言的 DBAPI 建立连接。

此方法的默认实现为：

def connect(self, *cargs, **cparams):
    return self.dbapi.connect(*cargs, **cparams)

*cargs, **cparams 参数直接从此方言的 Dialect.create_connect_args() 方法生成。

此方法可用于需要在从 DBAPI 获得新连接时执行程序化的每个连接步骤的方言。

参数：

• *cargs – 从 Dialect.create_connect_args() 方法返回的位置参数
• **cparams – 从 Dialect.create_connect_args() 方法返回的关键字参数。

返回：

一个 DBAPI 连接，通常来自于 PEP 249 模块级别的 .connect() 函数。

另请参阅

Dialect.create_connect_args()

Dialect.on_connect()

attribute construct_arguments: List[Tuple[Type[SchemaItem | ClauseElement], Mapping[str, Any]]] | None = None

继承自 Dialect 的 Dialect.construct_arguments 属性

各种 SQLAlchemy 构造的可选参数说明，通常是模式项。

要实现，将其建立为元组的系列，如下所示：

construct_arguments = [
    (schema.Index, {
        "using": False,
        "where": None,
        "ops": None
    })
]

如果以上结构在 PostgreSQL 方言上建立，则 Index 结构现在将接受关键字参数 postgresql_using、postgresql_where 和 postgresql_ops。构造函数中以 postgresql_ 为前缀的任何其他参数都将引发 ArgumentError。

不包括construct_arguments成员的方言将不参与参数验证系统。对于这样的方言，任何参数名称都被所有参与的构造接受，在以该方言名称为前缀的参数命名空间内。这里的原理是，尚未实现此功能的第三方方言将继续以旧方式运行。

另请参阅

DialectKWArgs - 实现基类，它消耗DefaultDialect.construct_arguments

method create_connect_args(url)

构建 DB-API 兼容的连接参数。

给定一个URL对象，返回一个包含(*args, **kwargs)的元组，适合直接发送到 dbapi 的 connect 函数。这些参数被发送到Dialect.connect()方法，然后运行 DBAPI 级别的connect()函数。

该方法通常利用URL.translate_connect_args()方法生成一个选项字典。

默认实现为：

def create_connect_args(self, url):
    opts = url.translate_connect_args()
    opts.update(url.query)
    return ([], opts)

参数：

url – 一个URL对象

返回：

一个将传递给Dialect.connect()方法的(*args, **kwargs)元组。

另请参阅

URL.translate_connect_args()

method create_xid()

创建一个随机的两阶段事务 ID。

此 ID 将传递给 do_begin_twophase()、do_rollback_twophase()、do_commit_twophase()。其格式未指定。

attribute cte_follows_insert: bool = False

给定 CTE 和 INSERT 语句时的目标数据库，需要 CTE 在 INSERT 语句之下。

attribute dbapi: ModuleType | None

DBAPI 模块对象本身的引用。

SQLAlchemy 方言使用 classmethod Dialect.import_dbapi() 导入 DBAPI 模块。其原因是任何方言模块都可以被导入和用于生成 SQL 语句，而无需安装实际的 DBAPI 驱动程序。只有在使用create_engine()构造Engine时，DBAPI 才会被导入；此时，创建过程将把 DBAPI 模块分配给此属性。

因此，方言应实现 Dialect.import_dbapi()，它将导入必要的模块并返回它，然后在方言代码中引用 self.dbapi 以引用 DBAPI 模块内容。

版本更改：Dialect.dbapi 属性专门用作每个Dialect 实例对 DBAPI 模块的引用。以前未完全记录的 .Dialect.dbapi() 类方法已被弃用，并由 Dialect.import_dbapi() 替换。

attribute dbapi_exception_translation_map: Mapping[str, str] = {}

继承自 Dialect 的 Dialect.dbapi_exception_translation_map 属性

一个名称字典，其值将包含作为值的 pep-249 异常的名称（“IntegrityError”、“OperationalError” 等），键入为替代类名，以支持 DBAPI 具有不以它们所引用的方式命名的异常类的情况（例如 IntegrityError = MyException）。在绝大多数情况下，此字典为空。

attribute ddl_compiler

DDLCompiler 的别名

attribute default_isolation_level: IsolationLevel | None

在新连接上隐含存在的隔离级别

attribute default_metavalue_token: str = 'DEFAULT'

对于 INSERT… VALUES (DEFAULT) 语法，括号中放置的令牌。

attribute default_schema_name: str | None = None

默认模式的名称。此值仅适用于支持的方言，并且通常在与数据库的初始连接期间填充。

attribute default_sequence_base: int = 1

将呈现为 CREATE SEQUENCE DDL 语句的“START WITH” 部分的默认值。

attribute delete_executemany_returning: bool = False

方言支持具有 executemany 的 DELETE…RETURNING。

attribute delete_returning: bool = False

如果方言支持带有 DELETE 的 RETURNING

版本 2.0 中的新功能。

attribute delete_returning_multifrom: bool = False

如果方言支持带有 DELETE…FROM 的 RETURNING

版本 2.0 中的新功能。

method denormalize_name(name)

如果给定的名称是全小写名称，则将其转换为后端的不区分大小写标识符。

此方法仅在方言定义 requires_name_normalize=True 时使用。

attribute div_is_floordiv: bool = True

目标数据库将 / 除法运算符视为“地板除法”

method do_begin(dbapi_connection)

提供给定 DB-API 连接的 connection.begin() 实现。

DBAPI 没有专用的“开始”方法，预期事务是隐式的。此挂钩是为了那些可能需要在此领域提供额外帮助的 DBAPI 而提供的。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在 ConnectionFairy 中被代理。

method do_begin_twophase(connection: Connection, xid: Any) → None

继承自 Dialect 的 Dialect.do_begin_twophase() 方法

在给定连接上开始两阶段事务。

参数：

• connection – 一个 Connection。
• xid – xid

method do_close(dbapi_connection)

提供给定 DBAPI 连接的 connection.close() 实现。

当连接从池中分离或被返回超出池的正常容量时，将调用此钩子。

method do_commit(dbapi_connection)

提供 connection.commit() 的实现，给定一个 DB-API 连接。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在 ConnectionFairy 中代理。

method do_commit_twophase(connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False) → None

继承自 Dialect 方法的 Dialect.do_commit_twophase()。

在给定连接上提交一个两阶段事务。

参数：

• connection – 一个 Connection。
• xid – xid
• is_prepared – 是否调用了 TwoPhaseTransaction.prepare()。
• recover – 如果传递了恢复标志。

method do_execute(cursor, statement, parameters, context=None)

提供 cursor.execute(statement, parameters) 的实现。

method do_execute_no_params(cursor, statement, context=None)

提供 cursor.execute(statement) 的实现。

不应发送参数集合。

method do_executemany(cursor, statement, parameters, context=None)

提供 cursor.executemany(statement, parameters) 的实现。

method do_ping(dbapi_connection: DBAPIConnection) → bool

检查 DBAPI 连接并在连接可用时返回 True。

method do_prepare_twophase(connection: Connection, xid: Any) → None

继承自 Dialect 方法的 Dialect.do_prepare_twophase()。

在给定连接上准备一个两阶段事务。

参数：

• connection – 一个 Connection。
• xid – xid

method do_recover_twophase(connection: Connection) → List[Any]

继承自 Dialect 方法的 Dialect.do_recover_twophase()。

在给定连接上恢复未提交的准备好的两阶段事务标识符列表。

参数：

connection – 一个 Connection。

method do_release_savepoint(connection, name)

在连接上释放命名保存点。

参数：

• connection – 一个 Connection。
• name – 保存点名称。

method do_rollback(dbapi_connection)

提供 connection.rollback() 的实现，给定一个 DB-API 连接。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在 ConnectionFairy 中代理。

method do_rollback_to_savepoint(connection, name)

将连接回滚到命名保存点。

参数：

• connection – 一个 Connection。
• name – 保存点名称。

method do_rollback_twophase(connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False) → None

继承自 Dialect 方法的 Dialect.do_rollback_twophase()。

在给定连接上回滚两阶段事务。

参数：

• connection – 一个 Connection。
• xid – xid
• is_prepared – 是否调用了TwoPhaseTransaction.prepare()。
• recover – 如果传递了 recover 标志。

method do_savepoint(connection, name)

使用给定名称创建一个保存点。

参数：

• connection – 一个Connection。
• name – 保存点名称。

method do_set_input_sizes(cursor: DBAPICursor, list_of_tuples: _GenericSetInputSizesType, context: ExecutionContext) → Any

继承自 Dialect 的 Dialect.do_set_input_sizes() *方法。

使用适当的参数调用cursor.setinputsizes()方法。

如果Dialect.bind_typing属性设置为BindTyping.SETINPUTSIZES值，则调用此钩子。参数数据以元组列表的形式传递（paramname，dbtype，sqltype），其中paramname是语句中参数的键，dbtype是 DBAPI 数据类型，sqltype是 SQLAlchemy 类型。元组的顺序是正确的参数顺序。

自 1.4 版本新推出。

在 2.0 版本中更改：- 通过将Dialect.bind_typing设置为BindTyping.SETINPUTSIZES来启用 setinputsizes 模式。接受use_setinputsizes参数的方言应适当设置此值。

method do_terminate(dbapi_connection)

提供一个实现了尽可能不阻塞的connection.close()的钩子，给定一个 DBAPI 连接。

在绝大多数情况下，这只是调用.close()，但是对于某些 asyncio 方言可能调用不同的 API 功能。

当连接被回收或无效时，此钩子由Pool调用。

自 1.4.41 版本新推出。

attribute driver: str

方言的 DBAPI 的标识名称。

attribute engine_config_types: Mapping[str, Any] = {'echo': <function bool_or_str.<locals>.bool_or_value>, 'echo_pool': <function bool_or_str.<locals>.bool_or_value>, 'future': <function asbool>, 'max_overflow': <function asint>, 'pool_recycle': <function asint>, 'pool_size': <function asint>, 'pool_timeout': <function asint>}

一个字符串键的映射，可以是引擎配置中的类型转换函数。

classmethod engine_created(engine: Engine) → None

继承自 Dialect 的 Dialect.engine_created() *方法。

一个方便的钩子，在返回最终Engine之前调用。

如果方言从get_dialect_cls()方法返回了不同的类，则该钩子将在两个类上调用，首先在由get_dialect_cls()方法返回的方言类上调用，然后在调用方法的类上调用。

钩子应由方言和/或包装器用于将特殊事件应用于引擎或其组件。特别是，它允许方言包装类应用方言级事件。

attribute exclude_set_input_sizes: Set[Any] | None = None

设置应在自动 cursor.setinputsizes() 调用中排除的 DBAPI 类型对象集合。

仅当 bind_typing 为 BindTyping.SET_INPUT_SIZES 时才使用此选项。

attribute execute_sequence_format

tuple 的别名

attribute execution_ctx_cls

DefaultExecutionContext 的别名

attribute favor_returning_over_lastrowid: bool = False

对于支持 lastrowid 和 RETURNING 插入策略的后端，请优先使用 RETURNING 进行简单的单整数 pk 插入。

在大多数后端上，cursor.lastrowid 往往更具性能。

attribute full_returning

自版本 2.0 弃用：full_returning 已弃用，请改用 insert_returning、update_returning、delete_returning

classmethod get_async_dialect_cls(url: URL) → Type[Dialect]

继承自 Dialect 的 Dialect.get_async_dialect_cls() 方法

给定一个 URL，返回将由异步引擎使用的 Dialect。

默认情况下，这是 Dialect.get_dialect_cls() 的别名，只返回 cls。如果一个方言在同一名称下提供了同步和异步版本，则可以使用它，例如 psycopg 驱动程序。

版本 2 中的新功能。

另请参见

Dialect.get_dialect_cls()

method get_check_constraints(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedCheckConstraint]

继承自 Dialect 的 Dialect.get_check_constraints() 方法

返回 table_name 中检查约束的信息。

给定一个字符串 table_name 和一个可选的字符串 schema，将检查约束信息作为与 ReflectedCheckConstraint 字典相对应的字典列表返回。

这是一个内部方言方法。应用程序应使用 Inspector.get_check_constraints()。

method get_columns(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedColumn]

继承自 Dialect 的 Dialect.get_columns() 方法

返回关于 table_name 中列的信息。

给定一个 Connection、一个字符串 table_name 和一个可选的字符串 schema，将列信息作为与 ReflectedColumn 字典相对应的字典列表返回。

这是一个内部方言方法。 应用程序应使用Inspector.get_columns()。

method get_default_isolation_level(dbapi_conn)

给定一个 DBAPI 连接，返回其隔离级别，或者如果无法检索到隔离级别，则返回默认隔离级别。

可以由子类覆盖，以提供对于无法可靠检索实际隔离级别的数据库的“回退”隔离级别。

默认情况下，调用Interfaces.get_isolation_level()方法，传播引发的任何异常。

新版本中新增 1.3.22。

classmethod get_dialect_cls(url: URL) → Type[Dialect]

继承自 方言 的 Dialect.get_dialect_cls() 方法

给定一个 URL，返回将要使用的方言。

这是一个挂钩，允许外部插件围绕现有方言提供功能，通过允许从基于入口点的 URL 加载插件，然后插件返回要使用的实际方言。

默认情况下，这只是返回 cls。

method get_dialect_pool_class(url: URL) → Type[Pool]

返回用于给定 URL 的 Pool 类。

method get_driver_connection(connection)

返回由外部驱动程序包返回的连接对象。

对于使用 DBAPI 兼容驱动程序的普通方言，此调用将只返回作为参数传递的connection。 对于改用非 DBAPI 兼容驱动程序进行适配的方言，例如在适配异步驱动程序时，此调用将返回驱动程序返回的类似连接的对象。

新版本中新增 1.4.24。

method get_foreign_keys(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedForeignKeyConstraint]

继承自 方言 的 Dialect.get_foreign_keys() 方法

返回关于table_name中外键的信息。

给定一个连接，一个字符串table_name，和一个可选字符串schema，返回作为与ReflectedForeignKeyConstraint字典对应的字典列表的外键信息。

这是一个内部方言方法。 应用程序应使用Inspector.get_foreign_keys()。

method get_indexes(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedIndex]

继承自 方言 的 Dialect.get_indexes() 方法

返回关于table_name中索引的信息。

给定一个连接，一个字符串table_name和一个可选字符串schema，返回作为与ReflectedIndex字典对应的字典列表的索引信息。

这是一个内部方言方法。应用程序应使用 Inspector.get_indexes()。

method get_isolation_level(dbapi_connection: DBAPIConnection) → Literal['SERIALIZABLE', 'REPEATABLE READ', 'READ COMMITTED', 'READ UNCOMMITTED', 'AUTOCOMMIT']

继承自 Dialect 的 Dialect.get_isolation_level() 方法

给定一个 DBAPI 连接，返回其隔离级别。

当使用 Connection 对象时，可以使用 Connection.connection 访问器获取相应的 DBAPI 连接。

请注意，这是一个方言级方法，用作 Connection 和 Engine 隔离级别功能实现的一部分；对于大多数典型用例，应优先使用这些 API。

另请参阅

Connection.get_isolation_level() - 查看当前级别

Connection.default_isolation_level - 查看默认级别

Connection.execution_options.isolation_level - 设置每个 Connection 的隔离级别

create_engine.isolation_level - 设置每个 Engine 的隔离级别

method get_isolation_level_values(dbapi_conn: DBAPIConnection) → List[Literal['SERIALIZABLE', 'REPEATABLE READ', 'READ COMMITTED', 'READ UNCOMMITTED', 'AUTOCOMMIT']]

继承自 Dialect 的 Dialect.get_isolation_level_values() 方法

返回一个字符串隔离级别名称序列，该序列被此方言接受。

可用名称应使用以下约定：

• 使用大写命名。隔离级别方法将接受小写名称，但在传递给方言之前会将其标准化为大写。
• 单词之间应该用空格分隔，而不是下划线，例如 REPEATABLE READ。在传递给方言之前，隔离级别名称将下划线转换为空格。
• 对于标准隔离名称，如果后端支持，应为 READ UNCOMMITTED、READ COMMITTED、REPEATABLE READ、SERIALIZABLE
• 如果方言支持自动提交选项，则应使用隔离级别名称 AUTOCOMMIT。
• 其他隔离模式也可能存在，只要它们以大写形式命名并使用空格而不是下划线。

此函数用于默认方言检查给定的隔离级别参数是否有效，否则会引发ArgumentError。

在可能的情况下，方法会传递一个 DBAPI 连接，以便方言自身需要查询连接本身以确定此列表，但是大多数后端都会返回一个硬编码的值列表。如果方言支持“AUTOCOMMIT”，那么该值也应该存在于返回的序列中。

该方法默认引发NotImplementedError。如果方言未实现此方法，则默认方言将不会在将其传递给Dialect.set_isolation_level()方法之前对给定的隔离级别值执行任何检查。这是为了与尚未实现此方法的第三方方言保持向后兼容。

版本 2.0 新增。

method get_materialized_view_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_materialized_view_names() 方法

返回数据库中所有可用物化视图名称的列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_materialized_view_names()。

参数：

模式 –

查询的模式名称，如果不是默认模式。

版本 2.0 新增。

method get_multi_check_constraints(connection, **kw)

返回给定schema中所有表的检查约束信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_check_constraints()。

注意

DefaultDialect提供了一个默认实现，将针对Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()返回的每个对象调用单表方法，具体取决于提供的kind。希望支持更快实现的方言应该实现此方法。

版本 2.0 新增。

method get_multi_columns(connection, **kw)

返回给定schema中所有表的列信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_columns()。

注意

DefaultDialect提供了一个默认实现，将针对Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()返回的每个对象调用单表方法，具体取决于提供的kind。希望支持更快实现的方言应该实现此方法。

版本 2.0 新增。

method get_multi_foreign_keys(connection, **kw)

返回给定 schema 中所有表的外键信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_foreign_keys()。

注意

DefaultDialect 提供了一个默认实现，它会根据提供的 kind 对 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法。希望支持更快实现的方言应该实现这个方法。

2.0 版本中新增。

method get_multi_indexes(connection, **kw)

返回给定 schema 中所有表的索引信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_indexes()。

注意

DefaultDialect 提供了一个默认实现，它会根据提供的 kind 对 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法。希望支持更快实现的方言应该实现这个方法。

2.0 版本中新增。

method get_multi_pk_constraint(connection, **kw)

返回给定 schema 中所有表的主键约束信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_pk_constraint()。

注意

DefaultDialect 提供了一个默认实现，它会根据提供的 kind 对 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法。希望支持更快实现的方言应该实现这个方法。

2.0 版本中新增。

method get_multi_table_comment(connection, **kw)

返回给定 schema 中所有表的表注释信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_table_comment()。

注意

DefaultDialect 提供了一个默认实现，它会根据提供的 kind 对 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法。希望支持更快实现的方言应该实现这个方法。

2.0 版本中新增。

method get_multi_table_options(connection, **kw)

返回给定 schema 中表创建时指定的选项字典。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_table_options()。

注意

DefaultDialect 提供了一个默认实现，它会根据提供的 kind 对 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法。希望支持更快实现的方言应该实现这个方法。

2.0 版本中新增。

method get_multi_unique_constraints(connection, **kw)

返回给定schema中所有表的唯一约束信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_unique_constraints()。

注意

DefaultDialect提供了一个默认实现，将根据提供的kind调用Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()返回的每个对象的单表方法。希望支持更快实现的方言应该实现这个方法。

新版本 2.0。

method get_pk_constraint(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → ReflectedPrimaryKeyConstraint

继承自 Dialect 的 Dialect.get_pk_constraint() *方法。

返回table_name上主键约束的信息。

给定Connection、字符串table_name和可选字符串schema，返回与ReflectedPrimaryKeyConstraint字典对应的主键信息字典。

这是一个内部方言方法。应用程序应该使用Inspector.get_pk_constraint()。

method get_schema_names(connection: Connection, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_schema_names() *方法。

返回数据库中所有模式名称的列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_schema_names()。

method get_sequence_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_sequence_names() *方法。

返回数据库中所有序列名称的列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_sequence_names()。

参数：

schema – 要查询的模式名称，如果不是默认模式。

新版本 1.4。

method get_table_comment(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → ReflectedTableComment

继承自 Dialect 的 Dialect.get_table_comment() *方法。

返回由table_name标识的表的“注释”。

给定字符串table_name和可选字符串schema，返回与ReflectedTableComment字典对应的表注释信息字典。

这是一个内部方言方法。应用程序应该使用Inspector.get_table_comment()。

抛出：

对于不支持注释的方言，抛出 NotImplementedError。

版本 1.2 中的新功能。

method get_table_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_table_names() 方法。

返回 schema 的表名列表。

这是一个内部方言方法。应用程序应使用 Inspector.get_table_names()。

method get_table_options(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → Dict[str, Any]

继承自 Dialect 的 Dialect.get_table_options() 方法。

返回创建 table_name 时指定的选项字典。

这是一个内部方言方法。应用程序应使用 Inspector.get_table_options()。

method get_temp_table_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_temp_table_names() 方法。

返回给定连接上的临时表名列表，如果底层后端支持。

这是一个内部方言方法。应用程序应使用 Inspector.get_temp_table_names()。

method get_temp_view_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_temp_view_names() 方法。

返回给定连接上的临时视图名列表，如果底层后端支持。

这是一个内部方言方法。应用程序应使用 Inspector.get_temp_view_names()。

method get_unique_constraints(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedUniqueConstraint]

继承自 Dialect 的 Dialect.get_unique_constraints() 方法。

返回 table_name 中唯一约束的信息。

给定一个字符串 table_name 和一个可选的字符串 schema，返回唯一约束信息，作为与 ReflectedUniqueConstraint 字典相对应的字典列表。

这是一个内部方言方法。应用程序应使用 Inspector.get_unique_constraints()。

method get_view_definition(connection: Connection, view_name: str, schema: str | None = None, **kw: Any) → str

继承自 Dialect 的 Dialect.get_view_definition() 方法。

返回普通或材料化视图定义。

这是一个内部方言方法。应用程序应使用 Inspector.get_view_definition()。

给定一个 Connection，一个字符串 view_name，和一个可选的字符串 schema，返回视图定义。

method get_view_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

继承自 Dialect 的 Dialect.get_view_names() 方法。

返回数据库中所有非材料化视图名称的列表。

这是一个内部方言方法。应用程序应使用 Inspector.get_view_names()。

参数：

schema – 要查询的模式名称，如果不是默认模式。

method has_index(connection, table_name, index_name, schema=None, **kw)

检查数据库中特定索引名称的存在性。

给定一个 Connection 对象，一个字符串 table_name 和字符串索引名称，如果给定表上存在给定名称的索引，则返回 True，否则返回 False。

DefaultDialect 在 Dialect.has_table() 和 Dialect.get_indexes() 方法方面实现了这一点，但是方言可以实现更高效的版本。

这是一个内部方言方法。应用程序应使用 Inspector.has_index()。

版本 1.4 中的新功能。

method has_schema(connection: Connection, schema_name: str, **kw: Any) → bool

检查数据库中特定模式名称的存在性。

给定一个 Connection 对象，一个字符串 schema_name，如果存在给定的模式，则返回 True，否则返回 False。

DefaultDialect 通过检查 Dialect.get_schema_names() 返回的模式中是否存在 schema_name 来实现这一点，但是方言可以实现更高效的版本。

这是一个内部方言方法。应用程序应使用 Inspector.has_schema()。

版本 2.0 中的新功能。

method has_sequence(connection: Connection, sequence_name: str, schema: str | None = None, **kw: Any) → bool

从 Dialect 的 Dialect.has_sequence() 方法继承

检查数据库中特定序列的存在性。

给定一个 Connection 对象和一个字符串 sequence_name，如果数据库中存在给定的序列，则返回 True，否则返回 False。

这是一个内部方言方法。应用程序应使用 Inspector.has_sequence()。

method has_table(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → bool

从 Dialect 的 Dialect.has_table() 方法继承

对于内部方言使用，检查数据库中特定表或视图的存在性。

给定一个 Connection 对象，一个字符串 table_name 和可选的模式名称，如果数据库中存在给定的表，则返回 True，否则返回 False。

此方法作为公共面向的 Inspector.has_table() 方法的底层实现，并且在内部用于实现方法如 Table.create() 和 MetaData.create_all() 的“checkfirst”行为。

注意

此方法由 SQLAlchemy 内部使用，并发布以便第三方方言可以提供实现。这不是用于检查表存在性的公共 API。请使用 Inspector.has_table() 方法。

2.0 版本更改::: Dialect.has_table() 现在正式支持检查其他类似表的对象：

• 任何类型的视图（普通或材料化）
• 任何类型的临时表

以前，这两个检查没有正式规定，不同的方言在行为上会有所不同。方言测试套件现在包括对所有这些对象类型的测试，支持视图或临时表的程度应该寻求支持定位这些对象以实现完全的兼容性。

attribute has_terminate: bool = False

此方言是否具有单独的“终止”实现，不会阻塞或需要等待。

attribute identifier_preparer: IdentifierPreparer

一旦构造了 DefaultDialect 的实例，此元素将引用一个 IdentifierPreparer 的实例。

classmethod import_dbapi() → module

继承自 Dialect 的 Dialect.import_dbapi() *方法。

导入此方言使用的 DBAPI 模块。

此处返回的 Python 模块对象将被分配为构造的方言的一个实例变量，名称为 .dbapi。

2.0 版本更改：Dialect.import_dbapi() 类方法从先前的方法 .Dialect.dbapi() 重命名，该方法将在方言实例化时由 DBAPI 模块本身替换，因此以两种不同方式使用相同的名称。如果第三方方言上存在 .Dialect.dbapi() 类方法，将使用它并���出弃用警告。

attribute include_set_input_sizes: Set[Any] | None = None

应包含在自动 cursor.setinputsizes() 调用中的一组 DBAPI 类型对象。

仅在 bind_typing 为 BindTyping.SET_INPUT_SIZES 时使用。

method initialize(connection)

在使用连接创建方言时调用。

允许方言根据服务器版本信息或其他属性配置选项。

此处传递的连接是一个具有完整功能的 SQLAlchemy 连接对象。

应通过 super()调用基础方言的 initialize()方法。

注意

从 SQLAlchemy 1.4 开始，在调用任何Dialect.on_connect()钩子之前调用此方法。

attribute inline_comments: bool = False

指示方言是否支持与表或列定义内联的注释 DDL。如果为 False，则意味着必须使用 ALTER 来设置表和列的注释。

attribute insert_executemany_returning: bool

当 dialect.do_executemany()被使用时，方言/驱动程序/数据库支持某些方法来提供 INSERT…RETURNING 支持。

attribute insert_executemany_returning_sort_by_parameter_order: bool

当 dialect.do_executemany()与设置了Insert.returning.sort_by_parameter_order参数一起使用时，方言/驱动程序/数据库支持某些方法来提供 INSERT…RETURNING 支持。

attribute insert_returning: bool = False

如果方言支持 INSERT 与 RETURNING

2.0 版本中的新功能。

attribute insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts = symbol('NOT_SUPPORTED')

指示数据库是否支持一种形式的批量插入，其中自增整数主键可以可靠地用作 INSERT 的行的排序。

2.0.10 版本中的新功能。

另请参见

将返回的行与参数集相关联

attribute insertmanyvalues_max_parameters: int = 32700

与 insertmanyvalues_page_size 替代，还将基于语句中的参数总数限制页面大小。

attribute insertmanyvalues_page_size: int = 1000

每个ExecuteStyle.INSERTMANYVALUES执行中渲染为单个 INSERT…VALUES()语句的行数。

默认方言将此默认设置为 1000。

2.0 版本中的新功能。

另请参见

Connection.execution_options.insertmanyvalues_page_size - Connection上可用的执行选项，语句

attribute is_async: bool = False

此方言是否用于 asyncio 使用。

method is_disconnect(e, connection, cursor)

如果给定的 DB-API 错误表示无效连接，则返回 True

attribute label_length: int | None

SQL 标签的可选用户定义的最大长度

classmethod load_provisioning()

为此方言设置 provision.py 模块。

对于包含一个设置供应跟随者的 provision.py 模块的方言，此方法应启动该过程。

典型实现可能是：

@classmethod
def load_provisioning(cls):
    __import__("mydialect.provision")

默认方法假定当前方言的所有者包中有一个名为provision.py的模块，基于__module__属性：

@classmethod
def load_provisioning(cls):
    package = ".".join(cls.__module__.split(".")[0:-1])
    try:
        __import__(package + ".provision")
    except ImportError:
        pass

1.3.14 版本中的新功能。

attribute loaded_dbapi

attribute max_identifier_length: int = 9999

标识符名称的最大长度。

attribute name: str = 'default'

方言的从 DBAPI 中立点来看的标识名称（即“sqlite”）

method normalize_name(name)

如果检测到名称不区分大小写，则将给定名称转换为小写。

仅当方言定义 requires_name_normalize=True 时才使用此方法。

method on_connect()

返回一个可调用对象，该对象设置新创建的 DBAPI 连接。

这个可调用函数应该接受一个名为“conn”的参数，它就是 DBAPI 连接本身。内部可调用函数没有返回值。

例如：

class MyDialect(default.DefaultDialect):
    # ...

    def on_connect(self):
        def do_on_connect(connection):
            connection.execute("SET SPECIAL FLAGS etc")

        return do_on_connect

用于设置方言范围内的每个连接的选项，例如隔离模式、Unicode 模式等。

“do_on_connect” 可调用函数是通过使用 PoolEvents.connect() 事件钩子来调用的，然后解包 DBAPI 连接并将其传递给可调用函数。

在 1.4 版本中更改：不再为方言的第一个连接调用两次 on_connect 钩子。然而，在 Dialect.initialize() 方法之前仍会调用 on_connect 钩子。

在 1.4.3 版本中更改：从一个新方法 on_connect_url 调用 on_connect 钩子，该方法传递用于创建连接参数的 URL。如果方言需要使用用于连接的 URL 对象来获取附加上下文，则可以实现 on_connect_url 而不是 on_connect。

如果返回 None，则不生成事件监听器。

返回：

一个可调用的函数，接受一个单一的 DBAPI 连接作为参数，或者为 None。

另请参阅

Dialect.connect() - 允许控制 DBAPI connect() 序列本身。

Dialect.on_connect_url() - 取代了 Dialect.on_connect() 来接收上下文中的 URL 对象。

method on_connect_url(url: URL) → Callable[[Any], Any] | None

继承自 Dialect 的 Dialect.on_connect_url() *方法。

返回一个可调用的函数，用于设置新创建的 DBAPI 连接。

当由方言实现时，这个方法是一个新的钩子，它取代了 Dialect.on_connect() 方法。当方言没有实现时，它直接调用 Dialect.on_connect() 方法，以保持与现有方言的兼容性。不会为 Dialect.on_connect() 预期进行弃用。

这个可调用函数应该接受一个名为“conn”的参数，它就是 DBAPI 连接本身。内部可调用函数没有返回值。

例如：

class MyDialect(default.DefaultDialect):
    # ...

    def on_connect_url(self, url):
        def do_on_connect(connection):
            connection.execute("SET SPECIAL FLAGS etc")

        return do_on_connect

用于设置方言范围内的每个连接的选项，例如隔离模式、Unicode 模式等。

这个方法与 Dialect.on_connect() 不同之处在于，它接收与连接参数相关的 URL 对象。通常，从 Dialect.on_connect() 钩子获取这个对象的唯一方式是查看 Engine 本身，但是这个 URL 对象可能已经被插件替换。

注意

Dialect.on_connect_url() 的默认实现是调用 Dialect.on_connect() 方法。因此，如果一个方言实现了这个方法，那么除非覆盖方言直接从这里调用，否则不会调用 Dialect.on_connect() 方法。

版本 1.4.3 中的新内容：增加了 Dialect.on_connect_url()，它通常调用 Dialect.on_connect()。

参数：

url – 表示传递给 Dialect.create_connect_args() 方法的 URL 的 URL 对象。

返回：

一个可接受单个 DBAPI 连接作为参数的可调用对象，或者为 None。

另请参见

Dialect.on_connect()

attribute paramstyle: str

将要使用的参数风格（某些 DB-API 支持多个参数风格）。

attribute positional: bool

如果这个 Dialect 的参数风格是按位置的，则为 True。

attribute preexecute_autoincrement_sequences: bool = False

如果没有使用 RETURNING，则‘implicit’ 主键函数必须分别执行以获取它们的值，则为 True。

当在 Table 对象上使用 implicit_returning=False 参数时，这目前是针对 PostgreSQL 的。

attribute preparer

IdentifierPreparer 的别名

attribute reflection_options: Sequence[str] = ()

继承自 Dialect 的 Dialect.reflection_options 属性

一个字符串名称序列，指示可以在使用 Table.autoload_with 时作为“反射选项”传递的关键字参数，这些参数将在 Table 对象上设置。

当前示例是 Oracle 方言中的“oracle_resolve_synonyms”。

method reset_isolation_level(dbapi_conn)

给定一个 DBAPI 连接，将其隔离恢复为默认值。

请注意，这是一个方言级方法，用作Connection和Engine隔离级别设施的实现的一部分；这些 API 应该优先用于大多数典型用例。

另请参阅

Connection.get_isolation_level() - 查看当前级别

Connection.default_isolation_level - 查看默认级别

Connection.execution_options.isolation_level - 设置每个Connection的隔离级别

create_engine.isolation_level - 设置每个Engine的隔离级别

attribute returns_native_bytes: bool = False

指示 Python bytes()对象是否由驱动程序原生返回 SQL“binary”数据类型。

新版本 2.0.11 中提供。

attribute sequences_optional: bool = False

如果为 True，则表示Sequence.optional参数在Sequence构造上是否应该发出信号以不生成 CREATE SEQUENCE。仅适用于支持序列的方言。目前仅用于允许在指定 Sequence()用于其他后端的列上使用 PostgreSQL SERIAL。

attribute server_side_cursors: bool = False

已弃用；指示方言是否应尝试默认使用服务器端游标

attribute server_version_info: Tuple[Any, ...] | None = None

包含正在使用的 DB 后端的版本号的元组。

此值仅适用于支持的方言，并且通常在初始连接到数据库时填充。

method set_connection_execution_options(connection: Connection, opts: Mapping[str, Any]) → None

为给定连接建立执行选项。

这由DefaultDialect实现，以实现Connection.execution_options.isolation_level执行选项。方言可以拦截各种执行选项，这些选项可能需要修改特定 DBAPI 连接上的状态。

新版本 1.4 中提供。

method set_engine_execution_options(engine: Engine, opts: Mapping[str, Any]) → None

为给定引擎建立执行选项。

这由DefaultDialect实现，用于为给定的Engine创建的新Connection实例建立事件钩子，然后调用该连接的Dialect.set_connection_execution_options()方法。

method set_isolation_level(dbapi_connection: DBAPIConnection, level: Literal['SERIALIZABLE', 'REPEATABLE READ', 'READ COMMITTED', 'READ UNCOMMITTED', 'AUTOCOMMIT']) → None

继承自 Dialect 的 Dialect.set_isolation_level() 方法

给定一个 DBAPI 连接，设置其隔离级别。

注意，这是一个方言级方法，用作Connection和Engine隔离级别功能的实现的一部分；对于大多数典型用例，应优先使用这些 API。

如果方言还实现了Dialect.get_isolation_level_values()方法，则给定的级别将保证是该序列中的字符串名称之一，且该方法不需要预先考虑查找失败。

另请参阅

Connection.get_isolation_level() - 查看当前级别

Connection.default_isolation_level - 查看默认级别

Connection.execution_options.isolation_level - 设置每个Connection的隔离级别

create_engine.isolation_level - 设置每个Engine的隔离级别

attribute statement_compiler

SQLCompiler的别名

attribute supports_alter: bool = True

如果数据库支持ALTER TABLE，则为True - 仅在某些情况下用于生成外键约束

attribute supports_comments: bool = False

表明方言支持对表和列进行评论的 DDL。

attribute supports_constraint_comments: bool = False

表示方言是否支持对约束进行评论的 DDL。

attribute supports_default_metavalue: bool = False

方言支持 INSERT… VALUES (DEFAULT)语法

attribute supports_default_values: bool = False

方言支持 INSERT… DEFAULT VALUES 语法

attribute supports_empty_insert: bool = True

方言支持 INSERT () VALUES ()

attribute supports_identity_columns: bool = False

目标数据库支持 IDENTITY

attribute supports_multivalues_insert: bool = False

目标数据库支持使用多个值集合的 INSERT…VALUES，即 INSERT INTO table (cols) VALUES (…), (…), (…), …

attribute supports_native_boolean: bool = False

指示方言是否支持本地布尔构造。这将阻止 Boolean 在使用该类型时生成 CHECK 约束。

attribute supports_native_decimal: bool = False

指示 Decimal 对象是否被处理并返回为精度数字类型，或者返回浮点数。

attribute supports_native_enum: bool = False

指示方言是否支持本地 ENUM 构造。这将阻止 Enum 在“本地”模式下使用时生成 CHECK 约束。

attribute supports_native_uuid: bool = False

指示 Python UUID() 对象是否由驱动程序原生处理 SQL UUID 数据类型。

新于版本 2.0。

attribute supports_sane_multi_rowcount: bool = True

指示方言是否正确地实现了通过 executemany 执行的 UPDATE 和 DELETE 语句的 rowcount。

attribute supports_sane_rowcount: bool = True

指示方言是否正确地实现了 UPDATE 和 DELETE 语句的 rowcount。

attribute supports_sane_rowcount_returning

如果此方言支持使用 RETURNING，则即使使用 RETURNING，也支持合理的行数。

对于不支持 RETURNING 的方言，这与 supports_sane_rowcount 是同义词。

attribute supports_sequences: bool = False

指示方言是否支持 CREATE SEQUENCE 或类似操作。

attribute supports_server_side_cursors: bool = False

指示方言是否支持服务器端游标。

attribute supports_simple_order_by_label: bool = True

目标数据库支持 ORDER BY ，其中 是 SELECT 的列子句中的标签。

attribute supports_statement_cache: bool = True

指示此方言是否支持缓存。

所有与语句缓存兼容的方言都应该在每个支持它的方言类和子类上直接设置此标志为 True。SQLAlchemy 在使用语句缓存之前会测试每个方言子类上是否本地存在此标志。这是为了提供对尚未完全测试以符合 SQL 语句缓存的旧版或新版方言的安全性。

新于版本 1.4.5。

另请参阅

第三方方言的缓存

attribute tuple_in_values: bool = False

目标数据库支持元组 IN，即 (x, y) IN ((q, p), (r, z))

attribute type_compiler: Any

传统的；这是一个在类级别的 TypeCompiler 类，在实例级别的 TypeCompiler 实例。

参考 type_compiler_instance。

attribute type_compiler_cls

GenericTypeCompiler 的别名。

attribute type_compiler_instance: TypeCompiler

用于编译 SQL 类型对象的 Compiled 类的实例。

新于版本 2.0。

method type_descriptor(typeobj)

提供一个特定于数据库的 TypeEngine 对象，给定来自 types 模块的通用对象。

此方法寻找一个名为 colspecs 的字典，作为类或实例级变量，并传递给 adapt_type()。

attribute update_executemany_returning: bool = False

方言是否支持 UPDATE…RETURNING 与 executemany。

attribute update_returning: bool = False

如果方言支持使用 RETURNING 的 UPDATE

新于版本 2.0。

attribute update_returning_multifrom: bool = False

如果方言支持使用 RETURNING 的 UPDATE…FROM

新于版本 2.0。

attribute use_insertmanyvalues: bool = False

如果为 True，则表示应使用“insertmanyvalues”功能，以允许进行insert_executemany_returning行为，如果可能的话。

在实践中，将其设置为 True 意味着：

如果supports_multivalues_insert、insert_returning和use_insertmanyvalues都为 True，则 SQL 编译器将生成一个 INSERT，由DefaultDialect解释为ExecuteStyle.INSERTMANYVALUES执行，允许通过将单行 INSERT 语句重写为具有多个 VALUES 子句来 INSERT 多行并在给定大量行时多次执行语句以进行一系列批处理。

对于默认方言，该参数为 False，并且对于 SQLAlchemy 内部方言 SQLite、MySQL/MariaDB、PostgreSQL、SQL Server，该参数设置为 True。对于提供本地“带 RETURNING 的 executemany”支持且不支持supports_multivalues_insert的 Oracle，该参数保持为 False。对于不支持 RETURNING 的 MySQL/MariaDB，这些 MySQL 方言将不会报告insert_executemany_returning为 True。

版本 2.0 中的新功能。

另请参见

“插入多个值”行为适用于 INSERT 语句

attribute use_insertmanyvalues_wo_returning: bool = False

如果为 True，并且 use_insertmanyvalues 也为 True，则不包括 RETURNING 的 INSERT 语句也将使用“insertmanyvalues”。

版本 2.0 中的新功能。

另请参见

“插入多个值”行为适用于 INSERT 语句

class sqlalchemy.engine.Dialect

定义特定数据库和 DB-API 组合的行为。

元数据定义、SQL 查询生成、执行、结果集处理或其他在数据库之间变化的任何方面都在方言的一般类别下定义。方言充当其他特定于数据库的对象实现的工厂，包括 ExecutionContext、Compiled、DefaultGenerator 和 TypeEngine。

注意

第三方方言不应直接子类化Dialect。而应该子类化DefaultDialect或后代类。

成员

bind_typing, colspecs, connect(), construct_arguments, create_connect_args(), create_xid(), cte_follows_insert, dbapi, dbapi_exception_translation_map, ddl_compiler, default_isolation_level, default_metavalue_token, default_schema_name, default_sequence_base, delete_executemany_returning, delete_returning, delete_returning_multifrom, denormalize_name(), div_is_floordiv, do_begin(), do_begin_twophase(), do_close(), do_commit(), do_commit_twophase(), do_execute(), do_execute_no_params(), do_executemany(), do_ping(), do_prepare_twophase(), do_recover_twophase(), do_release_savepoint(), do_rollback(), do_rollback_to_savepoint(), do_rollback_twophase(), do_savepoint(), do_set_input_sizes(), do_terminate(), driver, engine_config_types, engine_created(), exclude_set_input_sizes, execute_sequence_format, execution_ctx_cls, favor_returning_over_lastrowid, get_async_dialect_cls(), get_check_constraints(), get_columns(), get_default_isolation_level(), get_dialect_cls(), get_dialect_pool_class(), get_driver_connection(), get_foreign_keys(), get_indexes(), get_isolation_level(), get_isolation_level_values(), get_materialized_view_names(), get_multi_check_constraints(), get_multi_columns(), get_multi_foreign_keys(), get_multi_indexes(), get_multi_pk_constraint(), get_multi_table_comment(), get_multi_table_options(), get_multi_unique_constraints(), get_pk_constraint(), get_schema_names(), get_sequence_names(), get_table_comment(), get_table_names(), get_table_options(), get_temp_table_names(), get_temp_view_names(), get_unique_constraints(), get_view_definition(), get_view_names(), has_index(), has_schema(), has_sequence(), has_table(), has_terminate, identifier_preparer, import_dbapi(), include_set_input_sizes, initialize(), inline_comments, insert_executemany_returning, insert_executemany_returning_sort_by_parameter_order, insert_returning, insertmanyvalues_implicit_sentinel, insertmanyvalues_max_parameters, insertmanyvalues_page_size, is_async, is_disconnect(), label_length, load_provisioning(), loaded_dbapi, max_identifier_length, name, normalize_name(), on_connect(), on_connect_url(), paramstyle, positional, preexecute_autoincrement_sequences, preparer, reflection_options, reset_isolation_level(), returns_native_bytes, sequences_optional, server_side_cursors, server_version_info, set_connection_execution_options(), set_engine_execution_options(), set_isolation_level(), statement_compiler, supports_alter, supports_comments, supports_constraint_comments, supports_default_metavalue, supports_default_values, supports_empty_insert, supports_identity_columns, supports_multivalues_insert, supports_native_boolean, supports_native_decimal, supports_native_enum, supports_native_uuid, supports_sane_multi_rowcount, supports_sane_rowcount, supports_sequences, supports_server_side_cursors, supports_simple_order_by_label, supports_statement_cache, tuple_in_values, type_compiler, type_compiler_cls, type_compiler_instance, type_descriptor(), update_executemany_returning, update_returning, update_returning_multifrom, use_insertmanyvalues, use_insertmanyvalues_wo_returning

类签名

类sqlalchemy.engine.Dialect（sqlalchemy.event.registry.EventTarget）

attribute bind_typing = 1

定义一种将类型信息传递给数据库和/或驱动程序以用于绑定参数的方法。

请参阅BindTyping以获取值。

2.0 版本中的新功能。

attribute colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]]

从 sqlalchemy.types 映射到特定于方言类的子类的 TypeEngine 类的字典。此字典仅在类级别上存在，不从方言实例本身访问。

method connect(*cargs: Any, **cparams: Any) → DBAPIConnection

使用此方言的 DBAPI 建立连接。

此方法的默认实现是：

def connect(self, *cargs, **cparams):
    return self.dbapi.connect(*cargs, **cparams)

*cargs, **cparams参数直接从此方言的Dialect.create_connect_args()方法生成。

当需要在从 DBAPI 获取新连接时执行程序化的每个连接步骤时，可以使用此方法进行方言处理。

参数：

• *cargs – 从Dialect.create_connect_args()方法返回的位置参数
• **cparams – 从Dialect.create_connect_args()方法返回的关键字参数。

返回：

一个 DBAPI 连接，通常来自PEP 249模块级别的.connect()函数。

另请参阅

Dialect.create_connect_args()

Dialect.on_connect()

attribute construct_arguments: List[Tuple[Type[SchemaItem | ClauseElement], Mapping[str, Any]]] | None = None

各种 SQLAlchemy 构造的可选参数说明，通常是模式项。

要实现，建立为一系列元组，如下所示：

construct_arguments = [
    (schema.Index, {
        "using": False,
        "where": None,
        "ops": None
    })
]

如果上述构造在 PostgreSQL 方言上建立，则Index构造现在将接受关键字参数postgresql_using、postgresql_where和postgresql_ops。任何其他指定给Index构造函数的以postgresql_为前缀的参数都将引发ArgumentError。

不包括construct_arguments成员的方言将不参与参数验证系统。对于这样的方言，所有参与构造的命名空间中以该方言名称为前缀的参数名称都被所有参与构造接受。这里的理由是，尚未实现此功能的第三方方言将继续以旧方式运行。

另请参阅

DialectKWArgs - 实现基类，消耗DefaultDialect.construct_arguments

method create_connect_args(url: URL) → ConnectArgsType

构建与 DB-API 兼容的连接参数。

给定一个URL对象，返回一个元组，包含一个适合直接发送到 dbapi 的 connect 函数的(*args, **kwargs)。这些参数将发送到Dialect.connect()方法，然后运行 DBAPI 级别的connect()函数。

该方法通常使用URL.translate_connect_args()方法来生成一个选项字典。

默认实现为：

def create_connect_args(self, url):
    opts = url.translate_connect_args()
    opts.update(url.query)
    return ([], opts)

参数：

url – 一个URL对象

返回：

一个(*args, **kwargs)元组，将传递给Dialect.connect()方法。

另请参阅

URL.translate_connect_args()

method create_xid() → Any

创建一个两阶段事务 ID。

此 ID 将传递给 do_begin_twophase()、do_rollback_twophase()、do_commit_twophase()。其格式未指定。

attribute cte_follows_insert: bool

目标数据库，在给定带有 INSERT 语句的 CTE 时，需要 CTE 位于 INSERT 语句下方。

attribute dbapi: ModuleType | None

对 DBAPI 模块对象本身的引用。

SQLAlchemy 方言使用类方法Dialect.import_dbapi()导入 DBAPI 模块。其原理是任何方言模块都可以被导入并用于生成 SQL 语句，而无需安装实际的 DBAPI 驱动程序。只有在使用create_engine()构造Engine时才会导入 DBAPI；在那时，创建过程将把 DBAPI 模块分配给此属性。

因此，方言应该实现Dialect.import_dbapi()方法，该方法将导入必要的模块并返回它，然后在方言代码中引用self.dbapi以引用 DBAPI 模块内容。

自版本更改：Dialect.dbapi属性是作为每个Dialect实例对 DBAPI 模块的引用。以前未完全记录的.Dialect.dbapi()类方法已被弃用，并由Dialect.import_dbapi()替换。

attribute dbapi_exception_translation_map: Mapping[str, str] = {}

一个名称字典，其值将包含 pep-249 异常的名称（“IntegrityError”，“OperationalError”等），键为备用类名，以支持 DBAPI 具有未按其引用命名的异常类的情况（例如，IntegrityError = MyException）。在绝大多数情况下，此字典为空。

attribute ddl_compiler: Type[DDLCompiler]

用于编译 DDL 语句的Compiled类。

attribute default_isolation_level: IsolationLevel | None

在新连接上隐式存在的隔离性。

attribute default_metavalue_token: str = 'DEFAULT'

对于 INSERT… VALUES (DEFAULT)语法，放在括号中的标记。

例如，对于 SQLite，这是关键字“NULL”。

attribute default_schema_name: str | None

默认模式的名称。此值仅适用于支持方言，并且通常在与数据库的初始连接期间填充。

attribute default_sequence_base: int

将默认值转换为 CREATE SEQUENCE DDL 语句的“START WITH”部分。

attribute delete_executemany_returning: bool

支持使用executemany的DELETE..RETURNING方言。

attribute delete_returning: bool

如果方言支持带DELETE的RETURNING。

自版本 2.0 开始新增。

attribute delete_returning_multifrom: bool

如果方言支持DELETE..FROM带RETURNING。

自版本 2.0 开始新增。

method denormalize_name(name: str) → str

如果名称为全小写，则将给定名称转换为后端的不区分大小写的标识符。

仅当方言定义了requires_name_normalize=True时才会使用此方法。

attribute div_is_floordiv: bool

目标数据库将/运算符视为“floor division”。

method do_begin(dbapi_connection: PoolProxiedConnection) → None

提供给定 DB-API 连接的connection.begin()的实现。

DBAPI 没有专用的“begin”方法，并且预计事务是隐式的。为那些可能需要在此区域提供额外帮助的 DBAPI 提供此挂钩。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在ConnectionFairy内代理。

method do_begin_twophase(connection: Connection, xid: Any) → None

在给定连接上开始一个两阶段事务。

参数：

• connection – 一个Connection。
• xid – xid

method do_close(dbapi_connection: DBAPIConnection) → None

提供给定 DBAPI 连接的connection.close()的实现。

当连接已从池中分离或超出池的正常容量返回时，Pool将调用此挂钩。

method do_commit(dbapi_connection: PoolProxiedConnection) → None

提供给定 DB-API 连接的connection.commit()的实现。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在ConnectionFairy内代理。

method do_commit_twophase(connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False) → None

在给定连接上提交一个两阶段事务。

参数：

• connection – 一个Connection。
• xid – xid
• is_prepared – 是否调用了TwoPhaseTransaction.prepare()。
• recover – 如果传递了 recover 标志。

method do_execute(cursor: DBAPICursor, statement: str, parameters: Sequence[Any] | Mapping[str, Any] | None, context: ExecutionContext | None = None) → None

提供 cursor.execute(statement, parameters) 的实现。

method do_execute_no_params(cursor: DBAPICursor, statement: str, context: ExecutionContext | None = None) → None

提供 cursor.execute(statement) 的实现。

不应发送参数集合。

method do_executemany(cursor: DBAPICursor, statement: str, parameters: Sequence[Sequence[Any]] | Sequence[Mapping[str, Any]], context: ExecutionContext | None = None) → None

提供 cursor.executemany(statement, parameters) 的实现。

method do_ping(dbapi_connection: DBAPIConnection) → bool

检查 DBAPI 连接并在连接可用时返回 True。

method do_prepare_twophase(connection: Connection, xid: Any) → None

在给定的连接上准备两阶段事务。

参数：

• connection – 一个Connection。
• xid – xid

method do_recover_twophase(connection: Connection) → List[Any]

恢复在给定连接上未提交的准备好的两阶段事务标识符列表。

参数：

connection – 一个Connection。

method do_release_savepoint(connection: Connection, name: str) → None

在连接上释放指定的保存点。

参数：

• connection – 一个Connection。
• name – 保存点名称。

method do_rollback(dbapi_connection: PoolProxiedConnection) → None

给定 DB-API 连接，提供 connection.rollback() 的实现。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在 ConnectionFairy 中被代理。

method do_rollback_to_savepoint(connection: Connection, name: str) → None

将连接回滚到指定的保存点。

参数：

• connection – 一个Connection。
• name – 保存点名称。

method do_rollback_twophase(connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False) → None

在给定连接上回滚两阶段事务。

参数：

• connection – 一个Connection。
• xid – xid
• is_prepared – 是否调用了TwoPhaseTransaction.prepare()。
• recover – 如果传递了 recover 标志。

method do_savepoint(connection: Connection, name: str) → None

使用给定名称创建保存点。

参数：

• connection – 一个Connection。
• name – 保存点名称。

method do_set_input_sizes(cursor: DBAPICursor, list_of_tuples: _GenericSetInputSizesType, context: ExecutionContext) → Any

调用 cursor.setinputsizes() 方法并传递适当的参数。

如果 Dialect.bind_typing 属性设置为 BindTyping.SETINPUTSIZES 值，则调用此挂钩。参数数据以元组列表形式传递（paramname、dbtype、sqltype），其中 paramname 是语句中参数的键，dbtype 是 DBAPI 数据类型，sqltype 是 SQLAlchemy 类型。元组的顺序是正确的参数顺序。

新版本 1.4 中新增。

2.0 版本中的更改：- 通过将 Dialect.bind_typing 设置为 BindTyping.SETINPUTSIZES 来启用 setinputsizes 模式。接受 use_setinputsizes 参数的方言应适当设置此值。

method do_terminate(dbapi_connection: DBAPIConnection) → None

提供了一个实现 connection.close() 的方法，尽可能地避免阻塞，给定一个 DBAPI 连接。

在绝大多数情况下，这只是调用了 .close()，但对于一些 asyncio 方言可能调用了不同的 API 特性。

当连接正在被回收利用或已被废弃时，该钩子由 Pool 调用。

在版本 1.4.41 中新增。

attribute driver: str

方言的 DBAPI 的标识名称

attribute engine_config_types: Mapping[str, Any]

一个字符串键的映射，可以在引擎配置中链接到类型转换函数。

classmethod engine_created(engine: Engine) → None

在返回最终 Engine 之前调用的一个方便的钩子。

如果方言从 get_dialect_cls() 方法返回了一个不同的类，则该钩子将在两个类上调用，首先在由 get_dialect_cls() 方法返回的方言类上调用，然后在调用该方法的类上调用。

该钩子应该由方言和/或包装器使用，以应用特殊事件到引擎或其组件。特别是，它允许方言包装类应用方言级别的事件。

attribute exclude_set_input_sizes: Set[Any] | None

在自动 cursor.setinputsizes() 调用中应该排除的一组 DBAPI 类型对象。

仅在 bind_typing 为 BindTyping.SET_INPUT_SIZES 时使用。

attribute execute_sequence_format: Type[Tuple[Any, ...]] | Type[Tuple[List[Any]]]

要么是 ‘tuple’ 类型，要么是 ‘list’ 类型，取决于 cursor.execute() 对于第二个参数接受的是什么（它们会变化）。

attribute execution_ctx_cls: Type[ExecutionContext]

用于处理语句执行的 ExecutionContext 类。

attribute favor_returning_over_lastrowid: bool

对于同时支持 lastrowid 和 RETURNING 插入策略的后端，优先考虑 RETURNING 用于简单的单整数主键插入。

cursor.lastrowid 在大多数后端上性能更好。

classmethod get_async_dialect_cls(url: URL) → Type[Dialect]

给定一个 URL，返回将由异步引擎使用的 Dialect。

默认情况下，这是 Dialect.get_dialect_cls() 的别名，并且只是返回 cls。如果方言提供了同名的同步和异步版本，如 psycopg 驱动程序，则可能会使用它。

在版本 2 中新增。

另请参阅

Dialect.get_dialect_cls()

method get_check_constraints(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedCheckConstraint]

返回 table_name 中检查约束的信息。

给定一个字符串table_name和一个可选的字符串schema，返回检查约束信息，作为与ReflectedCheckConstraint字典对应的字典列表。

这是一种内部方言方法。应用程序应该使用Inspector.get_check_constraints()。

method get_columns(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedColumn]

返回table_name中的列信息。

给定一个Connection，一个字符串table_name和一个可选的字符串schema，返回列信息，作为与ReflectedColumn字典对应的字典列表。

这是一种内部方言方法。应用程序应该使用Inspector.get_columns()。

method get_default_isolation_level(dbapi_conn: DBAPIConnection) → Literal['SERIALIZABLE', 'REPEATABLE READ', 'READ COMMITTED', 'READ UNCOMMITTED', 'AUTOCOMMIT']

给定一个 DBAPI 连接，返回其隔离级别，或者如果无法检索到隔离级别，则返回默认隔离级别。

此方法只能引发 NotImplementedError，并且不能引发任何其他异常，因为它在第一次连接时隐式使用。

该方法必须返回一个值，以便于支持隔离级别设置的方言，因为这个级别是在进行每个连接隔离级别更改时将要回滚到的级别。

该方法默认使用Dialect.get_isolation_level()方法，除非被方言覆盖。

在 1.3.22 版本中新增。

classmethod get_dialect_cls(url: URL) → Type[Dialect]

给定一个 URL，返回将要使用的Dialect。

这是一个钩子，允许外部插件围绕现有方言提供功能，通过允许根据入口点从 URL 加载插件，然后插件返回实际要使用的方言。

默认情况下，这只是返回 cls。

method get_dialect_pool_class(url: URL) → Type[Pool]

返回用于给定 URL 的 Pool 类。

method get_driver_connection(connection: DBAPIConnection) → Any

返回由外部驱动程序包返回的连接对象。

对于使用 DBAPI 兼容驱动程序的普通方言，此调用将只返回作为参数传递的connection。 对于代替适配非 DBAPI 兼容驱动程序的方言，例如在适配异步驱动程序时，此调用将返回驱动程序返回的类似连接的对象。

在 1.4.24 版本中新增。

method get_foreign_keys(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedForeignKeyConstraint]

返回table_name中的 foreign_keys 信息。

给定一个Connection、一个字符串table_name和一个可选的字符串schema，返回外键信息，作为与ReflectedForeignKeyConstraint字典对应的字典列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_foreign_keys()。

method get_indexes(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedIndex]

返回table_name中索引的信息。

给定一个Connection、一个字符串table_name和一个可选的字符串schema，返回索引信息，作为与ReflectedIndex字典对应的字典列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_indexes()。

method get_isolation_level(dbapi_connection: DBAPIConnection) → Literal['SERIALIZABLE', 'REPEATABLE READ', 'READ COMMITTED', 'READ UNCOMMITTED', 'AUTOCOMMIT']

给定一个 DBAPI 连接，返回其隔离级别。

在使用Connection对象时，可以使用Connection.connection访问器获取相应的 DBAPI 连接。

请注意，这是一个方言级别的方法，用作Connection和Engine隔离级别功能实现的一部分；这些 API 应该优先用于大多数典型用例。

另请参阅

Connection.get_isolation_level() - 查看当前级别

Connection.default_isolation_level - 查看默认级别

Connection.execution_options.isolation_level - 设置每个Connection的隔离级别

create_engine.isolation_level - 设置每个Engine的隔离级别

method get_isolation_level_values(dbapi_conn: DBAPIConnection) → List[Literal['SERIALIZABLE', 'REPEATABLE READ', 'READ COMMITTED', 'READ UNCOMMITTED', 'AUTOCOMMIT']]

返回一个由此方言接受的字符串隔离级别名称序列。

可用的名称应遵循以下约定：

• 使用大写名称。隔离级别方法将接受小写名称，但在传递给方言之前将其规范化为大写。
• 应将分隔的单词用空格分隔，而不是下划线，例如REPEATABLE READ。隔离级别名称在传递给方言之前将下划线转换为空格。
• 四个标准隔离级别名称的名称，以它们受到后端支持的程度来说应该是READ UNCOMMITTED READ COMMITTED、REPEATABLE READ、SERIALIZABLE
• 如果方言支持自动提交选项，则应使用隔离级别名称AUTOCOMMIT。
• 其他隔离模式也可能存在，只要它们以大写命名，并使用空格而不是下划线。

此函数用于默认方言检查给定的隔离级别参数是否有效，否则会引发ArgumentError。

一个 DBAPI 连接被传递给该方法，在极少情况下，方言需要询问连接本身以确定此列表，但预计大多数后端将返回一个硬编码的值列表。如果方言支持“AUTOCOMMIT”，则该值也应该出现在返回的序列中。

该方法默认引发NotImplementedError。如果方言未实现此方法，则默认方言将不会在传递给Dialect.set_isolation_level()方法之前对给定的隔离级别值执行任何检查。这是为了与可能尚未实现此方法的第三方方言保持向后兼容性。

新版本 2.0 中。

method get_materialized_view_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

返回数据库中所有可用的物化视图名称列表。

这是一个内部方言方法。应用程序应使用Inspector.get_materialized_view_names()。

参数：

模式 -

要查询的模式名称，如果不是默认模式。

新版本 2.0 中。

method get_multi_check_constraints(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, List[ReflectedCheckConstraint]]]

返回给定schema中所有表的检查约束的信息。

这是一个内部方言方法。应用程序应使用Inspector.get_multi_check_constraints()。

注意

DefaultDialect 提供了一个默认实现，将对由 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法，取决于提供的 kind。希望支持更快实现的方言应该实现此方法。

从版本 2.0 开始。

method get_multi_columns(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, List[ReflectedColumn]]]

返回给定 schema 中所有表中列的信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_columns()。

注意

DefaultDialect 提供了一个默认实现，将对由 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法，取决于提供的 kind。希望支持更快实现的方言应该实现此方法。

从版本 2.0 开始。

method get_multi_foreign_keys(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, List[ReflectedForeignKeyConstraint]]]

返回给定 schema 中所有表中外键的信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_foreign_keys()。

注意

DefaultDialect 提供了一个默认实现，将对由 Dialect.get_table_names()、Dialect.get_view_names() 或 Dialect.get_materialized_view_names() 返回的每个对象调用单个表方法，取决于提供的 kind。希望支持更快实现的方言应该实现此方法。

从版本 2.0 开始。

method get_multi_indexes(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, List[ReflectedIndex]]]

返回给定 schema 中所有表中索引的信息。

这是一个内部方言方法。应用程序应该使用 Inspector.get_multi_indexes()。

注意

DefaultDialect提供了一个默认实现，将根据提供的kind调用Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()中的每个对象的单表方法。希望支持更快实现的方言应该实现这个方法。

版本 2.0 中新增。

method get_multi_pk_constraint(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, ReflectedPrimaryKeyConstraint]]

返回给定schema中所有表的主键约束信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_pk_constraint()。

注意

DefaultDialect提供了一个默认实现，将根据提供的kind调用Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()中的每个对象的单表方法。希望支持更快实现的方言应该实现这个方法。

版本 2.0 中新增。

method get_multi_table_comment(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, ReflectedTableComment]]

返回给定schema中所有表的表注释信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_table_comment()。

注意

DefaultDialect提供了一个默认实现，将根据提供的kind调用Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()中的每个对象的单表方法。希望支持更快实现的方言应该实现这个方法。

版本 2.0 中新增。

method get_multi_table_options(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, Dict[str, Any]]]

返回在创建给定schema中的表时指定的选项字典。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_table_options()。

注意

DefaultDialect提供了一个默认实现，将根据提供的kind调用每个对象的单表方法Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()。想要支持更快实现的方言应该实现这个方法。

新版本 2.0 中引入。

method get_multi_unique_constraints(connection: Connection, schema: str | None = None, filter_names: Collection[str] | None = None, **kw: Any) → Iterable[Tuple[TableKey, List[ReflectedUniqueConstraint]]]

返回给定schema中所有表的唯一约束信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_multi_unique_constraints()。

注意

DefaultDialect提供了一个默认实现，将根据提供的kind调用每个对象的单表方法Dialect.get_table_names()、Dialect.get_view_names()或Dialect.get_materialized_view_names()。想要支持更快实现的方言应该实现这个方法。

新版本 2.0 中引入。

method get_pk_constraint(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → ReflectedPrimaryKeyConstraint

返回table_name表上主键约束的信息。

给定一个Connection、一个字符串table_name和一个可选的字符串schema，返回作为字典对应于ReflectedPrimaryKeyConstraint字典的主键信息。

这是一个内部方言方法。应用程序应该使用Inspector.get_pk_constraint()。

method get_schema_names(connection: Connection, **kw: Any) → List[str]

返回数据库中所有模式名称的列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_schema_names()。

method get_sequence_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

返回数据库中所有序列名称的列表。

这是一个内部方言方法。应用程序应该使用Inspector.get_sequence_names()。

参数：

schema - 要查询的模式名称，如果不是默认模式。

新版本 1.4 中引入。

method get_table_comment(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → ReflectedTableComment

返回由table_name标识的表的“注释”。

给定一个字符串table_name和一个可选的字符串schema，返回一个对应于ReflectedTableComment字典的表注释信息字典。

这是一个内部方言方法。应用程序应使用Inspector.get_table_comment()。

引发：

对于不支持注释的方言，抛出NotImplementedError。

版本 1.2 中的新功能。

method get_table_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

返回schema的表名称列表。

这是一个内部方言方法。应用程序应使用Inspector.get_table_names()。

method get_table_options(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → Dict[str, Any]

返回创建table_name时指定的选项字典。

这是一个内部方言方法。应用程序应使用Inspector.get_table_options()。

method get_temp_table_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

返回给定连接上的临时表名称列表（如果底层后端支持）。

这是一个内部方言方法。应用程序应使用Inspector.get_temp_table_names()。

method get_temp_view_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

返回给定连接上的临时视图名称列表（如果底层后端支持）。

这是一个内部方言方法。应用程序应使用Inspector.get_temp_view_names()。

method get_unique_constraints(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → List[ReflectedUniqueConstraint]

返回table_name中关于唯一约束的信息。

给定一个字符串table_name和一个可选的字符串schema，返回一个对应于ReflectedUniqueConstraint字典的唯一约束信息列表。

这是一个内部方言方法。应用程序应使用Inspector.get_unique_constraints()。

method get_view_definition(connection: Connection, view_name: str, schema: str | None = None, **kw: Any) → str

返回普通或物化视图定义。

这是一个内部方言方法。应用程序应使用Inspector.get_view_definition()。

给定一个Connection对象，一个字符串view_name和一个可选的字符串schema，返回视图定义。

method get_view_names(connection: Connection, schema: str | None = None, **kw: Any) → List[str]

返回数据库中所有非物化视图名称的列表。

这是一个内部方言方法。应用程序应使用Inspector.get_view_names()。

参数：

schema – 查询的模式名称，如果不是默认模式。

method has_index(connection: Connection, table_name: str, index_name: str, schema: str | None = None, **kw: Any) → bool

检查数据库中特定索引名称的存在。

给定一个Connection对象，一个字符串table_name和字符串索引名称，如果给定表上存在给定名称的索引，则返回True，否则返回False。

DefaultDialect根据Dialect.has_table()和Dialect.get_indexes()方法实现此功能，但是方言可以实现更高效的版本。

这是一个内部方言方法。应用程序应该使用Inspector.has_index()。

新版本 1.4 中新增。

method has_schema(connection: Connection, schema_name: str, **kw: Any) → bool

检查数据库中特定模式名称的存在。

给定一个Connection对象和一个字符串schema_name，如果给定的架构存在，则返回True，否则返回False。

DefaultDialect通过检查Dialect.get_schema_names()返回的模式中是否存在schema_name来实现此功能，但是方言可以实现更高效的版本。

这是一个内部方言方法。应用程序应该使用Inspector.has_schema()。

新版本 2.0 中新增。

method has_sequence(connection: Connection, sequence_name: str, schema: str | None = None, **kw: Any) → bool

检查数据库中特定序列的存在。

给定一个Connection对象和一个字符串sequence_name，如果数据库中存在给定的序列，则返回True，否则返回False。

这是一个内部方言方法。应用程序应该使用Inspector.has_sequence()。

method has_table(connection: Connection, table_name: str, schema: str | None = None, **kw: Any) → bool

对内部方言使用，检查数据库中特定表或视图的存在。

给定一个Connection对象，一个字符串table_name和可选的模式名称，如果数据库中存在给定的表，则返回True，否则返回False。

此方法作为公共面向用户的Inspector.has_table()方法的基础实现，并且还在内部用于实现像Table.create()和MetaData.create_all()等方法的“checkfirst”行为。

注意

此方法在 SQLAlchemy 内部使用，并公开以便第三方方言可以提供实现。这不是用于检查表存在的公共 API。请使用Inspector.has_table()方法。

从版本 2.0 开始更改：Dialect.has_table()现在正式支持检查其他类似表的对象：

• 任何类型的视图（普通或材料化）
• 任何类型的临时表

以前，这两个检查没有正式规定，不同的方言在行为上会有所不同。方言测试套件现在包括对所有这些对象类型的测试，以及在支持视图或临时表的程度上应该寻求支持定位这些对象以实现完全的兼容性。

attribute has_terminate: bool

此方言是否具有单独的“终止”实现，不会阻塞或需要等待。

attribute identifier_preparer: IdentifierPreparer

一旦构建了DefaultDialect的实例，此元素将引用一个IdentifierPreparer的实例。

classmethod import_dbapi() → module

导入此方言使用的 DBAPI 模块。

此处返回的 Python 模块对象将分配为构建的方言的一个实例变量，名称为.dbapi。

从版本 2.0 开始更改：Dialect.import_dbapi()类方法从先前的方法.Dialect.dbapi()重命名，该方法将在方言实例化时由 DBAPI 模块本身替换，因此以两种不同的方式使用相同的名称。如果第三方方言上存在.Dialect.dbapi()类方法，将使用它并发出弃用警告。

attribute include_set_input_sizes: Set[Any] | None

应包括在自动 cursor.setinputsizes()调用中的一组���该包含的 DBAPI 类型对象。

仅在 bind_typing 为 BindTyping.SET_INPUT_SIZES 时使用。

method initialize(connection: Connection) → None

在连接的策略化创建期间调用与连接一起的方言。

允许方言根据服务器版本信息或其他属性配置选项。

此处传递的连接是一个完全具备功能的 SQLAlchemy Connection 对象。

应通过 super()调用基本方言的 initialize()方法。

注意

从 SQLAlchemy 1.4 开始，此方法在调用任何Dialect.on_connect()钩子之前被调用。

attribute inline_comments: bool

表示方言支持与表或列的定义相一致的内联注释 DDL。如果为 False，则意味着必须使用 ALTER 来设置表和列的注释。

attribute insert_executemany_returning: bool

当使用dialect.do_executemany()时，方言/驱动程序/数据库支持某种方式提供 INSERT…RETURNING 支持。

attribute insert_executemany_returning_sort_by_parameter_order: bool

当使用Insert.returning.sort_by_parameter_order参数设置时，方言/驱动程序/数据库支持某种方式提供 INSERT…RETURNING 支持，同时使用dialect.do_executemany()。

attribute insert_returning: bool

如果方言支持 INSERT 时的 RETURNING

2.0 版本中的新功能。

attribute insertmanyvalues_implicit_sentinel: InsertmanyvaluesSentinelOpts

表示数据库支持一种形式的批量插入，其中自增整数主键可可靠用作插入行的排序。

2.0.10 版本中的新功能。

另请参阅

将 RETURNING 行与参数集相关联

attribute insertmanyvalues_max_parameters: int

insertmanyvalues_page_size 的替代方案，还将基于语句中参数的总数限制页面大小。

attribute insertmanyvalues_page_size: int