SqlAlchemy 2.0 中文文档（四十一）

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

自定义 DDL

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

在前面的章节中，我们讨论了各种模式构造，包括 Table、ForeignKeyConstraint、CheckConstraint 和 Sequence。在整个过程中，我们依赖于 Table 和 MetaData 的 create() 和 create_all() 方法来为所有构造发出数据定义语言 (DDL)。当发出时，会调用预先确定的操作顺序，并且无条件地创建用于创建每个表的 DDL，包括与其关联的所有约束和其他对象。对于需要数据库特定 DDL 的更复杂的场景，SQLAlchemy 提供了两种技术，可以根据任何条件添加任何 DDL，既可以附带标准生成表格，也可以单独使用。

自定义 DDL

自定义 DDL 短语最容易通过 DDL 结构实现。这个结构的工作方式与所有其他 DDL 元素相同，除了它接受一个字符串作为要发出的文本：

event.listen(
    metadata,
    "after_create",
    DDL(
        "ALTER TABLE users ADD CONSTRAINT "
        "cst_user_name_length "
        " CHECK (length(user_name) >= 8)"
    ),
)

创建 DDL 构造库的更全面的方法是使用自定义编译 - 有关详细信息，请参阅 自定义 SQL 构造和编译扩展。

控制 DDL 序列

之前介绍的 DDL 结构还具有根据对数据库的检查有条件地调用的能力。可以使用 ExecutableDDLElement.execute_if() 方法实现此功能。例如，如果我们想要创建一个触发器，但只在 PostgreSQL 后端上，我们可以这样调用：

mytable = Table(
    "mytable",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("data", String(50)),
)

func = DDL(
    "CREATE FUNCTION my_func() "
    "RETURNS TRIGGER AS $$ "
    "BEGIN "
    "NEW.data := 'ins'; "
    "RETURN NEW; "
    "END; $$ LANGUAGE PLPGSQL"
)

trigger = DDL(
    "CREATE TRIGGER dt_ins BEFORE INSERT ON mytable "
    "FOR EACH ROW EXECUTE PROCEDURE my_func();"
)

event.listen(mytable, "after_create", func.execute_if(dialect="postgresql"))

event.listen(mytable, "after_create", trigger.execute_if(dialect="postgresql"))

ExecutableDDLElement.execute_if.dialect 关键字还接受一个字符串方言名称的元组：

event.listen(
    mytable, "after_create", trigger.execute_if(dialect=("postgresql", "mysql"))
)
event.listen(
    mytable, "before_drop", trigger.execute_if(dialect=("postgresql", "mysql"))
)

ExecutableDDLElement.execute_if() 方法也可以针对一个可调用函数进行操作，该函数将接收正在使用的数据库连接。在下面的示例中，我们使用这个方法来有条件地创建一个 CHECK 约束，首先在 PostgreSQL 目录中查看是否存在：

def should_create(ddl, target, connection, **kw):
    row = connection.execute(
        "select conname from pg_constraint where conname='%s'" % ddl.element.name
    ).scalar()
    return not bool(row)

def should_drop(ddl, target, connection, **kw):
    return not should_create(ddl, target, connection, **kw)

event.listen(
    users,
    "after_create",
    DDL(
        "ALTER TABLE users ADD CONSTRAINT "
        "cst_user_name_length CHECK (length(user_name) >= 8)"
    ).execute_if(callable_=should_create),
)
event.listen(
    users,
    "before_drop",
    DDL("ALTER TABLE users DROP CONSTRAINT cst_user_name_length").execute_if(
        callable_=should_drop
    ),
)

users.create(engine)
CREATE  TABLE  users  (
  user_id  SERIAL  NOT  NULL,
  user_name  VARCHAR(40)  NOT  NULL,
  PRIMARY  KEY  (user_id)
)

SELECT  conname  FROM  pg_constraint  WHERE  conname='cst_user_name_length'
ALTER  TABLE  users  ADD  CONSTRAINT  cst_user_name_length  CHECK  (length(user_name)  >=  8)
users.drop(engine)
SELECT  conname  FROM  pg_constraint  WHERE  conname='cst_user_name_length'
ALTER  TABLE  users  DROP  CONSTRAINT  cst_user_name_length
DROP  TABLE  users 

使用内置 DDLElement 类

sqlalchemy.schema 包含提供 DDL 表达式的 SQL 表达式构造，所有这些构造都扩展自公共基类 ExecutableDDLElement。例如，要生成 CREATE TABLE 语句，可以使用 CreateTable 构造：

from sqlalchemy.schema import CreateTable

with engine.connect() as conn:
    conn.execute(CreateTable(mytable))
CREATE  TABLE  mytable  (
  col1  INTEGER,
  col2  INTEGER,
  col3  INTEGER,
  col4  INTEGER,
  col5  INTEGER,
  col6  INTEGER
) 

在上述内容中，CreateTable 构造与任何其他表达式构造（例如 select()、table.insert() 等）一样工作。SQLAlchemy 所有面向 DDL 的构造都是 ExecutableDDLElement 基类的子类；这是 SQLAlchemy 中的所有对象对应 CREATE 和 DROP 以及 ALTER 的基础，不仅在 SQLAlchemy 中，在 Alembic 迁移中也是如此。可用构造的完整参考在 DDL 表达式构造 API 中。

用户定义的 DDL 构造也可以作为 ExecutableDDLElement 的子类而创建。在自定义 SQL 构造和编译扩展文档中有几个示例。

控制约束和索引的 DDL 生成

新版本 2.0 中的新增内容。

虽然前面提到的 ExecutableDDLElement.execute_if() 方法对于需要有条件地调用的自定义 DDL 类很有用，但通常也有一种常见需求，即通常与特定 Table 相关的元素，例如约束和索引，也要受到“条件”规则的约束，例如一个索引包含特定于特定后端（如 PostgreSQL 或 SQL Server）的功能。对于这种用例，可以针对诸如 CheckConstraint、UniqueConstraint 和 Index 等构造使用 Constraint.ddl_if() 和 Index.ddl_if() 方法，接受与 ExecutableDDLElement.execute_if() 方法相同的参数，以控制它们的 DDL 是否会在其父 Table 对象的情况下发出。这些方法可以在创建 Table 的定义时内联使用（或类似地，在 ORM 声明映射中使用 __table_args__ 集合时），例如：

from sqlalchemy import CheckConstraint, Index
from sqlalchemy import MetaData, Table, Column
from sqlalchemy import Integer, String

meta = MetaData()

my_table = Table(
    "my_table",
    meta,
    Column("id", Integer, primary_key=True),
    Column("num", Integer),
    Column("data", String),
    Index("my_pg_index", "data").ddl_if(dialect="postgresql"),
    CheckConstraint("num > 5").ddl_if(dialect="postgresql"),
)

在上面的例子中，Table 构造同时指代 Index 和 CheckConstraint 构造，它们都表明 .ddl_if(dialect="postgresql")，这意味着这些元素只会在针对 PostgreSQL 方言时包含在 CREATE TABLE 序列中。例如，如果我们针对 SQLite 方言运行 meta.create_all()，那么这两个构造都不会被包含：

>>> from sqlalchemy import create_engine
>>> sqlite_engine = create_engine("sqlite+pysqlite://", echo=True)
>>> meta.create_all(sqlite_engine)
BEGIN  (implicit)
PRAGMA  main.table_info("my_table")
[raw  sql]  ()
PRAGMA  temp.table_info("my_table")
[raw  sql]  ()

CREATE  TABLE  my_table  (
  id  INTEGER  NOT  NULL,
  num  INTEGER,
  data  VARCHAR,
  PRIMARY  KEY  (id)
) 

然而，如果我们针对 PostgreSQL 数据库运行相同的命令，我们将看到 CHECK 约束的内联 DDL 以及为索引发出的单独的 CREATE 语句：

>>> from sqlalchemy import create_engine
>>> postgresql_engine = create_engine(
...     "postgresql+psycopg2://scott:tiger@localhost/test", echo=True
... )
>>> meta.create_all(postgresql_engine)
BEGIN  (implicit)
select  relname  from  pg_class  c  join  pg_namespace  n  on  n.oid=c.relnamespace  where  pg_catalog.pg_table_is_visible(c.oid)  and  relname=%(name)s
[generated  in  0.00009s]  {'name':  'my_table'}

CREATE  TABLE  my_table  (
  id  SERIAL  NOT  NULL,
  num  INTEGER,
  data  VARCHAR,
  PRIMARY  KEY  (id),
  CHECK  (num  >  5)
)
[no  key  0.00007s]  {}
CREATE  INDEX  my_pg_index  ON  my_table  (data)
[no  key  0.00013s]  {}
COMMIT 

Constraint.ddl_if()和Index.ddl_if()方法创建了一个事件钩子，该事件钩子不仅可以在 DDL 执行时进行查询，就像ExecutableDDLElement.execute_if()的行为一样，还可以在CreateTable对象的 SQL 编译阶段内进行查询，该对象负责在 CREATE TABLE 语句中内联渲染CHECK (num > 5) DDL。因此，ddl_if.callable_()参数接收到的事件钩子具有更丰富的参数集，包括传递了一个dialect关键字参数，以及通过compiler关键字参数传递给“内联渲染”部分的DDLCompiler的实例。当事件在DDLCompiler序列中触发时，bind参数不存在，因此，现代事件钩子如果希望检查数据库版本信息，则最好使用给定的Dialect对象，例如测试 PostgreSQL 版本：

def only_pg_14(ddl_element, target, bind, dialect, **kw):
    return dialect.name == "postgresql" and dialect.server_version_info >= (14,)

my_table = Table(
    "my_table",
    meta,
    Column("id", Integer, primary_key=True),
    Column("num", Integer),
    Column("data", String),
    Index("my_pg_index", "data").ddl_if(callable_=only_pg_14),
)

另见

Constraint.ddl_if()

Index.ddl_if() ## DDL 表达式构造 API

function sqlalchemy.schema.sort_tables(tables: Iterable[TableClause], skip_fn: Callable[[ForeignKeyConstraint], bool] | None = None, extra_dependencies: typing_Sequence[Tuple[TableClause, TableClause]] | None = None) → List[Table]

根据依赖关系对一组Table对象进行排序。

这是一个依赖顺序排序，将发出Table对象，使其跟随其依赖的Table对象。表是根据存在的ForeignKeyConstraint对象以及由Table.add_is_dependent_on()添加的显式依赖关系而相互依赖的。

警告

sort_tables()函数本身无法处理表之间的依赖循环，这些循环通常是由相互依赖的外键约束引起的。当检测到这些循环时，这些表的外键将被从排序中排除。当发生此情况时会发出警告，这将在将来的版本中引发异常。不属于循环的表仍将按依赖顺序返回。

为解决这些循环，可以将 ForeignKeyConstraint.use_alter 参数应用于创建循环的约束。或者，当检测到循环时，sort_tables_and_constraints() 函数将自动返回外键约束的单独集合，以便可以将其分别应用于模式。

在版本 1.3.17 中更改：- 当sort_tables() 由于循环依赖关系无法执行正确排序时，会发出警告。在将来的版本中，这将成为一个异常。此外，排序将继续返回其他未涉及到的表，这些表的排序不是之前的那种依赖顺序。

参数:

• tables – 一个Table 对象的序列。
• skip_fn – 可选的可调用对象，将传递一个ForeignKeyConstraint 对象；如果返回 True，则此约束将不被视为依赖项。请注意，这与sort_tables_and_constraints() 中的相同参数不同，后者实际上是传递了拥有者ForeignKeyConstraint 对象。
• extra_dependencies – 2-元组序列，这些表也将被视为彼此相关。

另请参见

sort_tables_and_constraints()

MetaData.sorted_tables - 使用此函数进行排序

function sqlalchemy.schema.sort_tables_and_constraints(tables, filter_fn=None, extra_dependencies=None, _warn_for_cycles=False)

对Table / ForeignKeyConstraint 对象进行排序。

这是一个依赖项排序，将发出元组 (Table, [ForeignKeyConstraint, ...])，以便每个Table 后跟其依赖的 Table 对象。由于排序未满足依赖关系规则而分离的其余ForeignKeyConstraint 对象稍后作为 (None, [ForeignKeyConstraint ...]) 发出。

表格依赖于另一个基于存在ForeignKeyConstraint对象，通过Table.add_is_dependent_on()添加的显式依赖关系，以及在此处使用sort_tables_and_constraints.skip_fn和/或sort_tables_and_constraints.extra_dependencies参数指定的依赖关系。

参数：

• tables – Table对象的序列。
• filter_fn – 可选的可调用对象，将传递给ForeignKeyConstraint对象，并根据此约束是否应作为内联约束绝对包含或排除的值返回一个值，或者两者都不是。如果返回 False，则该约束肯定会被包含为无法进行 ALTER 的依赖项；如果返回 True，则它将仅作为 ALTER 结果在最后包含。返回 None 意味着该约束将包含在基于表的结果中，除非它被检测为依赖循环的一部分。
• extra_dependencies – 2 元组序列，其中的表也将被视为相互依赖。

另请参阅

sort_tables()

class sqlalchemy.schema.BaseDDLElement

DDL 构造的根，包括那些在“create table”和其他进程中作为子元素的元素。

版本 2.0 中的新功能。

类签名

类sqlalchemy.schema.BaseDDLElement（sqlalchemy.sql.expression.ClauseElement）

class sqlalchemy.schema.ExecutableDDLElement

独立可执行 DDL 表达式构造的基类。

此类是通用目的DDL类的基类，以及各种创建/删除子句构造，如CreateTable、DropTable、AddConstraint等。

在版本 2.0 中更改：ExecutableDDLElement 从 DDLElement 重命名，后者仍然存在以保持向后兼容性。

ExecutableDDLElement 与 SQLAlchemy 事件紧密集成，在 事件 中介绍。其实例本身就是一个接收事件的可调用对象：

event.listen(
    users,
    'after_create',
    AddConstraint(constraint).execute_if(dialect='postgresql')
)

另请参阅

DDL

DDLEvents

事件

控制 DDL 序列

成员

call(), against(), execute_if()

类签名

类 sqlalchemy.schema.ExecutableDDLElement (sqlalchemy.sql.roles.DDLRole, sqlalchemy.sql.expression.Executable, sqlalchemy.schema.BaseDDLElement)

method __call__(target, bind, **kw)

将 DDL 作为 ddl_listener 执行。

method against(target: SchemaItem) → Self

返回一个包含给定目标的 ExecutableDDLElement 的副本。

这基本上是将给定项应用于返回的 ExecutableDDLElement 对象的.target 属性。然后，此目标可由事件处理程序和编译例程使用，以提供诸如按特定 Table 来标记 DDL 字符串等服务。

当 ExecutableDDLElement 对象被建立为 DDLEvents.before_create() 或 DDLEvents.after_create() 事件的事件处理程序，并且事件然后发生在给定目标（如 Constraint 或 Table）上时，该目标将使用此方法与 ExecutableDDLElement 对象的副本建立，并继续调用 ExecutableDDLElement.execute() 方法以调用实际的 DDL 指令。

参数:

target – 将进行 DDL 操作的 SchemaItem。

返回:

将此ExecutableDDLElement的副本与.target属性分配给给定的SchemaItem。

另请参见

DDL - 在处理 DDL 字符串时针对“目标”使用标记化。

method execute_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

返回一个可调用对象，在事件处理程序中有条件地执行此ExecutableDDLElement。

用于提供事件监听的包装器：

event.listen(
            metadata,
            'before_create',
            DDL("my_ddl").execute_if(dialect='postgresql')
        )

参数：

方言 –

可能是字符串或字符串元组。如果是字符串，则将与执行数据库方言的名称进行比较：

DDL('something').execute_if(dialect='postgresql')

如果是元组，则指定多个方言名称：

DDL('something').execute_if(dialect=('postgresql', 'mysql'))

callable_ –

一个可调用对象，将以三个位置参数以及可选关键字参数的形式调用：

ddl： 此 DDL 元素。 目标： 此事件的目标是Table或MetaData对象。如果显式执行 DDL，则可能为 None。 绑定： 用于执行 DDL 的Connection。如果此构造在表内创建，则可能为 None，在这种情况下，编译器将存在。 表： 可选关键字参数 - 要在 MetaData.create_all()或 drop_all()方法调用中创建/删除的 Table 对象列表。 方言： 关键字参数，但始终存在 - 涉及操作的Dialect。 编译器： 关键字参数。对于引擎级别的 DDL 调用，将为None，但如果此 DDL 元素在表内创建时，将引用DDLCompiler。 状态： 可选关键字参数 - 将是传递给此函数的state参数。 checkfirst： 关键字参数，如果在调用create()、create_all()、drop()、drop_all()时设置了‘checkfirst’标志，则为 True。

如果可调用函数返回 True 值，则将执行 DDL 语句。

状态 – 任何值，将作为state关键字参数传递给callable_。

另请参见

SchemaItem.ddl_if()

DDLEvents

事件

class sqlalchemy.schema.DDL

一个字面 DDL 语句。

指定要由数据库执行的文字 SQL DDL。DDL 对象作为 DDL 事件监听器，可以订阅那些在DDLEvents中列出的事件，使用Table或MetaData对象作为目标。基本的模板支持允许单个 DDL 实例处理多个表的重复任务。

例子：

from sqlalchemy import event, DDL

tbl = Table('users', metadata, Column('uid', Integer))
event.listen(tbl, 'before_create', DDL('DROP TRIGGER users_trigger'))

spow = DDL('ALTER TABLE %(table)s SET secretpowers TRUE')
event.listen(tbl, 'after_create', spow.execute_if(dialect='somedb'))

drop_spow = DDL('ALTER TABLE users SET secretpowers FALSE')
connection.execute(drop_spow)

在操作 Table 事件时，以下statement字符串替换可用：

%(table)s  - the Table name, with any required quoting applied
%(schema)s - the schema name, with any required quoting applied
%(fullname)s - the Table name including schema, quoted if needed

如果有的话，DDL 的“context”将与上述标准替换组合在一起。上下文中存在的键将覆盖标准替换。

成员

init()

类签名

类sqlalchemy.schema.DDL (sqlalchemy.schema.ExecutableDDLElement)

method __init__(statement, context=None)

创建一个 DDL 语句。

参数：

• statement – 要执行的字符串或 unicode 字符串。语句将使用 Python 的字符串格式化操作符以及由可选的DDL.context参数提供的一组固定字符串替换处理。 语句中的字面‘%’必须被转义为‘%%’。 DDL 语句中不可用 SQL 绑定参数。
• context – 可选字典，默认为 None。这些值将可用于对 DDL 语句进行字符串替换。

另请参阅

DDLEvents

事件

class sqlalchemy.schema._CreateDropBase

用于表示 CREATE 和 DROP 或等效操作的 DDL 构造的基类。

_CreateDropBase 的共同主题是一个element属性，它指的是要创建或删除的元素。

类签名

类 sqlalchemy.schema._CreateDropBase (sqlalchemy.schema.ExecutableDDLElement)

class sqlalchemy.schema.CreateTable

表示一个 CREATE TABLE 语句。

成员

init()

类签名

类sqlalchemy.schema.CreateTable (sqlalchemy.schema._CreateBase)

method __init__(element: Table, include_foreign_key_constraints: typing_Sequence[ForeignKeyConstraint] | None = None, if_not_exists: bool = False)

创建一个CreateTable 构造。

参数：

• element – 一个Table ，是 CREATE 的主题
• on – 参见DDL中on的描述。
• include_foreign_key_constraints – 可选的ForeignKeyConstraint对象序列，将内联包含在 CREATE 构造中；如果省略，那么所有没有指定 use_alter=True 的外键约束都将被包含。
• if_not_exists – 如果为 True，则将应用 IF NOT EXISTS 操作符到构造中。 新版本 1.4.0b2 中提供。

class sqlalchemy.schema.DropTable

代表一个 DROP TABLE 语句。

成员

init()

类签名

类sqlalchemy.schema.DropTable(sqlalchemy.schema._DropBase)

method __init__(element: Table, if_exists: bool = False)

创建一个DropTable构造。

参数：

• element – 一个Table，是 DROP 的主题。
• on – 查看DDL中关于on的描述。
• if_exists – 如果为 True，则将应用 IF EXISTS 操作符到构造中。 新版本 1.4.0b2 中提供。

class sqlalchemy.schema.CreateColumn

代表一个Column在 CREATE TABLE 语句中的呈现，通过CreateTable构造。

这是为了在生成 CREATE TABLE 语句时支持自定义列 DDL，通过使用在自定义 SQL 构造和编译扩展中记录的编译器扩展来扩展CreateColumn。

典型的集成是检查传入的Column对象，并在找到特定标志或条件时重定向编译：

from sqlalchemy import schema
from sqlalchemy.ext.compiler import compiles

@compiles(schema.CreateColumn)
def compile(element, compiler, **kw):
    column = element.element

    if "special" not in column.info:
        return compiler.visit_create_column(element, **kw)

    text = "%s SPECIAL DIRECTIVE %s" % (
            column.name,
            compiler.type_compiler.process(column.type)
        )
    default = compiler.get_column_default_string(column)
    if default is not None:
        text += " DEFAULT " + default

    if not column.nullable:
        text += " NOT NULL"

    if column.constraints:
        text += " ".join(
                    compiler.process(const)
                    for const in column.constraints)
    return text

上述构造可以应用到一个Table中，如下所示：

from sqlalchemy import Table, Metadata, Column, Integer, String
from sqlalchemy import schema

metadata = MetaData()

table = Table('mytable', MetaData(),
        Column('x', Integer, info={"special":True}, primary_key=True),
        Column('y', String(50)),
        Column('z', String(20), info={"special":True})
    )

metadata.create_all(conn)

上述，我们添加到Column.info集合的指令将被我们的自定义编译方案检测到：

CREATE TABLE mytable (
        x SPECIAL DIRECTIVE INTEGER NOT NULL,
        y VARCHAR(50),
        z SPECIAL DIRECTIVE VARCHAR(20),
    PRIMARY KEY (x)
)

CreateColumn构造也可以用于在生成CREATE TABLE时跳过某些列。这是通过创建一个有条件地返回None的编译规则来实现的。这本质上就是如何产生与在Column上使用system=True参数相同的效果，这个参数将列标记为隐式存在的“系统”列。

例如，假设我们希望生成一个Table，它在 PostgreSQL 后端跳过渲染 PostgreSQL xmin 列，但在其他后端会渲染它，以预期触发规则。条件编译规则只会在 PostgreSQL 上跳过此名称：

from sqlalchemy.schema import CreateColumn

@compiles(CreateColumn, "postgresql")
def skip_xmin(element, compiler, **kw):
    if element.element.name == 'xmin':
        return None
    else:
        return compiler.visit_create_column(element, **kw)

my_table = Table('mytable', metadata,
            Column('id', Integer, primary_key=True),
            Column('xmin', Integer)
        )

上述的CreateTable 结构将生成一个 CREATE TABLE，其中字符串只包含 id 列；xmin 列将被省略，但仅针对 PostgreSQL 后端。

类签名

类 sqlalchemy.schema.CreateColumn（sqlalchemy.schema.BaseDDLElement）

class sqlalchemy.schema.CreateSequence

代表一个 CREATE SEQUENCE 语句。

类签名

类 sqlalchemy.schema.CreateSequence（sqlalchemy.schema._CreateBase）

class sqlalchemy.schema.DropSequence

代表一个 DROP SEQUENCE 语句。

类签名

类 sqlalchemy.schema.DropSequence（sqlalchemy.schema._DropBase）

class sqlalchemy.schema.CreateIndex

代表一个 CREATE INDEX 语句。

成员

init()

类签名

类 sqlalchemy.schema.CreateIndex（sqlalchemy.schema._CreateBase）

method __init__(element, if_not_exists=False)

创建一个 Createindex 结构。

参数：

• element – 一个 Index，是 CREATE 的主题。
• if_not_exists – 若为真，则会对结构应用 IF NOT EXISTS 操作符。 从版本 1.4.0b2 开始的新功能。

class sqlalchemy.schema.DropIndex

代表一个 DROP INDEX 语句。

成员

init()

类签名

类 sqlalchemy.schema.DropIndex（sqlalchemy.schema._DropBase）

method __init__(element, if_exists=False)

创建一个 DropIndex 结构。

参数：

• element – 一个 Index，是 DROP 的主题。
• if_exists – 若为真，则会对结构应用 IF EXISTS 操作符。 从版本 1.4.0b2 开始的新功能。

class sqlalchemy.schema.AddConstraint

代表一个 ALTER TABLE ADD CONSTRAINT 语句。

类签名

类 sqlalchemy.schema.AddConstraint（sqlalchemy.schema._CreateBase）

class sqlalchemy.schema.DropConstraint

代表一个 ALTER TABLE DROP CONSTRAINT 语句。

类签名

类 sqlalchemy.schema.DropConstraint（sqlalchemy.schema._DropBase）

class sqlalchemy.schema.CreateSchema

代表一个 CREATE SCHEMA 语句。

此处的参数是模式的字符串名称。

成员

init()

类签名

类 sqlalchemy.schema.CreateSchema (sqlalchemy.schema._CreateBase)

method __init__(name, if_not_exists=False)

创建一个新的 CreateSchema 构造。

class sqlalchemy.schema.DropSchema

表示一个 DROP SCHEMA 语句。

这里的参数是模式的字符串名称。

成员

init()

类签名

类 sqlalchemy.schema.DropSchema (sqlalchemy.schema._DropBase)

method __init__(name, cascade=False, if_exists=False)

创建一个新的 DropSchema 构造。

自定义 DDL

使用 DDL 构造最容易实现自定义 DDL 短语。此构造与所有其他 DDL 元素的工作方式相同，只是它接受一个文本字符串作为要发出的文本：

event.listen(
    metadata,
    "after_create",
    DDL(
        "ALTER TABLE users ADD CONSTRAINT "
        "cst_user_name_length "
        " CHECK (length(user_name) >= 8)"
    ),
)

创建 DDL 构造库的更全面的方法是使用自定义编译 - 有关详细信息，请参阅 自定义 SQL 构造和编译扩展。

控制 DDL 序列

之前介绍的 DDL 构造也具有根据对数据库的检查有条件地调用的功能。使用 ExecutableDDLElement.execute_if() 方法可以使用此功能。例如，如果我们想要创建一个触发器，但仅在 PostgreSQL 后端上，我们可以这样调用：

mytable = Table(
    "mytable",
    metadata,
    Column("id", Integer, primary_key=True),
    Column("data", String(50)),
)

func = DDL(
    "CREATE FUNCTION my_func() "
    "RETURNS TRIGGER AS $$ "
    "BEGIN "
    "NEW.data := 'ins'; "
    "RETURN NEW; "
    "END; $$ LANGUAGE PLPGSQL"
)

trigger = DDL(
    "CREATE TRIGGER dt_ins BEFORE INSERT ON mytable "
    "FOR EACH ROW EXECUTE PROCEDURE my_func();"
)

event.listen(mytable, "after_create", func.execute_if(dialect="postgresql"))

event.listen(mytable, "after_create", trigger.execute_if(dialect="postgresql"))

ExecutableDDLElement.execute_if.dialect 关键字还接受一组字符串方言名称：

event.listen(
    mytable, "after_create", trigger.execute_if(dialect=("postgresql", "mysql"))
)
event.listen(
    mytable, "before_drop", trigger.execute_if(dialect=("postgresql", "mysql"))
)

ExecutableDDLElement.execute_if() 方法还可以针对一个可调用函数进行操作，该函数将接收正在使用的数据库连接。在下面的示例中，我们使用这个方法来有条件地创建一个 CHECK 约束，首先在 PostgreSQL 目录中查看它是否存在：

def should_create(ddl, target, connection, **kw):
    row = connection.execute(
        "select conname from pg_constraint where conname='%s'" % ddl.element.name
    ).scalar()
    return not bool(row)

def should_drop(ddl, target, connection, **kw):
    return not should_create(ddl, target, connection, **kw)

event.listen(
    users,
    "after_create",
    DDL(
        "ALTER TABLE users ADD CONSTRAINT "
        "cst_user_name_length CHECK (length(user_name) >= 8)"
    ).execute_if(callable_=should_create),
)
event.listen(
    users,
    "before_drop",
    DDL("ALTER TABLE users DROP CONSTRAINT cst_user_name_length").execute_if(
        callable_=should_drop
    ),
)

users.create(engine)
CREATE  TABLE  users  (
  user_id  SERIAL  NOT  NULL,
  user_name  VARCHAR(40)  NOT  NULL,
  PRIMARY  KEY  (user_id)
)

SELECT  conname  FROM  pg_constraint  WHERE  conname='cst_user_name_length'
ALTER  TABLE  users  ADD  CONSTRAINT  cst_user_name_length  CHECK  (length(user_name)  >=  8)
users.drop(engine)
SELECT  conname  FROM  pg_constraint  WHERE  conname='cst_user_name_length'
ALTER  TABLE  users  DROP  CONSTRAINT  cst_user_name_length
DROP  TABLE  users 

使用内置的 DDLElement 类

sqlalchemy.schema 包含提供 DDL 表达式的 SQL 表达式构造，所有这些构造都从共同基类 ExecutableDDLElement 扩展。例如，要生成一个 CREATE TABLE 语句，可以使用 CreateTable 构造：

from sqlalchemy.schema import CreateTable

with engine.connect() as conn:
    conn.execute(CreateTable(mytable))
CREATE  TABLE  mytable  (
  col1  INTEGER,
  col2  INTEGER,
  col3  INTEGER,
  col4  INTEGER,
  col5  INTEGER,
  col6  INTEGER
) 

在上面的例子中，CreateTable 构造像任何其他表达式构造一样工作（例如 select()、table.insert() 等）。所有的 SQLAlchemy 的 DDL 相关构造都是 ExecutableDDLElement 基类的子类；这是所有与 CREATE、DROP 以及 ALTER 相关的对象的基类，不仅仅在 SQLAlchemy 中，在 Alembic 迁移中也是如此。可用构造的完整参考在 DDL 表达式构造 API 中。

用户定义的 DDL 构造也可以作为 ExecutableDDLElement 的子类创建。自定义 SQL 构造和编译扩展 的文档中有几个示例。

控制约束和索引的 DDL 生成

新版本 2.0 中新增功能。

虽然之前提到的 ExecutableDDLElement.execute_if() 方法对于需要有条件地调用的自定义 DDL 类很有用，但通常还有一个常见的需求，即通常与特定 Table 相关的元素，如约束和索引，也要受到“条件”规则的约束，比如一个包含特定于特定后端（如 PostgreSQL 或 SQL Server）的特性的索引。对于这种用例，可以针对诸如 CheckConstraint、UniqueConstraint 和 Index 这样的构造使用 Constraint.ddl_if() 和 Index.ddl_if() 方法，接受与 ExecutableDDLElement.execute_if() 方法相同的参数，以控制它们的 DDL 是否将以其父 Table 对象的形式发出。在创建 Table 的定义时（或类似地，在使用 ORM 声明性映射的 __table_args__ 集合时），可以内联使用这些方法，例如：

from sqlalchemy import CheckConstraint, Index
from sqlalchemy import MetaData, Table, Column
from sqlalchemy import Integer, String

meta = MetaData()

my_table = Table(
    "my_table",
    meta,
    Column("id", Integer, primary_key=True),
    Column("num", Integer),
    Column("data", String),
    Index("my_pg_index", "data").ddl_if(dialect="postgresql"),
    CheckConstraint("num > 5").ddl_if(dialect="postgresql"),
)

在上面的示例中，Table 构造同时指代 Index 和 CheckConstraint 构造，均表明 .ddl_if(dialect="postgresql")，这表示这些元素仅针对 PostgreSQL 方言将包括在 CREATE TABLE 序列中。例如，如果我们针对 SQLite 方言运行 meta.create_all()，则不会包括任何构造：

>>> from sqlalchemy import create_engine
>>> sqlite_engine = create_engine("sqlite+pysqlite://", echo=True)
>>> meta.create_all(sqlite_engine)
BEGIN  (implicit)
PRAGMA  main.table_info("my_table")
[raw  sql]  ()
PRAGMA  temp.table_info("my_table")
[raw  sql]  ()

CREATE  TABLE  my_table  (
  id  INTEGER  NOT  NULL,
  num  INTEGER,
  data  VARCHAR,
  PRIMARY  KEY  (id)
) 

但是，如果我们对 PostgreSQL 数据库运行相同的命令，我们将看到内联的 DDL 用于 CHECK 约束，以及为索引发出的单独的 CREATE 语句：

>>> from sqlalchemy import create_engine
>>> postgresql_engine = create_engine(
...     "postgresql+psycopg2://scott:tiger@localhost/test", echo=True
... )
>>> meta.create_all(postgresql_engine)
BEGIN  (implicit)
select  relname  from  pg_class  c  join  pg_namespace  n  on  n.oid=c.relnamespace  where  pg_catalog.pg_table_is_visible(c.oid)  and  relname=%(name)s
[generated  in  0.00009s]  {'name':  'my_table'}

CREATE  TABLE  my_table  (
  id  SERIAL  NOT  NULL,
  num  INTEGER,
  data  VARCHAR,
  PRIMARY  KEY  (id),
  CHECK  (num  >  5)
)
[no  key  0.00007s]  {}
CREATE  INDEX  my_pg_index  ON  my_table  (data)
[no  key  0.00013s]  {}
COMMIT 

Constraint.ddl_if() 和 Index.ddl_if() 方法创建一个事件挂钩，该挂钩不仅可以在 DDL 执行时查询，如 ExecutableDDLElement.execute_if() 的行为，而且还可以在 CreateTable 对象的 SQL 编译阶段内查询，该阶段负责在 CREATE TABLE 语句中内联渲染 CHECK (num > 5) DDL。因此，通过 ddl_if.callable_() 参数接收到的事件挂钩具有更丰富的参数集，包括传递的 dialect 关键字参数，以及通过 compiler 关键字参数传递的 DDLCompiler 的实例，用于序列的“内联渲染”部分。当事件在 DDLCompiler 序列内触发时，bind 参数 不存在，因此，希望检查数据库版本信息的现代事件挂钩最好使用给定的 Dialect 对象，例如测试 PostgreSQL 版本：

def only_pg_14(ddl_element, target, bind, dialect, **kw):
    return dialect.name == "postgresql" and dialect.server_version_info >= (14,)

my_table = Table(
    "my_table",
    meta,
    Column("id", Integer, primary_key=True),
    Column("num", Integer),
    Column("data", String),
    Index("my_pg_index", "data").ddl_if(callable_=only_pg_14),
)

另请参阅

Constraint.ddl_if()

Index.ddl_if()

DDL 表达式构造 API

function sqlalchemy.schema.sort_tables(tables: Iterable[TableClause], skip_fn: Callable[[ForeignKeyConstraint], bool] | None = None, extra_dependencies: typing_Sequence[Tuple[TableClause, TableClause]] | None = None) → List[Table]

根据依赖关系对一组Table对象进行排序。

这是一个依赖排序，将发出Table对象，以便它们将遵循其依赖的Table对象。表依赖于另一个表，根据ForeignKeyConstraint对象的存在以及由Table.add_is_dependent_on()添加的显式依赖关系。 |

警告

sort_tables()函数本身无法自动解决表之间的依赖循环，这些循环通常是由相互依赖的外键约束引起的。当检测到这些循环时，这些表的外键将被从排序考虑中省略。当出现此条件时会发出警告，在未来的版本中将引发异常。不属于循环的表仍将按照依赖顺序返回。

为了解决这些循环，可以将ForeignKeyConstraint.use_alter参数应用于创建循环的约束。另外，当检测到循环时，sort_tables_and_constraints()函数将自动将外键约束返回到一个单独的集合中，以便可以单独应用到模式中。

在版本 1.3.17 中更改：当sort_tables()由于循环依赖而无法执行适当排序时，会发出警告。这将在未来的版本中成为异常。此外，排序将继续返回其他未涉及循环的表以依赖顺序，而这在以前的情况下并非如此。

参数：

• tables – 一系列Table对象。
• skip_fn – 可选的可调用对象，将传递一个ForeignKeyConstraint对象；如果返回 True，则不会考虑此约束作为依赖项。请注意，这与sort_tables_and_constraints()中相同参数的不同之处，该参数将传递给拥有的ForeignKeyConstraint对象。
• extra_dependencies – 一个包含表之间互相依赖的 2 元组序列。

另请参阅

sort_tables_and_constraints()函数用于排序表和约束。

MetaData.sorted_tables - 使用此函数进行排序。

function sqlalchemy.schema.sort_tables_and_constraints(tables, filter_fn=None, extra_dependencies=None, _warn_for_cycles=False)

对一组Table / ForeignKeyConstraint对象进行排序。

这是一个依赖顺序排序，将发出(Table, [ForeignKeyConstraint, ...])元组，以便每个Table都跟随其依赖的Table对象。由于排序未满足的依赖规则而分开的其余ForeignKeyConstraint对象将作为(None, [ForeignKeyConstraint ...])之后发出。

表依赖于另一个表，基于存在的ForeignKeyConstraint对象，由Table.add_is_dependent_on()添加的显式依赖关系，以及在此处使用sort_tables_and_constraints.skip_fn和/或sort_tables_and_constraints.extra_dependencies参数声明的依赖关系。

参数:

• tables – 一个包含Table对象的序列。
• filter_fn – 可选的可调用对象，将传递一个ForeignKeyConstraint对象，并根据此约束是否应明确包含或排除为内联约束返回一个值，或者两者都不是。如果返回 False，则该约束将明确包含为不能受 ALTER 影响的依赖项；如果为 True，则它将仅作为最终的 ALTER 结果包含。返回 None 意味着该约束将包含在基于表的结果中，除非它被检测为依赖循环的一部分。
• extra_dependencies – 一个包含两个表的 2 元组序列，这两个表也将被视为相互依赖。

另请参阅

sort_tables()

class sqlalchemy.schema.BaseDDLElement

DDL 构造的根，包括那些作为“create table”和其他过程中的子元素的构造。

版本 2.0 中的新功能。

类签名

类sqlalchemy.schema.BaseDDLElement（sqlalchemy.sql.expression.ClauseElement）。

class sqlalchemy.schema.ExecutableDDLElement

独立可执行的 DDL 表达式构造的基类。

此类是通用目的 DDL 类的基类，以及各种创建/删除子句构造，例如 CreateTable、DropTable、AddConstraint 等等。

从版本 2.0 起更改：ExecutableDDLElement 从 DDLElement 重命名，DDLElement 仍然存在以保持向后兼容性。

ExecutableDDLElement 与 SQLAlchemy 事件密切集成，介绍在 Events 中。一个实例本身就是一个事件接收器：

event.listen(
    users,
    'after_create',
    AddConstraint(constraint).execute_if(dialect='postgresql')
)

另请参见

DDL

DDLEvents

Events

控制 DDL 序列

成员

call(), against(), execute_if()

类签名

类 sqlalchemy.schema.ExecutableDDLElement (sqlalchemy.sql.roles.DDLRole, sqlalchemy.sql.expression.Executable, sqlalchemy.schema.BaseDDLElement)

method __call__(target, bind, **kw)

将 DDL 作为 ddl_listener 执行。

method against(target: SchemaItem) → Self

返回此 ExecutableDDLElement 的副本，其中将包含给定的目标。

这实质上将给定项应用于返回的 ExecutableDDLElement 对象的 .target 属性。然后可以由事件处理程序和编译例程使用此目标，以提供诸如基于特定 Table 的 DDL 字符串的标记化之类的服务。

当将ExecutableDDLElement对象作为DDLEvents.before_create()或DDLEvents.after_create()事件的事件处理程序进行建立，并且事件随后发生在诸如Constraint或Table之类的给定目标上时，使用此方法使用ExecutableDDLElement对象的副本来为该目标建立，然后进入ExecutableDDLElement.execute()方法以调用实际的 DDL 指令。

参数：

target – 一个SchemaItem，将成为 DDL 操作的主体。

返回：

此ExecutableDDLElement的副本，其.target属性分配给给定的SchemaItem。

另请参阅

DDL - 对处理 DDL 字符串时针对“target”进行标记化。

method execute_if(dialect: str | None = None, callable_: DDLIfCallable | None = None, state: Any | None = None) → Self

返回一个可调用对象，该对象将在事件处理程序中有条件地执行此ExecutableDDLElement。

用于提供事件监听的包装器：

event.listen(
            metadata,
            'before_create',
            DDL("my_ddl").execute_if(dialect='postgresql')
        )

参数：

dialect –

可以是字符串或字符串元组。如果是字符串，则将其与执行数据库方言的名称进行比较：

DDL('something').execute_if(dialect='postgresql')

如果是元组，则指定多个方言名称：

DDL('something').execute_if(dialect=('postgresql', 'mysql'))

callable_ –

一个可调用对象，将使用三个位置参数以及可选的关键字参数进行调用：

ddl： 此 DDL 元素。 target： 此事件的目标Table或MetaData对象。如果 DDL 是显式执行的，则可以为 None。 bind： 用于执行 DDL 的Connection。如果此构造是在表内创建的，则可以为 None，在这种情况下将存在compiler。 tables： 可选关键字参数 - 一个 Table 对象列表，这些对象将在 MetaData.create_all() 或 drop_all() 方法调用时被创建/删除。 dialect： 关键字参数，但始终存在 - 涉及操作的Dialect。 compiler： 关键字参数。对于引擎级别的 DDL 调用，将为None，但如果此 DDL 元素在表内联中创建，则将引用DDLCompiler。 state: 可选关键字参数 - 将作为此函数传递的state参数。 checkfirst： 关键字参数，在调用create()、create_all()、drop()、drop_all()时，如果设置了checkfirst标志，则为 True。

如果可调用函数返回 True 值，则将执行 DDL 语句。

state - 任何将作为state关键字参数传递给可调用函数的值。

另请参阅

SchemaItem.ddl_if()

DDLEvents

Events

class sqlalchemy.schema.DDL

字面 DDL 语句。

指定要由数据库执行的字面 SQL DDL。DDL 对象充当 DDL 事件侦听器，并可以订阅DDLEvents中列出的事件，使用Table或MetaData对象作为目标。基本的模板支持允许单个 DDL 实例处理多个表的重复任务。

示例：

from sqlalchemy import event, DDL

tbl = Table('users', metadata, Column('uid', Integer))
event.listen(tbl, 'before_create', DDL('DROP TRIGGER users_trigger'))

spow = DDL('ALTER TABLE %(table)s SET secretpowers TRUE')
event.listen(tbl, 'after_create', spow.execute_if(dialect='somedb'))

drop_spow = DDL('ALTER TABLE users SET secretpowers FALSE')
connection.execute(drop_spow)

在操作表事件时，以下statement字符串替换可用：

%(table)s  - the Table name, with any required quoting applied
%(schema)s - the schema name, with any required quoting applied
%(fullname)s - the Table name including schema, quoted if needed

DDL 的“上下文”，如果有的话，将与上述标准替换组合。上下文中存在的键将覆盖标准替换。

成员

init()

类签名

类sqlalchemy.schema.DDL（sqlalchemy.schema.ExecutableDDLElement）

method __init__(statement, context=None)

创建 DDL 语句。

参数：

• statement - 要执行的字符串或 Unicode 字符串。语句将使用 Python 的字符串格式化运算符处理，使用一组固定的字符串替换，以及可选的DDL.context参数提供的其他替换。 语句中的字面‘%’必须转义为‘%%’。 DDL 语句中不可用 SQL 绑定参数。
• context - 可选字典，默认为 None。这些值将可用于 DDL 语句中的字符串替换。

另请参阅

DDLEvents

Events

class sqlalchemy.schema._CreateDropBase

用于表示 CREATE 和 DROP 或等效操作的 DDL 构造的基类。

_CreateDropBase 的共同主题是一个element属性，指向要创建或删除的元素。

类签名

类sqlalchemy.schema._CreateDropBase（sqlalchemy.schema.ExecutableDDLElement）

class sqlalchemy.schema.CreateTable

表示 CREATE TABLE 语句。

成员

init()

类签名

类sqlalchemy.schema.CreateTable（sqlalchemy.schema._CreateBase）

method __init__(element: Table, include_foreign_key_constraints: typing_Sequence[ForeignKeyConstraint] | None = None, if_not_exists: bool = False)

创建一个CreateTable构造。

参数：

• element – 是创建的主题Table。
• on – 请参阅DDL中关于on的描述。
• include_foreign_key_constraints – 将作为内联包含在 CREATE 构造中的可选的ForeignKeyConstraint对象序列；如果省略，则包括所有未指定 use_alter=True 的外键约束。
• if_not_exists – 如果为 True，则将应用 IF NOT EXISTS 操作符到构造中。 新版本 1.4.0b2 中新增。

class sqlalchemy.schema.DropTable

表示 DROP TABLE 语句。

成员

init()

类签名

类sqlalchemy.schema.DropTable（sqlalchemy.schema._DropBase）

method __init__(element: Table, if_exists: bool = False)

创建一个DropTable构造。

参数：

• element – 是 DROP 的主题Table。
• on – 请参阅DDL中关于on的描述。
• if_exists – 如果为 True，则将应用 IF EXISTS 操作符到构造中。 新版本 1.4.0b2 中新增。

class sqlalchemy.schema.CreateColumn

将Column表示为通过CreateTable构造在 CREATE TABLE 语句中呈现的形式。

这是为了支持在生成 CREATE TABLE 语句时使用 Custom SQL Constructs and Compilation Extension 中记录的编译器扩展来扩展CreateColumn以支持自定义列 DDL 而提供的。

典型的集成是检查传入的Column对象，并且在找到特定标志或条件时重定向编译：

from sqlalchemy import schema
from sqlalchemy.ext.compiler import compiles

@compiles(schema.CreateColumn)
def compile(element, compiler, **kw):
    column = element.element

    if "special" not in column.info:
        return compiler.visit_create_column(element, **kw)

    text = "%s SPECIAL DIRECTIVE %s" % (
            column.name,
            compiler.type_compiler.process(column.type)
        )
    default = compiler.get_column_default_string(column)
    if default is not None:
        text += " DEFAULT " + default

    if not column.nullable:
        text += " NOT NULL"

    if column.constraints:
        text += " ".join(
                    compiler.process(const)
                    for const in column.constraints)
    return text

上述构造可以应用于Table如下：

from sqlalchemy import Table, Metadata, Column, Integer, String
from sqlalchemy import schema

metadata = MetaData()

table = Table('mytable', MetaData(),
        Column('x', Integer, info={"special":True}, primary_key=True),
        Column('y', String(50)),
        Column('z', String(20), info={"special":True})
    )

metadata.create_all(conn)

以上，我们添加到Column.info集合中的指令将被我们自定义的编译方案检测到：

CREATE TABLE mytable (
        x SPECIAL DIRECTIVE INTEGER NOT NULL,
        y VARCHAR(50),
        z SPECIAL DIRECTIVE VARCHAR(20),
    PRIMARY KEY (x)
)

CreateColumn构造也可以用于在生成CREATE TABLE时跳过某些列。这是通过创建一个有条件返回None的编译规则来实现的。这实质上就是如何产生与在Column上使用system=True参数相同的效果，该参数将列标记为隐含的“系统”列。

例如，假设我们希望生成一个Table，在 PostgreSQL 后端跳过渲染 PostgreSQL xmin列，但在其他后端进行渲染，以预期触发规则。一个条件编译规则可以仅在 PostgreSQL 上跳过此名称：

from sqlalchemy.schema import CreateColumn

@compiles(CreateColumn, "postgresql")
def skip_xmin(element, compiler, **kw):
    if element.element.name == 'xmin':
        return None
    else:
        return compiler.visit_create_column(element, **kw)

my_table = Table('mytable', metadata,
            Column('id', Integer, primary_key=True),
            Column('xmin', Integer)
        )

上面，一个CreateTable结构将仅在字符串中包含id列；xmin列将被省略，但仅针对 PostgreSQL 后端。

类签名

类sqlalchemy.schema.CreateColumn（sqlalchemy.schema.BaseDDLElement）

class sqlalchemy.schema.CreateSequence

表示一个 CREATE SEQUENCE 语句。

类签名

类sqlalchemy.schema.CreateSequence（sqlalchemy.schema._CreateBase）

class sqlalchemy.schema.DropSequence

表示一个 DROP SEQUENCE 语句。

类签名

类sqlalchemy.schema.DropSequence（sqlalchemy.schema._DropBase）

class sqlalchemy.schema.CreateIndex

表示一个 CREATE INDEX 语句。

成员

init()

类签名

类sqlalchemy.schema.CreateIndex（sqlalchemy.schema._CreateBase）

method __init__(element, if_not_exists=False)

创建一个Createindex结构。

参数：

• element – 一个Index，是 CREATE 的主题。
• if_not_exists – 如果为 True，则将 IF NOT EXISTS 运算符应用于该结构。 新版本 1.4.0b2 中新增。

class sqlalchemy.schema.DropIndex

表示一个 DROP INDEX 语句。

成员

init()

类签名

类sqlalchemy.schema.DropIndex（sqlalchemy.schema._DropBase）

method __init__(element, if_exists=False)

创建一个DropIndex结构。

参数：

• element – 一个Index，是 DROP 的主题。
• if_exists – 如果为 True，则将 IF EXISTS 运算符应用于该结构。 新版本 1.4.0b2 中新增。

class sqlalchemy.schema.AddConstraint

表示一个 ALTER TABLE ADD CONSTRAINT 语句。

类签名

类 sqlalchemy.schema.AddConstraint (sqlalchemy.schema._CreateBase)

class sqlalchemy.schema.DropConstraint

表示一个 ALTER TABLE DROP CONSTRAINT 语句。

类签名

类 sqlalchemy.schema.DropConstraint (sqlalchemy.schema._DropBase)

class sqlalchemy.schema.CreateSchema

表示一个 CREATE SCHEMA 语句。

这里的参数是模式的字符串名称。

成员

init()

类签名

类 sqlalchemy.schema.CreateSchema (sqlalchemy.schema._CreateBase)

method __init__(name, if_not_exists=False)

创建一个新的 CreateSchema 构造。

class sqlalchemy.schema.DropSchema

表示一个 DROP SCHEMA 语句。

这里的参数是模式的字符串名称。

成员

init()

类签名

类 sqlalchemy.schema.DropSchema (sqlalchemy.schema._DropBase)

method __init__(name, cascade=False, if_exists=False)

创建一个新的 DropSchema 构造。

SQL 数据类型对象

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

• 类型层次结构
  • “驼峰式”数据类型
  • “大写”数据类型
  • 特定后端的“大写”数据类型
  • 在多个后端使用“大写”和特定后端类型
  • 通用“驼峰式”类型
    • BigInteger
    • Boolean
    • Date
    • DateTime
    • Enum
    • Double
    • Float
    • Integer
    • Interval
    • LargeBinary
    • MatchType
    • Numeric
    • PickleType
    • SchemaType
    • SmallInteger
    • String
    • Text
    • Time
    • Unicode
    • UnicodeText
    • Uuid
  • SQL 标准和多厂商“大写”类型
    • ARRAY
    • BIGINT
    • BINARY
    • BLOB
    • BOOLEAN
    • CHAR
    • CLOB
    • DATE
    • DATETIME
    • DECIMAL
    • DOUBLE
    • DOUBLE_PRECISION
    • FLOAT
    • INT
    • JSON
    • INTEGER
    • NCHAR
    • NVARCHAR
    • NUMERIC
    • REAL
    • SMALLINT
    • TEXT
    • TIME
    • TIMESTAMP
    • UUID
    • VARBINARY
    • VARCHAR
• 自定义类型
  • 覆盖类型编译
  • 增强现有类型
    • TypeDecorator
  • 类型修饰器示例
    • 将编码字符串强制转换为 Unicode
    • 数值四舍五入
    • 将时区感知时间戳存储为时区无关的 UTC
    • 与后端无关的 GUID 类型
    • 编组 JSON 字符串
  • 应用 SQL 级别的绑定/结果处理
  • 重新定义和创建新操作符
  • 创建新类型
    • UserDefinedType
  • 使用自定义类型和反射
• 基础类型 API
  • TypeEngine
    • TypeEngine.Comparator
    • TypeEngine.adapt()
    • TypeEngine.as_generic()
    • TypeEngine.bind_expression()
    • TypeEngine.bind_processor()
    • TypeEngine.coerce_compared_value()
    • TypeEngine.column_expression()
    • TypeEngine.comparator_factory
    • TypeEngine.compare_values()
    • TypeEngine.compile()
    • TypeEngine.dialect_impl()
    • TypeEngine.evaluates_none()
    • TypeEngine.get_dbapi_type()
    • TypeEngine.hashable
    • TypeEngine.literal_processor()
    • TypeEngine.python_type
    • TypeEngine.render_bind_cast
    • TypeEngine.render_literal_cast
    • TypeEngine.result_processor()
    • TypeEngine.should_evaluate_none
    • TypeEngine.sort_key_function
    • TypeEngine.with_variant()
  • Concatenable
    • Concatenable.Comparator
    • Concatenable.comparator_factory
  • Indexable
    • Indexable.Comparator
    • Indexable.comparator_factory
  • NullType
  • ExternalType
    • ExternalType.cache_ok
  • Variant
    • Variant.with_variant()

类型层次结构

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

SQLAlchemy 提供了对大多数常见数据库数据类型的抽象，以及多种自定义数据类型的技术。

数据库类型使用 Python 类表示，所有这些类最终都是从名为TypeEngine的基本类型类扩展而来。有两种一般类别的数据类型，它们在类型层次结构中以不同的方式表达自己。根据两种不同的命名约定，即“驼峰命名法”和“大写字母”，可以识别个别数据类型类使用的类别。

另请参见

使用表对象设置 MetaData - 在 SQLAlchemy Unified Tutorial 中。以教程形式演示了使用TypeEngine类型对象定义Table元数据并介绍了类型对象的概念的最基本用法。

“驼峰命名法”数据类型

初级类型的命名采用“驼峰命名法”，如String、Numeric、Integer和DateTime。所有TypeEngine的直接子类都是“驼峰命名法”类型。尽可能“驼峰命名法”类型是与数据库无关的，这意味着它们可以在任何数据库后端上使用，在这些后端上，它们将以适合该后端的方式行事，以产生所需的行为。

简单的“驼峰命名法”数据类型示例是String。在大多数后端上，将此数据类型用于 table specification 将对应于在目标后端上使用VARCHAR数据库类型，从而在数据库和数据库之间传递字符串值，如下例所示：

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

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String, primary_key=True),
    Column("email_address", String(60)),
)

在表定义或整体 SQL 表达式中使用特定的TypeEngine类时，如果不需要参数，则可以将其作为类本身传递，即不需要实例化它，例如上面的"email_address"列中的长度参数 60。如果需要参数，则可以将类型实例化。

另一个表达更具后端特定行为的“驼峰命名法”数据类型是Boolean数据类型。与String表示所有数据库都具有的字符串数据类型不同，不是每个后端都有真正的“布尔”数据类型；一些后端使用整数或比特值 0 和 1，一些具有布尔字面常量true和false，而另一些则没有。对于此数据类型，Boolean在后端（如 PostgreSQL）上可能会呈现为BOOLEAN，在 MySQL 后端上可能为BIT，在 Oracle 上可能为SMALLINT。当使用此类型发送和接收数据到数据库时，根据正在使用的方言，它可能会解释 Python 数字或布尔值。

典型的 SQLAlchemy 应用程序通常会在一般情况下主要使用“驼峰命名法”类型，因为它们通常提供最佳的基本行为，并且可以自动地在所有后端上移植。

通用“驼峰命名法”数据类型的参考资料请参见通用“驼峰命名法”类型。

“大写字母”数据类型

与“驼峰命名法”类型相反的是“大写字母”数据类型。这些数据类型总是从特定的“驼峰命名法”数据类型继承，并且始终表示确切的数据类型。当使用“大写字母”数据类型时，类型的名称始终精确地呈现，而不考虑当前后端是否支持它。因此，在 SQLAlchemy 应用程序中使用“大写字母”类型表示需要特定数据类型，这随后意味着应用程序通常（如果没有采取额外步骤）会受限于那些完全使用给定类型的后端。大写字母类型的示例包括VARCHAR、NUMERIC、INTEGER和TIMESTAMP，它们直接继承自前面提到的“驼峰命名法”类型String、Numeric、Integer和DateTime。

作为sqlalchemy.types的一部分的“大写字母”数据类型是通用 SQL 类型，通常期望在至少两个后端上可用。

通用“大写字母”数据类型的参考资料请参见 SQL 标准和多供应商“大写字母”类型。

后端特定的“大写字母”数据类型

大多数数据库还具有完全特定于这些数据库的数据类型，或者添加了特定于这些数据库的附加参数。对于这些数据类型，特定的 SQLAlchemy 方言提供了后端特定的“大写”数据类型，用于在其他后端上没有类似物的 SQL 类型。后端特定大写数据类型的示例包括 PostgreSQL 的JSONB、SQL Server 的IMAGE和 MySQL 的TINYTEXT。

某些后端还可能包括“大写”数据类型，这些数据类型扩展了来自sqlalchemy.types模块中相同“大写”数据类型的参数。例如，当创建 MySQL 字符串数据类型时，可能希望指定 MySQL 特定参数，如charset或national，这些参数可以从 MySQL 版本的VARCHAR作为仅 MySQL 参数VARCHAR.charset和VARCHAR.national。

后端特定类型的 API 文档在方言特定文档中列出，详见方言。## 使用“大写”和后端特定类型用于多个后端

检查“大写”和“驼峰”类型的存在自然会引出如何在使用特定后端时利用“大写”数据类型的自然用例，但仅当该后端正在使用时。为了将数据库无关的“驼峰”和特定后端的“大写”系统联系在一起，可以使用TypeEngine.with_variant()方法将类型组合在一起，以在特定后端上使用特定行为。

例如，要使用String数据类型，但在运行时在 MySQL 上使用VARCHAR.charset参数的VARCHAR创建表时，可以使用TypeEngine.with_variant()如下所示：

from sqlalchemy import MetaData
from sqlalchemy import Table, Column, Integer, String
from sqlalchemy.dialects.mysql import VARCHAR

metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("user_name", String(100), primary_key=True),
    Column(
        "bio",
        String(255).with_variant(VARCHAR(255, charset="utf8"), "mysql", "mariadb"),
    ),
)

在上面的表定义中，"bio"列将在所有后端上具有字符串行为。在大多数后端上，它将在 DDL 中呈现为VARCHAR。然而，在 MySQL 和 MariaDB（通过以mysql或mariadb开头的数据库 URL 表示）上，它将呈现为VARCHAR(255) CHARACTER SET utf8。

另请参阅

TypeEngine.with_variant() - 附加用法示例和注意事项 ## 通用“驼峰大小写”类型

通用类型指定一个列，该列可以读取、写入和存储特定类型的 Python 数据。当发出CREATE TABLE语句时，SQLAlchemy 将选择目标数据库上可用的最佳数据库列类型。对于完全控制在CREATE TABLE中发出的列类型，比如VARCHAR，请参见 SQL 标准和多个供应商的“大写”类型和本章的其他部分。

class sqlalchemy.types.BigInteger

用于较大的int整数的类型。

在 DDL 中通常生成 BIGINT，在 Python 端则像正常的 Integer 一样操作。

类签名

class sqlalchemy.types.BigInteger (sqlalchemy.types.Integer)

class sqlalchemy.types.Boolean

布尔数据类型。

Boolean 通常在 DDL 方面使用 BOOLEAN 或 SMALLINT，在 Python 方面处理 True 或 False。

Boolean 数据类型目前有两个断言级别，用于确保持久化的值是简单的 true/false 值。对于所有后端，仅接受 Python 值 None、True、False、1 或 0 作为参数值。对于不支持“本地布尔”数据类型的后端，还可以在目标列上创建 CHECK 约束的选项

1.2 版本中的变化：Boolean 数据类型现在断言传入的 Python 值已经是纯布尔形式。

成员

init(), bind_processor(), literal_processor(), python_type, result_processor()

类签名

class sqlalchemy.types.Boolean (sqlalchemy.types.SchemaType, sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method __init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)

构造一个布尔值。

参数：

• create_constraint – 默认为 False。如果布尔值生成为 int/smallint，还会在表上创建一个 CHECK 约束，以确保值为 1 或 0。 注意 强烈建议 CHECK 约束具有明确的名称，以支持模式管理方面的关注。可以通过设置 Boolean.name 参数或设置适当的命名约定来实现；有关背景信息，请参阅 配置约束命名约定。 1.4 版本中的变化：- 此标志现在默认为 False，表示非本机枚举类型不会生成 CHECK 约束。
• name – 如果生成了 CHECK 约束，请指定约束的名称。

method bind_processor(dialect)

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收一个绑定参数值作为唯一位置参数，并返回一个要发送到 DB-API 的值。

如果不需要处理，方法应返回 None。

注意

此方法仅相对于方言特定类型对象调用，该对象通常是方言中使用的私有对象，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供备用的TypeEngine.bind_processor()方法，除非明确地子类化UserDefinedType类。

为了为TypeEngine.bind_processor()提供备用行为，实现一个TypeDecorator类，并提供一个TypeDecorator.process_bind_param()的实现。

另见

增强现有类型

参数：

dialect – 正在使用的方言实例。

method literal_processor(dialect)

返回一个转换函数，用于处理要直接呈现而不使用绑定的文字值。

当编译器使用“literal_binds”标志时，通常在 DDL 生成以及某些后端不接受绑定参数的情况下使用此函数。

返回一个可调用对象，它将接收一个字面 Python 值作为唯一的位置参数，并返回一个字符串表示以在 SQL 语句中呈现。

注意

此方法仅相对于方言特定类型对象调用，该对象通常是方言中使用的私有对象，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供备用的TypeEngine.literal_processor()方法，除非明确地子类化UserDefinedType类。

为了为TypeEngine.literal_processor()提供备用行为，实现一个TypeDecorator类，并提供一个TypeDecorator.process_literal_param()的实现。

另见

增强现有类型

attribute python_type

method result_processor(dialect, coltype)

返回一个用于处理结果行值的转换函数。

返回一个可调用对象，该对象将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则方法应返回None。

注意

此方法仅相对于特定方言类型对象调用，该对象通常私有于使用的方言，并且不是与公共类型对象相同的类型对象，这意味着不可能通过继承TypeEngine类来提供替代的TypeEngine.result_processor()方法，除非显式地继承UserDefinedType类。

要为TypeEngine.result_processor()提供替代行为，需实现一个TypeDecorator类，并提供一个TypeDecorator.process_result_value()的实现。

另请参见

扩充现有类型

参数：

• dialect – 正在使用的方言实例。
• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

class sqlalchemy.types.Date

用于datetime.date()对象的类型。

成员

get_dbapi_type()，literal_processor()，python_type

类签名

类sqlalchemy.types.Date（sqlalchemy.types._RenderISO8601NoT，sqlalchemy.types.HasExpressionLookup，sqlalchemy.types.TypeEngine）

method get_dbapi_type(dbapi)

返回底层 DB-API 中相应的类型对象（如果有）。

例如，这对于调用setinputsizes()可能很有用。

method literal_processor(dialect)

返回一个用于处理直接呈现而不使用绑定的文字值的转换函数。

当编译器使用“literal_binds”标志时，通常用于 DDL 生成以及某些情况下后端不接受绑定参数时，将使用此函数。

返回一个可调用对象，该对象将接收一个文字 Python 值作为唯一的位置参数，并将返回一个字符串表示以在 SQL 语句中呈现。

注意

这个方法仅在特定方言的类型对象相关时才被调用，这通常是私有于正在使用的方言的，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供替代的TypeEngine.literal_processor()方法，除非明确地子类化UserDefinedType类。

要为 TypeEngine.literal_processor() 提供替代行为，请实现一个 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

扩展现有类型

attribute python_type

class sqlalchemy.types.DateTime

一个用于datetime.datetime()对象的类型。

日期和时间类型返回来自 Python datetime 模块的对象。大多数 DBAPI 都内置支持 datetime 模块，但 SQLite 是个例外。在 SQLite 的情况下，日期和时间类型存储为字符串，然后在返回行时将其转换回 datetime 对象。

在 datetime 类型内的时间表示中，一些后端包括其他选项，例如时区支持和分数秒支持。对于分数秒，使用特定于方言的数据类型，例如TIME。对于时区支持，至少使用TIMESTAMP数据类型，如果不是特定于方言的数据类型对象。

成员

init(), get_dbapi_type(), literal_processor(), python_type

类签名

类 sqlalchemy.types.DateTime (sqlalchemy.types._RenderISO8601NoT, sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method __init__(timezone: bool = False)

构造一个新的 DateTime。

参数：

timezone – 布尔值。指示日期时间类型是否应启用时区支持，如果仅在基本日期/时间保存类型上可用。建议在使用此标志时直接使用TIMESTAMP 数据类型，因为一些数据库包括与支持时区的 TIMESTAMP 数据类型不同的单独的通用日期/时间保存类型，如 Oracle。

method get_dbapi_type(dbapi)

如果有的话，返回底层 DB-API 的相应类型对象。

这对于调用setinputsizes()可能很有用。

method literal_processor(dialect)

返回一个转换函数，用于处理直接呈现而不使用绑定的字面值。

当编译器使用“literal_binds”标志时，通常用于 DDL 生成以及在某些后端不接受绑定参数的情况下使用此函数。

返回一个可调用对象，该对象将接收一个字面的 Python 值作为唯一的位置参数，并返回一个字符串表示，以在 SQL 语句中呈现。

注意

此方法仅相对于特定方言类型对象调用，该对象通常私有于正在使用的方言，并且不是公共类型对象，这意味着不可通过子类化TypeEngine 类来提供替代的TypeEngine.literal_processor() 方法，除非显式地子类化UserDefinedType 类。

要为TypeEngine.literal_processor() 提供替代行为，请实现一个TypeDecorator 类，并提供一个TypeDecorator.process_literal_param() 的实现。

另请参阅

扩展现有类型

attribute python_type

class sqlalchemy.types.Enum

通用枚举类型。

Enum 类型提供了一组可能的字符串值，列受其约束。

如果可用，Enum 类型将使用后端的本机“ENUM”类型；否则，它使用 VARCHAR 数据类型。还存在一个选项，即在生成 VARCHAR（所谓的“非本机”）变体时自动生成 CHECK 约束；请参阅Enum.create_constraint 标志。

Enum 类型在 Python 中也提供了对字符串值进行读写操作期间的验证。从结果集中读取数据库中的值时，始终检查字符串值是否与可能值列表匹配，如果找不到匹配项，则引发 LookupError。在将值作为 SQL 语句中的纯字符串传递给数据库时，如果 Enum.validate_strings 参数设置为 True，则对于未位于给定可能值列表中的任何字符串值，都会引发 LookupError；请注意，这会影响到具有枚举值的 LIKE 表达式的使用（这是一个不寻常的用例）。

枚举值的来源可以是字符串值列表，或者是符合 PEP-435 的枚举类。对于 Enum 数据类型，此类只需要提供一个 __members__ 方法即可。

当使用枚举类时，枚举对象用于输入和输出，而不是字符串，就像普通字符串枚举类型一样：

import enum
from sqlalchemy import Enum

class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3

t = Table(
    'data', MetaData(),
    Column('value', Enum(MyEnum))
)

connection.execute(t.insert(), {"value": MyEnum.two})
assert connection.scalar(t.select()) is MyEnum.two

在上面，每个元素的字符串名称（例如“one”、“two”、“three”）都会被持久化到数据库中；Python 枚举的值，这里表示为整数，不会被使用；因此，每个枚举的值可以是任何类型的 Python 对象，无论它是否可持久化。

为了持久化值而不是名称，可以使用 Enum.values_callable 参数。该参数的值是一个用户提供的可调用对象，旨在与符合 PEP-435 的枚举类一起使用，并返回要持久化的字符串值列表。对于使用字符串值的简单枚举，像 lambda x: [e.value for e in x] 这样的可调用对象就足够了。

另见

在类型映射中使用 Python 枚举或 pep-586 Literal 类型 - 使用 ORM 的 ORM 注释声明 功能时，关于在类型映射中使用 Enum 数据类型的背景信息。

ENUM - PostgreSQL 特定类型，具有额外的功能。

ENUM - MySQL 特定类型

成员

init(), create(), drop()

类签名

类sqlalchemy.types.Enum（sqlalchemy.types.String，sqlalchemy.types.SchemaType，sqlalchemy.types.Emulated，sqlalchemy.types.TypeEngine）

method __init__(*enums: object, **kw: Any)

构造枚举。

不适用于特定后端的关键字参数将被该后端忽略。

参数：

• *enums – 要么正好一个符合 PEP-435 标准的枚举类型，要么一个或多个字符串标签。
• create_constraint – 默认为 False。创建非本地枚举类型时，还在数据库上构建 CHECK 约束以针对有效值。 注意 强烈建议为 CHECK 约束指定显式名称，以支持模式管理方面的问题。这可以通过设置 Enum.name 参数或设置适当的命名约定来实现；有关背景，请参见配置约束命名约定。 自版本 1.4 更改： - 此标志现在默认为 False，意味着对非本地枚举类型不会生成 CHECK 约束。
• metadata – 将此类型直接关联到 MetaData 对象。对于作为独立模式构造存在于目标数据库上的类型（如 PostgreSQL），此类型将在 create_all() 和 drop_all() 操作中创建和删除。如果该类型未与任何 MetaData 对象相关联，则它将与使用它的每个 Table 相关联，并且将在创建任何这些单独表时创建，并在检查其存在后创建。但是，仅在对该 Table 对象的元数据调用 drop_all() 时才会删除该类型。 如果设置了MetaData 对象的 MetaData.schema 参数的值，并且未显式提供值，则将使用该对象上的 Enum.schema 的默认值。 自版本 1.4.12 更改：Enum 如果传递使用Enum.metadata 参数时继承 MetaData 对象的MetaData.schema 参数（如果存在）。
• name – 此类型的名称。这对于 PostgreSQL 和任何将来需要显式命名类型或显式命名约束以生成使用它的类型和/或表的支持数据库是必需的。如果使用了 PEP-435 枚举类，则默认情况下使用其名称（转换为小写）。
• native_enum – 在可用时使用数据库的本机 ENUM 类型。默认为 True。当为 False 时，对所有后端使用 VARCHAR + 检查约束。当为 False 时，如果 native_enum=True，则“length”将被忽略。
• length – 允许在使用非本机枚举数据类型时为 VARCHAR 指定自定义长度。默认情况下，它使用最长值的长度。 从版本 2.0.0 开始更改：无条件地使用 Enum.length 参数进行 VARCHAR 渲染，而不管 Enum.native_enum 参数的设置情况，对于那些使用 VARCHAR 作为枚举数据类型的后端。
• schema – 此类型的模式名称。对于作为独立模式构造存在于目标数据库上的类型（PostgreSQL），此参数指定了类型存在的命名模式。 如果不存在，则在传递为 Enum.metadata 的 MetaData 中获取模式名称，对于包含 MetaData.schema 参数的 MetaData。 从版本 1.4.12 开始更改：如果使用 Enum.metadata 参数传递，则 Enum 继承了 MetaData 对象的 MetaData.schema 参数（如果存在）。 否则，如果Enum.inherit_schema标志设置为True，则模式将从相关的Table对象继承，如果有的话；当Enum.inherit_schema处于默认值False时，不使用所属表的模式。
• quote – 为类型的名称设置明确的引用首选项。
• inherit_schema – 当为 True 时，将从所属 Table 的schema复制到此 Enum 的schema属性中，替换传递给 schema 属性的任何值。这也会在使用 Table.to_metadata() 操作时生效。
• validate_strings – 当为 True 时，将传递给 SQL 语句的字符串值将被检查是否有效。未识别的值将引发 LookupError。
• values_callable – 一个可调用对象，将传递符合 PEP-435 的枚举类型，然后应返回要持久化的字符串值列表。这允许替代用法，例如使用枚举的字符串值而不是其名称持久化到数据库中。可调用对象必须以与迭代枚举的 __member__ 属性相同的顺序返回要持久化的值。例如 lambda x: [i.value for i in x]。 从版本 1.2.3 起新增。
• sort_key_function – 可以作为 Python sorted() 内置函数中的“key”参数使用的 Python 可调用对象。SQLAlchemy ORM 要求映射的主键列必须以某种方式可排序。当使用不可排序的枚举对象，如 Python 3 的 Enum 对象时，可以使用此参数为对象设置默认的排序键函数。默认情况下，枚举的数据库值被用作排序函数。 从版本 1.3.8 起新增。
• omit_aliases – 当为 true 时，将从 pep 435 枚举中删除别名的布尔值。默认为 True。 自版本 2.0 起更改：此参数现在默认为 True。

method create(bind, checkfirst=False)

继承自 SchemaType.create() 方法的 SchemaType

如适用，为此类型发出 CREATE DDL。

method drop(bind, checkfirst=False)

继承自 SchemaType.drop() 方法的 SchemaType

如适用，为此类型发出 DROP DDL。

class sqlalchemy.types.Double

用于双 FLOAT 浮点类型的类型。

通常在 DDL 中生成 DOUBLE 或 DOUBLE_PRECISION，否则在 Python 方面的行为类似于普通的 Float。

从版本 2.0 起新增。

类签名

类 sqlalchemy.types.Double (sqlalchemy.types.Float)

class sqlalchemy.types.Float

表示浮点类型的类型，例如 FLOAT 或 REAL。

默认情况下，此类型返回 Python float对象，除非将Float.asdecimal标志设置为True，在这种情况下，它们将被强制转换为decimal.Decimal对象。

当Float.precision在Float类型中未提供时，某些后端可能将此类型编译为 8 字节/64 位浮点数据类型。要使用 4 字节/32 位浮点数据类型，通常可以提供精度<= 24，或者可以使用REAL类型。已知在将类型呈现为FLOAT的 PostgreSQL 和 MSSQL 方言中，这种情况是成立的，这两者都是DOUBLE PRECISION的别名。其他第三方方言可能具有类似的行为。

成员

init(), result_processor()

类签名

类sqlalchemy.types.Float（sqlalchemy.types.Numeric）

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

构造一个浮点数。

参数：

precision –

用于在 DDL CREATE TABLE中使用的数字精度。后端应该尝试确保此精度指示了通用Float数据类型的数字位数。

注意

对于 Oracle 后端，在渲染 DDL 时，不接受Float.precision参数，因为 Oracle 不支持将浮点精度指定为小数位数。相反，请使用特定于 Oracle 的FLOAT数据类型，并指定FLOAT.binary_precision参数。这是 SQLAlchemy 2.0 版本中的新功能。

要创建一个数据库通用的Float，并为 Oracle 单独指定二进制精度，请使用TypeEngine.with_variant()如下所示：

from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle")
)

asdecimal – 与Numeric相同的标志，但默认为False。请注意，将此标志设置为True会导致浮点数转换。

decimal_return_scale – 在将浮点数转换为 Python 小数时使用的默认精度。由于十进制的不准确性，浮点值通常会更长，而大多数浮点数据库类型没有“精度”的概念，因此默认情况下，当转换时，浮点类型将查找前十位小数。指定此值将覆盖该长度。请注意，如果未另行指定，则 MySQL 浮点类型将使用“精度”作为decimal_return_scale的默认值。

method result_processor(dialect, coltype)

返回一个用于处理结果行值的转换函数。

返回一个可调用对象，该对象将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，该方法应返回None。

注意

此方法仅相对于一个方言特定类型对象调用，该对象通常是正在使用的方言中的私有对象，并且不是与公共对象相同的类型对象，这意味着无法子类化TypeEngine类以提供替代TypeEngine.result_processor()方法，除非明确子类化UserDefinedType类。

要为TypeEngine.result_processor()提供替代行为，请实现TypeDecorator类，并提供TypeDecorator.process_result_value()的实现。

另请参阅

扩充现有类型

参数：

• 方言 – 正在使用的方言实例。
• coltype – 在 cursor.description 中接收的 DBAPI coltype 参数。

class sqlalchemy.types.Integer

一种适用于int整数的类型。

成员

get_dbapi_type()，literal_processor()，python_type

类签名

类sqlalchemy.types.Integer (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method get_dbapi_type(dbapi)

如果有的话，返回底层 DB-API 的相应类型对象。

例如，这对于调用setinputsizes()可能很有用。

method literal_processor(dialect)

返回一个用于处理直接呈现的字面值的转换函数，而无需使用绑定。

此函数在编译器使用 “literal_binds” 标志时使用，通常用于 DDL 生成以及在某些后端不接受绑定参数的情况下。

返回一个可调用对象，该对象将接收一个字面的 Python 值作为唯一的位置参数，并返回一个字符串表示以在 SQL 语句中呈现。

注意

此方法仅相对于 特定方言类型对象 调用，该对象通常是 特定方言私有的，并且与公共类型对象不同，这意味着不可能通过子类化 TypeEngine 类来提供替代的 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 TypeEngine.literal_processor() 提供替代行为，请实现一个 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

扩展现有类型

attribute python_type

class sqlalchemy.types.Interval

用于 datetime.timedelta() 对象的类型。

Interval 类型处理 datetime.timedelta 对象。在 PostgreSQL 和 Oracle 中，使用原生的 INTERVAL 类型；对于其他数据库，该值存储为相对于“epoch”（1970 年 1 月 1 日）的日期。

请注意，Interval 类型当前在不原生支持间隔类型的平台上不提供日期算术操作。这些操作通常需要对表达式的两侧进行转换（例如，首先将两侧转换为整数时期值），目前这是一个手动过程（例如，通过 expression.func）。

成员

init(), adapt_to_emulated(), bind_processor(), cache_ok, coerce_compared_value(), comparator_factory, impl, python_type, result_processor()

类签名

类sqlalchemy.types.Interval (sqlalchemy.types.Emulated, sqlalchemy.types._AbstractInterval, sqlalchemy.types.TypeDecorator)

class Comparator

类签名

类sqlalchemy.types.Interval.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method __init__(native: bool = True, second_precision: int | None = None, day_precision: int | None = None)

构造一个 Interval 对象。

参数：

• native – 当为 True 时，如果支持（目前是 PostgreSQL、Oracle），则使用数据库提供的实际 INTERVAL 类型。否则，无论如何都将间隔数据表示为时代值。
• second_precision – 对于支持“分秒精度”参数的本机间隔类型，例如 Oracle 和 PostgreSQL
• day_precision – 对于支持“天精度”参数的本机间隔类型，例如 Oracle。

method adapt_to_emulated(impltype, **kw)

给定一个 impl 类，将此类型适配到 impl，假设“模拟”。

impl 还应该是此类型的“模拟”版本，很可能是与此类型本身相同的类。

例如：sqltypes.Enum 适应于 Enum 类。

method bind_processor(dialect: Dialect) → _BindProcessorType[dt.timedelta]

返回一个用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收绑定参数值作为唯一的位置参数，并返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回None。

注

此方法仅相对于特定方言类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式地对UserDefinedType类进行子类化。

要为TypeEngine.bind_processor()提供替代行为，请实现一个TypeDecorator类，并提供TypeDecorator.process_bind_param()的实现。

另请参见

扩展现有类型

参数：

方言 – 正在使用的方言实例。

attribute cache_ok: bool | None = True

指示使用此ExternalType的语句是否“安全缓存”。

默认值None会发出警告，然后不允许缓存包含此类型的语句。设置为False以禁用完全不带警告缓存使用此类型的语句。当设置为True时，将使用对象的类和其状态的选定元素作为缓存键的一部分。例如，使用TypeDecorator:

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键将等同于：

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从类型中提取与__init__()方法中参数名称对应的属性。上面的“choices”属性成为缓存键的一部分，但“internal_only”不会，因为没有名为“internal_only”的参数。

可缓存元素的要求是它们是可哈希的，并且它们指示对于给定缓存值的表达式每次返回相同的 SQL 渲染。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，这些对象可以通过将可哈希结构分配给与参数名称对应的属性来“可缓存”。例如，一个接受查找值字典的数据类型可以将其发布为排序后的元组序列。假设以前不可缓存的类型如下：

class LookupType(UserDefinedType):
  '''a custom type that accepts a dictionary as a parameter.

 this is the non-cacheable version, as "self.lookup" is not
 hashable.

 '''

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self.lookup" ...

其中“lookup”是一个字典。该类型将无法生成缓存键：

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果我们确实设置了这样一个缓存键，它将无法使用。我们将得到一个包含字典的元组结构，该字典本身不能用作“缓存字典”中的键，例如 SQLAlchemy 的语句缓存，因为 Python 字典不可哈希：

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

通过将排序后的元组分配给“lookup”属性，可以使类型成为可缓存的：

class LookupType(UserDefinedType):
  '''a custom type that accepts a dictionary as a parameter.

 The dictionary is stored both as itself in a private variable,
 and published in a public variable as a sorted tuple of tuples,
 which is hashable and will also return the same value for any
 two equivalent dictionaries.  Note it assumes the keys and
 values of the dictionary are themselves hashable.

 '''

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple(
            (key, lookup[key]) for key in sorted(lookup)
        )

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self._lookup" ...

在上述情况下，LookupType({"a": 10, "b": 20})的缓存键将是：

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

新版本 1.4.14 中新增：- 添加了 cache_ok 标志，以允许对 TypeDecorator 类进行某些缓存配置。

新版本 1.4.28 中新增：- 添加了 ExternalType 混合类，它将 cache_ok 标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参阅

SQL 编译缓存

method coerce_compared_value(op, value)

在表达式中为‘coerced’ Python 值建议一个类型。

给定一个运算符和值，使类型有机会返回一个值应该被强制转换为的类型。

这里的默认行为是保守的；如果右侧已根据其 Python 类型强制转换为 SQL 类型，则通常会保持不变。

此处的最终用户功能扩展通常应通过 TypeDecorator 实现，该实现具有更宽松的行为，因为它默认将表达式的另一侧强制转换为此类型，从而对除 DBAPI 需要的特殊 Python 转换之外的内容进行应用。它还提供了 TypeDecorator.coerce_compared_value() 的公共方法，该方法用于最终用户自定义此行为。

attribute comparator_factory

别名 Comparator

attribute impl

别名 DateTime

attribute python_type

method result_processor(dialect: Dialect, coltype: Any) → _ResultProcessorType[dt.timedelta]

返回一个用于处理结果行值的转换函数。

返回一个可调用对象，该对象将接收一个结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，方法应返回None。

注

仅相对于方言特定类型对象调用此方法，该对象通常私有于正在使用的方言，并且与公共面向对象不同，这意味着无法通过子类化 TypeEngine 类来提供替代的 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类。

要为 TypeEngine.result_processor() 提供替代行为，实现一个 TypeDecorator 类并提供 TypeDecorator.process_result_value() 的实现。

另请参见

扩展现有类型

参数：

• dialect – 正在使用的方言实例。
• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

class sqlalchemy.types.LargeBinary

用于大型二进制字节数据的类型。

LargeBinary 类型对应于目标平台的大型和/或无长度的二进制类型，例如 MySQL 上的 BLOB 和 PostgreSQL 上的 BYTEA。它还处理了 DBAPI 的必要转换。

成员

init()

类签名

类 sqlalchemy.types.LargeBinary (sqlalchemy.types._Binary)

method __init__(length: int | None = None)

构造一个大型二进制类型。

参数：

长度 – 可选，用于 DDL 语句的列长度，用于那些接受长度的二进制类型，例如 MySQL 的 BLOB 类型。

class sqlalchemy.types.MatchType

指的是 MATCH 操作符的返回类型。

由于 ColumnOperators.match() 可能是 SQLAlchemy 核心中最开放的运算符，我们不能在 SQL 评估时假设返回类型，因为 MySQL 返回浮点数而不是布尔值，其他后端可能会执行不同的操作。因此，此类型充当占位符，目前是 Boolean 的子类。该类型允许方言在需要时注入结果处理功能，在 MySQL 上将返回浮点值。

类签名

类 sqlalchemy.types.MatchType (sqlalchemy.types.Boolean)

class sqlalchemy.types.Numeric

非整数数字类型的基类，例如 NUMERIC、FLOAT、DECIMAL 和其他变体。

当直接使用 Numeric 数据类型时，如果可用，会呈现对应精度数字的 DDL，例如 NUMERIC(precision, scale)。当使用 Float 子类时，会尝试呈现浮点数据类型，例如 FLOAT(precision)。

Numeric 默认返回 Python decimal.Decimal 对象，基于 Numeric.asdecimal 参数的默认值 True。如果此参数设置为 False，则返回的值将被强制转换为 Python float 对象。

Float 子类型更具体于浮点数，默认情况下，Float.asdecimal 标志设置为 False，以便默认的 Python 数据类型为 float。

注意

当针对返回 Python 浮点值的数据库类型使用 Numeric 数据类型时，由 Numeric.asdecimal 指示的十进制转换的精度可能受到限制。具体数字/浮点数据类型的行为取决于正在使用的 SQL 数据类型、正在使用的 Python DBAPI 以及在使用的 SQLAlchemy 方言中可能存在的策略。鼓励需要特定精度/比例的用户尝试使用可用数据类型以确定最佳结果。

成员

init(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

类签名

类 sqlalchemy.types.Numeric (sqlalchemy.types.HasExpressionLookup, sqlalchemy.types.TypeEngine)

method __init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)

构造一个 Numeric。

参数：

• precision – 用于 DDL CREATE TABLE 的数值精度。
• scale – 用于 DDL CREATE TABLE 的数值比例。
• asdecimal – 默认为 True。返回值是否应该作为 Python Decimal 对象发送，还是作为浮点数发送。不同的 DBAPI 根据数据类型发送其中之一 - Numeric 类型将确保跨 DBAPI 一致地返回值为其中之一。
• decimal_return_scale – 在从浮点数转换为 Python 十进制数时使用的默认精度。由于十进制不精确，浮点值通常会更长，并且大多数浮点数据库类型都没有“精度”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。包括显式“.scale”值的类型，例如基本 Numeric 和 MySQL 浮点类型，将使用“.scale”值作为默认的 decimal_return_scale，如果未另行指定。

使用 Numeric 类型时，应注意确保 asdecimal 设置适用于正在使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float-> Decimal 的转换时，此转换会为接收到的所有结果列产生额外的性能开销。

返回 Decimal 值的 DBAPI（例如 psycopg2）将在设置为True时具有更好的精度和更高的性能，因为对 Decimal 的本机转换减少了浮点问题的发生，并且 Numeric 类型本身不需要进行任何进一步的转换。然而，另一个返回浮点数的 DBAPI 将会产生额外的转换开销，并且仍然可能发生浮点数据丢失 - 在这种情况下，asdecimal=False 至少会消除额外的转换开销。

method bind_processor(dialect)

返回一个处理绑定值的转换函数。

返回一个可调用对象，该对象将接收一个绑定参数值作为唯一的位置参数，并返回要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

此方法仅相对于方言特定类型对象调用，通常私有于使用的方言，并且不是与公共类型对象相同的类型对象，这意味着无法简单地通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式地子类化UserDefinedType类。

要为TypeEngine.bind_processor()提供替代行为，需要实现一个TypeDecorator类，并提供TypeDecorator.process_bind_param()的实现。

另请参阅

扩展现有类型

参数：

方言 – 正在使用的方言实例。

method get_dbapi_type(dbapi)

如果有的话，从底层 DB-API 返回相应的类型对象。

例如，可以用于调用setinputsizes()。

method literal_processor(dialect)

返回一个转换函数，用于处理直接渲染而不使用绑定的文字值。

当编译器使用“literal_binds”标志时，通常用于 DDL 生成以及某些后端不接受绑定参数的情况下，将使用此函数。

返回一个可调用对象，它将接收一个文字 Python 值作为唯一的位置参数，并返回一个字符串表示，以在 SQL 语句中呈现。

注意

此方法仅针对方言特定类型对象，通常私有于使用的方言，并且与公共类型对象不同，这意味着无法简单地通过子类化TypeEngine类来提供替代的TypeEngine.literal_processor()方法，除非显式地子类化UserDefinedType类。

要为 TypeEngine.literal_processor() 提供替代行为，需实现一个 TypeDecorator 类，并提供一个 TypeDecorator.process_literal_param() 的实现。

请参见

增强现有类型

attribute python_type

method result_processor(dialect, coltype)

返回一个转换函数，用于处理结果行值。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并将返回一个值以返回给用户。

如果不需要处理，该方法应返回 None。

注意

此方法仅在特定方言类型对象相对调用，该对象通常是方言中私有的，并且不是与公共面向用户的对象相同，这意味着无法子类化 TypeEngine 类以提供替代 TypeEngine.result_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 TypeEngine.result_processor() 提供替代行为，需实现一个 TypeDecorator 类，并提供一个 TypeDecorator.process_result_value() 的实现。

请参见

增强现有类型

参数：

• dialect – 正在使用的方言实例。
• coltype – 在 cursor.description 中接收到的 DBAPI coltype 参数。

class sqlalchemy.types.PickleType

持有由 pickle 序列化的 Python 对象。

PickleType 是建立在 Binary 类型之上的，它将 Python 的 pickle.dumps() 应用于传入的对象，并在传出时应用 pickle.loads()，允许任何可 pickle 的 Python 对象被存储为序列化的二进制字段。

若要允许与 PickleType 关联的元素的 ORM 更改事件传播，请参见 变异跟踪。

成员

init(), bind_processor(), cache_ok, compare_values(), impl, result_processor()

类签名

类sqlalchemy.types.PickleType（sqlalchemy.types.TypeDecorator）

method __init__(protocol: int = 5, pickler: Any = None, comparator: Callable[[Any, Any], bool] | None = None, impl: _TypeEngineArgument[Any] | None = None)

构造一个 PickleType。

参数：

• protocol – 默认为pickle.HIGHEST_PROTOCOL。
• pickler – 默认为 pickle。可以是具有 pickle 兼容的dumps和loads方法的任何对象。
• comparator – 用于比较此类型的值的二元调用谓词。如果保持为None，则使用 Python 的“equals”运算符来比较值。
• impl – 用于替代默认的LargeBinary的二进制存储TypeEngine类或实例。例如，在使用 MySQL 时，:class: _mysql.LONGBLOB 类可能更有效。 新版本 1.4.20 中新增。

method bind_processor(dialect)

为给定的Dialect提供绑定值处理函数。

这是实现绑定值转换的TypeEngine合约的方法，通常通过TypeEngine.bind_processor()方法实现。

注

用户定义的TypeDecorator子类不应实现此方法，而应实现TypeDecorator.process_bind_param()，以便保持实现类型提供的“内部”处理。

参数：

方言 – 正在使用的方言实例。

attribute cache_ok: bool | None = True

表明使用此ExternalType的语句是否“安全可缓存”。

默认值None将发出警告，然后不允许缓存包含此类型的语句。设置为False可完全禁用包含此类型的语句的缓存而不发出警告。设置为True时，对象的类和其状态的选定元素将用作缓存键的一部分。例如，使用TypeDecorator：

class MyType(TypeDecorator):
    impl = String

    cache_ok = True

    def __init__(self, choices):
        self.choices = tuple(choices)
        self.internal_only = True

上述类型的缓存键相当于：

>>> MyType(["a", "b", "c"])._static_cache_key
(<class '__main__.MyType'>, ('choices', ('a', 'b', 'c')))

缓存方案将从与__init__()方法中参数名称相对应的类型中提取属性。在上面的示例中，“choices”属性成为缓存键的一部分，但“internal_only”则不是，因为没有名为“internal_only”的参数。

可缓存元素的要求是它们是可哈希的，并且还要表明每次针对给定缓存值使用此类型的表达式时生成相同的 SQL 渲染。

为了适应引用不可哈希结构（如字典、集合和列表）的数据类型，可以通过将可哈希结构分配给与参数名称相对应的属性来使这些对象“可缓存”。例如，一个接受查找值字典的数据类型可以将其公开为排序后的元组序列。假设先前不可缓存的类型为：

class LookupType(UserDefinedType):
  '''a custom type that accepts a dictionary as a parameter.

 this is the non-cacheable version, as "self.lookup" is not
 hashable.

 '''

    def __init__(self, lookup):
        self.lookup = lookup

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self.lookup" ...

这里的“lookup”是一个字典。该类型将无法生成缓存键：

>>> type_ = LookupType({"a": 10, "b": 20})
>>> type_._static_cache_key
<stdin>:1: SAWarning: UserDefinedType LookupType({'a': 10, 'b': 20}) will not
produce a cache key because the ``cache_ok`` flag is not set to True.
Set this flag to True if this type object's state is safe to use
in a cache key, or False to disable this warning.
symbol('no_cache')

如果我们设置了这样一个缓存键，它是不能用的。我们会得到一个包含字典的元组结构，其中的字典本身不能作为“缓存字典”（例如 SQLAlchemy 的语句缓存）中的键，因为 Python 字典不可哈希：

>>> # set cache_ok = True
>>> type_.cache_ok = True

>>> # this is the cache key it would generate
>>> key = type_._static_cache_key
>>> key
(<class '__main__.LookupType'>, ('lookup', {'a': 10, 'b': 20}))

>>> # however this key is not hashable, will fail when used with
>>> # SQLAlchemy statement cache
>>> some_cache = {key: "some sql value"}
Traceback (most recent call last): File "<stdin>", line 1,
in <module> TypeError: unhashable type: 'dict'

可以通过将排序后的元组元组分配给“lookup”属性来使类型可缓存：

class LookupType(UserDefinedType):
  '''a custom type that accepts a dictionary as a parameter.

 The dictionary is stored both as itself in a private variable,
 and published in a public variable as a sorted tuple of tuples,
 which is hashable and will also return the same value for any
 two equivalent dictionaries.  Note it assumes the keys and
 values of the dictionary are themselves hashable.

 '''

    cache_ok = True

    def __init__(self, lookup):
        self._lookup = lookup

        # assume keys/values of "lookup" are hashable; otherwise
        # they would also need to be converted in some way here
        self.lookup = tuple(
            (key, lookup[key]) for key in sorted(lookup)
        )

    def get_col_spec(self, **kw):
        return "VARCHAR(255)"

    def bind_processor(self, dialect):
        # ...  works with "self._lookup" ...

在上述情况下，LookupType({"a": 10, "b": 20})的缓存键将是：

>>> LookupType({"a": 10, "b": 20})._static_cache_key
(<class '__main__.LookupType'>, ('lookup', (('a', 10), ('b', 20))))

从版本 1.4.14 开始：- 添加了cache_ok标志，以允许对TypeDecorator 类进行某种缓存配置。

从版本 1.4.28 开始：- 添加了 ExternalType 混合类型，它将cache_ok标志推广到 TypeDecorator 和 UserDefinedType 类。

另请参见

SQL 编译缓存

method compare_values(x, y)

给定两个值，比较它们是否相等。

默认情况下，这将调用底层“impl”的 TypeEngine.compare_values() 方法，而该方法通常使用 Python 等号运算符==。

此函数由 ORM 用于比较原始加载值与拦截的“更改”值，以确定是否发生了净变化。

attribute impl

LargeBinary 的别名

method result_processor(dialect, coltype)

为给定的Dialect 提供结果值处理函数。

这是通过 TypeEngine.result_processor() 方法正常发生的绑定值转换的方法，用于实现 TypeEngine 合约的方法。

注意

用户自定义的 TypeDecorator 的子类不应该实现这个方法，而应该实现 TypeDecorator.process_result_value() 方法，以便保持实现类型提供的“内部”处理。

参数：

• dialect – 正在使用的方言实例。
• coltype – 一个 SQLAlchemy 数据类型

class sqlalchemy.types.SchemaType

为类型添加允许与类型关联的模式级 DDL 的功能。

支持必须显式创建/删除的类型（例如 PG ENUM 类型），以及受表或模式级约束、触发器和其他规则补充的类型。

SchemaType 类还可以成为 DDLEvents.before_parent_attach() 和 DDLEvents.after_parent_attach() 事件的目标，这些事件在类型对象与父 Column 关联时触发。

另见

Enum

Boolean

成员

adapt(), copy(), create(), drop(), name

类签名

类 sqlalchemy.types.SchemaType（sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.TypeEngineMixin）

method adapt(cls: Type[TypeEngine | TypeEngineMixin], **kw: Any) → TypeEngine

method copy(**kw)

method create(bind, checkfirst=False)

如适用，请为此类型生成 CREATE DDL。

method drop(bind, checkfirst=False)

如适用，请为此类型生成 DROP DDL。

attribute name: str | None

class sqlalchemy.types.SmallInteger

用于较小的 int 整数的类型。

通常在 DDL 中生成 SMALLINT，在 Python 端的行为与普通的 Integer 类型相似。

类签名

类 sqlalchemy.types.SmallInteger（sqlalchemy.types.Integer）

class sqlalchemy.types.String

所有字符串和字符类型的基类。

在 SQL 中，对应于 VARCHAR。

当在 CREATE TABLE 语句中使用 String 类型时，通常需要长度字段，因为大多数数据库都要求 VARCHAR 指定长度。

成员

init(), bind_processor(), get_dbapi_type(), literal_processor(), python_type, result_processor()

类签名

类sqlalchemy.types.String (sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

method __init__(length: int | None = None, collation: str | None = None)

创建一个字符串持有类型。

参数：

length – 可选，列的长度，用于 DDL 和 CAST 表达式。如果不会发出CREATE TABLE，可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含没有长度的 VARCHAR，则在发出CREATE TABLE DDL 时将引发异常。值是以字节还是字符解释的是与数据库相关的。

collation –

可选，用于 DDL 和 CAST 表达式的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字进行渲染。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

注意

在大多数情况下，应该使用Unicode或UnicodeText数据类型来存储非 ASCII 数据的Column。这些数据类型将确保在数据库上使用正确的类型。

method bind_processor(dialect)

返回一个用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收一个绑定参数值作为唯一的位置参数，并返回一个要发送到 DB-API 的值。

如果不需要处理，则方法应返回None。

注意

该方法仅相对于方言特定类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式子类化UserDefinedType类。

要为 TypeEngine.bind_processor() 提供替代行为，请实现一个 TypeDecorator 类，并提供 TypeDecorator.process_bind_param() 的实现。

另请参阅

扩展现有类型

参数：

方言 – 使用的方言实例。

method get_dbapi_type(dbapi)

如果有的话，从底层 DB-API 返回相应的类型对象。

例如，这对于调用 setinputsizes() 很有用。

method literal_processor(dialect)

返回一个用于处理直接呈现而不使用绑定的文字值的转换函数。

当编译器使用“literal_binds”标志时，通常用于 DDL 生成以及在某些后端不接受绑定参数的情况下使用此函数。

返回一个可调用对象，它将接收一个原始的 Python 值作为唯一的位置参数，并返回一个字符串表示，用于在 SQL 语句中呈现。

注意

此方法仅针对特定方言类型对象调用，该对象通常是使用的方言私有，并且不是公共类型对象，这意味着无法子类化 TypeEngine 类以提供替代 TypeEngine.literal_processor() 方法，除非显式子类化 UserDefinedType 类。

要为 TypeEngine.literal_processor() 提供替代行为，请实现一个 TypeDecorator 类，并提供 TypeDecorator.process_literal_param() 的实现。

另请参阅

扩展现有类型

attribute python_type

method result_processor(dialect, coltype)

返回一个用于处理结果行值的转换函数。

返回一个可调用对象，它将接收一个结果行列值作为唯一的位置参数，并返回一个值以返回给用户。

如果不需要处理，该方法应返回 None。

注意

此方法仅相对于特定于方言的类型对象调用，该对象通常是特定方言中私有的，并且不是与公共接口相同的类型对象，这意味着不可通过子类化TypeEngine类来提供备用的TypeEngine.result_processor()方法，除非显式地子类化UserDefinedType类。

要为TypeEngine.result_processor()提供备用行为，实现一个TypeDecorator类，并提供一个TypeDecorator.process_result_value()的实现。

另请参阅

增强现有类型

参数：

• dialect – 正在使用的方言实例。
• coltype – 在 cursor.description 中收到的 DBAPI coltype 参数。

class sqlalchemy.types.Text

可变大小的字符串类型。

在 SQL 中，通常对应于 CLOB 或 TEXT。一般而言，TEXT 对象没有长度；虽然某些数据库将在此处接受长度参数，但其他数据库将拒绝它。

类签名

类sqlalchemy.types.Text（sqlalchemy.types.String）

class sqlalchemy.types.Time

用于datetime.time()对象的类型。

成员

get_dbapi_type()，literal_processor()，python_type

类签名

类sqlalchemy.types.Time（sqlalchemy.types._RenderISO8601NoT，sqlalchemy.types.HasExpressionLookup，sqlalchemy.types.TypeEngine）

method get_dbapi_type(dbapi)

如果有的话，从底层 DB-API 返回相应的类型对象。

例如，这对于调用setinputsizes()可能很有用。

method literal_processor(dialect)

返回一个用于处理字面值的转换函数，这些字面值将直接呈现，而不使用绑定。

当编译器使用“literal_binds”标志时使用此函数，通常在 DDL 生成以及某些后端不接受绑定参数的情况下使用。

返回一个可调用对象，该对象将接收一个字面的 Python 值作为唯一的位置参数，并返回一个要在 SQL 语句中呈现的字符串表示。

注意

该方法仅相对于特定方言的类型对象调用，该对象通常私有于正在使用的方言，并且与公共面向的类型对象不同，这意味着无法子类化TypeEngine类以提供替代的TypeEngine.literal_processor()方法，除非显式子类化UserDefinedType类。

要为TypeEngine.literal_processor()提供替代行为，请实现一个TypeDecorator类，并提供一个TypeDecorator.process_literal_param()的实现。

另请参阅

增强现有类型

attribute python_type

class sqlalchemy.types.Unicode

变长 Unicode 字符串类型。

Unicode类型是一个String子类，假定输入和输出字符串可能包含非 ASCII 字符，并且对于一些后端，暗示着明确支持非 ASCII 数据的底层列类型，比如在 Oracle 和 SQL Server 上的NVARCHAR。这将影响方言级别的CREATE TABLE语句和CAST函数的输出。

数据库中用于传输和接收数据的Unicode类型使用的字符编码通常由 DBAPI 本身确定。所有现代 DBAPI 都支持非 ASCII 字符串，但可能具有不同的管理数据库编码的方法；如有必要，应按照 Dialects 部分目标 DBAPI 的注意事项进行配置。

在现代 SQLAlchemy 中，使用Unicode数据类型不意味着 SQLAlchemy 本身具有任何编码/解码行为。在 Python 3 中，所有字符串对象都具有 Unicode 功能，并且 SQLAlchemy 不会生成字节字符串对象，也不会适应不返回 Python Unicode 对象作为字符串值结果集的 DBAPI。

警告

一些数据库后端，特别是使用 pyodbc 的 SQL Server，已知存在与被标记为 NVARCHAR 类型而不是 VARCHAR 类型的数据相关的不良行为，包括数据类型不匹配错误和不使用索引。 有关解决像 SQL Server 与 pyodbc 以及 cx_Oracle 这样的后端的 Unicode 字符问题的背景信息，请参阅关于 DialectEvents.do_setinputsizes() 的部分。

另请参阅

UnicodeText - 与 Unicode 相对应的无长度文本类型。

DialectEvents.do_setinputsizes()

类签名

类 sqlalchemy.types.Unicode (sqlalchemy.types.String)

class sqlalchemy.types.UnicodeText

一个无界限长度的 Unicode 字符串类型。

参阅 Unicode 以了解此对象的 Unicode 行为详细信息。

与 Unicode 类似，使用 UnicodeText 类型意味着在后端使用 Unicode 能力类型，如 NCLOB、NTEXT。

类签名

类 sqlalchemy.types.UnicodeText (sqlalchemy.types.Text)

class sqlalchemy.types.Uuid

表示数据库无关的 UUID 数据类型。

对于没有“本地”UUID 数据类型的后端，该值将使用 CHAR(32) 并将 UUID 作为 32 个字符的字母数字十六进制字符串进行存储。

对于已知直接支持 UUID 或类似的 uuid 存储数据类型（例如 SQL Server 的 UNIQUEIDENTIFIER）的后端，启用默认的“本地”模式将允许在这些后端使用这些类型。

在其默认使用模式下，Uuid 数据类型期望来自 Python uuid 模块的Python uuid 对象：

import uuid

from sqlalchemy import Uuid
from sqlalchemy import Table, Column, MetaData, String

metadata_obj = MetaData()

t = Table(
    "t",
    metadata_obj,
    Column('uuid_data', Uuid, primary_key=True),
    Column("other_data", String)
)

with engine.begin() as conn:
    conn.execute(
        t.insert(),
        {"uuid_data": uuid.uuid4(), "other_data", "some data"}
    )

要使 Uuid 数据类型与基于字符串的 Uuid（例如 32 字符十六进制字符串）配合使用，传递 Uuid.as_uuid 参数，并将值设为 False。

新版本 2.0 中新增。

另请参阅

UUID - 表示没有任何后端不可知行为的 UUID 数据类型。

成员

init(), bind_processor(), coerce_compared_value(), literal_processor(), python_type, result_processor()

类签名

类 sqlalchemy.types.Uuid (sqlalchemy.types.Emulated, sqlalchemy.types.TypeEngine)

method __init__(as_uuid: bool = True, native_uuid: bool = True)

构造一个 Uuid 类型。

参数：

• as_uuid=True – 如果为 True，则将值解释为 Python uuid 对象，通过 DBAPI 转换为/从字符串。
• native_uuid=True – 如果为 True，则支持直接的 UUID 数据类型或存储 UUID 值的后端（例如 SQL Server 的 UNIQUEIDENTIFIER）将使用这些后端。如果为 False，则对于所有后端都将使用 CHAR(32) 数据类型，而不管原生支持情况。

method bind_processor(dialect)

返回一个转换函数，用于处理绑定值。

返回一个可调用对象，它将接收一个绑定参数值作为唯一的位置参数，并返回一个要发送到 DB-API 的值。

如果不需要处理，则该方法应返回 None。

注意

该方法仅相对于一个特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着不可通过子类化TypeEngine类来提供备用 TypeEngine.bind_processor() 方法，除非明确子类化UserDefinedType类。

要为 TypeEngine.bind_processor() 提供替代行为，请实现 TypeDecorator 类并提供 TypeDecorator.process_bind_param() 的实现。

另请参见

扩展现有类型

参数：

方言 – 正在使用的方言实例。

method coerce_compared_value(op, value)

有关说明，请参阅 TypeEngine.coerce_compared_value()。

method literal_processor(dialect)

返回一个转换函数，用于处理要直接渲染而不使用绑定的文本值。

当编译器使用“literal_binds”标志时，将使用此函数，通常在 DDL 生成以及后端不接受绑定参数的某些情况下使用。

返回一个可调用对象，该对象将接收一个字面 Python 值作为唯一位置参数，并返回要在 SQL 语句中呈现的字符串表示。

注意

此方法仅相对于特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着无法通过子类化 TypeEngine 类来提供替代 TypeEngine.literal_processor() 方法，除非显式地子类化 UserDefinedType 类。

要为 TypeEngine.literal_processor() 提供替代行为，实现一个 TypeDecorator 类并提供 TypeDecorator.process_literal_param() 的实现。

另请参见

扩展现有类型

attribute python_type

method result_processor(dialect, coltype)

返回用于处理结果行值的转换函数。

返回一个可调用对象，该对象将接收结果行列值作为唯一位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回None。

注意

此方法仅相对于特定方言的类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共类型对象相同的类型对象，这意味着无法通过子类化 TypeEngine 类来提供替代 TypeEngine.result_processor() 方法，除非显式地子类化 UserDefinedType 类。

要为 TypeEngine.result_processor() 提供替代行为，实现一个 TypeDecorator 类并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

增强现有类型

参数：

• 方言 – 正在使用的方言实例。
• coltype – 在 cursor.description 中接收的 DBAPI coltype 参数。## SQL 标准和多厂商“大写”类型

这类类型指的是那些要么是 SQL 标准的一部分，要么可能在一些数据库后端的子集中找到的类型。与“通用”类型不同，SQL 标准/多厂商类型没有保证在所有后端上工作，并且只会在那些明确以名称支持它们的后端上工作。也就是说，当发出 CREATE TABLE 时，该类型将始终以其确切名称在 DDL 中发出。

class sqlalchemy.types.ARRAY

表示 SQL 数组类型。

注意

这种类型是所有 ARRAY 操作的基础。然而，目前只有 PostgreSQL 后端支持 SQLAlchemy 中的 SQL 数组。建议在与 PostgreSQL 使用 ARRAY 类型时直接使用 PostgreSQL 特定的sqlalchemy.dialects.postgresql.ARRAY类型，因为它提供了特定于该后端的附加运算符。

ARRAY是 Core 中支持各种 SQL 标准函数的一部分，例如array_agg，这些函数明确涉及数组；然而，除了 PostgreSQL 后端和可能一些第三方方言外，没有其他 SQLAlchemy 内置方言支持这种类型。

给定元素的“类型”，构造了一个ARRAY类型：

mytable = Table("mytable", metadata,
        Column("data", ARRAY(Integer))
    )

上述类型表示一个 N 维数组，这意味着支持的后端（如 PostgreSQL）将自动解释具有任意维度数量的值。要生成传入整数一维数组的 INSERT 构造：

connection.execute(
        mytable.insert(),
        {"data": [1,2,3]}
)

可以根据固定的维度数量构造ARRAY类型：

mytable = Table("mytable", metadata,
        Column("data", ARRAY(Integer, dimensions=2))
    )

发送维度数量是可选的，但如果数据类型要表示多维数组，则建议这样做。这个数字被用于：

当将类型声明本身发送到数据库时，例如，INTEGER[][]

当将 Python 值转换为数据库值，反之亦然，例如，一个包含Unicode对象的数组使用这个数字来有效地访问数组结构内的字符串值，而不需要进行逐行类型检查

当与 Python 的getitem访问器一起使用时，维度数量用于定义[]运算符应返回的类型，例如，对于具有两个维度的整数数组：

>>> expr = table.c.column[5]  # returns ARRAY(Integer, dimensions=1)
>>> expr = expr[6]  # returns Integer

对于一维数组，没有维度参数的ARRAY实例通常假定单维行为。

类型为ARRAY的 SQL 表达式支持“索引”和“切片”行为。[]运算符生成表达式构造，这些构造将为 SELECT 语句生成适当的 SQL：

select(mytable.c.data[5], mytable.c.data[2:7])

以及在使用Update.values()方法时进行 UPDATE 语句：

mytable.update().values({
    mytable.c.data[5]: 7,
    mytable.c.data[2:7]: [1, 2, 3]
})

默认情况下，索引访问是基于一的；要进行从零开始的索引转换，请设置ARRAY.zero_indexes。

ARRAY 类型还提供运算符 Comparator.any() 和 Comparator.all()。PostgreSQL 特定版本的 ARRAY 还提供了其他运算符。

在使用 ORM 时检测 ARRAY 列的更改

当与 SQLAlchemy ORM 一起使用时，ARRAY 类型不会检测对数组的原位突变。为了检测到这些变化，必须使用 sqlalchemy.ext.mutable 扩展，并使用 MutableList 类：

from sqlalchemy import ARRAY
from sqlalchemy.ext.mutable import MutableList

class SomeOrmClass(Base):
    # ...

    data = Column(MutableList.as_mutable(ARRAY(Integer)))

此扩展将允许对数组进行“原位”更改，例如 .append() 以产生单位工作检测到的事件。请注意，对数组中的元素进行更改，包括原地突变的子数组，不会被检测到。

或者，将新的数组值分配给替换旧值的 ORM 元素将始终触发更改事件。

另请参阅

sqlalchemy.dialects.postgresql.ARRAY

成员

init(), contains(), any(), all()

类签名

类 sqlalchemy.types.ARRAY (sqlalchemy.sql.expression.SchemaEventTarget, sqlalchemy.types.Indexable, sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)

method __init__(item_type: _TypeEngineArgument[Any], as_tuple: bool = False, dimensions: int | None = None, zero_indexes: bool = False)

构造一个 ARRAY。

例如：

Column('myarray', ARRAY(Integer))

参数是：

参数：

• item_type – 此数组项的数据类型。请注意，此处维度不相关，因此像 INTEGER[][] 这样的多维数组被构造为 ARRAY(Integer)，而不是 ARRAY(ARRAY(Integer)) 或类似的。
• as_tuple=False – 指定返回结果是否应从列表转换为元组。通常不需要此参数，因为 Python 列表很好地对应于 SQL 数组。
• dimensions – 如果不是 None，则数组将假定具有固定数量的维度。这影响了数组在数据库上的声明方式，以及它如何解释 Python 和结果值，以及如何与“getitem”运算符结合使用时的表达式行为。有关更多详细信息，请参见ARRAY的描述。
• zero_indexes=False – 当为 True 时，索引值将在 Python 零基础和 SQL 一基础索引之间转换，例如，在传递到数据库之前，所有索引值都将增加一个值。

class Comparator

为ARRAY定义比较操作。

此类型的方言特定形式上还有更多的操作符。参见Comparator。

类签名

类sqlalchemy.types.ARRAY.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method contains(*arg, **kw)

ARRAY.contains() 对于基本的数组类型没有实现。请使用特定于方言的数组类型。

另请参阅

ARRAY - PostgreSQL 特定版本。

method any(other, operator=None)

返回other operator ANY (array)子句。

传统功能

这个方法是一个ARRAY - 特定的构造，现在已经被any_()函数取代，其具有不同的调用风格。any_()函数也通过ColumnOperators.any_()方法在方法级别进行了镜像。

使用数组特定的Comparator.any()的用法如下：

from sqlalchemy.sql import operators

conn.execute(
    select(table.c.data).where(
            table.c.data.any(7, operator=operators.lt)
        )
)

参数：

• other – 要进行比较的表达式
• operator – 来自sqlalchemy.sql.operators包的操作符对象，默认为eq()。

另请参阅

any_()

Comparator.all()

method all(other, operator=None)

返回other operator ALL (array)子句。

传统功能

此方法是一个 ARRAY - 特定构造，现在已被 all_() 函数取代，具有不同的调用风格。all_() 函数也通过 ColumnOperators.all_() 方法在方法级别进行了镜像。

使用特定于数组的 Comparator.all() 如下：

from sqlalchemy.sql import operators

conn.execute(
    select(table.c.data).where(
            table.c.data.all(7, operator=operators.lt)
        )
)

参数：

• other – 待比较的表达式
• operator – 来自 sqlalchemy.sql.operators 包的操作对象，默认为 eq()。

参见

all_()

Comparator.any()

class sqlalchemy.types.BIGINT

SQL BIGINT 类型。

参见

BigInteger - 基本类型的文档。

类签名

类sqlalchemy.types.BIGINT（sqlalchemy.types.BigInteger）

class sqlalchemy.types.BINARY

SQL BINARY 类型。

类签名

类sqlalchemy.types.BINARY（sqlalchemy.types._Binary）

class sqlalchemy.types.BLOB

SQL BLOB 类型。

成员

init()

类签名

类sqlalchemy.types.BLOB（sqlalchemy.types.LargeBinary）

method __init__(length: int | None = None)

继承自 LargeBinary 的 sqlalchemy.types.LargeBinary.__init__ 方法

构造一个 LargeBinary 类型。

参数：

length – 可选，用于 DDL 语句中的列长度，适用于接受长度的二进制类型，如 MySQL BLOB 类型。

class sqlalchemy.types.BOOLEAN

SQL BOOLEAN 类型。

成员

init()

类签名

类sqlalchemy.types.BOOLEAN（sqlalchemy.types.Boolean）

method __init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)

继承自 Boolean 的 sqlalchemy.types.Boolean.__init__ 方法

构造一个布尔值。

参数：

• create_constraint – 默认为 False。如果布尔值生成为 int/smallint，还会在表上创建一个 CHECK 约束，确保值为 1 或 0。 注意 强烈建议 CHECK 约束具有明确的名称，以支持模式管理问题。可以通过设置 Boolean.name 参数或设置适当的命名约定来建立这一点；参见配置约束命名约定以获取背景信息。 在版本 1.4 中更改：-此标志现在默认为 False，表示对非本地枚举类型不会生成 CHECK 约束。
• name – 如果生成 CHECK 约束，请指定约束的名称。

class sqlalchemy.types.CHAR

SQL CHAR 类型。

成员

init()

类签名

类sqlalchemy.types.CHAR（sqlalchemy.types.String）

method __init__(length: int | None = None, collation: str | None = None)

继承自 String 的 sqlalchemy.types.String.__init__ 方法

创建一个字符串类型。

参数：

length – 可选的，用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE，则可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含没有长度的VARCHAR，则在发出CREATE TABLE DDL 时会引发异常。该值是以字节还是字符解释的取决于数据库。

collation –

可选的，用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字渲染。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

注意

在大多数情况下，应该使用Unicode或UnicodeText数据类型来存储非 ASCII 数据的Column。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.CLOB

CLOB 类型。

此类型在 Oracle 和 Informix 中找到。

成员

init()

类签名

类sqlalchemy.types.CLOB（sqlalchemy.types.Text）

method __init__(length: int | None = None, collation: str | None = None)

继承自 String 的 sqlalchemy.types.String.__init__ 方法

创建一个字符串类型。

参数：

length – 可选的，用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE，则可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含没有长度的VARCHAR，则在发出CREATE TABLE DDL 时会引发异常。该值是以字节还是字符解释的取决于数据库。

collation –

可选，用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

注意

在大多数情况下，应使用 Unicode 或 UnicodeText 数据类型来存储非 ASCII 数据的 Column。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.DATE

SQL DATE 类型。

类签名

class sqlalchemy.types.DATE (sqlalchemy.types.Date)

class sqlalchemy.types.DATETIME

SQL DATETIME 类型。

成员

init()

类签名

class sqlalchemy.types.DATETIME (sqlalchemy.types.DateTime)

method __init__(timezone: bool = False)

继承自 sqlalchemy.types.DateTime.__init__ 方法 DateTime

构建一个新的 DateTime。

参数：

timezone – boolean。指示日期时间类型是否应在仅在基本日期/时间持有类型上启用时区支持。建议在使用此标志时直接使用 TIMESTAMP 数据类型，因为一些数据库包括与时区功能的 TIMESTAMP 数据类型不同的独立通用日期/时间持有类型，例如 Oracle。

class sqlalchemy.types.DECIMAL

SQL DECIMAL 类型。

另请参阅

Numeric - 基本类型的文档。

成员

init()

类签名

class sqlalchemy.types.DECIMAL (sqlalchemy.types.Numeric)

method __init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)

继承自 sqlalchemy.types.Numeric.__init__ 方法 Numeric

构建一个 Numeric。

参数：

• precision – 用于 DDL CREATE TABLE 的数字精度。
• scale – 用于 DDL CREATE TABLE 的数字规模。
• asdecimal – 默认为 True。返回值是否应作为 Python Decimal 对象发送，或作为浮点数发送。不同的 DBAPI 根据数据类型发送其中之一 - 数字类型将确保在 DBAPI 中一致地返回其中之一。
• decimal_return_scale – 将浮点数转换为 Python 十进制时要使用的默认精度。由于十进制的不精确性，浮点值通常会更长，而大多数浮点数据库类型并没有“精度”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。包含显式“.scale”值的类型，例如基本Numeric以及 MySQL 浮点类型，将使用“.scale”的值作为默认的 decimal_return_scale，如果未另行指定。

使用 Numeric 类型时，应注意确保 asdecimal 设置适用于正在使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float-> Decimal 的转换时，此转换会为接收到的所有结果列增加额外的性能开销。

本地返回 Decimal 的 DBAPI（例如 psycopg2）将在设置为 True 时具有更好的准确性和更高的性能，因为对 Decimal 的本地转换减少了涉及的浮点问题的数量，并且 Numeric 类型本身不需要应用任何进一步的转换。但是，另一个本地返回浮点数的 DBAPI 将 增加额外的转换开销，并且仍然可能存在浮点数据丢失 - 在这种情况下，asdecimal=False 将至少消除额外的转换开销。

class sqlalchemy.types.DOUBLE

SQL DOUBLE 类型。

在 2.0 版本中新增。

另请参阅

Double - 基本类型的文档。

成员

init()

类签名

类sqlalchemy.types.DOUBLE（sqlalchemy.types.Double）。

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

继承自 Float 的 sqlalchemy.types.Float.__init__ 方法

构造一个 Float。

参数：

precision –

DDL CREATE TABLE 中用于使用的数字精度。后端应该尽量确保此精度表示通用Float数据类型的数字位数。

注意

对于 Oracle 后端，当渲染 DDL 时，不接受Float.precision参数，因为 Oracle 不支持指定为小数位数的浮点精度。而是使用 Oracle 特定的FLOAT数据类型并指定FLOAT.binary_precision参数。这是 SQLAlchemy 2.0 版本的新功能。

要创建一个数据库不可知的Float，并为 Oracle 分别指定二进制精度，请使用TypeEngine.with_variant()如下：

from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle")
)

asdecimal – 与Numeric相同的标志，但默认为False。请注意，将此标志设置为True会导致浮点数转换。

decimal_return_scale – 在将浮点数转换为 Python 十进制数时使用的默认标度。由于十进制不准确性，浮点值通常会更长，并且大多数浮点数据库类型没有“标度”的概念，因此，默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，如果未另行指定，包括“标度”的 MySQL 浮点类型将使用“标度”作为decimal_return_scale的默认值。

class sqlalchemy.types.DOUBLE_PRECISION

SQL DOUBLE PRECISION 类型。

SQLAlchemy 2.0 中的新功能。

另请参阅

Double - 基本类型的文档。

成员

init()

类签名

类sqlalchemy.types.DOUBLE_PRECISION (sqlalchemy.types.Double)

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

继承自 Float 的 sqlalchemy.types.Float.__init__ 方法

构造一个 Float。

参数：

precision –

用于 DDL CREATE TABLE中的数字精度。后端应该尝试确保此精度表示通用Float数据类型的数字位数。

注意

对于 Oracle 后端，在渲染 DDL 时，不接受Float.precision参数，因为 Oracle 不支持将浮点精度指定为小数位数。相反，请使用特定于 Oracle 的FLOAT数据类型，并指定FLOAT.binary_precision参数。这是 SQLAlchemy 2.0 中的新功能。

要创建一个数据库不可知的Float，并为 Oracle 分别指定二进制精度，请使用TypeEngine.with_variant()如下：

from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle")
)

asdecimal – 与Numeric相同的标志，但默认为False。请注意，将此标志设置为True会导致浮点数转换。

decimal_return_scale – 将浮点数转换为 Python 十进制数时要使用的默认标度。由于十进制不准确，浮点值通常会更长，并且大多数浮点数据库类型没有“标度”概念，因此默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型包括“标度”，如果没有另外指定，将使用“标度”作为 decimal_return_scale 的默认值。

class sqlalchemy.types.FLOAT

SQL FLOAT 类型。

另请参阅

Float - 基本类型的文档。

成员

init()

类签名

类 sqlalchemy.types.FLOAT （sqlalchemy.types.Float）。

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

继承自 Float 的 sqlalchemy.types.Float.__init__ 方法

构造一个 Float。

参数：

precision –

用于 DDL CREATE TABLE 中的数字精度。后端应该尝试确保此精度指示了通用 Float 数据类型的位数。

注意

对于 Oracle 后端，在渲染 DDL 时，不接受 Float.precision 参数，因为 Oracle 不支持将浮点精度指定为小数位数。而是使用 Oracle 特定的 FLOAT 数据类型，并指定 FLOAT.binary_precision 参数。这是 SQLAlchemy 版本 2.0 中的新功能。

要创建一个与数据库无关的 Float，并为 Oracle 分别指定二进制精度，请使用 TypeEngine.with_variant() 如下：

from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle")
)

asdecimal – 与 Numeric 相同的标志，但默认为 False。请注意，将此标志设置为 True 会导致浮点转换。

decimal_return_scale – 将浮点数转换为 Python 十进制数时要使用的默认标度。由于十进制不准确，浮点值通常会更长，并且大多数浮点数据库类型没有“标度”概念，因此默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，MySQL 浮点类型包括“标度”，如果没有另外指定，将使用“标度”作为 decimal_return_scale 的默认值。

attribute sqlalchemy.types.INT

INTEGER 的别名

class sqlalchemy.types.JSON

表示 SQL JSON 类型。

注意

JSON 被提供为供应商特定的 JSON 类型的外观。由于它支持 JSON SQL 操作，因此它仅适用于具有实际 JSON 类型的后端，目前有:

• PostgreSQL - 有关特定于后端的注意事项，请参阅 sqlalchemy.dialects.postgresql.JSON 和 sqlalchemy.dialects.postgresql.JSONB
• MySQL - 有关特定于后端的注意事项，请参阅 sqlalchemy.dialects.mysql.JSON
• SQLite 截至版本 3.9 - 有关特定于后端的注意事项，请参阅 sqlalchemy.dialects.sqlite.JSON
• Microsoft SQL Server 2016 及更高版本 - 有关特定于后端的注意事项，请参阅 sqlalchemy.dialects.mssql.JSON

JSON 是核心的一部分，支持原生 JSON 数据类型日益增长的流行度。

JSON 类型存储任意的 JSON 格式数据，例如:

data_table = Table('data_table', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', JSON)
)

with engine.connect() as conn:
    conn.execute(
        data_table.insert(),
        {"data": {"key1": "value1", "key2": "value2"}}
    )

JSON 特定的表达式运算符

JSON 数据类型提供了这些额外的 SQL 操作:

键索引操作:

data_table.c.data['some key']

整数索引操作:

data_table.c.data[3]

路径索引操作:

data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')]

针对特定 JSON 元素类型的数据转换器，在调用索引或路径操作后:

data_table.c.data["some key"].as_integer()

1.3.11 版中的新功能。

可能还可以从 JSON 的特定于方言的版本中获得其他操作，例如 sqlalchemy.dialects.postgresql.JSON 和 sqlalchemy.dialects.postgresql.JSONB，它们都提供了额外的特定于 PostgreSQL 的操作。

将 JSON 元素转换为其他类型

索引操作，即通过使用 Python 方括号操作符调用表达式，如 some_column['some key']，将返回一个类型默认为 JSON 的表达式对象，默认情况下，以便可以调用进一步的面向 JSON 的指令。然而，更常见的情况是希望索引操作返回特定的标量元素，例如字符串或整数。为了以与后端无关的方式提供对这些元素的访问，提供了一系列数据转换器:

• Comparator.as_string() - 将元素作为字符串返回
• Comparator.as_boolean() - 将元素返回为布尔值
• Comparator.as_float() - 将元素返回为浮点数
• Comparator.as_integer() - 将元素返回为整数

这些数据转换器由支持方言实现，以确保与上述类型的比较将按预期工作，例如：

# integer comparison
data_table.c.data["some_integer_key"].as_integer() == 5

# boolean comparison
data_table.c.data["some_boolean"].as_boolean() == True

版本 1.3.11 中新增了基本 JSON 数据元素类型的特定类型转换器。

注意

数据转换器函数是 1.3.11 版本中的新功能，取代了以前记录的使用 CAST 的方法；作为参考，这看起来像是：

from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON
cast(
    data_table.c.data['some_key'], String
) == type_coerce(55, JSON)

上述情况现在直接有效为：

data_table.c.data['some_key'].as_integer() == 5

有关 1.3.x 系列中先前比较方法的详细信息，请参阅 SQLAlchemy 1.2 的文档或版本分发的 doc/目录中包含的 HTML 文件。

当使用 ORM 时检测 JSON 列中的更改

当与 SQLAlchemy ORM 一起使用时，JSON 类型不会检测到对结构的原地突变。为了检测这些情况，必须使用sqlalchemy.ext.mutable扩展，通常使用MutableDict类。此扩展将允许对数据结构进行“原地”更改以产生事件，这些事件将被工作单元检测到。有关涉及字典的简单示例，请参见HSTORE中的示例。

或者，将 JSON 结构分配给替换旧结构的 ORM 元素将始终触发更改事件。

支持 JSON null 与 SQL NULL

在处理 NULL 值时，JSON 类型建议使用两个特定的常量来区分一个计算为 SQL NULL 的列，例如，没有值，与 JSON 编码的字符串"null"。要插入或选择 SQL NULL 的值，请使用常量null()。当使用包含特殊逻辑的JSON数据类型时，此符号可以作为参数值传递，该逻辑解释此符号表示列值应为 SQL NULL，而不是 JSON 的"null"：

from sqlalchemy import null
conn.execute(table.insert(), {"json_value": null()})

要插入或选择 JSON 的值为"null"，请使用常量JSON.NULL：

conn.execute(table.insert(), {"json_value": JSON.NULL})

JSON 类型支持一个标志 JSON.none_as_null，当设置为 True 时，Python 常量 None 将评估为 SQL NULL 的值，当设置为 False 时，Python 常量 None 将评估为 JSON "null" 的值。Python 值 None 可以与 JSON.NULL 和 null() 结合使用，以指示 NULL 值，但在这些情况下必须注意 JSON.none_as_null 的值。

自定义 JSON 序列化器

JSON 序列化器和反序列化器使用了JSON默认的 Python json.dumps 和 json.loads 函数；在 psycopg2 方言的情况下，psycopg2 可能会使用自己的自定义加载器函数。

为了影响序列化器/反序列化器，它们目前可以在 create_engine() 级别通过 create_engine.json_serializer 和 create_engine.json_deserializer 参数进行配置。例如，要关闭 ensure_ascii：

engine = create_engine(
    "sqlite://",
    json_serializer=lambda obj: json.dumps(obj, ensure_ascii=False))

自版本 1.3.7 起更改：SQLite 方言的 json_serializer 和 json_deserializer 参数从 _json_serializer 和 _json_deserializer 重命名。

另请参阅

sqlalchemy.dialects.postgresql.JSON

sqlalchemy.dialects.postgresql.JSONB

sqlalchemy.dialects.mysql.JSON

sqlalchemy.dialects.sqlite.JSON

成员

as_boolean(), as_float(), as_integer(), as_json(), as_numeric(), as_string(), bind_processor(), literal_processor(), NULL, init(), bind_processor(), comparator_factory, hashable, python_type, result_processor(), should_evaluate_none

类签名

类 sqlalchemy.types.JSON (sqlalchemy.types.Indexable, sqlalchemy.types.TypeEngine)

class Comparator

为 JSON 定义比较操作。

类签名

类 sqlalchemy.types.JSON.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)

method as_boolean()

将索引值转换为布尔值。

例如：

stmt = select(
    mytable.c.json_column['some_data'].as_boolean()
).where(
    mytable.c.json_column['some_data'].as_boolean() == True
)

从 1.3.11 版本开始新增。

method as_float()

将索引值转换为浮点数。

例如：

stmt = select(
    mytable.c.json_column['some_data'].as_float()
).where(
    mytable.c.json_column['some_data'].as_float() == 29.75
)

从 1.3.11 版本开始新增。

method as_integer()

将索引值转换为整数。

例如：

stmt = select(
    mytable.c.json_column['some_data'].as_integer()
).where(
    mytable.c.json_column['some_data'].as_integer() == 5
)

从 1.3.11 版本开始新增。

method as_json()

将索引值转换为 JSON。

例如：

stmt = select(mytable.c.json_column['some_data'].as_json())

这通常是任何情况下索引元素的默认行为。

请注意，并非所有后端都支持对完整 JSON 结构的比较。

从 1.3.11 版本开始新增。

method as_numeric(precision, scale, asdecimal=True)

将索引值转换为数值/小数。

例如：

stmt = select(
    mytable.c.json_column['some_data'].as_numeric(10, 6)
).where(
    mytable.c.
    json_column['some_data'].as_numeric(10, 6) == 29.75
)

从 1.4.0b2 版本开始新增。

method as_string()

将索引值转换为字符串。

例如：

stmt = select(
    mytable.c.json_column['some_data'].as_string()
).where(
    mytable.c.json_column['some_data'].as_string() ==
    'some string'
)

从 1.3.11 版本开始新增。

class JSONElementType

JSON 表达式中索引/路径元素的常见函数。

类签名

类 sqlalchemy.types.JSON.JSONElementType (sqlalchemy.types.TypeEngine)

method bind_processor(dialect)

返回用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收一个绑定参数值作为唯一位置参数，并返回一个要发送到 DB-API 的值。

如果不需要处理，则方法应返回 None。

注意

此方法仅相对于特定方言类型对象调用，该对象通常是私有于正在使用的方言的，并且不是公共类型对象，这意味着不可通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式子类化UserDefinedType类。

要为TypeEngine.bind_processor()提供替代行为，请实现一个TypeDecorator类，并提供一个TypeDecorator.process_bind_param()的实现。

另请参阅

扩展现有类型

参数：

方言 - 正在使用的方言实例。

method literal_processor(dialect)

返回一个用于处理直接呈现而不使用绑定的字面值的转换函数。

当编译器使用“literal_binds”标志时，通常在 DDL 生成以及某些后端不接受绑定参数的情况下使用此函数。

返回一个可调用对象，该对象将接收一个字面的 Python 值作为唯一的位置参数，并返回一个字符串表示，以在 SQL 语句中呈现。

注意

此方法仅相对于特定方言类型对象调用，该对象通常是私有于正在使用的方言的，并且不是公共类型对象，这意味着不可通过子类化TypeEngine类来提供替代的TypeEngine.literal_processor()方法，除非显式子类化UserDefinedType类。

要为TypeEngine.literal_processor()提供替代行为，请实现一个TypeDecorator类，并提供一个TypeDecorator.process_literal_param()的实现。

另请参阅

扩展现有类型

class JSONIndexType

JSON 索引值的数据类型的占位符。

这允许对特殊语法的 JSON 索引值进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONIndexType (sqlalchemy.types.JSONElementType)

class JSONIntIndexType

JSON 索引值的数据类型的占位符。

这允许对特殊语法的 JSON 索引值进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONIntIndexType (sqlalchemy.types.JSONIndexType)

class JSONPathType

JSON 路径操作的占位符类型。

这允许对基于路径的索引值进行执行时处理，转换为特定的 SQL 语法。

类签名

类sqlalchemy.types.JSON.JSONPathType (sqlalchemy.types.JSONElementType)

class JSONStrIndexType

JSON 索引值的数据类型的占位符。

这允许对特殊语法的 JSON 索引值进行执行时处理。

类签名

类sqlalchemy.types.JSON.JSONStrIndexType (sqlalchemy.types.JSONIndexType)

attribute NULL = symbol('JSON_NULL')

描述 NULL 的 JSON 值。

此值用于强制使用 JSON 值"null"作为值。Python 的None值将根据JSON.none_as_null 标志的设置被识别为 SQL NULL 或 JSON"null"，常量JSON.NULL 可以始终解析为 JSON"null"，而不考虑此设置。这与总是解析为 SQL NULL 的null() 构造形成对比。例如：

from sqlalchemy import null
from sqlalchemy.dialects.postgresql import JSON

# will *always* insert SQL NULL
obj1 = MyObject(json_value=null())

# will *always* insert JSON string "null"
obj2 = MyObject(json_value=JSON.NULL)

session.add_all([obj1, obj2])
session.commit()

为了将 JSON NULL 设置为列的默认值，最透明的方法是使用text()：

Table(
    'my_table', metadata,
    Column('json_data', JSON, default=text("'null'"))
)

虽然在这种情况下可以使用JSON.NULL，但JSON.NULL 值将作为列的值返回，这在 ORM 或其他重新使用默认值的情况下可能不理想。使用 SQL 表达式意味着值将在检索生成的默认值的上下文中从数据库重新获取。

method __init__(none_as_null: bool = False)

构造一个JSON 类型。

参数：

none_as_null=False –

如果为 True，则将值None持久化为 SQL NULL 值，而不是null的 JSON 编码。请注意，当此标志为 False 时，null() 构造仍然可以用于持久化 NULL 值，可以直接作为参数值传递，由JSON 类型特别解释为 SQL NULL：

from sqlalchemy import null
conn.execute(table.insert(), {"data": null()})

注意

JSON.none_as_null 不适用于传递给 Column.default 和 Column.server_default 的值；对于这些参数传递的None值意味着“没有默认值”。

此外，在 SQL 比较表达式中使用时，Python 值None仍然指向 SQL null，而不是 JSON NULL。JSON.none_as_null 标志明确指的是值在 INSERT 或 UPDATE 语句中的持久性。应该使用JSON.NULL值用于希望与 JSON null 进���比较的 SQL 表达式。

参见

JSON.NULL

method bind_processor(dialect)

返回一个用于处理绑定值的转换函数。

返回一个可调用对象，该对象将接收一个绑定参数值作为唯一的位置参数，并返回一个要发送到 DB-API 的值。

如果不需要处理，则该方法应返回None。

注意

此方法仅相对于特定方言类型对象调用，该对象通常私有于正在使用的方言，并且不是公共类型对象，这意味着无法通过子类化TypeEngine类来提供替代的TypeEngine.bind_processor()方法，除非显式子类化UserDefinedType类。

要为TypeEngine.bind_processor()提供替代行为，请实现一个TypeDecorator类，并提供一个TypeDecorator.process_bind_param()的实现。

参见

增强现有类型

参数：

方言 – 正在使用的方言实例。

attribute comparator_factory

Comparator 的别名。

attribute hashable = False

标志，如果为 False，则表示该类型的值不可哈希。

在 ORM 中用于去重结果列表。

attribute python_type

method result_processor(dialect, coltype)

返回一个用于处理结果行值的转换函数。

返回一个可调用对象，该对象将接收结果行列值作为唯一的位置参数，并将返回一个要返回给用户的值。

如果不需要处理，则该方法应返回 None。

注意

该方法仅相对于特定方言类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是公共类型对象，这意味着无法通过继承 TypeEngine 类来提供替代 TypeEngine.result_processor() 方法，除非显式地继承 UserDefinedType 类。

要为 TypeEngine.result_processor() 提供替代行为，请实现一个 TypeDecorator 类并提供 TypeDecorator.process_result_value() 的实现。

另请参阅

扩展现有类型

参数：

• dialect – 正在使用的方言实例。
• coltype – 在 cursor.description 中接收的 DBAPI coltype 参数。

attribute should_evaluate_none: bool

如果为 True，则 Python 常量 None 被视为由此类型显式处理。

ORM 使用此标志指示在 INSERT 语句中传递了 None 的正值到列中，而不是省略了 INSERT 语句中的列，这会触发列级默认值。它还允许具有对 Python None 的特殊行为（例如 JSON 类型）的类型指示它们希望显式处理 None 值。

要在现有类型上设置此标志，请使用 TypeEngine.evaluates_none() 方法。

另请参阅

TypeEngine.evaluates_none() 方法。

class sqlalchemy.types.INTEGER

SQL INT 或 INTEGER 类型。

另请参阅

Integer - 基本类型的文档。

类签名

类 sqlalchemy.types.INTEGER（sqlalchemy.types.Integer）

class sqlalchemy.types.NCHAR

SQL NCHAR 类型。

成员

init()

类签名

类 sqlalchemy.types.NCHAR (sqlalchemy.types.Unicode)

method __init__(length: int | None = None, collation: str | None = None)

继承自 String 的 sqlalchemy.types.String.__init__ 方法

创建一个持有字符串的类型。

参数：

length – 可选，用于 DDL 和 CAST 表达式中的列的长度。如果不会发出 CREATE TABLE，则可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含了没有长度的 VARCHAR，则在发出 CREATE TABLE DDL 时会引发异常。值是以字节还是字符解释是与数据库特定的。

collation –

可选，用于 DDL 和 CAST 表达式中的列级排序规则。在 SQLite、MySQL 和 PostgreSQL 中支持使用 COLLATE 关键字进行渲染。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

注意

在大多数情况下，Unicode 或 UnicodeText 数据类型应该用于预期存储非 ASCII 数据的 Column。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.NVARCHAR

SQL NVARCHAR 类型。

成员

init()

类签名

类 sqlalchemy.types.NVARCHAR (sqlalchemy.types.Unicode)

method __init__(length: int | None = None, collation: str | None = None)

继承自 String 的 sqlalchemy.types.String.__init__ 方法

创建一个持有字符串的类型。

参数：

length – 可选，用于 DDL 和 CAST 表达式中的列的长度。如果不会发出 CREATE TABLE，则可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含了没有长度的 VARCHAR，则在发出 CREATE TABLE DDL 时会引发异常。值是以字节还是字符解释是与数据库特定的。

collation –

可选，用于 DDL 和 CAST 表达式中的列级排序规则。在 SQLite、MySQL 和 PostgreSQL 中支持使用 COLLATE 关键字进行渲染。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

注意

在大多数情况下，Unicode 或 UnicodeText 数据类型应该用于预期存储非 ASCII 数据的 Column。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.NUMERIC

SQL NUMERIC 类型。

另请参阅

Numeric - 基础类型的文档。

成员

init()

类签名

类 sqlalchemy.types.NUMERIC（sqlalchemy.types.Numeric）

method __init__(precision: int | None = None, scale: int | None = None, decimal_return_scale: int | None = None, asdecimal: bool = True)

继承自 Numeric 的 sqlalchemy.types.Numeric.__init__ 方法

构造一个 Numeric。

参数：

• precision - 用于 DDL CREATE TABLE 中的数值精度。
• scale - 用于 DDL CREATE TABLE 中的数值标度。
• asdecimal - 默认为 True。返回值应该作为 Python Decimal 对象还是作为浮点数发送。根据数据类型不同，不同的 DBAPIs 会发送其中之一 - Numeric 类型将确保返回值在各个 DBAPIs 之间一致地是其中之一。
• decimal_return_scale - 转换浮点数为 Python decimal 时使用的默认精度。由于浮点数的不准确性，浮点数值通常会更长，而大多数浮点数数据库类型没有“标度”概念，因此默认情况下，float 类型在转换时查找前十位小数点。指定此值将覆盖该长度。包含显式“.scale”值的类型，例如基本 Numeric 和 MySQL 浮点类型，如果未另行指定，将使用“.scale”的值作为 decimal_return_scale 的默认值。

使用 Numeric 类型时，应注意确保 asdecimal 设置适用于所使用的 DBAPI - 当 Numeric 应用从 Decimal->float 或 float-> Decimal 的转换时，此转换会为所有接收到的结果列增加额外的性能开销。

本地返回 Decimal 的 DBAPI（例如 psycopg2）将通过设置为 True 获得更好的准确性和更高的性能，因为本地转换为 Decimal 可降低浮点数问题的数量，并且 Numeric 类型本身不需要应用任何进一步的转换。但是，另一个本地返回浮点数的 DBAPI 将 需要额外的转换开销，并且仍然可能存在浮点数据丢失 - 在这种情况下，asdecimal=False 将至少消除额外的转换开销。

class sqlalchemy.types.REAL

SQL REAL 类型。

另请参阅

Float - 基本类型的文档。

成员

init()

类签名

类 sqlalchemy.types.REAL（sqlalchemy.types.Float）

method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)

继承自 Float 的 sqlalchemy.types.Float.__init__ 方法

构造一个 Float。

参数：

precision -

用于 DDL CREATE TABLE 中的数值精度。后端应尽量确保此精度指示了通用 Float 数据类型的数字位数。

注意

对于 Oracle 后端，在渲染 DDL 时不接受Float.precision参数，因为 Oracle 不支持以小数位数指定浮点精度。而是使用特定于 Oracle 的FLOAT数据类型，并指定FLOAT.binary_precision参数。这是 SQLAlchemy 2.0 版本的新功能。

要创建一个与 Oracle 分开指定二进制精度的数据库不可知的Float，请使用TypeEngine.with_variant()如下所示：

from sqlalchemy import Column
from sqlalchemy import Float
from sqlalchemy.dialects import oracle

Column(
    "float_data",
    Float(5).with_variant(oracle.FLOAT(binary_precision=16), "oracle")
)

asdecimal – 与Numeric相同的标志，但默认为False。请注意，将此标志设置为True会导致浮点转换。

decimal_return_scale – 将浮点数转换为 Python 十进制数时使用的默认精度。由于十进制不准确，浮点值通常会更长，并且大多数浮点数据库类型都没有“精度”的概念，因此默认情况下，浮点类型在转换时会查找前十位小数。指定此值将覆盖该长度。请注意，如果未另行指定，则 MySQL 浮点类型将使用“精度”作为 decimal_return_scale 的默认值。

class sqlalchemy.types.SMALLINT

SQL SMALLINT 类型。

另请参阅

SmallInteger - 基础类型的文档。

类签名

类sqlalchemy.types.SMALLINT (sqlalchemy.types.SmallInteger)

class sqlalchemy.types.TEXT

SQL TEXT 类型。

成员

init()

类签名

类sqlalchemy.types.TEXT (sqlalchemy.types.Text)

method __init__(length: int | None = None, collation: str | None = None)

继承自 String 的 sqlalchemy.types.String.__init__ 方法

创建一个保存字符串的类型。

参数：

length – 可选项，在 DDL 和 CAST 表达式中用于列的长度。如果不会发出CREATE TABLE，可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包括没有长度的VARCHAR，则在发出CREATE TABLE DDL 时会引发异常。值是按字节还是字符解释是特定于数据库的。

collation –

可选项，在 DDL 和 CAST 表达式中使用的列级排序规则。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如：

>>> from sqlalchemy import cast, select, String
>>> print(select(cast('some string', String(collation='utf8'))))
SELECT  CAST(:param_1  AS  VARCHAR  COLLATE  utf8)  AS  anon_1 

注意

在大多数情况下，应该为预期存储非 ASCII 数据的 Column 使用 Unicode 或 UnicodeText 数据类型。这些数据类型将确保在数据库上使用正确的类型。

class sqlalchemy.types.TIME

SQL TIME 类型。

类签名

类 sqlalchemy.types.TIME（sqlalchemy.types.Time）

class sqlalchemy.types.TIMESTAMP

SQL TIMESTAMP 类型。

TIMESTAMP 数据类型在一些后端（如 PostgreSQL 和 Oracle）上支持时区存储。请使用 TIMESTAMP.timezone 参数以在这些后端上启用“TIMESTAMP WITH TIMEZONE”。

成员

init()，get_dbapi_type()

类签名

类 sqlalchemy.types.TIMESTAMP（sqlalchemy.types.DateTime）

method __init__(timezone: bool = False)

构造一个新的TIMESTAMP。

参数：

timezone – 布尔值。指示 TIMESTAMP 类型应该在目标数据库上启用时区支持（如果可用）。在每个方言上类似于“TIMESTAMP WITH TIMEZONE”。如果目标数据库不支持时区，则此标志将被忽略。

method get_dbapi_type(dbapi)

返回底层 DB-API 的相应类型对象（如果有）。

这对于调用 setinputsizes() 等操作可能很有用。

class sqlalchemy.types.UUID

表示 SQL UUID 类型。

这是与以前的仅限于 PostgreSQL 版本的 UUID 向后兼容的 SQL 本地形式的 Uuid 数据库无关数据类型。

UUID 数据类型仅适用于具有名为 UUID 的 SQL 数据类型的数据库。对于没有这个确切命名类型的后端，包括 SQL Server，在其上不起作用。对于具有本机支持的与后端无关的 UUID 值，包括 SQL Server 的 UNIQUEIDENTIFIER 数据类型，请使用 Uuid 数据类型。

新版本 2.0 中的新增内容。

另请参见

Uuid

成员

init()

类签名

类 sqlalchemy.types.UUID（sqlalchemy.types.Uuid，sqlalchemy.types.NativeForEmulated）

method __init__(as_uuid: bool = True)

构造一个 UUID 类型。

参数：

as_uuid=True –

如果为 True，则值将被解释为 Python uuid 对象，并通过 DBAPI 转换为/从字符串。

class sqlalchemy.types.VARBINARY

SQL VARBINARY 类型。

类签名

类sqlalchemy.types.VARBINARY（sqlalchemy.types._Binary）

class sqlalchemy.types.VARCHAR

SQL VARCHAR 类型。

成员

init()

类签名

类sqlalchemy.types.VARCHAR（sqlalchemy.types.String）

method __init__(length: int | None = None, collation: str | None = None)

从 String 的 sqlalchemy.types.String.__init__ 方法继承

创建一个持有字符串的类型。

参数：

length – 可选，用于 DDL 和 CAST 表达式中的列的长度。 如果不会发出CREATE TABLE，可以安全地省略。 某些数据库可能需要在 DDL 中使用length，如果包含没有长度的VARCHAR，则在发出CREATE TABLE DDL 时会引发异常。 值是以字节还是字符解释是与数据库特定的。