定义约束和索引¶

本节将讨论 SQL 约束和索引。在 SQLAlchemy 中，关键类包括 ForeignKeyConstraint 和 Index。

定义外键¶

SQL 中的外键是一种表级结构，它约束表中的一个或多个列，使其仅允许出现在不同列集中的值，这些列集通常但不一定位于不同的表中。我们将被约束的列称为外键列，将它们约束指向的列称为被引用列。被引用列几乎总是定义其所属表的主键，尽管也有例外。外键是将彼此之间具有关系的行对连接在一起的“连接点”，SQLAlchemy 在其几乎所有操作领域都非常重视这个概念。

在 SQLAlchemy 以及 DDL 中，外键约束可以定义为表子句中的附加属性，或者对于单列外键，它们也可以选择在单个列的定义中指定。单列外键更常见，并且在列级别通过构造 ForeignKey 对象作为 Column 对象的参数来指定

user_preference = Table(
    "user_preference",
    metadata_obj,
    Column("pref_id", Integer, primary_key=True),
    Column("user_id", Integer, ForeignKey("user.user_id"), nullable=False),
    Column("pref_name", String(40), nullable=False),
    Column("pref_value", String(100)),
)

上面，我们定义了一个新表 user_preference，其中每行必须包含 user_id 列中的值，该值也存在于 user 表的 user_id 列中。

ForeignKey 的参数最常见的是 <tablename>.<columnname> 形式的字符串，或者对于远程模式或“所有者”中的表，形式为 <schemaname>.<tablename>.<columnname>。它也可以是实际的 Column 对象，我们稍后将看到，它是通过其 c 集合从现有的 Table 对象访问的

ForeignKey(user.c.user_id)

使用字符串的优点是 user 和 user_preference 之间的 Python 内部链接仅在首次需要时才解析，因此表对象可以轻松地分布在多个模块中并以任何顺序定义。

外键也可以在表级别定义，使用 ForeignKeyConstraint 对象。此对象可以描述单列或多列外键。多列外键称为复合外键，几乎总是引用具有复合主键的表。下面我们定义一个具有复合主键的表 invoice

invoice = Table(
    "invoice",
    metadata_obj,
    Column("invoice_id", Integer, primary_key=True),
    Column("ref_num", Integer, primary_key=True),
    Column("description", String(60), nullable=False),
)

然后是一个表 invoice_item，它具有引用 invoice 的复合外键

invoice_item = Table(
    "invoice_item",
    metadata_obj,
    Column("item_id", Integer, primary_key=True),
    Column("item_name", String(60), nullable=False),
    Column("invoice_id", Integer, nullable=False),
    Column("ref_num", Integer, nullable=False),
    ForeignKeyConstraint(
        ["invoice_id", "ref_num"], ["invoice.invoice_id", "invoice.ref_num"]
    ),
)

重要的是要注意，ForeignKeyConstraint 是定义复合外键的唯一方法。虽然我们也可以在 invoice_item.invoice_id 和 invoice_item.ref_num 列上放置单独的 ForeignKey 对象，但 SQLAlchemy 不会意识到这两个值应该配对在一起 - 这将是两个单独的外键约束，而不是引用两列的单个复合外键。

通过 ALTER 创建/删除外键约束¶

我们在教程和其他地方看到的关于带有 DDL 的外键的行为表明，约束通常在 CREATE TABLE 语句中“内联”呈现，例如

CREATE TABLE addresses (
    id INTEGER NOT NULL,
    user_id INTEGER,
    email_address VARCHAR NOT NULL,
    PRIMARY KEY (id),
    CONSTRAINT user_id_fk FOREIGN KEY(user_id) REFERENCES users (id)
)

CONSTRAINT .. FOREIGN KEY 指令用于在 CREATE TABLE 定义中以“内联”方式创建约束。MetaData.create_all() 和 MetaData.drop_all() 方法默认执行此操作，使用所涉及的所有 Table 对象的拓扑排序，以便按照外键依赖关系顺序创建和删除表（此排序也可通过 MetaData.sorted_tables 访问器获得）。

当两个或多个外键约束涉及“依赖循环”时，这种方法不起作用，其中一组表相互依赖，假设后端强制执行外键（除了 SQLite、MySQL/MyISAM 之外总是如此）。因此，这些方法会将此类循环中的约束分解为单独的 ALTER 语句，在除 SQLite 之外的所有后端上（SQLite 不支持大多数形式的 ALTER）。给定如下模式

node = Table(
    "node",
    metadata_obj,
    Column("node_id", Integer, primary_key=True),
    Column("primary_element", Integer, ForeignKey("element.element_id")),
)

element = Table(
    "element",
    metadata_obj,
    Column("element_id", Integer, primary_key=True),
    Column("parent_node_id", Integer),
    ForeignKeyConstraint(
        ["parent_node_id"], ["node.node_id"], name="fk_element_parent_node_id"
    ),
)

当我们在 PostgreSQL 后端等后端上调用 MetaData.create_all() 时，这两个表之间的循环会被解决，约束会单独创建

>>> withengine.connect()asconn:...     metadata_obj.create_all(conn, checkfirst=False)CREATE TABLE element (
    element_id SERIAL NOT NULL,
    parent_node_id INTEGER,
    PRIMARY KEY (element_id)
)

CREATE TABLE node (
    node_id SERIAL NOT NULL,
    primary_element INTEGER,
    PRIMARY KEY (node_id)
)

ALTER TABLE element ADD CONSTRAINT fk_element_parent_node_id
    FOREIGN KEY(parent_node_id) REFERENCES node (node_id)
ALTER TABLE node ADD FOREIGN KEY(primary_element)
    REFERENCES element (element_id)

为了发出这些表的 DROP，应用相同的逻辑，但请注意，在 SQL 中，发出 DROP CONSTRAINT 需要约束具有名称。在上面的 'node' 表的情况下，我们没有命名此约束；因此，系统将尝试仅为那些已命名的约束发出 DROP

>>> withengine.connect()asconn:...     metadata_obj.drop_all(conn, checkfirst=False)ALTER TABLE element DROP CONSTRAINT fk_element_parent_node_id
DROP TABLE node
DROP TABLE element

如果循环无法解决，例如如果我们没有在此处为任何约束应用名称，我们将收到以下错误

sqlalchemy.exc.CircularDependencyError: Can't sort tables for DROP;
an unresolvable foreign key dependency exists between tables:
element, node.  Please ensure that the ForeignKey and ForeignKeyConstraint
objects involved in the cycle have names so that they can be dropped
using DROP CONSTRAINT.

此错误仅适用于 DROP 情况，因为我们可以在 CREATE 情况中发出“ADD CONSTRAINT”而无需名称；数据库通常会自动分配一个。

ForeignKeyConstraint.use_alter 和 ForeignKey.use_alter 关键字参数可用于手动解决依赖循环。我们可以仅将此标志添加到 'element' 表，如下所示

element = Table(
    "element",
    metadata_obj,
    Column("element_id", Integer, primary_key=True),
    Column("parent_node_id", Integer),
    ForeignKeyConstraint(
        ["parent_node_id"],
        ["node.node_id"],
        use_alter=True,
        name="fk_element_parent_node_id",
    ),
)

在我们的 CREATE DDL 中，我们将看到仅针对此约束的 ALTER 语句，而不是另一个约束

>>> withengine.connect()asconn:...     metadata_obj.create_all(conn, checkfirst=False)CREATE TABLE element (
    element_id SERIAL NOT NULL,
    parent_node_id INTEGER,
    PRIMARY KEY (element_id)
)

CREATE TABLE node (
    node_id SERIAL NOT NULL,
    primary_element INTEGER,
    PRIMARY KEY (node_id),
    FOREIGN KEY(primary_element) REFERENCES element (element_id)
)

ALTER TABLE element ADD CONSTRAINT fk_element_parent_node_id
FOREIGN KEY(parent_node_id) REFERENCES node (node_id)

当 ForeignKeyConstraint.use_alter 和 ForeignKey.use_alter 与 drop 操作结合使用时，将要求约束被命名，否则会生成如下错误

sqlalchemy.exc.CompileError: Can't emit DROP CONSTRAINT for constraint
ForeignKeyConstraint(...); it has no name

另请参阅

配置约束命名约定

sort_tables_and_constraints()

ON UPDATE 和 ON DELETE¶

大多数数据库支持外键值的级联，即当更新父行时，新值会放入子行中，或者当删除父行时，所有相应的子行都会设置为 null 或删除。在数据定义语言中，这些是使用诸如 “ON UPDATE CASCADE”、“ON DELETE CASCADE” 和 “ON DELETE SET NULL” 之类的短语指定的，这些短语对应于外键约束。“ON UPDATE” 或 “ON DELETE” 之后的短语也可能允许其他特定于所用数据库的短语。ForeignKey 和 ForeignKeyConstraint 对象通过 onupdate 和 ondelete 关键字参数支持此子句的生成。该值是将在相应的 “ON UPDATE” 或 “ON DELETE” 短语之后输出的任何字符串

child = Table(
    "child",
    metadata_obj,
    Column(
        "id",
        Integer,
        ForeignKey("parent.id", onupdate="CASCADE", ondelete="CASCADE"),
        primary_key=True,
    ),
)

composite = Table(
    "composite",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("rev_id", Integer),
    Column("note_id", Integer),
    ForeignKeyConstraint(
        ["rev_id", "note_id"],
        ["revisions.id", "revisions.note_id"],
        onupdate="CASCADE",
        ondelete="SET NULL",
    ),
)

请注意，当与 MySQL 一起使用时，这些子句需要 InnoDB 表。它们也可能不受其他数据库支持。

另请参阅

有关 ON DELETE CASCADE 与 ORM relationship() 构造集成的背景信息，请参阅以下章节

将外键 ON DELETE 级联与 ORM 关系一起使用

将外键 ON DELETE 与多对多关系一起使用

UNIQUE 约束¶

可以使用 Column 上的 unique 关键字在单个列上匿名创建唯一约束。显式命名的唯一约束和/或具有多列的唯一约束通过 UniqueConstraint 表级构造创建。

from sqlalchemy import UniqueConstraint

metadata_obj = MetaData()
mytable = Table(
    "mytable",
    metadata_obj,
    # per-column anonymous unique constraint
    Column("col1", Integer, unique=True),
    Column("col2", Integer),
    Column("col3", Integer),
    # explicit/composite unique constraint.  'name' is optional.
    UniqueConstraint("col2", "col3", name="uix_1"),
)

CHECK 约束¶

检查约束可以是命名的或未命名的，并且可以在列或表级别创建，使用 CheckConstraint 构造。检查约束的文本直接传递到数据库，因此“数据库独立”行为有限。列级检查约束通常应仅引用放置它们的列，而表级约束可以引用表中的任何列。

请注意，某些数据库（例如 MySQL 的旧版本（8.0.16 之前的版本））不主动支持检查约束。

fromsqlalchemyimportCheckConstraintmetadata_obj=MetaData()mytable=Table("mytable",metadata_obj,# per-column CHECK constraintColumn("col1",Integer,CheckConstraint("col1>5")),Column("col2",Integer),Column("col3",Integer),# table level CHECK constraint.  'name' is optional.CheckConstraint("col2 > col3 + 5",name="check1"),)mytable.create(engine)CREATE TABLE mytable (
    col1 INTEGER  CHECK (col1>5),
    col2 INTEGER,
    col3 INTEGER,
    CONSTRAINT check1  CHECK (col2 > col3 + 5)
)

PRIMARY KEY 约束¶

任何 Table 对象的主键约束都隐式存在，基于标记有 Column.primary_key 标志的 Column 对象。PrimaryKeyConstraint 对象提供对此约束的显式访问，其中包括直接配置的选项

from sqlalchemy import PrimaryKeyConstraint

my_table = Table(
    "mytable",
    metadata_obj,
    Column("id", Integer),
    Column("version_id", Integer),
    Column("data", String(50)),
    PrimaryKeyConstraint("id", "version_id", name="mytable_pk"),
)

另请参阅

PrimaryKeyConstraint - 详细的 API 文档。

在使用声明式 ORM 扩展时设置约束¶

Table 是 SQLAlchemy Core 构造，允许用户定义表元数据，除其他外，SQLAlchemy ORM 可以将其用作映射类的目标。声明式扩展允许自动创建 Table 对象，给定表的内容，主要作为 Column 对象映射。

要将表级约束对象（例如 ForeignKeyConstraint）应用于使用声明式定义的表，请使用 __table_args__ 属性，详见表配置。

配置约束命名约定¶

关系数据库通常为所有约束和索引分配显式名称。在常见情况下，使用 CREATE TABLE 创建表，其中 CHECK、UNIQUE 和 PRIMARY KEY 约束与表定义内联生成，数据库通常有一个系统，如果未另行指定名称，则会自动为这些约束分配名称。当使用诸如 ALTER TABLE 之类的命令在数据库中更改现有数据库表时，此命令通常需要为新约束指定显式名称，并能够指定要删除或修改的现有约束的名称。

可以使用 Constraint.name 参数显式命名约束，对于索引，可以使用 Index.name 参数。但是，对于约束，此参数是可选的。还有使用 Column.unique 和 Column.index 参数的情况，这些参数创建 UniqueConstraint 和 Index 对象，而无需指定显式名称。

现有表和约束的更改用例可以通过模式迁移工具（例如 Alembic）来处理。但是，Alembic 和 SQLAlchemy 当前都不会为名称未另行指定的约束对象创建名称，这导致了能够更改现有约束的情况，这意味着必须逆向工程关系数据库用于自动分配名称的命名系统，或者必须注意确保所有约束都已命名。

与必须为所有 Constraint 和 Index 对象分配显式名称相比，可以使用事件构建自动命名方案。这种方法的优点是，约束将获得一致的命名方案，而无需在整个代码中使用显式名称参数，并且对于由 Column.unique 和 Column.index 参数生成的约束和索引，约定也同样适用。从 SQLAlchemy 0.9.2 开始，包含此基于事件的方法，并且可以使用参数 MetaData.naming_convention 进行配置。

为 MetaData 集合配置命名约定¶

MetaData.naming_convention 引用一个字典，该字典接受 Index 类或各个 Constraint 类作为键，以及 Python 字符串模板作为值。它还接受一系列字符串代码作为备用键，"fk"、"pk"、"ix"、"ck"、"uq" 分别表示外键、主键、索引、检查和唯一约束。每当约束或索引与此 MetaData 对象关联且没有给定现有名称时（包括一个现有名称可以进一步修饰的例外情况），都会使用此字典中的字符串模板。

适用于基本情况的命名约定示例如下

convention = {
    "ix": "ix_%(column_0_label)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s",
}

metadata_obj = MetaData(naming_convention=convention)

上述约定将为目标 MetaData 集合中的所有约束建立名称。例如，我们可以观察到当我们创建未命名的 UniqueConstraint 时生成的名称

>>> user_table = Table(
...     "user",
...     metadata_obj,
...     Column("id", Integer, primary_key=True),
...     Column("name", String(30), nullable=False),
...     UniqueConstraint("name"),
... )
>>> list(user_table.constraints)[1].name
'uq_user_name'

即使我们只使用 Column.unique 标志，此相同功能也会生效

>>> user_table = Table(
...     "user",
...     metadata_obj,
...     Column("id", Integer, primary_key=True),
...     Column("name", String(30), nullable=False, unique=True),
... )
>>> list(user_table.constraints)[1].name
'uq_user_name'

命名约定方法的一个主要优点是，名称是在 Python 构造时而不是在 DDL 发出时建立的。当使用 Alembic 的 --autogenerate 功能时，其效果是在生成新的迁移脚本时，命名约定将是显式的

def upgrade():
    op.create_unique_constraint("uq_user_name", "user", ["name"])

上面的 "uq_user_name" 字符串是从 UniqueConstraint 对象复制的，--autogenerate 在我们的元数据中找到了该对象。

可用的令牌包括 %(table_name)s、%(referred_table_name)s、%(column_0_name)s、%(column_0_label)s、%(column_0_key)s、%(referred_column_0_name)s 和 %(constraint_name)s，以及每个的多列版本，包括 %(column_0N_name)s、%(column_0_N_name)s、%(referred_column_0_N_name)s，它们呈现所有列名称，并用或不用下划线分隔。MetaData.naming_convention 的文档更详细地介绍了每个约定。

默认命名约定¶

MetaData.naming_convention 的默认值处理了长期存在的 SQLAlchemy 行为，即为使用 Column.index 参数创建的 Index 对象分配名称

>>> from sqlalchemy.sql.schema import DEFAULT_NAMING_CONVENTION
>>> DEFAULT_NAMING_CONVENTION
immutabledict({'ix': 'ix_%(column_0_label)s'})

长名称的截断¶

当生成的名称，特别是那些使用多列令牌的名称，对于目标数据库的标识符长度限制（例如，PostgreSQL 的限制为 63 个字符）而言太长时，将使用基于长名称的 md5 哈希的 4 个字符后缀确定性地截断该名称。例如，以下命名约定将根据使用的列名生成非常长的名称

metadata_obj = MetaData(
    naming_convention={"uq": "uq_%(table_name)s_%(column_0_N_name)s"}
)

long_names = Table(
    "long_names",
    metadata_obj,
    Column("information_channel_code", Integer, key="a"),
    Column("billing_convention_name", Integer, key="b"),
    Column("product_identifier", Integer, key="c"),
    UniqueConstraint("a", "b", "c"),
)

在 PostgreSQL 方言中，长度超过 63 个字符的名称将被截断，如以下示例所示

CREATE TABLE long_names (
    information_channel_code INTEGER,
    billing_convention_name INTEGER,
    product_identifier INTEGER,
    CONSTRAINT uq_long_names_information_channel_code_billing_conventi_a79e
    UNIQUE (information_channel_code, billing_convention_name, product_identifier)
)

上面的后缀 a79e 基于长名称的 md5 哈希，并且每次都会生成相同的值，以便为给定的模式生成一致的名称。

为命名约定创建自定义令牌¶

也可以通过在 naming_convention 字典中指定附加令牌和可调用对象来添加新令牌。例如，如果我们想使用 GUID 方案命名我们的外键约束，我们可以这样做，如下所示

import uuid


def fk_guid(constraint, table):
    str_tokens = (
        [
            table.name,
        ]
        + [element.parent.name for element in constraint.elements]
        + [element.target_fullname for element in constraint.elements]
    )
    guid = uuid.uuid5(uuid.NAMESPACE_OID, "_".join(str_tokens).encode("ascii"))
    return str(guid)


convention = {
    "fk_guid": fk_guid,
    "ix": "ix_%(column_0_label)s",
    "fk": "fk_%(fk_guid)s",
}

上面，当我们创建一个新的 ForeignKeyConstraint 时，我们将获得如下名称

>>> metadata_obj = MetaData(naming_convention=convention)

>>> user_table = Table(
...     "user",
...     metadata_obj,
...     Column("id", Integer, primary_key=True),
...     Column("version", Integer, primary_key=True),
...     Column("data", String(30)),
... )
>>> address_table = Table(
...     "address",
...     metadata_obj,
...     Column("id", Integer, primary_key=True),
...     Column("user_id", Integer),
...     Column("user_version_id", Integer),
... )
>>> fk = ForeignKeyConstraint(["user_id", "user_version_id"], ["user.id", "user.version"])
>>> address_table.append_constraint(fk)
>>> fk.name
fk_0cd51ab5-8d70-56e8-a83c-86661737766d

另请参阅

MetaData.naming_convention - 有关其他用法详细信息以及所有可用命名组件的列表。

命名约束的重要性 - 在 Alembic 文档中。

1.3.0 版本新增: 添加了多列命名令牌，例如 %(column_0_N_name)s。对于超出目标数据库字符限制的生成名称，将进行确定性截断。

命名 CHECK 约束¶

CheckConstraint 对象是针对任意 SQL 表达式配置的，该表达式可以包含任意数量的列，并且通常使用原始 SQL 字符串进行配置。因此，与 CheckConstraint 一起使用的常见约定是，我们期望对象已经有一个名称，然后我们使用其他约定元素对其进行增强。一个典型的约定是 "ck_%(table_name)s_%(constraint_name)s"

metadata_obj = MetaData(
    naming_convention={"ck": "ck_%(table_name)s_%(constraint_name)s"}
)

Table(
    "foo",
    metadata_obj,
    Column("value", Integer),
    CheckConstraint("value > 5", name="value_gt_5"),
)

上面的表将生成名称 ck_foo_value_gt_5

CREATE TABLE foo (
    value INTEGER,
    CONSTRAINT ck_foo_value_gt_5 CHECK (value > 5)
)

CheckConstraint 也支持 %(columns_0_name)s 标记；我们可以通过确保在约束的表达式中使用 Column 或 column() 元素来利用这一点，可以通过从表中单独声明约束

metadata_obj = MetaData(naming_convention={"ck": "ck_%(table_name)s_%(column_0_name)s"})

foo = Table("foo", metadata_obj, Column("value", Integer))

CheckConstraint(foo.c.value > 5)

或者通过内联使用 column()

from sqlalchemy import column

metadata_obj = MetaData(naming_convention={"ck": "ck_%(table_name)s_%(column_0_name)s"})

foo = Table(
    "foo", metadata_obj, Column("value", Integer), CheckConstraint(column("value") > 5)
)

两者都将生成名称 ck_foo_value

CREATE TABLE foo (
    value INTEGER,
    CONSTRAINT ck_foo_value CHECK (value > 5)
)

“零列”名称的确定是通过扫描给定表达式中的列对象来执行的。如果表达式中存在多个列，则扫描确实使用确定性搜索，但是表达式的结构将决定哪个列被标记为“零列”。

配置 Boolean、Enum 和其他模式类型的命名¶

SchemaType 类指的是类型对象，例如 Boolean 和 Enum，它们生成伴随类型的 CHECK 约束。此处的约束名称最直接的设置方式是发送 “name” 参数，例如 Boolean.name

Table("foo", metadata_obj, Column("flag", Boolean(name="ck_foo_flag")))

命名约定功能也可以与这些类型结合使用，通常通过使用包含 %(constraint_name)s 的约定，然后将名称应用于类型

metadata_obj = MetaData(
    naming_convention={"ck": "ck_%(table_name)s_%(constraint_name)s"}
)

Table("foo", metadata_obj, Column("flag", Boolean(name="flag_bool")))

上面的表将生成约束名称 ck_foo_flag_bool

CREATE TABLE foo (
    flag BOOL,
    CONSTRAINT ck_foo_flag_bool CHECK (flag IN (0, 1))
)

SchemaType 类使用特殊的内部符号，以便仅在 DDL 编译时确定命名约定。在 PostgreSQL 上，有一个原生的 BOOLEAN 类型，因此不需要 Boolean 的 CHECK 约束；即使为 check 约束设置了命名约定，我们也可以安全地设置一个没有名称的 Boolean 类型。只有当我们针对没有原生 BOOLEAN 类型的数据库（如 SQLite 或 MySQL）运行时，才会查阅此约定。

CHECK 约束也可以使用 column_0_name 标记，这与 SchemaType 非常适用，因为这些约束只有一个列

metadata_obj = MetaData(naming_convention={"ck": "ck_%(table_name)s_%(column_0_name)s"})

Table("foo", metadata_obj, Column("flag", Boolean()))

上面的模式将生成

CREATE TABLE foo (
    flag BOOL,
    CONSTRAINT ck_foo_flag CHECK (flag IN (0, 1))
)

将命名约定与 ORM 声明式混入一起使用¶

当将命名约定功能与 ORM 声明式混入 一起使用时，每个实际的表映射子类都必须存在单独的约束对象。有关背景和示例，请参阅在混入中使用命名约定创建索引和约束部分。

约束 API¶

对象名称	描述
CheckConstraint	表级或列级 CHECK 约束。
ColumnCollectionConstraint	代理 ColumnCollection 的约束。
ColumnCollectionMixin	`ColumnCollection` 的 `Column` 对象。
Constraint	表级 SQL 约束。
conv	标记一个字符串，指示名称已被命名约定转换。
ForeignKey	定义两个列之间的依赖关系。
ForeignKeyConstraint	表级 FOREIGN KEY 约束。
HasConditionalDDL	定义一个类，其中包含 `HasConditionalDDL.ddl_if()` 方法，允许有条件地渲染 DDL。
PrimaryKeyConstraint	表级 PRIMARY KEY 约束。
UniqueConstraint	表级 UNIQUE 约束。

class sqlalchemy.schema.Constraint¶

表级 SQL 约束。

Constraint 用作可以与 Table 对象关联的一系列约束对象的基础类，包括 PrimaryKeyConstraint, ForeignKeyConstraint UniqueConstraint, 和 CheckConstraint。

成员

__init__(), argument_for(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

class sqlalchemy.schema.Constraint (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.HasConditionalDDL, sqlalchemy.schema.SchemaItem)

method sqlalchemy.schema.Constraint.__init__(name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, info: _InfoType | None = None, comment: str | None = None, _create_rule: Any | None = None, _type_bound: bool = False, **dialect_kw: Any) → None¶

创建一个 SQL 约束。

参数:

name¶ – 可选参数，此 Constraint 在数据库中的名称。
deferrable¶ – 可选的布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选的字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY <value>。
info¶ – 可选的数据字典，它将被填充到此对象的 SchemaItem.info 属性中。
comment¶ –
可选字符串，将在外键约束创建时呈现 SQL 注释。

2.0 版本新增。
**dialect_kw¶ – 其他关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。有关记录在案的参数的详细信息，请参阅方言中关于各个方言的文档。
_create_rule¶ – 供某些也创建约束的数据类型在内部使用。
_type_bound¶ – 在内部使用，以指示此约束与特定的数据类型关联。

classmethod sqlalchemy.schema.Constraint.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。方言必须是可定位的，否则会引发 NoSuchModuleError。方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError。如果方言不包含此集合，则已经可以代表此方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

method sqlalchemy.schema.Constraint.copy(**kw: Any) → Self¶: Deprecated since version 1.4: Constraint.copy() 方法已弃用，并将在未来的版本中移除。

method sqlalchemy.schema.Constraint.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或指示多种方言类型的字符串名称元组。
callable_¶ – 可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 将传递给可调用对象的任何任意对象（如果存在）。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

attribute sqlalchemy.schema.Constraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.Constraint.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

attribute sqlalchemy.schema.Constraint.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

attribute sqlalchemy.schema.Constraint.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.ColumnCollectionMixin¶

ColumnCollection 的 Column 对象。

此集合表示此对象引用的列。

class sqlalchemy.schema.ColumnCollectionConstraint¶

代理 ColumnCollection 的约束。

成员

__init__(), argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

class sqlalchemy.schema.ColumnCollectionConstraint (sqlalchemy.schema.ColumnCollectionMixin, sqlalchemy.schema.Constraint)

method sqlalchemy.schema.ColumnCollectionConstraint.__init__(*columns: _DDLColumnArgument, name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, info: _InfoType | None = None, _autoattach: bool = True, _column_flag: bool = False, _gather_expressions: List[_DDLColumnArgument] | None = None, **dialect_kw: Any) → None¶

参数:

*columns¶ – 列名或 Column 对象序列。
name¶ – 可选参数，此约束在数据库中的名称。
deferrable¶ – 可选的布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选的字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY <value>。
**dialect_kw¶ – 其他关键字参数，包括特定于方言的参数，将传播到 Constraint 超类。

classmethod sqlalchemy.schema.ColumnCollectionConstraint.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。方言必须是可定位的，否则会引发 NoSuchModuleError 异常。方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果方言不包含此集合，则可以代表此方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

attribute sqlalchemy.schema.ColumnCollectionConstraint.columns: ReadOnlyColumnCollection[str, Column[Any]]¶: 继承自 ColumnCollectionMixin.columns 属性，属于 ColumnCollectionMixin

一个 ColumnCollection，表示此约束的列集合。

method sqlalchemy.schema.ColumnCollectionConstraint.contains_column(col: Column[Any]) → bool¶

如果此约束包含给定的列，则返回 True。

请注意，此对象还包含一个属性 .columns，它是一个 ColumnCollection，其中包含 Column 对象。

method sqlalchemy.schema.ColumnCollectionConstraint.copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint¶: Deprecated since version 1.4: ColumnCollectionConstraint.copy() 方法已弃用，并将在未来的版本中删除。

method sqlalchemy.schema.ColumnCollectionConstraint.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或表示多种方言类型的字符串名称元组。
callable_¶ – 一个可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何任意对象，如果存在，将传递给可调用对象。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

attribute sqlalchemy.schema.ColumnCollectionConstraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.ColumnCollectionConstraint.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

attribute sqlalchemy.schema.ColumnCollectionConstraint.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

attribute sqlalchemy.schema.ColumnCollectionConstraint.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.CheckConstraint¶

表级或列级 CHECK 约束。

可以包含在 Table 或 Column 的定义中。

成员

__init__(), argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

class sqlalchemy.schema.CheckConstraint (sqlalchemy.schema.ColumnCollectionConstraint)

method sqlalchemy.schema.CheckConstraint.__init__(sqltext: _TextCoercedExpressionArgument[Any], name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, table: Table | None = None, info: _InfoType | None = None, _create_rule: Any | None = None, _autoattach: bool = True, _type_bound: bool = False, **dialect_kw: Any) → None¶

构造一个 CHECK 约束。

参数:

sqltext¶ –
一个包含约束定义的字符串，将按字面意思使用，或一个 SQL 表达式构造。如果作为字符串给出，则对象将转换为 text() 对象。如果文本字符串包含冒号字符，请使用反斜杠转义它
```
CheckConstraint(r"foo ~ E'a(?\:b|c)d")
```
警告

CheckConstraint.sqltext 参数传递给 CheckConstraint 时，可以作为 Python 字符串参数传递，这将作为受信任的 SQL 文本处理并按给定方式呈现。 请勿将不受信任的输入传递给此参数。
name¶ – 可选，约束在数据库中的名称。
deferrable¶ – 可选布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY <value>。
info¶ – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。

classmethod sqlalchemy.schema.CheckConstraint.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。方言必须是可定位的，否则会引发 NoSuchModuleError 异常。方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果方言不包含此集合，则可以代表此方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

attribute sqlalchemy.schema.CheckConstraint.columns: ReadOnlyColumnCollection[str, Column[Any]]¶: 继承自 ColumnCollectionMixin.columns 属性，属于 ColumnCollectionMixin

一个 ColumnCollection，表示此约束的列集合。

method sqlalchemy.schema.CheckConstraint.contains_column(col: Column[Any]) → bool¶

继承自 ColumnCollectionConstraint.contains_column() 方法，属于 ColumnCollectionConstraint

如果此约束包含给定的列，则返回 True。

请注意，此对象还包含一个属性 .columns，它是一个 ColumnCollection，其中包含 Column 对象。

method sqlalchemy.schema.CheckConstraint.copy(*, target_table: Table | None = None, **kw: Any) → CheckConstraint¶: Deprecated since version 1.4: CheckConstraint.copy() 方法已弃用，并将在未来的版本中删除。

method sqlalchemy.schema.CheckConstraint.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或表示多种方言类型的字符串名称元组。
callable_¶ – 一个可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何任意对象，如果存在，将传递给可调用对象。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

attribute sqlalchemy.schema.CheckConstraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.CheckConstraint.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

attribute sqlalchemy.schema.CheckConstraint.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

attribute sqlalchemy.schema.CheckConstraint.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.ForeignKey¶

定义两个列之间的依赖关系。

ForeignKey 被指定为 Column 对象的一个参数，例如：

t = Table(
    "remote_table",
    metadata,
    Column("remote_id", ForeignKey("main_table.id")),
)

请注意，ForeignKey 只是一个标记对象，用于定义两列之间的依赖关系。实际的约束始终由 ForeignKeyConstraint 对象表示。当 ForeignKey 与 Column 关联时，将自动生成此对象，而 Column 又与 Table 关联。相反，当 ForeignKeyConstraint 应用于 Table 时，会自动生成 ForeignKey 标记，使其存在于每个关联的 Column 上，这些 Column 也与约束对象关联。

请注意，您不能使用 ForeignKey 对象定义“复合”外键约束，即多个父/子列分组之间的约束。要定义此分组，必须使用 ForeignKeyConstraint 对象，并将其应用于 Table。关联的 ForeignKey 对象会自动创建。

与单个 Column 对象关联的 ForeignKey 对象在列的 foreign_keys 集合中可用。

外键配置的更多示例请参见定义外键。

成员

__init__(), argument_for(), column, copy(), dialect_kwargs, dialect_options, get_referent(), info, kwargs, references(), target_fullname

类签名

class sqlalchemy.schema.ForeignKey (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.SchemaItem)

method sqlalchemy.schema.ForeignKey.__init__(column: _DDLColumnArgument, _constraint: ForeignKeyConstraint | None = None, use_alter: bool = False, name: _ConstraintNameArgument = None, onupdate: str | None = None, ondelete: str | None = None, deferrable: bool | None = None, initially: str | None = None, link_to_name: bool = False, match: str | None = None, info: _InfoType | None = None, comment: str | None = None, _unresolvable: bool = False, **dialect_kw: Any)¶

构造一个列级别的外键 (FOREIGN KEY)。

当构造 ForeignKey 对象时，会生成一个 ForeignKeyConstraint，该对象与父 Table 对象的约束集合相关联。

参数:

column¶ – 键关系的单个目标列。一个 Column 对象或作为字符串的列名： tablename.columnkey 或 schema.tablename.columnkey。 columnkey 是已分配给列的 key (默认为列名本身)，除非 link_to_name 为 True，在这种情况下，将使用列的渲染名称。
name¶ – 可选字符串。如果未提供 constraint，则为键的数据库内名称。
onupdate¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON UPDATE <value>。典型值包括 CASCADE、DELETE 和 RESTRICT。
ondelete¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON DELETE <value>。典型值包括 CASCADE、SET NULL 和 RESTRICT。
deferrable¶ – 可选布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY <value>。
link_to_name¶ – 如果为 True，则在 column 中给定的字符串名称是引用的列的渲染名称，而不是其本地分配的 key。
use_alter¶ –
传递给底层的 ForeignKeyConstraint，以指示约束应在 CREATE TABLE/ DROP TABLE 语句之外生成/删除。有关更多描述，请参阅 ForeignKeyConstraint.use_alter。

另请参阅

ForeignKeyConstraint.use_alter

通过 ALTER 创建/删除外键约束
match¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 MATCH <value>。典型值包括 SIMPLE、PARTIAL 和 FULL。
info¶ – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。
comment¶ –
可选字符串，将在外键约束创建时呈现 SQL 注释。

2.0 版本新增。
**dialect_kw¶ – 其他关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。这些参数最终由相应的 ForeignKeyConstraint 处理。有关记录在案的参数的详细信息，请参阅方言中有关各个方言的文档。

classmethod sqlalchemy.schema.ForeignKey.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。方言必须是可定位的，否则会引发 NoSuchModuleError。方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError。如果方言不包含此集合，则可以代表此方言指定任何关键字参数。 SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

attribute sqlalchemy.schema.ForeignKey.column¶

返回此 ForeignKey 引用的目标 Column。

如果未建立目标列，则会引发异常。

method sqlalchemy.schema.ForeignKey.copy(*, schema: str | None = None, **kw: Any) → ForeignKey¶: Deprecated since version 1.4: ForeignKey.copy() 方法已弃用，并将在未来的版本中删除。

attribute sqlalchemy.schema.ForeignKey.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.ForeignKey.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

method sqlalchemy.schema.ForeignKey.get_referent(table: FromClause) → Column[Any] | None¶

返回此 ForeignKey 引用的给定 Table (或任何 FromClause) 中的 Column。

如果此 ForeignKey 未引用给定的 Table，则返回 None。

attribute sqlalchemy.schema.ForeignKey.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

attribute sqlalchemy.schema.ForeignKey.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

method sqlalchemy.schema.ForeignKey.references(table: Table) → bool¶: 如果给定的 Table 由此 ForeignKey 引用，则返回 True。

attribute sqlalchemy.schema.ForeignKey.target_fullname¶

为此 ForeignKey 返回一个基于字符串的“列规范”。

这通常等效于最初传递给对象构造函数的基于字符串的“tablename.colname”参数。

class sqlalchemy.schema.ForeignKeyConstraint¶

表级 FOREIGN KEY 约束。

定义单个列或复合外键 (FOREIGN KEY) … REFERENCES 约束。对于一个简单、单列外键，将 ForeignKey 添加到 Column 的定义中，等效于一个未命名的单列 ForeignKeyConstraint 的简写形式。

外键配置的示例请参见定义外键。

成员

__init__(), argument_for(), column_keys, columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, elements, info, kwargs, referred_table

类签名

class sqlalchemy.schema.ForeignKeyConstraint (sqlalchemy.schema.ColumnCollectionConstraint)

method sqlalchemy.schema.ForeignKeyConstraint.__init__(columns: _typing_Sequence[_DDLColumnArgument], refcolumns: _typing_Sequence[_DDLColumnArgument], name: _ConstraintNameArgument = None, onupdate: str | None = None, ondelete: str | None = None, deferrable: bool | None = None, initially: str | None = None, use_alter: bool = False, link_to_name: bool = False, match: str | None = None, table: Table | None = None, info: _InfoType | None = None, comment: str | None = None, **dialect_kw: Any) → None¶

构造一个支持复合列的外键 (FOREIGN KEY)。

参数:

columns¶ – 本地列名称的序列。命名的列必须在父 Table 中定义并存在。除非 link_to_name 为 True，否则名称应与分配给每个列的 key (默认为名称) 匹配。
refcolumns¶ – 外键列名称或 Column 对象的序列。这些列必须都位于同一 Table 中。
name¶ – 可选参数，键的数据库内名称。
onupdate¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON UPDATE <value>。典型值包括 CASCADE、DELETE 和 RESTRICT。
ondelete¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 ON DELETE <value>。典型值包括 CASCADE、SET NULL 和 RESTRICT。
deferrable¶ – 可选布尔值。如果设置，则在为此约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选字符串。如果设置，则在为此约束发出 DDL 时发出 INITIALLY <value>。
link_to_name¶ – 如果为 True，则在 column 中给定的字符串名称是引用的列的渲染名称，而不是其本地分配的 key。
use_alter¶ –
如果为 True，则不要将此约束的 DDL 作为 CREATE TABLE 定义的一部分发出。而是通过在创建完整表集合后发出的 ALTER TABLE 语句生成它，并在删除完整表集合之前通过 ALTER TABLE 语句删除它。

使用 ForeignKeyConstraint.use_alter 特别适用于在相互依赖的外键约束关系中建立两个或多个表的情况；但是，MetaData.create_all() 和 MetaData.drop_all() 方法将自动执行此解析，因此通常不需要此标志。

另请参阅

通过 ALTER 创建/删除外键约束
match¶ – 可选字符串。如果设置，则在为此约束发布 DDL 时发出 MATCH <value>。典型值包括 SIMPLE、PARTIAL 和 FULL。
info¶ – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。
comment¶ –
可选字符串，将在外键约束创建时呈现 SQL 注释。

2.0 版本新增。
**dialect_kw¶ – 额外的关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。有关已记录参数的详细信息，请参阅关于方言的文档。

classmethod sqlalchemy.schema.ForeignKeyConstraint.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。该方言必须是可定位的，否则会引发 NoSuchModuleError 异常。该方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果方言不包含此集合，则可以代表此方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

attribute sqlalchemy.schema.ForeignKeyConstraint.column_keys¶

返回表示此 ForeignKeyConstraint 中本地列的字符串键列表。

此列表是发送给 ForeignKeyConstraint 构造函数的原始字符串参数，或者如果约束已使用 Column 对象初始化，则是每个元素的字符串 .key。

attribute sqlalchemy.schema.ForeignKeyConstraint.columns: ReadOnlyColumnCollection[str, Column[Any]]¶: 继承自 ColumnCollectionMixin.columns 属性，属于 ColumnCollectionMixin

一个 ColumnCollection，表示此约束的列集合。

method sqlalchemy.schema.ForeignKeyConstraint.contains_column(col: Column[Any]) → bool¶

继承自 ColumnCollectionConstraint.contains_column() 方法，属于 ColumnCollectionConstraint

如果此约束包含给定的列，则返回 True。

请注意，此对象还包含一个属性 .columns，它是一个 ColumnCollection，其中包含 Column 对象。

method sqlalchemy.schema.ForeignKeyConstraint.copy(*, schema: str | None = None, target_table: Table | None = None, **kw: Any) → ForeignKeyConstraint¶: Deprecated since version 1.4: ForeignKeyConstraint.copy() 方法已弃用，并将在未来的版本中移除。

method sqlalchemy.schema.ForeignKeyConstraint.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或指示多种方言类型的字符串名称元组。
callable_¶ – 可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何将传递给可调用对象的任意对象（如果存在）。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

attribute sqlalchemy.schema.ForeignKeyConstraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.ForeignKeyConstraint.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

attribute sqlalchemy.schema.ForeignKeyConstraint.elements: List[ForeignKey]¶

ForeignKey 对象的序列。

每个 ForeignKey 代表单个引用列/被引用列对。

此集合旨在为只读。

attribute sqlalchemy.schema.ForeignKeyConstraint.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

attribute sqlalchemy.schema.ForeignKeyConstraint.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

attribute sqlalchemy.schema.ForeignKeyConstraint.referred_table¶

此 ForeignKeyConstraint 引用的 Table 对象。

这是一个动态计算的属性，如果约束和/或父表尚未与包含被引用表的元数据集合关联，则可能不可用。

class sqlalchemy.schema.HasConditionalDDL¶

定义一个类，其中包含 HasConditionalDDL.ddl_if() 方法，允许有条件地渲染 DDL。

目前适用于约束和索引。

成员

ddl_if()

2.0 版本新增。

method sqlalchemy.schema.HasConditionalDDL.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或指示多种方言类型的字符串名称元组。
callable_¶ – 可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何将传递给可调用对象的任意对象（如果存在）。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

class sqlalchemy.schema.PrimaryKeyConstraint¶

表级 PRIMARY KEY 约束。

PrimaryKeyConstraint 对象自动存在于任何 Table 对象上；它被分配一组 Column 对象，这些对象对应于标记有 Column.primary_key 标志的对象

>>> my_table = Table(
...     "mytable",
...     metadata,
...     Column("id", Integer, primary_key=True),
...     Column("version_id", Integer, primary_key=True),
...     Column("data", String(50)),
... )
>>> my_table.primary_key
PrimaryKeyConstraint(
    Column('id', Integer(), table=<mytable>,
           primary_key=True, nullable=False),
    Column('version_id', Integer(), table=<mytable>,
           primary_key=True, nullable=False)
)

Table 的主键也可以通过显式使用 PrimaryKeyConstraint 对象来指定；在这种使用模式下，还可以指定约束的“名称”，以及方言可能识别的其他选项

my_table = Table(
    "mytable",
    metadata,
    Column("id", Integer),
    Column("version_id", Integer),
    Column("data", String(50)),
    PrimaryKeyConstraint("id", "version_id", name="mytable_pk"),
)

通常不应混合使用这两种列指定样式。如果 PrimaryKeyConstraint 中存在的列与标记为 primary_key=True 的列不匹配（如果两者都存在），则会发出警告；在这种情况下，列严格取自 PrimaryKeyConstraint 声明，而那些以其他方式标记为 primary_key=True 的列将被忽略。此行为旨在向后兼容之前的行为。

对于要在 PrimaryKeyConstraint 上指定特定选项，但仍然希望使用 primary_key=True 标志的常用样式的情况，可以指定一个空的 PrimaryKeyConstraint，它将根据标志从 Table 中获取主键列集合

my_table = Table(
    "mytable",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("version_id", Integer, primary_key=True),
    Column("data", String(50)),
    PrimaryKeyConstraint(name="mytable_pk", mssql_clustered=True),
)

成员

argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

class sqlalchemy.schema.PrimaryKeyConstraint (sqlalchemy.schema.ColumnCollectionConstraint)

classmethod sqlalchemy.schema.PrimaryKeyConstraint.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。该方言必须是可定位的，否则会引发 NoSuchModuleError 异常。该方言还必须包含现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果方言不包含此集合，则可以代表此方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

attribute sqlalchemy.schema.PrimaryKeyConstraint.columns: ReadOnlyColumnCollection[str, Column[Any]]¶: 继承自 ColumnCollectionMixin.columns 属性，属于 ColumnCollectionMixin

一个 ColumnCollection，表示此约束的列集合。

method sqlalchemy.schema.PrimaryKeyConstraint.contains_column(col: Column[Any]) → bool¶

继承自 ColumnCollectionConstraint.contains_column() 方法，属于 ColumnCollectionConstraint

如果此约束包含给定的列，则返回 True。

请注意，此对象还包含一个属性 .columns，它是一个 ColumnCollection，其中包含 Column 对象。

method sqlalchemy.schema.PrimaryKeyConstraint.copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint¶: 继承自 ColumnCollectionConstraint.copy() 方法，属于 ColumnCollectionConstraint

Deprecated since version 1.4: ColumnCollectionConstraint.copy() 方法已弃用，并将在未来的版本中删除。

method sqlalchemy.schema.PrimaryKeyConstraint.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或指示多种方言类型的字符串名称元组。
callable_¶ – 可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何将传递给可调用对象的任意对象（如果存在）。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

attribute sqlalchemy.schema.PrimaryKeyConstraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

attribute sqlalchemy.schema.PrimaryKeyConstraint.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

attribute sqlalchemy.schema.PrimaryKeyConstraint.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

attribute sqlalchemy.schema.PrimaryKeyConstraint.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

class sqlalchemy.schema.UniqueConstraint¶

表级 UNIQUE 约束。

定义单列或复合 UNIQUE 约束。对于简洁的单列约束，向 Column 定义添加 unique=True 是未命名的单列 UniqueConstraint 的简写等效方式。

成员

__init__(), argument_for(), columns, contains_column(), copy(), ddl_if(), dialect_kwargs, dialect_options, info, kwargs

类签名

class sqlalchemy.schema.UniqueConstraint (sqlalchemy.schema.ColumnCollectionConstraint) 类

方法 sqlalchemy.schema.UniqueConstraint.__init__(*columns: _DDLColumnArgument, name: _ConstraintNameArgument = None, deferrable: bool | None = None, initially: str | None = None, info: _InfoType | None = None, _autoattach: bool = True, _column_flag: bool = False, _gather_expressions: List[_DDLColumnArgument] | None = None, **dialect_kw: Any) → None¶

继承自 sqlalchemy.schema.ColumnCollectionConstraint.__init__ 方法，来自 ColumnCollectionConstraint

参数:

*columns¶ – 列名或 Column 对象的序列。
name¶ – 可选，此约束在数据库中的名称。
deferrable¶ – 可选布尔值。如果设置，则在为此约束发布 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选字符串。如果设置，则在为此约束发布 DDL 时发出 INITIALLY <value>。
**dialect_kw¶ – 其他关键字参数，包括特定于方言的参数，将传播到 Constraint 超类。

类方法 sqlalchemy.schema.UniqueConstraint.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。该方言必须是可定位的，否则会引发 NoSuchModuleError 异常。该方言还必须包含一个现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果该方言不包含此集合，则可以代表该方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

属性 sqlalchemy.schema.UniqueConstraint.columns: ReadOnlyColumnCollection[str, Column[Any]]¶: 继承自 ColumnCollectionMixin.columns 属性，属于 ColumnCollectionMixin

一个 ColumnCollection，表示此约束的列集合。

方法 sqlalchemy.schema.UniqueConstraint.contains_column(col: Column[Any]) → bool¶

继承自 ColumnCollectionConstraint.contains_column() 方法，属于 ColumnCollectionConstraint

如果此约束包含给定的列，则返回 True。

请注意，此对象还包含一个属性 .columns，它是一个 ColumnCollection，其中包含 Column 对象。

方法 sqlalchemy.schema.UniqueConstraint.copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint¶: 继承自 ColumnCollectionConstraint.copy() 方法，属于 ColumnCollectionConstraint

Deprecated since version 1.4: ColumnCollectionConstraint.copy() 方法已弃用，并将在未来的版本中删除。

方法 sqlalchemy.schema.UniqueConstraint.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或用于指示多种方言类型的字符串名称元组。
callable_¶ – 一个可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何任意对象，如果存在，将传递给可调用对象。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

属性 sqlalchemy.schema.UniqueConstraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

属性 sqlalchemy.schema.UniqueConstraint.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

属性 sqlalchemy.schema.UniqueConstraint.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

属性 sqlalchemy.schema.UniqueConstraint.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

函数 sqlalchemy.schema.conv(value: str, quote: bool | None = None) → Any¶

标记一个字符串，指示名称已被命名约定转换。

这是一个字符串子类，指示一个名称，该名称不应再受任何命名约定的约束。

例如，当我们使用如下命名约定创建一个 Constraint 时

m = MetaData(
    naming_convention={"ck": "ck_%(table_name)s_%(constraint_name)s"}
)
t = Table(
    "t", m, Column("x", Integer), CheckConstraint("x > 5", name="x5")
)

上述约束的名称将呈现为 "ck_t_x5"。也就是说，现有名称 x5 在命名约定中用作 constraint_name 标记。

在某些情况下，例如在迁移脚本中，我们可能正在渲染上述 CheckConstraint，其名称已被转换。为了确保名称不会被双重修改，新名称使用 conv() 标记应用。我们可以显式地使用它，如下所示

m = MetaData(
    naming_convention={"ck": "ck_%(table_name)s_%(constraint_name)s"}
)
t = Table(
    "t",
    m,
    Column("x", Integer),
    CheckConstraint("x > 5", name=conv("ck_t_x5")),
)

在上面，conv() 标记指示此处的约束名称是最终的，并且名称将呈现为 "ck_t_x5" 而不是 "ck_t_ck_t_x5"

另请参阅

配置约束命名约定

索引¶

可以为单列匿名创建索引（使用自动生成的名称 ix_<column label>），方法是在 Column 上使用内联 index 关键字，这也修改了 unique 的用法，以将唯一性应用于索引本身，而不是添加单独的 UNIQUE 约束。对于具有特定名称或包含多列的索引，请使用 Index 构造，这需要一个名称。

下面我们说明一个 Table，其中关联了多个 Index 对象。“CREATE INDEX” 的 DDL 在表的创建语句之后立即发出

metadata_obj=MetaData()mytable=Table("mytable",metadata_obj,# an indexed column, with index "ix_mytable_col1"Column("col1",Integer,index=True),# a uniquely indexed column with index "ix_mytable_col2"Column("col2",Integer,index=True,unique=True),Column("col3",Integer),Column("col4",Integer),Column("col5",Integer),Column("col6",Integer),)# place an index on col3, col4Index("idx_col34",mytable.c.col3,mytable.c.col4)# place a unique index on col5, col6Index("myindex",mytable.c.col5,mytable.c.col6,unique=True)mytable.create(engine)CREATE TABLE mytable (
    col1 INTEGER,
    col2 INTEGER,
    col3 INTEGER,
    col4 INTEGER,
    col5 INTEGER,
    col6 INTEGER
)
CREATE INDEX ix_mytable_col1 ON mytable (col1)
CREATE UNIQUE INDEX ix_mytable_col2 ON mytable (col2)
CREATE UNIQUE INDEX myindex ON mytable (col5, col6)
CREATE INDEX idx_col34 ON mytable (col3, col4)

请注意，在上面的示例中，Index 构造是在与其对应的表外部创建的，直接使用 Column 对象。Index 也支持在 Table 内部进行“内联”定义，使用字符串名称来标识列

metadata_obj = MetaData()
mytable = Table(
    "mytable",
    metadata_obj,
    Column("col1", Integer),
    Column("col2", Integer),
    Column("col3", Integer),
    Column("col4", Integer),
    # place an index on col1, col2
    Index("idx_col12", "col1", "col2"),
    # place a unique index on col3, col4
    Index("idx_col34", "col3", "col4", unique=True),
)

Index 对象还支持其自身的 create() 方法

i=Index("someindex",mytable.c.col5)i.create(engine)CREATE INDEX someindex ON mytable (col5)

函数索引¶

Index 支持 SQL 和函数表达式，这取决于目标后端支持的功能。要使用降序值对列创建索引，可以使用 ColumnElement.desc() 修饰符

from sqlalchemy import Index

Index("someindex", mytable.c.somecol.desc())

或者，对于支持函数索引的后端（例如 PostgreSQL），可以使用 lower() 函数创建“不区分大小写”的索引

from sqlalchemy import func, Index

Index("someindex", func.lower(mytable.c.somecol))

索引 API¶

对象名称	描述
Index	表级别的索引。

类 sqlalchemy.schema.Index¶

表级别的索引。

定义复合（一列或多列）索引。

例如：

sometable = Table(
    "sometable",
    metadata,
    Column("name", String(50)),
    Column("address", String(100)),
)

Index("some_index", sometable.c.name)

对于简单的单列索引，添加 Column 也支持 index=True

sometable = Table(
    "sometable", metadata, Column("name", String(50), index=True)
)

对于复合索引，可以指定多列

Index("some_index", sometable.c.name, sometable.c.address)

函数索引也受支持，通常通过结合使用 func 构造和表绑定的 Column 对象来实现

Index("some_index", func.lower(sometable.c.name))

Index 也可以手动与 Table 关联，可以通过内联声明或使用 Table.append_constraint()。当使用这种方法时，索引列的名称可以指定为字符串

Table(
    "sometable",
    metadata,
    Column("name", String(50)),
    Column("address", String(100)),
    Index("some_index", "name", "address"),
)

为了在这种形式下支持函数索引或基于表达式的索引，可以使用 text() 构造

from sqlalchemy import text

Table(
    "sometable",
    metadata,
    Column("name", String(50)),
    Column("address", String(100)),
    Index("some_index", text("lower(name)")),
)

另请参阅

索引 - 关于 Index 的通用信息。

PostgreSQL 特定索引选项 - 可用于 Index 构造的 PostgreSQL 特定选项。

MySQL / MariaDB 特定索引选项 - 可用于 Index 构造的 MySQL 特定选项。

聚集索引支持 - 可用于 Index 构造的 MSSQL 特定选项。

成员

__init__(), argument_for(), create(), ddl_if(), dialect_kwargs, dialect_options, drop(), info, kwargs

类签名

class sqlalchemy.schema.Index (sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.schema.ColumnCollectionMixin, sqlalchemy.schema.HasConditionalDDL, sqlalchemy.schema.SchemaItem) 类

方法 sqlalchemy.schema.Index.__init__(name: str | None, *expressions: _DDLColumnArgument, unique: bool = False, quote: bool | None = None, info: _InfoType | None = None, _table: Table | None = None, _column_flag: bool = False, **dialect_kw: Any) → None¶

构造一个索引对象。

参数:

name¶ – 索引的名称
*expressions¶ – 要包含在索引中的列表达式。表达式通常是 Column 的实例，但也可能是最终引用 Column 的任意 SQL 表达式。
unique=False¶ – 仅关键字参数；如果为 True，则创建唯一索引。
quote=None¶ – 仅关键字参数；是否对索引名称应用引号。工作方式与 Column.quote 相同。
info=None¶ – 可选数据字典，将填充到此对象的 SchemaItem.info 属性中。
**dialect_kw¶ – 上面未提及的其他关键字参数是特定于方言的，并以 <dialectname>_<argname> 的形式传递。有关记录的参数的详细信息，请参阅方言中关于各个方言的文档。

类方法 sqlalchemy.schema.Index.argument_for(dialect_name, argument_name, default)¶

继承自 DialectKWArgs.argument_for() 方法，来自 DialectKWArgs

为此类添加一种新的方言特定的关键字参数。

例如：

Index.argument_for("mydialect", "length", None)

some_index = Index("a", "b", mydialect_length=5)

DialectKWArgs.argument_for() 方法是一种逐参数的方式，用于将额外的参数添加到 DefaultDialect.construct_arguments 字典中。此字典提供了一个参数名称列表，这些参数名称被各种模式级别的构造所接受，以代表方言。

新的方言通常应该一次性将此字典指定为方言类的数据成员。临时添加参数名称的用例通常是用于最终用户代码，该代码也使用自定义编译方案，该方案使用附加参数。

参数:

dialect_name¶ – 方言的名称。该方言必须是可定位的，否则会引发 NoSuchModuleError 异常。该方言还必须包含一个现有的 DefaultDialect.construct_arguments 集合，表明它参与关键字参数验证和默认系统，否则会引发 ArgumentError 异常。如果该方言不包含此集合，则可以代表该方言指定任何关键字参数。SQLAlchemy 中打包的所有方言都包含此集合，但是对于第三方方言，支持可能会有所不同。
argument_name¶ – 参数的名称。
default¶ – 参数的默认值。

方法 sqlalchemy.schema.Index.create(bind: _CreateDropBind, checkfirst: bool = False) → None¶: 为此 Index 发出 CREATE 语句，使用给定的 Connection 或 Engine` 进行连接。

另请参阅

MetaData.create_all().

方法 sqlalchemy.schema.Index.ddl_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self¶

继承自 HasConditionalDDL.ddl_if() 方法，来自 HasConditionalDDL

将条件 DDL 规则应用于此模式项。

这些规则的工作方式与 ExecutableDDLElement.execute_if() 可调用对象类似，并添加了可以在诸如 CreateTable 之类的构造的 DDL 编译阶段检查标准的特性。 HasConditionalDDL.ddl_if() 当前适用于 Index 构造以及所有 Constraint 构造。

参数:

dialect¶ – 方言的字符串名称，或用于指示多种方言类型的字符串名称元组。
callable_¶ – 一个可调用对象，其构造形式与 ExecutableDDLElement.execute_if.callable_ 中描述的形式相同。
state¶ – 任何任意对象，如果存在，将传递给可调用对象。

2.0 版本新增。

另请参阅

控制约束和索引的 DDL 生成 - 背景和用法示例

属性 sqlalchemy.schema.Index.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

参数以其原始 <dialect>_<kwarg> 格式存在于此处。仅包含实际传递的参数；与 DialectKWArgs.dialect_options 集合不同，后者包含此方言已知的所有选项，包括默认值。

该集合也是可写的；键接受 <dialect>_<kwarg> 形式，其中值将组装到选项列表中。

另请参阅

DialectKWArgs.dialect_options - 嵌套字典形式

属性 sqlalchemy.schema.Index.dialect_options¶

继承自 DialectKWArgs.dialect_options 属性，来自 DialectKWArgs

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表，键为 <dialect_name> 和 <argument_name>。例如，postgresql_where 参数可以定位为

arg = my_object.dialect_options["postgresql"]["where"]

0.9.2 版本新增。

另请参阅

DialectKWArgs.dialect_kwargs - 平面字典形式

方法 sqlalchemy.schema.Index.drop(bind: _CreateDropBind, checkfirst: bool = False) → None¶: 为此 Index 发出一个 DROP 语句，使用给定的 Connection 或 Engine 进行连接。

另请参阅

MetaData.drop_all().

属性 sqlalchemy.schema.Index.info¶

继承自 SchemaItem.info 属性，来自 SchemaItem

与对象关联的 Info 字典，允许用户定义的数据与此 SchemaItem 关联。

该字典在首次访问时自动生成。它也可以在某些对象的构造函数中指定，例如 Table 和 Column。

属性 sqlalchemy.schema.Index.kwargs¶: 继承自 DialectKWArgs.kwargs 属性，来自 DialectKWArgs

DialectKWArgs.dialect_kwargs 的同义词。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

定义约束和索引¶

定义外键¶

通过 ALTER 创建/删除外键约束¶

ON UPDATE 和 ON DELETE¶

UNIQUE 约束¶

CHECK 约束¶

PRIMARY KEY 约束¶

在使用声明式 ORM 扩展时设置约束¶

配置约束命名约定¶

为 MetaData 集合配置命名约定¶

默认命名约定¶

长名称的截断¶

为命名约定创建自定义令牌¶

命名 CHECK 约束¶

配置 Boolean、Enum 和其他模式类型的命名¶

将命名约定与 ORM 声明式混入一起使用¶

约束 API¶

索引¶

函数索引¶

索引 API¶