定义约束和索引¶

本节将讨论 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（不支持大多数 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 与删除操作结合使用时，将要求约束具有名称，否则会生成类似于以下内容的错误

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 cascade 与 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 用作映射类的目标。声明式扩展允许在给定表内容（主要作为 Column 对象的映射）的情况下自动创建 Table 对象。

要将诸如 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.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" 字符串是从 --autogenerate 在我们的元数据中定位的 UniqueConstraint 对象中复制的。

可用的标记包括 %(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 哈希值，并且每次生成相同的名称，以生成给定模式的一致名称。

为命名约定创建自定义标记¶

还可以通过在命名约定字典中指定一个额外的标记和一个可调用对象来添加新的标记。例如，如果我们想使用 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)
)

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

为布尔值、枚举和其他模式类型配置命名¶

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 约束不需要；我们可以安全地设置 Boolean 类型而没有名称，即使为检查约束设置了命名约定。只有当我们针对没有原生 BOOLEAN 类型的数据库（如 SQLite 或 MySQL）运行时，才会查询此约定以获取 CHECK 约束。

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 Declarative Mixins 中使用命名约定¶

在 ORM Declarative Mixins 中使用命名约定功能时，每个实际的表映射子类都必须存在单独的约束对象。有关背景和示例，请参阅在 Mixins 上使用命名约定创建索引和约束部分。

约束 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¶ – 可选 bool。如果设置，在为该约束发出 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¶: 从版本 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 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

与对象关联的信息字典，允许将用户定义的数据与该 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¶ – 参数的默认值。

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

一个 ColumnCollection 代表此约束的列集。

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

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

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

方法 sqlalchemy.schema.ColumnCollectionConstraint.copy(*, target_table: Table | None = None, **kw: Any) → ColumnCollectionConstraint¶: 从版本 1.4 起已弃用: The ColumnCollectionConstraint.copy() method is deprecated and will be removed in a future release.

方法 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 HasConditionalDDL.ddl_if() 目前适用于 Index 构造函数以及所有 Constraint 构造函数。

参数：

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

版本 2.0 中的新增功能。

另见

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

属性 sqlalchemy.schema.ColumnCollectionConstraint.dialect_kwargs¶

继承自 DialectKWArgs.dialect_kwargs 属性 DialectKWArgs

指定为特定于方言的选项的此构造函数的一组关键字参数。

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

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

另见

DialectKWArgs.dialect_options - 嵌套字典形式

属性 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 - 平铺字典形式

属性 sqlalchemy.schema.ColumnCollectionConstraint.info¶

继承自 SchemaItem.info 属性 SchemaItem

与对象关联的信息字典，允许将用户定义的数据与该 SchemaItem 关联。

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

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

是 DialectKWArgs.dialect_kwargs 的同义词。

类 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)

方法 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 的 CheckConstraint.sqltext 参数可以作为 Python 字符串参数传递，该参数将被视为受信任的 SQL 文本并按原样呈现。 不要将不受信任的输入传递给此参数。
name¶ – 可选，约束的数据库内名称。
deferrable¶ – 可选 bool。如果设置，则在为该约束发出 DDL 时发出 DEFERRABLE 或 NOT DEFERRABLE。
initially¶ – 可选字符串。如果设置，则在为该约束发出 DDL 时发出 INITIALLY <value>。
info¶ – 可选数据字典，它将填充到该对象的 SchemaItem.info 属性中。

类方法 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¶ – 参数的默认值。

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

一个 ColumnCollection 代表此约束的列集。

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

从 ColumnCollectionConstraint.contains_column() 方法继承而来 ColumnCollectionConstraint

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

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

方法 sqlalchemy.schema.CheckConstraint.copy(*, target_table: Table | None = None, **kw: Any) → CheckConstraint¶: 自版本 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 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

与对象关联的信息字典，允许将用户定义的数据与该 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 时，会自动生成与每个关联的 Column 相关联的 ForeignKey 标记，这些 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)¶

构建列级外键。

构造的 ForeignKey 对象生成一个与父级 Table 对象的约束集合相关联的 ForeignKeyConstraint 。

参数：

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 、 DELETE 和 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¶: 自版本 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¶

返回给定 Table（或任何 FromClause）中由此 ForeignKey 引用的 Column。

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

attribute sqlalchemy.schema.ForeignKey.info¶

继承自 SchemaItem.info 属性 SchemaItem

与对象关联的信息字典，允许将用户定义的数据与该 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 的简写等效项。

有关外键配置的示例，请参见 Defining Foreign Keys。

成员

__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、DELETE 和 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> 的形式传递。有关已记录参数的详细信息，请参阅 Dialects 中有关单个方言的文档。

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¶: 自版本 1.4 起已弃用： The 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 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

与对象关联的信息字典，允许将用户定义的数据与该 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 HasConditionalDDL.ddl_if() 目前适用于 Index 构造函数以及所有 Constraint 构造函数。

参数：

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

版本 2.0 中的新增功能。

另见

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

class sqlalchemy.schema.PrimaryKeyConstraint¶

表级 PRIMARY KEY 约束。

在任何 Table 对象上，PrimaryKeyConstraint 对象会自动存在；它被分配一组 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)
)

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

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

从版本 1.4 起已弃用: The ColumnCollectionConstraint.copy() method is deprecated and will be removed in a future release.

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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 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

与对象关联的信息字典，允许将用户定义的数据与该 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)

method 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¶

inherited from the sqlalchemy.schema.ColumnCollectionConstraint.__init__ method of ColumnCollectionConstraint

参数：

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

classmethod 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¶ – 参数的默认值。

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

一个 ColumnCollection 代表此约束的列集。

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

从 ColumnCollectionConstraint.contains_column() 方法继承而来 ColumnCollectionConstraint

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

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

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

从版本 1.4 起已弃用: The ColumnCollectionConstraint.copy() method is deprecated and will be removed in a future release.

方法 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 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

与对象关联的信息字典，允许将用户定义的数据与该 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)

method 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> 的形式传递。有关已记录参数的详细信息，请参阅方言中有关单个方言的文档。

classmethod 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¶ – 参数的默认值。

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

另见

MetaData.create_all().

method 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() 可调用函数，但新增功能是可以在 DDL 编译阶段检查条件，例如 CreateTable。 HasConditionalDDL.ddl_if() 目前适用于 Index 构造函数以及所有 Constraint 构造函数。

参数：

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

版本 2.0 中的新增功能。

另见

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

attribute 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¶: 使用给定的 Connection 或 Engine 连接，为这个 Index 发出 DROP 语句。

另见

MetaData.drop_all().

属性 sqlalchemy.schema.Index.info¶

继承自 SchemaItem.info 属性 SchemaItem

与对象关联的信息字典，允许将用户定义的数据与该 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 扩展时设置约束¶

配置约束命名约定¶

为元数据集合配置命名约定¶

默认命名约定¶

长名称的截断¶

为命名约定创建自定义标记¶

命名 CHECK 约束¶

为布尔值、枚举和其他模式类型配置命名¶

在 ORM Declarative Mixins 中使用命名约定¶

约束 API¶

索引¶

函数索引¶

索引 API¶