列 INSERT/UPDATE 默认值¶

列 INSERT 和 UPDATE 默认值是指创建默认值值，因为 INSERT 或 UPDATE 语句正在针对该行进行，如果 VALUE 没有向 INSERT 或 UPDATE 语句。也就是说，如果一个表有一个名为 “timestamp” 的列，并且 INSERT 语句继续执行，该语句不包含此列的值，则 INSERT 默认值将创建一个新值，例如当前时间，该值用作要 INSERT 到 “timestamp” 列中的值。如果语句包含此列的值，则不会发生默认值。

列默认值可以是服务器端函数或常量值，这些值与DDL中的架构一起在数据库中定义，或者是直接在SQLAlchemy发出的INSERT或UPDATE语句中呈现的SQL表达式;它们也可以是客户端 Python 函数或常量值，在将数据传递到数据库之前由 SQLAlchemy 调用。

注意

不应将列默认处理程序与拦截和修改 INSERT 和 UPDATE 语句的传入值的构造混淆，这些语句在调用语句时提供给语句。这称为数据封送，其中应用程序在将列值发送到数据库之前以某种方式对其进行修改。SQLAlchemy 提供了一些实现此目的的方法，包括使用自定义数据类型、SQL 执行事件和 ORM 中的自定义验证器以及属性事件。仅当 SQL 中的列没有值时，才会调用列默认值 DML 语句。

SQLAlchemy 提供了一系列有关默认生成函数的功能，这些功能在 INSERT 和 UPDATE 语句期间对不存在的值进行处理。选项包括：

在 INSERT 和 UPDATE作期间用作默认值的标量值
在 INSERT 和 UPDATE作时执行的 Python 函数
嵌入在 INSERT 语句中的 SQL 表达式（或在某些情况下预先执行）
嵌入在 UPDATE 语句中的 SQL 表达式
INSERT 期间使用的服务器端默认值
UPDATE 期间使用的服务器端触发器的标记

所有 insert/update 默认值的一般规则是，它们仅在特定列的值未作为 execute（） 参数传递时生效;否则，使用给定的值。

标量默认值¶

最简单的 default 类型是用作列的默认值的标量值：

Table("mytable", metadata_obj, Column("somecolumn", Integer, default=12))

在上面，如果未提供其他值，则值 “12” 将在 INSERT 期间绑定为列值。

标量值也可能与 UPDATE 语句相关联，尽管这并不常见（因为 UPDATE 语句通常正在寻找动态默认值）：

Table("mytable", metadata_obj, Column("somecolumn", Integer, onupdate=25))

Python 执行的函数¶

Column.default 和 Column.onupdate 关键字参数也接受 Python 函数。如果未提供该列的其他值，则在 insert 或 update 时调用这些函数，并且返回的值用于列的值。下面说明了将递增计数器分配给主键列的粗略 “序列”：

# a function which counts upwards
i = 0


def mydefault():
    global i
    i += 1
    return i


t = Table(
    "mytable",
    metadata_obj,
    Column("id", Integer, primary_key=True, default=mydefault),
)

应该注意的是，对于真正的 “递增序列” 行为，通常应该使用数据库的内置功能，这可能会包括 Sequence 对象或其他自动递增功能。对于主要 key 列，SQLAlchemy 在大多数情况下会使用这些功能自然而然。请参阅 API 文档 列（包括 Column.autoincrement 标志），以及本章后面的 Sequence 部分，了解标准主键生成技术的背景信息。

为了说明 onupdate，我们现在将 Python datetime 函数分配给 Column.onupdate 属性：

import datetime

t = Table(
    "mytable",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    # define 'last_updated' to be populated with datetime.now()
    Column("last_updated", DateTime, onupdate=datetime.datetime.now),
)

当执行 update 语句且未为 last_updated传递任何值时，将执行 datetime.datetime.now（） Python 函数，并将其返回值用作 last_updated 的值。请注意，我们现在提供作为函数本身而不调用它（即没有括号 following） - SQLAlchemy 将在语句执行。

上下文相关的默认函数¶

Column.default 和 Column.onupdate 还可以利用当前语句的上下文来确定值。语句的上下文是一个内部 SQLAlchemy 对象，其中包含有关正在执行的语句的所有信息，包括其源表达式、与其关联的参数以及游标。此上下文在默认值生成方面的典型用例是有权访问在行上插入或更新的其他值。要访问上下文，请提供一个接受单个 context 参数的函数：

def mydefault(context):
    return context.get_current_parameters()["counter"] + 12


t = Table(
    "mytable",
    metadata_obj,
    Column("counter", Integer),
    Column("counter_plus_twelve", Integer, default=mydefault, onupdate=mydefault),
)

应用上述默认生成函数，以便它将对所有未提供 counter_plus_twelve 值的 INSERT 和 UPDATE 语句执行，该值将是 counter 列的执行中存在的任何值加上数字 12。

对于使用 “executemany” 样式执行的单个语句，例如，将多个参数集传递给 Connection.execute（），为每组参数调用一次用户定义的函数。对于多值 Insert 构造的用例（例如，通过 Insert.values（） 方法设置了多个 VALUES 子句），用户定义的函数也会为每组参数调用一次。

调用函数时，特殊方法 DefaultExecutionContext.get_current_parameters() 可从 context 对象（DefaultExecutionContext 的子类）获得。此方法返回一个 column-key to values 字典，该字典表示 INSERT 或 UPDATE 语句的完整值集。对于多值 INSERT 构造，与单个 VALUES 子句对应的参数子集与完整参数字典隔离并单独返回。

1.2 版本中的新功能：新增 DefaultExecutionContext.get_current_parameters() 方法它改进了仍然存在的 DefaultExecutionContext.current_parameters 属性。

客户端调用的 SQL 表达式¶

Column.default 和 Column.onupdate 关键字也可以传递 SQL 表达式，这些表达式在大多数情况下在 INSERT 或 UPDATE 语句中内联呈现：

t = Table(
    "mytable",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    # define 'create_date' to default to now()
    Column("create_date", DateTime, default=func.now()),
    # define 'key' to pull its default from the 'keyvalues' table
    Column(
        "key",
        String(20),
        default=select(keyvalues.c.key).where(keyvalues.c.type="type1"),
    ),
    # define 'last_modified' to use the current_timestamp SQL function on update
    Column("last_modified", DateTime, onupdate=func.utc_timestamp()),
)

在上面，create_date 列将填充 现在（）SQL 函数（根据后端，编译为 NOW（） 或 CURRENT_TIMESTAMP）在 INSERT 语句中，并且 key 列，其中包含来自另一个表的 SELECT 子查询的结果。这当为此表发出 UPDATE 语句时，last_modified列将填充 SQL UTC_TIMESTAMP（） MySQL 函数的值。

注意

当使用带有 func 结构的 SQL 函数时，我们 “调用” 命名函数，例如，如 func.now（） 中带括号。这有所不同 from，当我们指定 Python 可调用对象作为默认值时，例如 datetime.datetime 中，我们传递函数本身，但我们没有我们自己调用它。对于 SQL 函数，调用 func.now（） 返回 SQL 表达式对象，该对象会将 “NOW” 函数呈现到正在发出的 SQL 中。

默认和更新 SQL 表达式，由 Column.default 和 Column.onupdate 在发生 INSERT 或 UPDATE 语句时由 SQLAlchemy 显式调用，通常在 DML 语句中内联呈现，下面列出的某些情况除外。这与 “server side” default不同，后者是 table 的 DDL 定义的一部分，例如作为 “CREATE TABLE” 语句的一部分，后者可能更常见。有关服务器端默认值，请参阅下一部分 Server-invoked DDL-Explicit 默认表达式。

当 Column.default 指示的 SQL 表达式与主键列一起使用时，在某些情况下，SQLAlchemy 必须“预执行”默认生成的 SQL 函数，这意味着它在单独的 SELECT 语句中调用，并且结果值作为参数传递给 INSERT。这仅发生在要求返回此主键值的 INSERT 语句的主键列上，其中 RETURNING 或 cursor.lastrowid 不得使用。一个 Insert 构造，用于指定 insert.inline 标志将始终内联呈现默认表达式。

当使用一组参数执行语句时（即，它是不是 “executemany” 样式的执行），则返回的 CursorResult 将包含一个可通过 CursorResult.postfetch_cols（） 访问的集合，其中包含所有具有内联执行的违约。同样，绑定到该语句的所有参数，包括所有预先执行的 Python 和 SQL 表达式都存在于 CursorResult.last_inserted_params() 或 CursorResult.last_updated_params() 集合 CursorResult 的 Cursor Result 中。这 CursorResult.inserted_primary_key collection 包含插入行的主键值列表（该列表，以便单列和复合列主键以相同的格式表示）。

服务器调用的 DDL-Explicit 默认表达式¶

SQL 表达式 default 的一个变体是 Column.server_default，它在 Table.create（）作期间被放置在 CREATE TABLE 语句中：

t = Table(
    "test",
    metadata_obj,
    Column("abc", String(20), server_default="abc"),
    Column("created_at", DateTime, server_default=func.sysdate()),
    Column("index_value", Integer, server_default=text("0")),
)

对上表的 create 调用将产生：

CREATE TABLE test (
    abc varchar(20) default 'abc',
    created_at datetime default sysdate,
    index_value integer default 0
)

上面的示例说明了 Column.server_default 的两个典型用例 SQL 函数（上例中为 SYSDATE）以及服务器端常量的值（上面示例中的整数 “0”）。建议使用 text（） 结构，而不是传递原始值，因为 SQLAlchemy 通常不会对这些值执行任何引用或转义。

与客户端生成的表达式一样，Column.server_default通常可以容纳 SQL 表达式，但预计这些表达式通常是简单的函数和表达式，而不是更复杂的情况，如嵌入的 SELECT。

标记隐式生成的值、时间戳和触发列¶

基于其他服务器端数据库机制在 INSERT 或 UPDATE 上生成新值的列，例如特定于数据库的自动生成行为，例如某些平台上的 TIMESTAMP 列，以及在 INSERT 或 UPDATE 上调用以生成新值的自定义触发器，可以使用 FetchedValue 作为标记来调用：

from sqlalchemy.schema import FetchedValue

t = Table(
    "test",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("abc", TIMESTAMP, server_default=FetchedValue()),
    Column("def", String(20), server_onupdate=FetchedValue()),
)

FetchedValue 指示符不会影响 CREATE TABLE 的 CREATE TABLE 中。相反，它将列标记为将具有新值的列在 INSERT 或 UPDATE 语句过程中由数据库填充，和 for supporting databases 可用于指示该列应为语句的 RETURNING 或 OUTPUT 子句的一部分。诸如 SQLAlchemy ORM 利用这个标记来了解如何获取值。具体而言， ValuesBase.return_defaults（） 方法可以与 Insert 一起使用或 Update 构造，以指示应返回这些值。

有关将 FetchedValue 与 ORM 结合使用的详细信息，请参阅获取 Server 生成的默认值。

警告

Column.server_onupdate 指令 目前不生成 MySQL 的 “ON UPDATE CURRENT_TIMESTAMP（）” 子句。看为 MySQL / MariaDB 的 explicit_defaults_for_timestamp 渲染 ON UPDATE CURRENT TIMESTAMP，以获取有关如何生成此子句的背景信息。

另请参阅

获取 Server 生成的默认值

定义序列¶

SQLAlchemy 使用 Sequence 对象，该对象被视为 “column default” 的特殊情况。它只对具有显式支持序列，在 SQLAlchemy 包含的方言中包括 PostgreSQL、Oracle Database、MS SQL Server 和 MariaDB。这 否则，将忽略 Sequence 对象。

提示

在较新的数据库引擎中，生成整数主键值时，Identity 结构可能比 Sequence 更受欢迎。请参阅标识列（GENERATED { ALWAYS |BY DEFAULT } 作为标识）了解此构造的背景。

Sequence 可以作为 INSERT作期间使用的“默认”生成器放置在任何列上，如果需要，也可以配置为在 UPDATE作期间触发。它最常与单个整数主键列结合使用：

table = Table(
    "cartitems",
    metadata_obj,
    Column(
        "cart_id",
        Integer,
        Sequence("cart_id_seq", start=1),
        primary_key=True,
    ),
    Column("description", String(40)),
    Column("createdate", DateTime()),
)

在上面，表 cartitems 与一个名为 cart_id_seq。上表的 Emitting MetaData.create_all（） 将包括：

CREATE SEQUENCE cart_id_seq START WITH 1

CREATE TABLE cartitems (
  cart_id INTEGER NOT NULL,
  description VARCHAR(40),
  createdate TIMESTAMP WITHOUT TIME ZONE,
  PRIMARY KEY (cart_id)
)

提示

当使用具有显式架构名称的表时（详见指定 Schema Name），配置的 Table 的 schema 不会自动由嵌入的 Sequence 共享，而是指定 Sequence.schema：

Sequence("cart_id_seq", start=1, schema="some_schema")

Sequence 也可以自动使用 MetaData.schema 设置;请参阅将序列与元数据关联以了解背景信息。

当对 cartitems 调用 Insert DML 构造时 table 中，如果没有为 cart_id 列传递显式值，则 cart_id_seq序列将用于在参与的后端上生成值。通常，序列函数嵌入在 INSERT 语句中，该语句与 RETURNING 结合使用，以便可以将新生成的值返回给 Python 进程：

INSERT INTO cartitems (cart_id, description, createdate)
VALUES (next_val(cart_id_seq), 'some description', '2015-10-15 12:00:15')
RETURNING cart_id

当使用 Connection.execute（） 调用 Insert 结构时，新生成的主键标识符（包括但不限于使用 Sequence 生成的主键标识符）可从 CursorResult 获得构造。 CursorResult.inserted_primary_key

当 Sequence 与 Column 作为其 Python 端默认生成器，则当为拥有的 Table 发出类似的 DDL 时，例如使用 MetaData.create_all（） 为一系列表生成 DDL 时，Sequence 也将受到 “CREATE SEQUENCE” 和 “DROP SEQUENCE” DDL 的约束。

序列 还可以与 MetaData 构造。这允许 Sequence 一次在多个 Table 中使用，并且还允许 MetaData.schema 参数。请参阅该部分将序列与元数据关联以进行背景。

在 SERIAL 列上关联 Sequence¶

PostgreSQL 的 SERIAL 数据类型是一种自动递增类型，这意味着在发出 CREATE TABLE 时隐式创建 PostgreSQL 序列。当为 Column 指示 Sequence 构造时，可以通过为 Sequence.optional 参数指定 True 值来指示不应在此特定情况下使用它。这允许给定的 Sequence 用于没有替代主键生成系统的后端，但对于后端（如 PostgreSQL），可以忽略它，这将为特定列自动生成一个序列：

table = Table(
    "cartitems",
    metadata_obj,
    Column(
        "cart_id",
        Integer,
        # use an explicit Sequence where available, but not on
        # PostgreSQL where SERIAL will be used
        Sequence("cart_id_seq", start=1, optional=True),
        primary_key=True,
    ),
    Column("description", String(40)),
    Column("createdate", DateTime()),
)

在上面的示例中，CREATE TABLE for PostgreSQL 将使用 SERIAL 数据类型，cart_id 列的 cart_id_seq 序列将被忽略。但是，在 Oracle Database 上，cart_id_seq sequence 将被显式创建。

提示

SERIAL 和 SEQUENCE 的这种特殊交互是相当遗留的，并且与其他情况一样，使用 Identity 将简化作，只需在所有支持的后端上使用 IDENTITY。

独立执行序列¶

SEQUENCE 是 SQL 中的一类架构对象，可用于在数据库中独立生成值。如果您有一个 Sequence 对象，它可以通过其 “next value” 指令调用将其直接传递给 SQL 执行方法：

with my_engine.connect() as conn:
    seq = Sequence("some_sequence", start=1)
    nextid = conn.execute(seq)

为了嵌入 Sequence 的 “next value” 函数在 SQL 语句（如 SELECT 或 INSERT）中，使用 Sequence.next_value（） 方法，它将在语句编译时呈现一个 SQL 函数，该函数是适合目标后端：

>>> my_seq=Sequence("some_sequence",start=1)>>> stmt=select(my_seq.next_value())>>> print(stmt.compile(dialect=postgresql.dialect()))SELECT nextval('some_sequence') AS next_value_1

将序列与 MetaData 关联¶

对于要与任意 Table 对象中，Sequence 可以与特定的 MetaData 相关联，使用 Sequence.metadata 参数：

seq = Sequence("my_general_seq", metadata=metadata_obj, start=1)

然后，可以以通常的方式将这样的序列与列相关联：

table = Table(
    "cartitems",
    metadata_obj,
    seq,
    Column("description", String(40)),
    Column("createdate", DateTime()),
)

在上面的示例中，Sequence 对象被视为独立的架构构造，该构造可以单独存在，也可以在表之间共享。

将 Sequence 与 MetaData 显式关联允许以下行为：

序列将继承 MetaData.schema 参数指定给目标 MetaData，其中影响 CREATE / DROP DDL 的生成以及 Sequence.next_value（） 函数在 SQL 语句中呈现。
MetaData.create_all（） 和 MetaData.drop_all（） 方法将为此 Sequence 发出 CREATE / DROP，即使该 Sequence 未与任何 Sequence 关联 作为 this 成员的 Table / Column 元数据。

将序列关联为服务器端默认值¶

注意

已知以下技术仅适用于 PostgreSQL 数据库。它不适用于 Oracle Database。

前面的部分说明了如何将 Sequence 与 Column 作为 Python 端默认生成器：

Column(
    "cart_id",
    Integer,
    Sequence("cart_id_seq", metadata=metadata_obj, start=1),
    primary_key=True,
)

在上述情况下，当相关 Table 受 CREATE / DROP 的约束。但是，当发出 CREATE TABLE 时，该序列将不会作为列的服务器端默认值出现。

如果我们希望将序列用作服务器端默认值，这意味着即使我们从 SQL 命令行向表发出 INSERT 命令，它也会发生，我们可以使用 Column.server_default 参数与 sequence 中，可从 Sequence.next_value（） 方法获得。下面我们说明了与 列作为 Python 端默认生成器和服务器端默认生成器：

cart_id_seq = Sequence("cart_id_seq", metadata=metadata_obj, start=1)
table = Table(
    "cartitems",
    metadata_obj,
    Column(
        "cart_id",
        Integer,
        cart_id_seq,
        server_default=cart_id_seq.next_value(),
        primary_key=True,
    ),
    Column("description", String(40)),
    Column("createdate", DateTime()),
)

或使用 ORM：

class CartItem(Base):
    __tablename__ = "cartitems"

    cart_id_seq = Sequence("cart_id_seq", metadata=Base.metadata, start=1)
    cart_id = Column(
        Integer, cart_id_seq, server_default=cart_id_seq.next_value(), primary_key=True
    )
    description = Column(String(40))
    createdate = Column(DateTime)

当发出 “CREATE TABLE” 语句时，在 PostgreSQL 上，它将发出为：

CREATE TABLE cartitems (
    cart_id INTEGER DEFAULT nextval('cart_id_seq') NOT NULL,
    description VARCHAR(40),
    createdate TIMESTAMP WITHOUT TIME ZONE,
    PRIMARY KEY (cart_id)
)

将 Sequence 放置在 Python 端和服务器端默认生成上下文中可确保 “primary key fetch” 逻辑在所有情况下都有效。通常，启用序列的数据库还支持 RETURNING 用于 INSERT 语句，SQLAlchemy 在发出此语句时会自动使用该语句。但是，如果 RETURNING 不用于特定的插入，则 SQLAlchemy 更愿意在 INSERT 语句本身之外“预执行”序列，这仅在序列作为 Python 端默认生成器函数包含时才有效。

该示例还将 Sequence 与封闭的 MetaData 直接调用，这再次确保 Sequence 与 MetaData 集合的参数完全关联，包括默认架构（如果有）。

另请参阅

Sequences/SERIAL/IDENTITY - 在 PostgreSQL 方言文档中

RETURNING Support - 在 Oracle Database dialect 文档中

计算列（GENERATED ALWAYS AS）¶

在 1.3.11 版本加入.

Computed 结构允许在 DDL 中将 Column 声明为 “GENERATED ALWAYS AS” 列，即具有由数据库服务器计算的值的列。该构造接受通常使用 string 或 text（） 构造以文本方式声明的 SQL 表达式，其方式与 CheckConstraint 类似。然后，数据库服务器将解释 SQL 表达式，以确定行中列的值。

例：

from sqlalchemy import Table, Column, MetaData, Integer, Computed

metadata_obj = MetaData()

square = Table(
    "square",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("side", Integer),
    Column("area", Integer, Computed("side * side")),
    Column("perimeter", Integer, Computed("4 * side")),
)

在 PostgreSQL 12 后端运行时，square table 的 DDL 将如下所示：

CREATE TABLE square (
    id SERIAL NOT NULL,
    side INTEGER,
    area INTEGER GENERATED ALWAYS AS (side * side) STORED,
    perimeter INTEGER GENERATED ALWAYS AS (4 * side) STORED,
    PRIMARY KEY (id)
)

该值是在 INSERT 和 UPDATE 时保留，还是计算 on fetch 是数据库的实现细节;前者被称为 “stored”，后者称为“virtual”。一些数据库实现同时支持两者，但有些仅支持其中一种。可选的 Computed.persisted 标志可以指定为 True 或 False 以指示 “STORED” 还是 “VIRTUAL” 关键字应该在 DDL 中呈现，但是，如果目标不支持该关键字，这将引发错误后端;不设置它将使用 Target backend 的工作默认值。

Computed 构造是 FetchedValue 的子类对象，并将自身设置为 “server default” 和 “server onupdate“生成器，这意味着在生成 INSERT 和 UPDATE 语句时，它将被视为默认生成列，并且在使用 ORM 时，它将被作为生成列获取。这包括，对于支持 RETURNING 的数据库，它将成为数据库 RETURNING 子句的一部分，并且生成的值将被急切地获取。

注意

使用 Computed construct 不能存储服务器应用的值之外的任何值对它; 为此类列传递值时 SQLAlchemy 的行为写入 INSERT 或 UPDATE 当前的值将为忽视。

目前已知 “GENERATED ALWAYS AS” 受以下机构支持：

MySQL 版本 5.7 及更高版本
MariaDB 10.x 系列及更高版本
PostgreSQL 版本 12 以上
Oracle 数据库 - 需要注意的是，RETURNING 不能与 UPDATE 一起正常工作（当 UPDATE..RETURNING，则包含计算列）
Microsoft SQL 服务器
SQLite 3.31 及以上版本

当 Computed 与不支持的后端一起使用时，如果目标方言不支持它，则在尝试以呈现构造。否则，如果方言支持它，但使用的特定数据库服务器版本不会，则 DBAPIError（通常为 OperationalError）在将 DDL 发送到数据库时引发。

另请参阅

计算

标识列（GENERATED { ALWAYS |默认 } 作为标识）¶

在 1.4 版本加入.

Identity 构造允许声明 Column 作为标识列，并在 DDL 中呈现为 “GENERATED { ALWAYS |默认情况下 } 作为身份”。标识列的值由使用递增（或递减）序列的数据库服务器。构造共享它的大部分选项来控制数据库行为 序列。

例：

from sqlalchemy import Table, Column, MetaData, Integer, Identity, String

metadata_obj = MetaData()

data = Table(
    "data",
    metadata_obj,
    Column("id", Integer, Identity(start=42, cycle=True), primary_key=True),
    Column("data", String),
)

在 PostgreSQL 12 后端运行时，数据表的 DDL 将如下所示：

CREATE TABLE data (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 42 CYCLE) NOT NULL,
    data VARCHAR,
    PRIMARY KEY (id)
)

如果语句尚未包含 id 列的值，则数据库将在插入时为 id 列生成一个值，从 42 开始。标识列还可以要求数据库生成值中，忽略与语句一起传递的值或引发错误，具体取决于后端。要激活此模式，请设置参数 Identity.always 设置为 True Identity 构造。更新前面的示例以包含此参数将生成以下 DDL：

CREATE TABLE data (
    id INTEGER GENERATED ALWAYS AS IDENTITY (START WITH 42 CYCLE) NOT NULL,
    data VARCHAR,
    PRIMARY KEY (id)
)

Identity 构造是 FetchedValue 的子类对象，并将自身设置为 target Column，这意味着当生成 INSERT 语句时，它将被视为默认生成列，并且在使用 ORM 时，它将被作为生成列获取。这包括，对于支持 RETURNING 的数据库，它将成为数据库 RETURNING 子句的一部分，并且生成的值将被急切地获取。

目前已知 Identity 结构受以下各项支持：

从版本 10 开始的 PostgreSQL。
Oracle Database 版本 12 以上。它还支持传递 always=None 以启用默认生成模式，并传递参数 on_null=True 以指定 “ON NULL” 和 “BY DEFAULT” 标识列。
Microsoft SQL Server。MSSQL 使用仅支持 start 和 increment 参数，并忽略所有其他参数。

当 Identity 与不支持的后端一起使用时，它将被忽略，并使用用于自动递增列的默认 SQLAlchemy 逻辑。

当 Column 同时指定 Identity 并设置 Column.autoincrement 设置为 False。

另请参阅

身份

默认对象 API¶

对象名称	描述
列默认	列上的普通默认值。
计算	定义生成列，即 “GENERATED ALWAYS AS” 语法。
默认子句	DDL 指定的 DEFAULT 列值。
DefaultGenerator	列默认值的基类。
提取值	透明数据库端默认值的标记。
身份	定义一个标识列，即 “GENERATED { ALWAYS \|BY DEFAULT } 作为标识“语法。
序列	表示命名的数据库序列。

类 sqlalchemy.schema 中。计算¶

定义生成列，即 “GENERATED ALWAYS AS” 语法。

Computed 构造是添加到 Column 对象的参数列表中的内联构造：

from sqlalchemy import Computed

Table(
    "square",
    metadata_obj,
    Column("side", Float, nullable=False),
    Column("area", Float, Computed("side * side")),
)

有关完整详细信息，请参阅下面的链接文档。

在 1.3.11 版本加入.

另请参阅

计算列（GENERATED ALWAYS AS）

成员

__init__（），复制（）

类签名

类 sqlalchemy.schema.Computed （ sqlalchemy.schema.FetchedValue ， sqlalchemy.schema.SchemaItem）

方法 sqlalchemy.schema.Computed。__init__（sqltext： _DDLColumnArgument， persisted：boolNone=None）→ 无¶

构造一个 GENERATED ALWAYS AS DDL 构造以伴随 列。

参数

sqltext （英语） ¶ –

包含列生成表达式的字符串，该表达式将为逐字使用 SQL 表达式构造，例如 文本（） 对象。如果以字符串形式给出，则对象将转换为 text（） 对象。

警告

Computed 的 Computed.sqltext 参数可以作为 Python 字符串参数传递，该参数将被视为受信任的 SQL 文本并呈现为给定的。不要将不受信任的输入传递给此参数。
持久化¶ –

可选，控制数据库应如何保留此列。可能的值为：
- None，则默认使用数据库定义的默认持久化。
- True，将呈现， GENERATED ALWAYS AS ... STORED 或目标数据库的等效值（如果支持）。
- False，将呈现， GENERATED ALWAYS AS ... VIRTUAL 或目标数据库的等效值（如果支持）。
如果数据库不支持该持久性选项，则在将 DDL 发送到目标数据库时，指定 True 或 False 可能会引发错误。将此参数保留为默认值 None 可以保证所有支持 生成始终为。

方法 sqlalchemy.schema.Computed。copy（*， target_table：TableNone=None， **kw： Any）→ 计算¶: 1.4 版后已移除： Computed.copy（） 方法已弃用，并将在将来的发行版中删除。

类 sqlalchemy.schema 中。ColumnDefault（列默认）¶

列上的普通默认值。

这可能对应于常量、可调用函数或 SQL 子句。

每当 Column 的 Row 一起使用。一个 ColumnDefault 也可以按位置传递。

例如，以下内容：

Column("foo", Integer, default=50)

等效于：

Column("foo", Integer, ColumnDefault(50))

类签名

类 sqlalchemy.schema.ColumnDefault （ sqlalchemy.schema.DefaultGenerator ， abc.美国广播公司）

类 sqlalchemy.schema 中。DefaultClause 函数¶

DDL 指定的 DEFAULT 列值。

DefaultClause 是 FetchedValue ，当发出 “CREATE TABLE”。

DefaultClause 每当server_default、server_onupdate Column 的 Row 一起使用。一个 DefaultClause 也可以按位置传递。

例如，以下内容：

Column("foo", Integer, server_default="50")

等效于：

Column("foo", Integer, DefaultClause("50"))

类签名

类 sqlalchemy.schema.DefaultClause （ sqlalchemy.schema.FetchedValue ）

类 sqlalchemy.schema 中。DefaultGenerator 函数¶

列默认值的基类。

此对象仅存在于 column.default 或 column.onupdate 上。它作为服务器默认值无效。

类签名

类 sqlalchemy.schema.DefaultGenerator （ sqlalchemy.sql.expression.Executable ， sqlalchemy.schema.SchemaItem）

类 sqlalchemy.schema 中。FetchedValue（获取值）¶

透明数据库端默认值的标记。

当数据库配置为为列提供一些自动默认值时，请使用 FetchedValue。

例如：

Column("foo", Integer, FetchedValue())

表示某些触发器或默认生成器将在 INSERT 期间为 foo 列创建一个新值。

另请参阅

标记隐式生成的值、时间戳和触发的列

类签名

类 sqlalchemy.schema.FetchedValue （ sqlalchemy.sql.expression.SchemaEventTarget ）

类 sqlalchemy.schema 中。序列¶

表示命名的数据库序列。

Sequence 对象表示数据库序列的名称和配置参数。它还表示可由 SQLAlchemy 引擎 “执行” 的构造或 Connection 中，为目标数据库呈现适当的“next value”函数并返回结果。

Sequence 通常与主键列相关联：

some_table = Table(
    "some_table",
    metadata,
    Column(
        "id",
        Integer,
        Sequence("some_table_seq", start=1),
        primary_key=True,
    ),
)

当上述 Table 发出 CREATE TABLE 时，如果目标平台支持序列，则也会发出 CREATE SEQUENCE 语句。对于不支持序列的平台，将忽略 Sequence 构造。

另请参阅

定义序列

CreateSequence （创建序列）

DropSequence

成员

__init__（）、create（）、drop（）、next_value（）

类签名

类 sqlalchemy.schema.Sequence （ sqlalchemy.schema.HasSchemaAttr ， sqlalchemy.schema.IdentityOptions ， sqlalchemy.schema.DefaultGenerator ）

方法 sqlalchemy.schema.Sequence 中。__init__（name： str， start：intNone=None， increment：intNone=None， minvalue：intNone=None， maxvalue：intNone=None， nominvalue：boolNone=None， nomaxvalue：boolNone=None， cycle：boolNone=None， schema：strLiteral[SchemaConst.BLANK_SCHEMA]None=None， cache：intNone=None， order：boolNone=None， data_type：_TypeEngineArgument[int]None=None， 可选： bool = False， quote：boolNone=无， metadata：MetaDataNone=无， quote_schema：boolNone=无， for_update： bool = False）→ 无¶

构造 Sequence 对象。

参数

name¶- 序列的名称。
开始¶ –

序列的起始索引。当 CREATE SEQUENCE 命令作为 “START WITH” 子句的值发送到数据库时，将使用此值。如果为 None，则省略该子句，在大多数平台上，该子句表示起始值为 1。

在 2.0 版更改： 需要 Sequence.start 参数才能让 DDL 发出 “START WITH”。这是对 1.4 版中所做的更改的相反，如果不包含 Sequence.start，则会隐式呈现 “START WITH 1”。有关更多详细信息，请参阅序列结构恢复为没有任何显式默认 “start” 值;影响 MS SQL Server。
increment¶- 序列的 increment 值。当 CREATE SEQUENCE 命令作为 “INCREMENT BY” 子句的值发送到数据库时，将使用此值。如果为 None，则省略该子句，在大多数平台上，该子句表示增量为 1。
minValue¶ – 序列的最小值。当 CREATE SEQUENCE 命令作为 “MINVALUE” 子句的值发送到数据库时，将使用此值。如果为 None，则省略该子句，在大多数平台上，升序和降序序列的最小值分别为 1 和 -2^63-1。
maxValue¶ – 序列的最大值。当 CREATE SEQUENCE 命令作为 “MAXVALUE” 子句的值发送到数据库时，将使用此值。如果为 None，则省略该子句，在大多数平台上，升序和降序序列的最大值分别为 2^63-1 和 -1。
nominValue¶ —— 序列没有最小值。当 CREATE SEQUENCE 命令作为 “NO MINVALUE” 子句的值发送到数据库时，将使用此值。如果为 None，则省略该子句，在大多数平台上，升序和降序序列的最小值分别为 1 和 -2^63-1。
nomaxvalue¶ – 序列没有最大值。当 CREATE SEQUENCE 命令作为 “NO MAXVALUE” 子句的值发送到数据库时，将使用此值。如果为 None，则省略该子句，在大多数平台上，升序和降序序列的最大值分别为 2^63-1 和 -1。
cycle¶ —— 允许序列在升序或降序分别达到 maxValue 或 minValue 时环绕。当 CREATE SEQUENCE 命令作为 “CYCLE” 子句发送到数据库时，将使用此值。如果达到限制，则生成的下一个数字将分别是 minvalue 或 maxvalue。如果 cycle=False （默认值），则在序列达到其最大值后对 nextval 的任何调用都将返回错误。
schema¶- 序列的可选 schema 名称，如果位于 default 以外的 schema 中。当 MetaData 也存在相同的与 Table.schema 相同。
cache¶ —— 可选的整数值;序列中预先计算的未来值的数量。呈现 Oracle Database 和 PostgreSQL 可理解的 CACHE 关键字。
order¶ – 可选的布尔值;如果为 True，则呈现 Oracle Database 可以理解的 ORDER 关键字，指示序列已明确排序。可能需要使用 Oracle RAC 提供确定性排序。
data_type¶ –

序列返回的类型，对于允许我们在 INTEGER、BIGINT 等之间进行选择的方言（例如，mssql）。

1.4.0 新版功能.
optional¶ —— 布尔值，当 True 时，表示这个 Sequence 对象只需要在没有提供其他生成主键标识符的方法的后端上显式生成。目前，它本质上意味着，“不要在 PostgreSQL 后端创建此序列，其中 SERIAL 关键字会自动为我们创建一个序列”。
quote¶—— 布尔值，当 True 或 False 时，显式强制打开或关闭 Sequence.name 的引用。当保留为默认值 None 时，将发生基于 casing 和 reserved words 的正常引用规则。
quote_schema¶– 设置架构的引用首选项名字。
元数据¶ –

可选的 MetaData 对象，该对象 序列将关联。A 序列 与 MetaData 关联的获得以下能力：
- Sequence 将继承 MetaData.schema 参数，这会影响 CREATE / DROP DDL 的生成（如果有）。
- Sequence.create（） 和 Sequence.drop（） 方法自动使用绑定到 MetaData 的引擎 object（如果有）。
- MetaData.create_all（） 和 MetaData.drop_all（） 方法将为此 Sequence 发出 CREATE / DROP，即使该 Sequence 未与任何 Sequence 关联 表 / 列 那是这个的成员 元数据。
仅当 Sequence 与 MetaData 显式关联时，才会发生上述行为通过此参数。

另请参阅

将序列与元数据关联 - 全面讨论 Sequence.metadata 参数。
for_update¶– 指示当与列关联时，应为该列表上的 UPDATE 语句调用此序列，而不是为该列的 INSERT 语句调用，当语句中该列没有其他值时。

方法 sqlalchemy.schema.Sequence 中。create（bind： _CreateDropBind， checkfirst： bool = True）→ 无¶: 在数据库中创建此序列。

方法 sqlalchemy.schema.Sequence 中。drop（bind： _CreateDropBind， checkfirst： bool = True）→ 无¶: 从数据库中删除此序列。

方法 sqlalchemy.schema.Sequence 中。next_value（）→ 函数[int]¶: 返回一个 next_value 函数元素，该元素将在任何 SQL 表达式中为此 Sequence 呈现适当的增量函数。

类 sqlalchemy.schema 中。身份¶

定义一个标识列，即 “GENERATED { ALWAYS |BY DEFAULT } 作为标识“语法。

Identity 构造是添加到 Column 对象的参数列表中的内联构造：

from sqlalchemy import Identity

Table(
    "foo",
    metadata_obj,
    Column("id", Integer, Identity()),
    Column("description", Text),
)

有关完整详细信息，请参阅下面的链接文档。

在 1.4 版本加入.

另请参阅

标识列（GENERATED { ALWAYS |默认情况下 } 作为标识）

成员

__init__（），复制（）

类签名

类 sqlalchemy.schema.Identity （ sqlalchemy.schema.IdentityOptions ， sqlalchemy.schema.FetchedValue ， sqlalchemy.schema.SchemaItem）

方法 sqlalchemy.schema.Identity 中。__init__（总是： bool = False， on_null：boolNone=无， start：intNone=无， increment：intNone=无， minvalue：intNone=无， maxvalue：intNone=无， nominvalue：boolNone=无， nomaxvalue：boolNone=无， cycle：boolNone=无， cache：intNone=无， order：boolNone=无）→没有¶

构造一个 GENERATED { ALWAYS |BY DEFAULT } 作为 Identity DDL 结构来附带 Column。

有关大多数参数的完整描述，请参阅 Sequence 文档。

注意

MSSQL 支持将此构造作为在列上生成 IDENTITY 的首选替代方法，但它使用仅支持 Identity.start 的非标准语法和 Identity.increment 的 Identity.increment 中。所有其他参数都将被忽略。

参数

always¶– 一个布尔值，表示标识列的类型。如果指定了 False，则默认值优先，则用户指定的值优先。如果指定了 True，则不接受用户指定的值（在某些后端（如 PostgreSQL）上，覆盖 SYSTEM VALUE或 similar，可以在 INSERT 中指定以覆盖序列值）。一些后端也有这个参数的默认值 None 不能用于省略在 DDL 中渲染此部分。如果后端没有默认值，则它将被视为 False。
on_null¶– 设置为 True 以指定 ON NULL 和 always=False identity 列。此选项仅在某些后端（如 Oracle Database）上受支持。
start¶ – 序列的起始索引。
increment¶- 序列的 increment 值。
minValue¶ – 序列的最小值。
maxValue¶ – 序列的最大值。
nominValue¶ —— 序列没有最小值。
nomaxvalue¶ – 序列没有最大值。
cycle¶ —— 允许序列在达到 maxValue 或 minValue 时回绕。
cache¶ —— 可选的整数值;序列中预先计算的未来值的数量。
order¶ – 可选的布尔值;如果为 true，则呈现 ORDER 关键字。

方法 sqlalchemy.schema.Identity 中。copy（**kw： Any）→ 身份¶: 1.4 版后已移除： Identity.copy（） 方法已弃用，并将在未来版本中删除。

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy 核心

列 INSERT/UPDATE 默认值¶

标量默认值¶

Python 执行的函数¶

上下文相关的默认函数¶

客户端调用的 SQL 表达式¶

服务器调用的 DDL-Explicit 默认表达式¶

标记隐式生成的值、时间戳和触发列¶

定义序列¶

在 SERIAL 列上关联 Sequence¶

独立执行序列¶

将序列与 MetaData 关联¶

将序列关联为服务器端默认值¶

计算列（GENERATED ALWAYS AS）¶

标识列（GENERATED { ALWAYS |默认 } 作为标识）¶

默认对象 API¶

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy 核心

列 INSERT/UPDATE 默认值¶

标量默认值¶

Python 执行的函数¶

上下文相关的默认函数¶

客户端调用的 SQL 表达式¶

服务器调用的 DDL-Explicit 默认表达式¶

标记隐式生成的值、时间戳和触发列¶

定义序列¶

在 SERIAL 列上关联 Sequence¶

独立执行序列¶

将序列与 MetaData 关联¶

将序列关联为服务器端默认值¶

计算列 （GENERATED ALWAYS AS）¶

标识列 （GENERATED { ALWAYS |默认 } 作为标识）¶

默认对象 API¶

计算列（GENERATED ALWAYS AS）¶

标识列（GENERATED { ALWAYS |默认 } 作为标识）¶