SqlAlchemy 2.0 中文文档（四十八）（1）https://developer.aliyun.com/article/1563006
PostgreSQL 数据类型
与所有 SQLAlchemy 方言一样，所有已知与 PostgreSQL 兼容的大写类型都可以从顶级方言导入，无论它们是来自 sqlalchemy.types 还是本地方言：
from sqlalchemy.dialects.postgresql import ( ARRAY, BIGINT, BIT, BOOLEAN, BYTEA, CHAR, CIDR, CITEXT, DATE, DATEMULTIRANGE, DATERANGE, DOMAIN, DOUBLE_PRECISION, ENUM, FLOAT, HSTORE, INET, INT4MULTIRANGE, INT4RANGE, INT8MULTIRANGE, INT8RANGE, INTEGER, INTERVAL, JSON, JSONB, JSONPATH, MACADDR, MACADDR8, MONEY, NUMERIC, NUMMULTIRANGE, NUMRANGE, OID, REAL, REGCLASS, REGCONFIG, SMALLINT, TEXT, TIME, TIMESTAMP, TSMULTIRANGE, TSQUERY, TSRANGE, TSTZMULTIRANGE, TSTZRANGE, TSVECTOR, UUID, VARCHAR, )
特定于 PostgreSQL 或具有 PostgreSQL 特定构造参数的类型如下：
| 对象名称 | 描述 |
| AbstractMultiRange | PostgreSQL MULTIRANGE 类型的基类。 |
| AbstractRange | 单个和多个 Range SQL 类型的基类。 |
| AbstractSingleRange | PostgreSQL RANGE 类型的基类。 |
| ARRAY | PostgreSQL ARRAY 类型。 |
| BIT | |
| BYTEA | |
| CIDR | |
| CITEXT | 提供 PostgreSQL 的 CITEXT 类型。 |
| DATEMULTIRANGE | 表示 PostgreSQL 的 DATEMULTIRANGE 类型。 |
| DATERANGE | 表示 PostgreSQL 的 DATERANGE 类型。 |
| DOMAIN | 表示 PostgreSQL 的 DOMAIN 类型。 |
| ENUM | PostgreSQL 的 ENUM 类型。 |
| HSTORE | 表示 PostgreSQL 的 HSTORE 类型。 |
| INET | |
| INT4MULTIRANGE | 表示 PostgreSQL 的 INT4MULTIRANGE 类型。 |
| INT4RANGE | 表示 PostgreSQL 的 INT4RANGE 类型。 |
| INT8MULTIRANGE | 表示 PostgreSQL 的 INT8MULTIRANGE 类型。 |
| INT8RANGE | 表示 PostgreSQL 的 INT8RANGE 类型。 |
| INTERVAL | PostgreSQL 的 INTERVAL 类型。 |
| JSON | 表示 PostgreSQL 的 JSON 类型。 |
| JSONB | 表示 PostgreSQL 的 JSONB 类型。 |
| JSONPATH | JSON 路径类型。 |
| MACADDR | |
| MACADDR8 | |
| MONEY | 提供 PostgreSQL 的 MONEY 类型。 |
| MultiRange | 表示多范围序列。 |
| NUMMULTIRANGE | 表示 PostgreSQL 的 NUMMULTIRANGE 类型。 |
| NUMRANGE | 表示 PostgreSQL 的 NUMRANGE 类型。 |
| OID | 提供 PostgreSQL 的 OID 类型。 |
| REGCLASS | 提供 PostgreSQL 的 REGCLASS 类型。 |
| REGCONFIG | 提供 PostgreSQL 的 REGCONFIG 类型。 |
| TIME | PostgreSQL 的 TIME 类型。 |
| TIMESTAMP | 提供 PostgreSQL 的 TIMESTAMP 类型。 |
| TSMULTIRANGE | 表示 PostgreSQL 的 TSRANGE 类型。 |
| TSQUERY | 提供 PostgreSQL 的 TSQUERY 类型。 |
| TSRANGE | 表示 PostgreSQL 的 TSRANGE 类型。 |
| TSTZMULTIRANGE | 表示 PostgreSQL 的 TSTZRANGE 类型。 |
| TSTZRANGE | 表示 PostgreSQL TSTZRANGE 类型。 |
| TSVECTOR | TSVECTOR 类型实现了 PostgreSQL 文本搜索类型 TSVECTOR。 |
class sqlalchemy.dialects.postgresql.AbstractRange
单个和多个范围 SQL 类型的基类。
成员
adjacent_to(), contained_by(), contains(), difference(), intersection(), not_extend_left_of(), not_extend_right_of(), overlaps(), strictly_left_of(), strictly_right_of(), union()
类签名
类 sqlalchemy.dialects.postgresql.AbstractRange (sqlalchemy.types.TypeEngine)
class comparator_factory
为范围类型定义比较操作。
类签名
类 sqlalchemy.dialects.postgresql.AbstractRange.comparator_factory (sqlalchemy.types.Comparator)
method adjacent_to(other: Any) → ColumnElement[bool]
布尔表达式。如果列中的范围与操作数中的范围相邻，则返回 true。
method contained_by(other: Any) → ColumnElement[bool]
布尔表达式。如果列包含在右手操作数中，则返回 true。
method contains(other: Any, **kw: Any) → ColumnElement[bool]
布尔表达式。如果右手操作数（可以是元素或范围）包含在列中，则返回 true。
此运算符可能会忽略 kwargs，但对于 API 符合性而言，它们是必需的。
method difference(other: Any) → ColumnElement[bool]
范围表达式。返回两个范围的并集。如果结果范围不连续，则会引发异常。
method intersection(other: Any) → ColumnElement[Range[_T]]
范围表达式。返回两个范围的交集。如果结果范围不连续，则会引发异常。
method not_extend_left_of(other: Any) → ColumnElement[bool]
布尔表达式。如果列中的范围不延伸到操作数的左侧，则返回 true。
method not_extend_right_of(other: Any) → ColumnElement[bool]
布尔表达式。如果列中的范围不延伸到操作数的右侧，则返回 true。
method overlaps(other: Any) → ColumnElement[bool]
布尔表达式。如果列与右操作数重叠（具有共同点），则返回 true。
method strictly_left_of(other: Any) → ColumnElement[bool]
布尔表达式。如果列严格位于右操作数的左侧，则返回 true。
method strictly_right_of(other: Any) → ColumnElement[bool]
布尔表达式。如果列严格位于右操作数的右侧，则返回 true。
method union(other: Any) → ColumnElement[bool]
范围表达式。返回两个范围的并集。如果结果范围不连续，将引发异常。
class sqlalchemy.dialects.postgresql.AbstractSingleRange
PostgreSQL RANGE 类型的基础。
这些是返回单个Range对象的类型。
另请参阅
类签名
类sqlalchemy.dialects.postgresql.AbstractSingleRange (sqlalchemy.dialects.postgresql.ranges.AbstractRange)
class sqlalchemy.dialects.postgresql.AbstractMultiRange
PostgreSQL MULTIRANGE 类型的基础。
这些是返回一系列Range对象的类型。
类签名
类sqlalchemy.dialects.postgresql.AbstractMultiRange (sqlalchemy.dialects.postgresql.ranges.AbstractRange)
class sqlalchemy.dialects.postgresql.ARRAY
PostgreSQL 数组类型。
ARRAY 类型的构造与核心ARRAY类型相同；需要成员类型，并且如果要将类型用于多个维度，则建议指定维度的数量：
from sqlalchemy.dialects import postgresql mytable = Table("mytable", metadata, Column("data", postgresql.ARRAY(Integer, dimensions=2)) )
ARRAY 类型提供了在核心 ARRAY 类型上定义的所有操作，包括对“维度”的支持、索引访问以及简单的匹配，如 Comparator.any() 和 Comparator.all()。ARRAY 类还提供了用于包含操作的 PostgreSQL 特定方法，包括 Comparator.contains()、Comparator.contained_by() 和 Comparator.overlap()，例如：
mytable.c.data.contains([1, 2])
默认情况下，索引访问是基于一的，以匹配 PostgreSQL 的索引访问；要进行基于零的索引访问，请设置 ARRAY.zero_indexes。
此外，ARRAY 类型不能直接与ENUM 类型配合使用。有关解决方法，请参阅 使用 ENUM 与 ARRAY 的特殊类型。
使用 ORM 时检测 ARRAY 列中的更改
当与 SQLAlchemy ORM 一起使用时，ARRAY 类型无法检测数组的原位突变。为了检测这些突变，必须使用 sqlalchemy.ext.mutable 扩展，使用 MutableList 类：
from sqlalchemy.dialects.postgresql import ARRAY from sqlalchemy.ext.mutable import MutableList class SomeOrmClass(Base): # ... data = Column(MutableList.as_mutable(ARRAY(Integer)))
此扩展将允许对数组进行“就地”更改，如 .append()，以产生将被工作单元检测到的事件。请注意，对数组内部元素的更改，包括就地突变的子数组，不会被检测到。
或者，将新的数组值分配给替换旧值的 ORM 元素将始终触发更改事件。
请参阅
ARRAY - 基本数组类型
array - 生成文字数组值。
成员
init(), contains(), contained_by(), overlap()
类签名
类sqlalchemy.dialects.postgresql.ARRAY（sqlalchemy.types.ARRAY）
method __init__(item_type: _TypeEngineArgument[Any], as_tuple: bool = False, dimensions: int | None = None, zero_indexes: bool = False)
构造一个数组。
例如：
Column('myarray', ARRAY(Integer))
参数为：
参数：
item_type– 此数组项的数据类型。请注意，这里维度是无关紧要的，因此像INTEGER[][]这样的多维数组被构造为ARRAY(Integer)，而不是ARRAY(ARRAY(Integer))或类似的。as_tuple=False– 指定返回结果是否应从列表转换为元组。例如，DBAPIs 如 psycopg2 默认返回列表。当返回元组时，结果是可哈希的。dimensions– 如果非 None，则 ARRAY 将假定具有固定数量的维度。这将导致为此 ARRAY 发出的 DDL 包括确切数量的方括号[]，并且还将优化整体类型的性能。请注意，PG 数组始终隐式地“非维度化”，这意味着无论如何声明，它们都可以存储任意数量的维度。zero_indexes=False– 当为 True 时，索引值将在 Python 基于零和 PostgreSQL 基于一的索引之间转换，例如，在传递到数据库之前，所有索引值将增加一个值。
class Comparator
为ARRAY定义比较操作。
注意，这些操作是基于基础Comparator类提供的操作之外的，包括Comparator.any()和Comparator.all()。
类签名
类sqlalchemy.dialects.postgresql.ARRAY.Comparator（sqlalchemy.types.Comparator）
method contains(other, **kwargs)
布尔表达式。测试元素是否是参数数组表达式的元素的超集。
kwargs 可能会被此操作符忽略，但对于 API 一致性是必需的。
method contained_by(other)
布尔表达式。测试元素是否是参数数组表达式的元素的真子集。
method overlap(other)
布尔表达式。测试数组是否与参数数组表达式有共同元素。
class sqlalchemy.dialects.postgresql.BIT
类签名
类 sqlalchemy.dialects.postgresql.BIT (sqlalchemy.types.TypeEngine) - PostgreSQL 的 BIT 类型
class sqlalchemy.dialects.postgresql.BYTEA
成员
init() - 初始化方法
类签名
类 sqlalchemy.dialects.postgresql.BYTEA (sqlalchemy.types.LargeBinary) - PostgreSQL 的 BYTEA 类型
method __init__(length: int | None = None)
继承自 LargeBinary 的 sqlalchemy.types.LargeBinary.__init__ 方法 - 从 sqlalchemy.types.LargeBinary 继承
构造一个 LargeBinary 类型。
参数：
length – 可选，用于 DDL 语句中的列长度，对于那些接受长度的二进制类型，例如 MySQL 的 BLOB 类型。
class sqlalchemy.dialects.postgresql.CIDR
类签名
类 sqlalchemy.dialects.postgresql.CIDR (sqlalchemy.types.TypeEngine) - PostgreSQL 的 CIDR 类型
class sqlalchemy.dialects.postgresql.CITEXT
提供 PostgreSQL CITEXT 类型。
版本 2.0.7 中新增。
成员
init() - 初始化方法
类签名
类 sqlalchemy.dialects.postgresql.CITEXT (sqlalchemy.types.TEXT) - PostgreSQL 的 CITEXT 类型
method __init__(length: int | None = None, collation: str | None = None)
继承自 String 的 sqlalchemy.types.String.__init__ 方法 - 从 sqlalchemy.types.String 继承
创建一个持有字符串的类型。
参数：
length– 可选，用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE，可以安全地省略。某些数据库可能需要在 DDL 中使用长度，并且如果包含长度为零的VARCHAR，则在发出CREATE TABLEDDL 时会引发异常。值是作为字节还是字符解释是特定于数据库的。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.dialects.postgresql.DOMAIN
代表 DOMAIN PostgreSQL 类型。
域本上，域是具有可选约束的数据类型，约束限制了允许的值集。例如：
PositiveInt = DOMAIN( "pos_int", Integer, check="VALUE > 0", not_null=True ) UsPostalCode = DOMAIN( "us_postal_code", Text, check="VALUE ~ '^\d{5}$' OR VALUE ~ '^\d{5}-\d{4}$'" )
有关更多详细信息，请参阅PostgreSQL 文档
新版本 2.0 中新增。
成员
init(), create(), drop()
类签名
类sqlalchemy.dialects.postgresql.DOMAIN（sqlalchemy.dialects.postgresql.named_types.NamedType，sqlalchemy.types.SchemaType）
method __init__(name: str, data_type: _TypeEngineArgument[Any], *, collation: str | None = None, default: elements.TextClause | str | None = None, constraint_name: str | None = None, not_null: bool | None = None, check: elements.TextClause | str | None = None, create_type: bool = True, **kw: Any)
构造一个 DOMAIN。
参数：
name– 域的名称data_type– 域的基础数据类型。这可以包括数组说明符。collation– 域的可选排序规则。如果未指定排序规则，则使用基础数据类型的默认排序规则。如果指定了collation，则基础类型必须是可排序的。default– DEFAULT 子句为域数据类型的列指定默认值。默认值应为字符串或text()值。如果未指定默认值，则默认值为 null 值。constraint_name– 约束的可选名称。如果未指定，则后端会生成一个名称。not_null– 此域的值不允许为 null。默认情况下，域允许为 null。如果未指定，则不会发出空值约束。check– CHECK 子句指定域值必须满足的完整性约束或测试。约束必须是一个产生布尔结果的表达式，可以使用关键字 VALUE 来引用正在测试的值。与 PostgreSQL 不同，目前在 SQLAlchemy 中只允许一个检查子句。schema– 可选的模式名称metadata– 可选的MetaData对象，此DOMAIN将直接关联create_type– 默认为 True。指示在创建父表时应发出CREATE TYPE，并在必要时检查类型的存在；此外，在删除表时调用DROP TYPE。
method create(bind, checkfirst=True, **kw)
继承自 NamedType 的 NamedType.create() 方法
发出此类型的CREATE DDL。
参数：
bind– 一个可连接的Engine、Connection或类似对象以发出 SQL。checkfirst– 如果为True，则在创建之前首先对 PG 目录执行查询，以查看类型是否已存在。
method drop(bind, checkfirst=True, **kw)
继承自 NamedType.drop() 方法的 NamedType
发出此类型的DROP DDL。
参数：
bind– 一个可连接的Engine、Connection或类似对象以发出 SQL。checkfirst– 如果为True，则首先对 PG 目录执行查询，以查看类型是否实际存在才会删除。
class sqlalchemy.dialects.postgresql.DOUBLE_PRECISION
SQL DOUBLE PRECISION 类型。
新版本中新增。
另请参阅
Double - 基本类型的文档。
类签名
类 sqlalchemy.dialects.postgresql.DOUBLE_PRECISION (sqlalchemy.types.Double)
method __init__(precision: int | None = None, asdecimal: bool = False, decimal_return_scale: int | None = None)
继承自 sqlalchemy.types.Float.__init__ 方法的 Float
构造一个 Float。
参数：
precision–
用于在 DDLCREATE 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.dialects.postgresql.ENUM
PostgreSQL ENUM 类型。
这是Enum的子类，包括对 PG 的CREATE TYPE和DROP TYPE的支持。
当使用内置类型Enum并且Enum.native_enum标志保持默认值为 True 时，PostgreSQL 后端将使用ENUM类型作为实现，因此将使用特殊的创建/删除规则。
由于 ENUM 类型与父表的尴尬关系，ENUM 的创建/删除行为必然复杂，因为它可能仅被单个表“拥有”，也可能被多个表共享。
当以“内联”方式使用Enum或ENUM时，将发出CREATE TYPE和DROP TYPE，对应于调用Table.create()和Table.drop()方法时：
table = Table('sometable', metadata, Column('some_enum', ENUM('a', 'b', 'c', name='myenum')) ) table.create(engine) # will emit CREATE ENUM and CREATE TABLE table.drop(engine) # will emit DROP TABLE and DROP ENUM
要在多个表之间使用共同的枚举类型，最佳实践是独立声明Enum或ENUM，并将其与MetaData对象本身关联：
my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata) t1 = Table('sometable_one', metadata, Column('some_enum', myenum) ) t2 = Table('sometable_two', metadata, Column('some_enum', myenum) )
当使用这种模式时，仍然必须在单个表创建的级别上小心处理。发出 CREATE TABLE 而不指定checkfirst=True仍会导致问题：
t1.create(engine) # will fail: no such type 'myenum'
如果我们指定checkfirst=True，则单个表级别的创建操作将检查ENUM是否存在，如果不存在则创建：
# will check if enum exists, and emit CREATE TYPE if not t1.create(engine, checkfirst=True)
当使用基于元数据的 ENUM 类型时，如果调用元数据范围的创建/删除，则该类型将始终被创建和删除：
metadata.create_all(engine) # will emit CREATE TYPE metadata.drop_all(engine) # will emit DROP TYPE
该类型也可以直接创建和删除：
my_enum.create(engine) my_enum.drop(engine)
成员
init(), create(), drop()
类签名
类sqlalchemy.dialects.postgresql.ENUM (sqlalchemy.dialects.postgresql.named_types.NamedType, sqlalchemy.types.NativeForEmulated, sqlalchemy.types.Enum)
method __init__(*enums, name: str | _NoArg | None = _NoArg.NO_ARG, create_type: bool = True, **kw)
构造一个ENUM。
参数与Enum相同，但还包括以下参数。
参数：
create_type – 默认为 True。指示在创建父表时应发出CREATE TYPE，并在需要时检查类型的存在；此外，在删除表时调用DROP TYPE。当为False时，不会执行任何检查，也不会发出CREATE TYPE或DROP TYPE，除非直接调用ENUM.create()或ENUM.drop()。在没有实际数据库访问的情况下向 SQL 文件调用创建方案时，将其设置为False是有帮助的 - 可以使用ENUM.create()和ENUM.drop()方法向目标绑定发出 SQL。
method create(bind=None, checkfirst=True)
为此ENUM发出CREATE TYPE。
如果底层方言不支持 PostgreSQL CREATE TYPE，则不会采取任何操作。
参数：
bind– 一个可连接的Engine、Connection或类似对象，用于发出 SQL。checkfirst– 如果为True，将首先执行针对 PG 目录的查询，以查看在创建之前类型是否已存在。
method drop(bind=None, checkfirst=True)
为此ENUM发出DROP TYPE。
如果底层方言不支持 PostgreSQL DROP TYPE，则不会采取任何操作。
参数：
bind– 一个可连接的Engine、Connection或类似对象，用于发出 SQL。checkfirst– 如果为True，将首先执行针对 PG 目录的查询，以查看类型是否实际存在，然后再执行删除。
class sqlalchemy.dialects.postgresql.HSTORE
表示 PostgreSQL HSTORE 类型。
HSTORE 类型存储包含字符串的字典，例如：
data_table = Table('data_table', metadata, Column('id', Integer, primary_key=True), Column('data', HSTORE) ) with engine.connect() as conn: conn.execute( data_table.insert(), data = {"key1": "value1", "key2": "value2"} )
HSTORE 提供广泛的操作，包括：
- 索引操作：
data_table.c.data['some key'] == 'some value'
- 包含操作：
data_table.c.data.has_key('some key') data_table.c.data.has_all(['one', 'two', 'three'])
- 连接：
data_table.c.data + {"k1": "v1"}
有关特殊方法的完整列表，请参见comparator_factory。
在使用 ORM 时检测 HSTORE 列中的更改
对于在 SQLAlchemy ORM 中的使用，可能希望将HSTORE的使用与MutableDict字典结合起来，该字典现在是sqlalchemy.ext.mutable扩展的一部分。这个扩展将允许对字典进行“原地”更改，例如添加新键或将现有键替换/删除到/从当前字典中，以产生将被工作单元检测到的事件：
from sqlalchemy.ext.mutable import MutableDict class MyClass(Base): __tablename__ = 'data_table' id = Column(Integer, primary_key=True) data = Column(MutableDict.as_mutable(HSTORE)) my_object = session.query(MyClass).one() # in-place mutation, requires Mutable extension # in order for the ORM to detect my_object.data['some_key'] = 'some value' session.commit()
当不使用sqlalchemy.ext.mutable扩展时，ORM 将不会被提醒对现有字典内容的任何更改，除非该字典值被重新分配给 HSTORE 属性本身，从而生成更改事件。
另见
hstore - 渲染 PostgreSQL 的 hstore() 函数。
成员
array(), contained_by(), contains(), defined(), delete(), has_all(), has_any(), has_key(), keys(), matrix(), slice(), vals(), init(), bind_processor(), comparator_factory, hashable, result_processor()
类签名
类sqlalchemy.dialects.postgresql.HSTORE（sqlalchemy.types.Indexable, sqlalchemy.types.Concatenable, sqlalchemy.types.TypeEngine)
class Comparator
为HSTORE定义比较操作。
类签名
类sqlalchemy.dialects.postgresql.HSTORE.Comparator（sqlalchemy.types.Comparator，sqlalchemy.types.Comparator）
method array()
文本数组表达式。返回交替键和值的数组。
method contained_by(other)
布尔表达式。测试键是否为参数 jsonb 表达式的键的真子集。
method contains(other, **kwargs
布尔表达式。测试键（或数组）是否为参数 jsonb 表达式的键的超集/包含。
kwargs 可能会被此操作符忽略，但对 API 一致性来说是必需的。
method defined(key)
布尔表达式。测试键的非 NULL 值是否存在。请注意键可以是 SQLA 表达式。
method delete(key)
HStore 表达式。返回删除了给定键的此 hstore 的内容。请注意键可以是 SQLA 表达式。
method has_all(other)
布尔表达式。测试 jsonb 中所有键是否存在。
method has_any(other)
布尔表达式。测试 jsonb 中是否存在任何键。
method has_key(other)
布尔表达式。测试键是否存在。请注意键可以是 SQLA 表达式。
method keys()
文本数组表达式。返回键的数组。
method matrix()
文本数组表达式。返回[键，值]对的数组。
method slice(array)
HStore 表达式。返回由键数组定义的 hstore 的子集。
method vals()
文本数组表达式。返回值数组。
method __init__(text_type=None)
构建一个新的HSTORE。
参数：
text_type - 应用于索引值的类型。默认为Text。
method bind_processor(dialect)
返回一个处理绑定值的转换函数。
返回一个可调用函数，该函数将接收绑定参数值作为唯一位置参数，并返回要发送到 DB-API 的值。
如果不需要处理，则该方法应返回None。
注意
该方法仅相对于特定方言类型对象调用，该对象通常是正在使用的方言的私有对象，并且不是与公共面向的对象相同的类型对象，这意味着无法通过子类化TypeEngine类来提供替代TypeEngine.bind_processor()方法，除非明确子类化UserDefinedType类。
为了为TypeEngine.bind_processor()提供替代行为，实现一个TypeDecorator类并提供一个TypeDecorator.process_bind_param()的实现。
另请参见
扩充现有类型
参数：
dialect – 使用的方言实例。
attribute comparator_factory
Comparator的别名。
attribute hashable = False
标志，如果为 False，则表示此类型的值不可哈希。
在 ORM 中用于唯一化结果列表。
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.dialects.postgresql.INET
类签名
类sqlalchemy.dialects.postgresql.INET (sqlalchemy.types.TypeEngine)。
class sqlalchemy.dialects.postgresql.INTERVAL
PostgreSQL 间隔类型。
成员
init()
类签名
类sqlalchemy.dialects.postgresql.INTERVAL（sqlalchemy.types.NativeForEmulated，sqlalchemy.types._AbstractInterval）
method __init__(precision: int | None = None, fields: str | None = None) → None
构造一个 INTERVAL。
参数：
precision– 可选的整数精度值fields–
字段字符串指定器。允许限制存储字段，例如"YEAR"，"MONTH"，"DAY TO HOUR"等。
版本 1.2 中的新功能。
class sqlalchemy.dialects.postgresql.JSON
表示 PostgreSQL 的 JSON 类型。
当基本 JSON 数据类型用于 PostgreSQL 后端时，将自动使用 JSON，但基本 JSON 数据类型不提供用于 PostgreSQL 特定比较方法的 Python 访问器，例如 Comparator.astext()；此外，要使用 PostgreSQL 的 JSONB，应明确使用 JSONB 数据类型。
另请参阅
JSON - 用于通用跨平台 JSON 数据类型的主要文档。
PostgreSQL 版本提供的 JSON 运算符包括：
- 索引操作（
->运算符）：
data_table.c.data['some key'] data_table.c.data[5]
- 返回文本的索引操作（
->>运算符）：
data_table.c.data['some key'].astext == 'some value'
- 请注意，等效功能也可以通过
Comparator.as_string访问器实现。 - 使用 CAST 进行索引操作（相当于
CAST(col ->> ['some key'] AS )）：
data_table.c.data['some key'].astext.cast(Integer) == 5
- 请注意，等效功能也可以通过
Comparator.as_integer和类似的访问器实现。 - 路径索引操作（
#>运算符）：
data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')]
- 返回文本的路径索引操作（
#>>运算符）：
data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')].astext == 'some value'
索引操作默认返回一个类型为JSON的表达式对象，因此可以对结果类型调用更多面向 JSON 的指令。
自定义序列化器和反序列化器在方言级别指定，即使用create_engine()。这样做的原因是，在使用 psycopg2 时，DBAPI 只允许在每个游标或每个连接级别上进行序列化。例如：
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test", json_serializer=my_serialize_fn, json_deserializer=my_deserialize_fn )
在使用 psycopg2 方言时，json_deserializer 是通过 psycopg2.extras.register_default_json 注册到数据库中的。
另请参阅
JSON - 核心级别的 JSON 类型
JSONB
成员
astext, init(), comparator_factory
类签名
类sqlalchemy.dialects.postgresql.JSON（sqlalchemy.types.JSON）
class Comparator
为JSON 定义比较操作。
类签名
类sqlalchemy.dialects.postgresql.JSON.Comparator（sqlalchemy.types.Comparator）
attribute astext
在索引表达式上，当在 SQL 中渲染时，使用“astext”（例如“->>”）转换。
例如：
select(data_table.c.data['some key'].astext)
另请参阅
ColumnElement.cast()
method __init__(none_as_null=False, astext_type=None)
构造一个JSON 类型。
参数：
none_as_null-
如果为 True，则将值None持久化为 SQL NULL 值，而不是null的 JSON 编码。请注意，当此标志为 False 时，仍然可以使用null()构造来持久化 NULL 值：
from sqlalchemy import null conn.execute(table.insert(), {"data": null()})
- 另请参阅
JSON.NULL astext_type- 用于索引属性上的Comparator.astext访问器的类型。默认为Text。
attribute comparator_factory
的别名Comparator
class sqlalchemy.dialects.postgresql.JSONB
表示 PostgreSQL 的 JSONB 类型。
JSONB 类型存储任意的 JSONB 格式数据，例如：
data_table = Table('data_table', metadata, Column('id', Integer, primary_key=True), Column('data', JSONB) ) with engine.connect() as conn: conn.execute( data_table.insert(), data = {"key1": "value1", "key2": "value2"} )
JSONB类型包括JSON提供的所有操作，包括索引操作的相同行为。它还添加了特定于 JSONB 的其他运算符，包括Comparator.has_key()、Comparator.has_all()、Comparator.has_any()、Comparator.contains()、Comparator.contained_by()、Comparator.delete_path()、Comparator.path_exists()和Comparator.path_match()。
与JSON类型类似，JSONB类型在使用 ORM 时，除非使用了sqlalchemy.ext.mutable扩展，否则不会检测到原地更改。
自定义序列化器和反序列化器与JSON类共享，使用json_serializer和json_deserializer关键字参数。必须在方言级别使用create_engine()指定这些参数。当使用 psycopg2 时，序列化器与 jsonb 类型相关联，使用psycopg2.extras.register_default_jsonb在每个连接上基于 psycopg2 方式注册这些处理程序，与使用psycopg2.extras.register_default_json将这些处理程序注册到 json 类型的方式相同。
另请参阅
JSON
成员
contained_by(), contains(), delete_path(), has_all(), has_any(), has_key(), path_exists(), path_match(), comparator_factory。
类签名
类 sqlalchemy.dialects.postgresql.JSONB (sqlalchemy.dialects.postgresql.json.JSON)。
class Comparator
为 JSON 定义比较操作。
类签名
类 sqlalchemy.dialects.postgresql.JSONB.Comparator (sqlalchemy.dialects.postgresql.json.Comparator)。
method contained_by(other)
布尔表达式。测试键是否是参数 jsonb 表达式的键的真子集。
method contains(other, **kwargs)
布尔表达式。测试键（或数组）是否是参数 jsonb 表达式的键的超集/包含。
kwargs 可能会被此运算符忽略，但对于 API 一致性是必需的。
method delete_path(array)
JSONB 表达���。删除参数数组中指定的字段或数组元素。
输入可以是一个将被强制转换为 ARRAY 的字符串列表，或者是 _postgres.array() 的实例。
版本 2.0 中新增。
method has_all(other)
布尔表达式。测试 jsonb 中是否存在所有键。
method has_any(other)
布尔表达式。测试 jsonb 中是否存在任何键。
method has_key(other)
布尔表达式。测试键是否存在。请注意，键可能是 SQLA 表达式。
method path_exists(other)
布尔表达式。测试参数 JSONPath 表达式给出的项目是否存在。
版本 2.0 中新增。
method path_match(other)
布尔表达式。测试参数 JSONPath 表达式给出的 JSONPath 谓词是否匹配。
仅考虑结果的第一项。
版本 2.0 中新增。
attribute comparator_factory
Comparator 的别名。
class sqlalchemy.dialects.postgresql.JSONPATH
JSON 路径类型。
当使用类似于 jsonb_path_query_array 或 jsonb_path_exists 的 json 搜索函数时，通常需要将字面值转换为 json 路径：
stmt = sa.select( sa.func.jsonb_path_query_array( table.c.jsonb_col, cast("$.address.id", JSONPATH) ) )
类签名
类 sqlalchemy.dialects.postgresql.JSONPATH (sqlalchemy.dialects.postgresql.json.JSONPathType)。
class sqlalchemy.dialects.postgresql.MACADDR
类签名
类sqlalchemy.dialects.postgresql.MACADDR（sqlalchemy.types.TypeEngine）
class sqlalchemy.dialects.postgresql.MACADDR8
类签名
类sqlalchemy.dialects.postgresql.MACADDR8（sqlalchemy.types.TypeEngine）
class sqlalchemy.dialects.postgresql.MONEY
提供 PostgreSQL MONEY 类型。
取决于驱动程序，使用此类型的结果行可能会返回包含货币符号的字符串值。
因此，最好使用 TypeDecorator 将其转换为基于数字的货币数据类型：
import re import decimal from sqlalchemy import Dialect from sqlalchemy import TypeDecorator class NumericMoney(TypeDecorator): impl = MONEY def process_result_value( self, value: Any, dialect: Dialect ) -> None: if value is not None: # adjust this for the currency and numeric m = re.match(r"\$([\d.]+)", value) if m: value = decimal.Decimal(m.group(1)) return value
或者，可以使用 TypeDecorator.column_expression() 方法将转换应用为 CAST 如下所示：
import decimal from sqlalchemy import cast from sqlalchemy import TypeDecorator class NumericMoney(TypeDecorator): impl = MONEY def column_expression(self, column: Any): return cast(column, Numeric())
新版本 1.2 中新增。
类签名
类sqlalchemy.dialects.postgresql.MONEY（sqlalchemy.types.TypeEngine）
class sqlalchemy.dialects.postgresql.OID
提供 PostgreSQL OID 类型。
类签名
类sqlalchemy.dialects.postgresql.OID（sqlalchemy.types.TypeEngine）
class sqlalchemy.dialects.postgresql.REAL
SQL REAL 类型。
参见
Float - 基本类型的文档。
类签名
类 sqlalchemy.dialects.postgresql.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–
用于 DDLCREATE 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.dialects.postgresql.REGCONFIG
提供 PostgreSQL 的 REGCONFIG 类型。
新版本 2.0.0rc1 中新增。
类签名
类 sqlalchemy.dialects.postgresql.REGCONFIG (sqlalchemy.types.TypeEngine)
class sqlalchemy.dialects.postgresql.REGCLASS
提供 PostgreSQL 的 REGCLASS 类型。
新版本 1.2.7 中新增。
类签名
类 sqlalchemy.dialects.postgresql.REGCLASS (sqlalchemy.types.TypeEngine)
class sqlalchemy.dialects.postgresql.TIMESTAMP
提供 PostgreSQL 的 TIMESTAMP 类型。
成员
init()
类签名
类 sqlalchemy.dialects.postgresql.TIMESTAMP (sqlalchemy.types.TIMESTAMP)
method __init__(timezone: bool = False, precision: int | None = None) → None
构造一个 TIMESTAMP。
参数：
timezone– 如果存在时区则为布尔值，默认为 Falseprecision–
可选的整数精度值
新版本 1.4 中新增。
class sqlalchemy.dialects.postgresql.TIME
PostgreSQL 的 TIME 类型。
成员
init()
类签名
类 sqlalchemy.dialects.postgresql.TIME (sqlalchemy.types.TIME)
method __init__(timezone: bool = False, precision: int | None = None) → None
构建一个 TIME。
参数：
timezone– 如果存在时区，则为布尔值，默认为 Falseprecision–
可选的整数精度值
新版本 1.4 中新增。
class sqlalchemy.dialects.postgresql.TSQUERY
提供 PostgreSQL TSQUERY 类型。
新版本 2.0.0rc1 中新增。
类签名
类 sqlalchemy.dialects.postgresql.TSQUERY (sqlalchemy.types.TypeEngine)
class sqlalchemy.dialects.postgresql.TSVECTOR
TSVECTOR 类型实现了 PostgreSQL 文本搜索类型 TSVECTOR。
可用于对自然语言文档进行全文查询。
另请参见
全文搜索
类签名
类 sqlalchemy.dialects.postgresql.TSVECTOR (sqlalchemy.types.TypeEngine)
class sqlalchemy.dialects.postgresql.UUID
表示 SQL UUID 类型。
这是 Uuid 数据库不可知数据类型的 SQL 本机形式，并且向后兼容以前的仅限于 PostgreSQL 的 UUID 版本。
UUID 数据类型仅适用于具有名为 UUID 的 SQL 数据类型的数据库。它不适用于没有这个确切命名类型的后端，包括 SQL Server。对于具有本机支持的后端不可知 UUID 值，包括 SQL Server 的 UNIQUEIDENTIFIER 数据类型，请使用 Uuid 数据类型。
新版本 2.0 中新增。
另请参见
Uuid
类签名
类 sqlalchemy.dialects.postgresql.UUID (sqlalchemy.types.Uuid, sqlalchemy.types.NativeForEmulated)
method __init__(as_uuid: bool = True)
构建一个 UUID 类型。
参数：
as_uuid=True –
如果为 True，则值将被解释为 Python uuid 对象，通过 DBAPI 转换为字符串。
class sqlalchemy.dialects.postgresql.INT4RANGE
表示 PostgreSQL INT4RANGE 类型。
类签名
类 sqlalchemy.dialects.postgresql.INT4RANGE (sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange)
class sqlalchemy.dialects.postgresql.INT8RANGE
表示 PostgreSQL INT8RANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.INT8RANGE（sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）
class sqlalchemy.dialects.postgresql.NUMRANGE
表示 PostgreSQL NUMRANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.NUMRANGE（sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）
class sqlalchemy.dialects.postgresql.DATERANGE
表示 PostgreSQL DATERANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.DATERANGE（sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）
class sqlalchemy.dialects.postgresql.TSRANGE
表示 PostgreSQL TSRANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.TSRANGE（sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）
class sqlalchemy.dialects.postgresql.TSTZRANGE
表示 PostgreSQL TSTZRANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.TSTZRANGE（sqlalchemy.dialects.postgresql.ranges.AbstractSingleRange）
class sqlalchemy.dialects.postgresql.INT4MULTIRANGE
表示 PostgreSQL INT4MULTIRANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.INT4MULTIRANGE（sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange）
class sqlalchemy.dialects.postgresql.INT8MULTIRANGE
表示 PostgreSQL INT8MULTIRANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.INT8MULTIRANGE（sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange）
class sqlalchemy.dialects.postgresql.NUMMULTIRANGE
表示 PostgreSQL NUMMULTIRANGE 类型。
类签名
类sqlalchemy.dialects.postgresql.NUMMULTIRANGE（sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange）
class sqlalchemy.dialects.postgresql.DATEMULTIRANGE
表示 PostgreSQL DATEMULTIRANGE 类型。
类签名
类 sqlalchemy.dialects.postgresql.DATEMULTIRANGE (sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange)
class sqlalchemy.dialects.postgresql.TSMULTIRANGE
表示 PostgreSQL TSRANGE 类型。
类签名
类 sqlalchemy.dialects.postgresql.TSMULTIRANGE (sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange)
class sqlalchemy.dialects.postgresql.TSTZMULTIRANGE
表示 PostgreSQL TSTZRANGE 类型。
类签名
类 sqlalchemy.dialects.postgresql.TSTZMULTIRANGE (sqlalchemy.dialects.postgresql.ranges.AbstractMultiRange)
class sqlalchemy.dialects.postgresql.MultiRange
表示一个多范围序列。
这个列表子类是一个实用工具，允许根据单个范围值自动推断适当的多范围 SQL 类型。在操作文字多范围时非常有用：
import sqlalchemy as sa from sqlalchemy.dialects.postgresql import MultiRange, Range value = literal(MultiRange([Range(2, 4)])) select(tbl).where(tbl.c.value.op("@")(MultiRange([Range(-3, 7)])))
新版本 2.0.26 中新增。
另请参阅
- 使用 MultiRange 序列推断多范围类型。
类签名
类 sqlalchemy.dialects.postgresql.MultiRange (builtins.list, typing.Generic)
PostgreSQL SQL 元素和函数
| 对象名称 | 描述 |
| aggregate_order_by | 表示 PostgreSQL 聚合排序表达式。 |
| All(other, arrexpr[, operator]) | ARRAY 级别的 Comparator.all() 方法的同义词。有关详细信息，请参阅该方法。 |
| Any(other, arrexpr[, operator]) | ARRAY 级别的 Comparator.any() 方法的同义词。有关详细信息，请参阅该方法。 |
| array | PostgreSQL ARRAY 文本。 |
| array_agg(*arg, **kw) | array_agg 的 PostgreSQL 特定形式，确保返回类型是 ARRAY 而不是普通的 ARRAY，除非传递了显式的 type_。 |
| hstore | 使用 PostgreSQL hstore() 函数在 SQL 表达式中构造 hstore 值。 |
| phraseto_tsquery | PostgreSQL phraseto_tsquery SQL 函数。 |
| plainto_tsquery | PostgreSQL plainto_tsquery SQL 函数。 |
| to_tsquery | PostgreSQL to_tsquery SQL 函数。 |
| to_tsvector | PostgreSQL to_tsvector SQL 函数。 |
| ts_headline | PostgreSQL ts_headline SQL 函数。 |
| websearch_to_tsquery | PostgreSQL websearch_to_tsquery SQL 函数。 |
class sqlalchemy.dialects.postgresql.aggregate_order_by
表示一个 PostgreSQL 聚合的 order by 表达式。
例如：
from sqlalchemy.dialects.postgresql import aggregate_order_by expr = func.array_agg(aggregate_order_by(table.c.a, table.c.b.desc())) stmt = select(expr)
将表示表达式：
SELECT array_agg(a ORDER BY b DESC) FROM table;
类似地：
expr = func.string_agg( table.c.a, aggregate_order_by(literal_column("','"), table.c.a) ) stmt = select(expr)
表示：
SELECT string_agg(a, ',' ORDER BY a) FROM table;
在版本 1.2.13 中更改：- ORDER BY 参数可以是多个术语
另请参阅
array_agg
类签名
类 sqlalchemy.dialects.postgresql.aggregate_order_by（sqlalchemy.sql.expression.ColumnElement)
class sqlalchemy.dialects.postgresql.array
PostgreSQL 的 ARRAY 字面量。
用于在 SQL 表达式中生成 ARRAY 字面量，例如：
from sqlalchemy.dialects.postgresql import array from sqlalchemy.dialects import postgresql from sqlalchemy import select, func stmt = select(array([1,2]) + array([3,4,5])) print(stmt.compile(dialect=postgresql.dialect()))
生成 SQL：
SELECT ARRAY[%(param_1)s, %(param_2)s] || ARRAY[%(param_3)s, %(param_4)s, %(param_5)s]) AS anon_1
array 的实例始终具有数据类型 ARRAY。数组的“内部”类型是从存在的值中推断出的，除非传递了 type_ 关键字参数：
array(['foo', 'bar'], type_=CHAR)
多维数组通过嵌套 array 构造而产生。最终 ARRAY 类型的维数是通过递归添加内部 ARRAY 类型的维数来计算的：
stmt = select( array([ array([1, 2]), array([3, 4]), array([column('q'), column('x')]) ]) ) print(stmt.compile(dialect=postgresql.dialect()))
产生：
SELECT ARRAY[ARRAY[%(param_1)s, %(param_2)s], ARRAY[%(param_3)s, %(param_4)s], ARRAY[q, x]] AS anon_1
版本 1.3.6 中的新内容：增加了对多维数组字面值的支持
另请参阅
ARRAY
类签名
类 sqlalchemy.dialects.postgresql.array (sqlalchemy.sql.expression.ExpressionClauseList)
function sqlalchemy.dialects.postgresql.array_agg(*arg, **kw)
array_agg 的 PostgreSQL 特定形式，确保返回类型为 ARRAY 而不是普通的 ARRAY，除非显式传递了 type_。
function sqlalchemy.dialects.postgresql.Any(other, arrexpr, operator=<built-in function eq>)
一个 Comparator.any() 方法的 ARRAY 级别的同义词。有关详细信息，请参见该方法。
function sqlalchemy.dialects.postgresql.All(other, arrexpr, operator=<built-in function eq>)
一个 Comparator.all() 方法的 ARRAY 级别的同义词。有关详细信息，请参见该方法。
class sqlalchemy.dialects.postgresql.hstore
使用 PostgreSQL hstore() 函数在 SQL 表达式中构造 hstore 值。
hstore 函数接受一个或两个参数，如 PostgreSQL 文档所述。
例如：
from sqlalchemy.dialects.postgresql import array, hstore select(hstore('key1', 'value1')) select( hstore( array(['key1', 'key2', 'key3']), array(['value1', 'value2', 'value3']) ) )
另请参见
HSTORE - PostgreSQL 的 HSTORE 数据类型。
成员
inherit_cache, type
类签名
类 sqlalchemy.dialects.postgresql.hstore (sqlalchemy.sql.functions.GenericFunction)
attribute inherit_cache: bool | None = True
指示此 HasCacheKey 实例是否应使用其直接超类使用的缓存键生成方案。
该属性默认为 None，表示构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。
如果与此类本地属性无关且不是其超类的属性，则可以在特定类上将此标志设置为 True，如果与对象对应的 SQL 不基于这些属性而变化。
另请参见
为自定义结构启用缓存支持 - 设置第三方或用户定义的 SQL 结构的 HasCacheKey.inherit_cache 属性的一般指南。
attribute type
别名HSTORE
class sqlalchemy.dialects.postgresql.to_tsvector
PostgreSQL to_tsvector SQL 函数。
此函数将自动将 REGCONFIG 参数转换为使用REGCONFIG数据类型，并应用返回类型TSVECTOR。
假设已导入 PostgreSQL 方言，可以通过调用from sqlalchemy.dialects import postgresql或使用create_engine("postgresql...")创建 PostgreSQL 引擎，当调用sqlalchemy.func.to_tsvector()时，将自动使用to_tsvector，确保在编译和执行时使用正确的参数和返回类型处理程序。
版本 2.0.0rc1 中的新功能。
类签名
类sqlalchemy.dialects.postgresql.to_tsvector（sqlalchemy.dialects.postgresql.ext._regconfig_fn）的别名
class sqlalchemy.dialects.postgresql.to_tsquery
PostgreSQL to_tsquery SQL 函数。
此函数将自动将 REGCONFIG 参数转换为使用REGCONFIG数据类型，并应用返回类型TSQUERY。
假设已导入 PostgreSQL 方言，可以通过调用from sqlalchemy.dialects import postgresql或使用create_engine("postgresql...")创建 PostgreSQL 引擎，当调用sqlalchemy.func.to_tsquery()时，将自动使用to_tsquery，确保在编译和执行时使用正确的参数和返回类型处理程序。
版本 2.0.0rc1 中的新功能。
类签名
类sqlalchemy.dialects.postgresql.to_tsquery（sqlalchemy.dialects.postgresql.ext._regconfig_fn）的别名
class sqlalchemy.dialects.postgresql.plainto_tsquery
PostgreSQL plainto_tsquery SQL 函数。
此函数将自动将 REGCONFIG 参数转换为使用REGCONFIG数据类型，并应用返回类型TSQUERY。
假设已经导入了 PostgreSQL 方言，可以通过调用 from sqlalchemy.dialects import postgresql 或者使用 create_engine("postgresql...") 创建 PostgreSQL 引擎来实现，当调用 sqlalchemy.func.plainto_tsquery() 时将自动使用 plainto_tsquery，确保在编译和执行时使用正确的参数和返回类型处理程序。
版本 2.0.0rc1 中的新内容。
类签名
类 sqlalchemy.dialects.postgresql.plainto_tsquery (sqlalchemy.dialects.postgresql.ext._regconfig_fn)
class sqlalchemy.dialects.postgresql.phraseto_tsquery
PostgreSQL phraseto_tsquery SQL 函数。
此函数将自动将 REGCONFIG 参数转换为 REGCONFIG 数据类型，并应用返回类型 TSQUERY。
假设已经导入了 PostgreSQL 方言，可以通过调用 from sqlalchemy.dialects import postgresql 或者使用 create_engine("postgresql...") 创建 PostgreSQL 引擎来实现，当调用 sqlalchemy.func.phraseto_tsquery() 时将自动使用 phraseto_tsquery，确保在编译和执行时使用正确的参数和返回类型处理程序。
版本 2.0.0rc1 中的新内容。
类签名
类 sqlalchemy.dialects.postgresql.phraseto_tsquery (sqlalchemy.dialects.postgresql.ext._regconfig_fn)
class sqlalchemy.dialects.postgresql.websearch_to_tsquery
PostgreSQL websearch_to_tsquery SQL 函数。
此函数将自动将 REGCONFIG 参数转换为 REGCONFIG 数据类型，并应用返回类型 TSQUERY。
假设已经导入了 PostgreSQL 方言，可以通过调用 from sqlalchemy.dialects import postgresql 或者使用 create_engine("postgresql...") 创建 PostgreSQL 引擎来实现，当调用 sqlalchemy.func.websearch_to_tsquery() 时将自动使用 websearch_to_tsquery，确保在编译和执行时使用正确的参数和返回类型处理程序。
版本 2.0.0rc1 中的新内容。
类签名
类 sqlalchemy.dialects.postgresql.websearch_to_tsquery (sqlalchemy.dialects.postgresql.ext._regconfig_fn)
class sqlalchemy.dialects.postgresql.ts_headline
PostgreSQL 的ts_headline SQL 函数。
此函数自动将 REGCONFIG 参数转换为使用REGCONFIG数据类型，并应用TEXT的返回类型。
假设已导入 PostgreSQL 方言，可以通过调用from sqlalchemy.dialects import postgresql或使用create_engine("postgresql...")创建 PostgreSQL 引擎，当调用sqlalchemy.func.ts_headline()时，ts_headline将自动使用，确保在编译和执行时使用正确的参数和返回类型处理程序。
版本 2.0.0rc1 中的新功能。
类签名
类sqlalchemy.dialects.postgresql.ts_headline（sqlalchemy.dialects.postgresql.ext._regconfig_fn）
PostgreSQL 约束类型
SQLAlchemy 通过ExcludeConstraint类支持 PostgreSQL EXCLUDE 约束：
| 对象名称 | 描述 |
| ExcludeConstraint | 表级 EXCLUDE 约束。 |
class sqlalchemy.dialects.postgresql.ExcludeConstraint
表级 EXCLUDE 约束。
定义了在PostgreSQL 文档中描述的 EXCLUDE 约束。
成员
init()
类签名
类sqlalchemy.dialects.postgresql.ExcludeConstraint（sqlalchemy.schema.ColumnCollectionConstraint）
method __init__(*elements, **kw)
创建一个ExcludeConstraint对象。
例如：
const = ExcludeConstraint( (Column('period'), '&&'), (Column('group'), '='), where=(Column('group') != 'some group'), ops={'group': 'my_operator_class'} )
约束通常直接嵌入到Table构造中，或者稍后使用append_constraint()添加：
some_table = Table( 'some_table', metadata, Column('id', Integer, primary_key=True), Column('period', TSRANGE()), Column('group', String) ) some_table.append_constraint( ExcludeConstraint( (some_table.c.period, '&&'), (some_table.c.group, '='), where=some_table.c.group != 'some group', name='some_table_excl_const', ops={'group': 'my_operator_class'} ) )
此示例中定义的排除约束需要btree_gist扩展，可以使用命令CREATE EXTENSION btree_gist;创建。
参数：
*elements–
一个由两个形式为(column, operator)的元组序列，其中“column”可以是一个Column对象，或者一个 SQL 表达式元素（例如func.int8range(table.from, table.to)），或者作为字符串的列名，“operator”是包含要使用的操作符的字符串（例如“&&”或“=”）。
为了在没有Column对象可用时指定列名，并确保任何必要的引号规则生效，应使用临时的Column或column()对象。当作为literal_column()或text()传递时，column也可以是字符串 SQL 表达式。name– 可选，此约束的数据库中名称。deferrable– 可选布尔值。如果设置，当为此约束发出 DDL 时，发出 DEFERRABLE 或 NOT DEFERRABLE。initially– 可选字符串。如果设置，当为此约束发出 DDL 时，发出 INITIALLY 。using– 可选字符串。如果设置，当为此约束发出 DDL 时，发出 USING 。默认为‘gist’。where–
可选的 SQL 表达式构造或文字 SQL 字符串。如果设置，当为此约束发出 DDL 时，发出 WHERE 。
警告ExcludeConstraint.where参数可以作为 Python 字符串参数传递给ExcludeConstraint，它将被视为受信任的 SQL 文本并按照给定的方式呈现。不要将不受信任的输入传递给此参数。ops–
可选字典。用于为元素定义操作符类；与指定给Index构造的 postgresql_ops 参数的工作方式相同。
版本 1.3.21 中的新功能。
参见
操作符类 - PostgreSQL 操作符类如何指定的一般描述。
例如：
from sqlalchemy.dialects.postgresql import ExcludeConstraint, TSRANGE class RoomBooking(Base): __tablename__ = "room_booking" room = Column(Integer(), primary_key=True) during = Column(TSRANGE()) __table_args__ = (ExcludeConstraint(("room", "="), ("during", "&&")),)
PostgreSQL DML 构造
| 对象名称 | 描述 |
| insert(table) | 构造一个 PostgreSQL 特定变体的 Insert 构造。 |
| Insert | INSERT 的 PostgreSQL 特定实现。 |
function sqlalchemy.dialects.postgresql.insert(table: _DMLTableArgument) → Insert
构建一个特定于 PostgreSQL 的变体Insert 构造。
sqlalchemy.dialects.postgresql.insert() 函数创建一个 sqlalchemy.dialects.postgresql.Insert。此类基于方言不可知的 Insert 构造，可以使用 SQLAlchemy Core 中的 insert() 函数构造。
Insert 构造包括额外的方法 Insert.on_conflict_do_update(), Insert.on_conflict_do_nothing()。
class sqlalchemy.dialects.postgresql.Insert
INSERT 的 PostgreSQL 特定实现。
添加了用于 PG 特定语法的方法，如 ON CONFLICT。
使用 sqlalchemy.dialects.postgresql.insert() 函数创建 Insert 对象。
成员
excluded, inherit_cache, on_conflict_do_nothing(), on_conflict_do_update()
类签名
类 sqlalchemy.dialects.postgresql.Insert (sqlalchemy.sql.expression.Insert)
attribute excluded
为 ON CONFLICT 语句提供 excluded 命名空间
PG 的 ON CONFLICT 子句允许引用将要插入的行，称为 excluded。此属性提供了此行中的所有列可供引用。
提示
Insert.excluded属性是ColumnCollection的一个实例，提供了与访问表和列中描述的Table.c集合相同的接口。通过这个集合，普通名称可以像属性一样访问（例如stmt.excluded.some_column），但特殊名称和字典方法名称应该使用索引访问，如stmt.excluded["column name"]或stmt.excluded["values"]。请参阅ColumnCollection的文档字符串以获取更多示例。
另请参阅
INSERT…ON CONFLICT（Upsert） - 如何使用Insert.excluded的示例
attribute inherit_cache: bool | None = False
指示此HasCacheKey实例是否应使用其直接超类使用的缓存键生成方案。
该属性默认为None，表示构造尚未考虑是否适合参与缓存；这在功能上等同于将值设置为False，只是还会发出警告。
如果与对象对应的 SQL 不基于本类的局部属性而是基于其超类，则可以在特定类上将此标志设置为True。
另请参阅
为自定义结构启用缓存支持 - 为第三方或用户定义的 SQL 结构设置HasCacheKey.inherit_cache属性的一般指导方针。
method on_conflict_do_nothing(constraint: _OnConflictConstraintT = None, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None) → Self
指定 ON CONFLICT 子句的 DO NOTHING 操作。
constraint和index_elements参数是可选的，但只能指定其中之一。
参数：
constraint– 表上唯一或排除约束的名称，或者如果具有.name属性，则是约束对象本身。index_elements– 由字符串列名、Column对象或其他列表达式对象组成的序列，用于推断目标索引。index_where– 可用于推断条件目标索引的附加 WHERE 条件。
另请参阅
INSERT…ON CONFLICT（Upsert）
method on_conflict_do_update(constraint: _OnConflictConstraintT = None, index_elements: _OnConflictIndexElementsT = None, index_where: _OnConflictIndexWhereT = None, set_: _OnConflictSetT = None, where: _OnConflictWhereT = None) → Self
指定 ON CONFLICT 子句的 DO UPDATE SET 操作。
constraint或index_elements参数中的一个是必需的，但只能指定其中之一。
参数：
constraint– 表上唯一或排除约束的名称，或者如果它有 .name 属性，则是约束对象本身。index_elements– 由字符串列名、Column对象或其他列表达式对象组成的序列，将用于推断目标索引。index_where– 可以用于推断条件目标索引的附加 WHERE 条件。set_–
一个字典或其他映射对象，其中键要么是目标表中的列名，要么是与目标表匹配的Column对象或其他 ORM 映射的列，并且表达式或文字作为值，指定要执行的SET操作。
版本 1.4 中的新内容：Insert.on_conflict_do_update.set_参数支持来自目标Table的Column对象作为键。
警告
此字典不会考虑 Python 指定的默认 UPDATE 值或生成函数，例如那些使用Column.onupdate指定的值。这些值在执行 ON CONFLICT 风格的 UPDATE 时将不会被使用，除非它们在Insert.on_conflict_do_update.set_字典中手动指定。where– 可选参数。如果存在，则可以是文字 SQL 字符串或可接受的WHERE子句表达式，用于限制受DO UPDATE SET影响的行。不符合WHERE条件的行将不会被更新（实际上对于这些行是DO NOTHING）。
另请参见
插入…在冲突时执行（Upsert）
psycopg2
通过 psycopg2 驱动程序支持 PostgreSQL 数据库。
DBAPI
psycopg2 的文档和下载信息（如果适用）可在以下网址获取：pypi.org/project/psycopg2/
连接
连接字符串：
postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]
psycopg2 连接参数
可传递给 create_engine() 的特定于 SQLAlchemy psycopg2 方言的关键字参数包括以下内容：
isolation_level: 对于所有 PostgreSQL 方言都可用的选项，当使用 psycopg2 方言时，包括了AUTOCOMMIT隔离级别。此选项在连接到数据库时立即设置连接的默认隔离级别，然后连接被池化。这个选项通常被更现代的Connection.execution_options.isolation_level执行选项所取代，详见 设置事务隔离级别，包括 DBAPI 自动提交。
另请参见
Psycopg2 事务隔离级别
设置事务隔离级别，包括 DBAPI 自动提交client_encoding: 使用 psycopg2 的set_client_encoding()方法以 libpq 无关的方式设置客户端编码。
另请参见
Psycopg2 中的 Unicodeexecutemany_mode,executemany_batch_page_size,executemany_values_page_size: 允许使用 psycopg2 扩展来优化“executemany”风格的查询。有关详细信息，请参阅下面引用的部分。
另请参见
Psycopg2 快速执行助手
提示
上述关键字参数是方言关键字参数，意味着它们作为显式关键字参数传递给 create_engine():
engine = create_engine( "postgresql+psycopg2://scott:tiger@localhost/test", isolation_level="SERIALIZABLE", )
这些不应与DBAPI连接参数混淆，后者作为 create_engine.connect_args 字典的一部分传递，或者作为 URL 查询字符串传递，详见 自定义 DBAPI connect() 参数 / 连接时例程 部分。 ### SSL 连接
psycopg2 模块有一个名为 sslmode 的连接参数，用于控制其关于安全（SSL）连接的行为。默认值是 sslmode=prefer；它会尝试建立 SSL 连接，如果失败，则回退到未加密连接。sslmode=require 可用于确保仅建立安全连接。请参阅 psycopg2 / libpq 文档以获取更多可用选项。
注意，sslmode 是特定于 psycopg2 的，因此它包含在连接 URI 中：
engine = sa.create_engine( "postgresql+psycopg2://scott:tiger@192.168.0.199:5432/test?sslmode=require" )
Unix 域连接
psycopg2 支持通过 Unix 域连接进行连接。当 URL 的 host 部分被省略时，SQLAlchemy 会将 None 传递给 psycopg2，这指定了与 TCP/IP 通信相反的 Unix 域通信：
create_engine("postgresql+psycopg2://user:password@/dbname")
默认情况下，用于连接到 Unix 域套接字的套接字文件是 /tmp 中的 Unix 域套接字，或者在构建 PostgreSQL 时指定的套接字目录。可以通过向 psycopg2 传递路径名，并将 host 作为附加关键字参数来覆盖此值：
create_engine("postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql")
警告
此处接受的格式允许在主 URL 中还有一个主机名，除了“host”查询字符串参数之外。在使用此 URL 格式时，初始主机将被悄悄地忽略。也就是说，此 URL：
engine = create_engine("postgresql+psycopg2://user:password@myhost1/dbname?host=myhost2")
上面，主机名myhost1被悄悄地忽略和丢弃了。连接的主机是myhost2主机。
这是为了保持与 PostgreSQL 自己的 URL 格式的一定程度的兼容性，后者已经测试过可以以相同的方式运行，并且像 PifPaf 这样的工具会将两个主机名硬编码。
另请参阅
指定多个备用主机
psycopg2 支持在连接字符串中指定多个连接点。当在 URL 的查询部分中多次使用host参数时，SQLAlchemy 将创建一个包含提供的主机和端口信息的单个字符串以进行连接。令牌可以包含host::port或仅包含host；在后一种情况下，libpq 将选择默认端口。在下面的示例中，指定了三个主机连接，分别为HostA::PortA、连接到默认端口的HostB和HostC::PortC：
create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA:PortA&host=HostB&host=HostC:PortC" )
作为替代方案，也可以使用 libpq 查询字符串格式；这使用单个查询字符串参数指定host和port，其中逗号分隔的列表 - 可以通过在逗号分隔的列表中指定空值来选择默认端口：
create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA,HostB,HostC&port=PortA,,PortC" )
使用任何一种 URL 样式，根据可配置的策略尝试对每个主机进行连接，该策略可以使用 libpq target_session_attrs参数进行配置。根据 libpq，默认为any，表示然后尝试连接到每个主机，直到连接成功。其他策略包括primary、prefer-standby等。完整列表由 PostgreSQL 在libpq 连接字符串中记录。
例如，要使用primary策略指示两个主机：
create_engine( "postgresql+psycopg2://user:password@/dbname?host=HostA:PortA&host=HostB&host=HostC:PortC&target_session_attrs=primary" )
从 1.4.40 版本开始更改：psycopg2 多主机格式中的端口规范已修复，先前在此上下文中未正确解释端口。现在还支持 libpq 逗号分隔格式。
1.3.20 版本新增功能：支持在 PostgreSQL 连接字符串中指定多个主机。
另请参阅
libpq 连接字符串 - 请参考 libpq 文档中关于多主机支持的完整背景信息。
空 DSN 连接 / 环境变量连接
psycopg2 DBAPI 可以通过向 libpq 客户端库传递空 DSN 来连接到 PostgreSQL，默认情况下表示连接到一个开放了“trust”连接的本地主机 PostgreSQL 数据库。可以使用一组特定的以PG_...为前缀的环境变量来进一步调整此行为，这些环境变量由libpq消耗，以取代连接字符串的任何或所有元素。
对于这种形式，URL 可以在没有初始方案之外的任何元素的情况下传递：
engine = create_engine('postgresql+psycopg2://')
在上述形式中，一个空的“dsn”字符串被传递给psycopg2.connect()函数，这代表了传递给 libpq 的空 DSN。
新版本 1.3.2 中：支持使用 psycopg2 进行无参数连接。
另请参阅
环境变量 - PostgreSQL 文档介绍如何使用PG_...环境变量进行连接。
每个语句/连接执行选项
当与Connection.execution_options()、Executable.execution_options()、Query.execution_options()一起使用时，以下 DBAPI 特定选项将被尊重，除了那些不特定于 DBAPI 的选项：
isolation_level- 为Connection的生命周期设置事务隔离级别（只能在连接上设置，而不能在语句或查询上设置）。请参阅 Psycopg2 事务隔离级别。stream_results- 启用或禁用 psycopg2 服务器端游标的使用 - 此功能结合了“命名”游标和特殊结果处理方法，以便结果行不被完全缓冲。默认为 False，意味着游标默认情况下是被缓冲的。max_row_buffer- 在使用stream_results时，一个整数值，指定一次最大缓冲的行数。这由BufferedRowCursorResult解释，如果省略，缓冲区将最终增长到一次存储 1000 行。
从版本 1.4 开始：max_row_buffer大小现在可以大于 1000，并且缓冲区将增长到该大小。 ### Psycopg2 快速执行助手
现代版本的 psycopg2 包括一个名为快速执行助手，在基准测试中已经显示出可以将 psycopg2 的 executemany()性能提升至少一个数量级，主要是对 INSERT 语句的改进。
SQLAlchemy 实现了一种本地形式的“插入多个值”处理程序，它将重写单行 INSERT 语句，以适应在扩展 VALUES 子句中一次插入多个值；这个处理程序等同于 psycopg2 的execute_values()处理程序；关于此功能及其配置的概述在 INSERT 语句的“插入多个值”行为。
版本 2.0 中的新功能：使用称为 insertmanyvalues 的本机 SQLAlchemy 机制替换了 psycopg2 的execute_values()快速执行助手。
psycopg2 方言保留了使用 psycopg2 特定的execute_batch()功能的能力，尽管预计这不是一个广泛使用的功能。可以使用传递给create_engine()的executemany_mode标志来启用此扩展：
engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode='values_plus_batch')
executemany_mode的可能选项包括：
values_only- 默认值。假设create_engine.use_insertmanyvalues保持默认值True，SQLAlchemy 的本地 insertmanyvalues 处理程序用于为合格的 INSERT 语句添加参数，该处理程序将简单的 INSERT 语句重写为包含多个 VALUES 子句，以便一次插入多个参数集合的语句。'values_plus_batch'- 默认值。假设create_engine.use_insertmanyvalues保持默认值True，SQLAlchemy 的本地 insertmanyvalues 处理程序用于为合格的 INSERT 语句添加参数，然后，当使用多个参数集合执行 UPDATE 和 DELETE 语句时，将使用 psycopg2 的execute_batch()处理程序进行合格处理。使用此模式时，对 UPDATE 和 DELETE 语句执行的 executemany 样式执行将不会包含CursorResult.rowcount属性的值。
2.0 版本更改：从 psycopg2 的executemany_mode中删除了'batch'和'None'选项。现在，对于 INSERT 语句的批处理控制是通过create_engine.use_insertmanyvalues引擎级参数配置的。
“合格语句”一词指正在执行的语句是核心insert()、update()或delete()构造，并且不是普通的文本 SQL 字符串或使用text()构造的语句。它也可能不是特殊的“扩展”语句，如“ON CONFLICT”“upsert”语句。使用 ORM 时，ORM 刷新过程中使用的所有插入/更新/删除语句都是合格的。
psycopg2“批量”策略的“页面大小”可以通过使用executemany_batch_page_size参数来影响，默认为 100。
对于“insertmanyvalues”功能，可以使用create_engine.insertmanyvalues_page_size参数来控制页面大小，默认为 1000。下面是修改两个参数的示例：
engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode='values_plus_batch', insertmanyvalues_page_size=5000, executemany_batch_page_size=500)
另请参阅
INSERT 语句的“插入多个值”行为 - “插入多个值”的背景
发送多个参数 - 使用Connection对象执行语句的一般信息，以便利用 DBAPI 的.executemany()方法。### 使用 Psycopg2 进行 Unicode
psycopg2 DBAPI 驱动程序支持透明的 Unicode 数据。
可以通过以下方式控制 psycopg2 方言的客户端字符编码：
- 对于 PostgreSQL 9.1 及以上版本，
client_encoding参数可以在数据库 URL 中传递；此参数由底层的libpqPostgreSQL 客户端库使用：
engine = create_engine("postgresql+psycopg2://user:pass@host/dbname?client_encoding=utf8")
- 或者，上述
client_encoding值可以通过create_engine.connect_args传递给libpq进行编程建立连接：
engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname", connect_args={'client_encoding': 'utf8'} )
- 对于所有 PostgreSQL 版本，psycopg2 支持在首次建立数据库连接时传递的客户端端编码值。SQLAlchemy psycopg2 方言支持使用传递给
create_engine()的client_encoding参数：
engine = create_engine( "postgresql+psycopg2://user:pass@host/dbname", client_encoding="utf8" )
- 提示
上述client_encoding参数在外观上与在create_engine.connect_args字典中使用参数的方式非常相似；上述区别在于参数由 psycopg2 消耗，并使用SET client_encoding TO 'utf8'将其传递给数据库连接；在先前提到的样式中，参数通过 psycopg2 传递并由libpq库消耗。 - 在 PostgreSQL 数据库中设置客户端编码的常见方法是确保在服务器端的 postgresql.conf 文件中进行配置；这是为所有数据库一致使用一种编码设置编码的推荐方式：
# postgresql.conf file # client_encoding = sql_ascii # actually, defaults to database # encoding client_encoding = utf8
事务
psycopg2 方言完全支持 SAVEPOINT 和两阶段提交操作。
Psycopg2 事务隔离级别
如 事务隔离级别 中所讨论的，所有 PostgreSQL 方言都支持通过传递给 create_engine() 的 isolation_level 参数设置事务隔离级别，以及 Connection.execution_options() 使用的 isolation_level 参数。在使用 psycopg2 方言时，这些选项利用了 psycopg2 的 set_isolation_level() 连接方法，而不是发出 PostgreSQL 指令；这是因为无论如何，在每个事务开始时，psycopg2 的 API 级设置始终会被发出。
psycopg2 方言支持这些隔离级别的常量：
READ COMMITTEDREAD UNCOMMITTEDREPEATABLE READSERIALIZABLEAUTOCOMMIT
另请参阅
事务隔离级别
pg8000 事务隔离级别
注意日志记录
psycopg2 方言将通过 sqlalchemy.dialects.postgresql 记录 PostgreSQL NOTICE 消息。当此记录器设置为 logging.INFO 级别时，将记录注意消息：
import logging logging.getLogger('sqlalchemy.dialects.postgresql').setLevel(logging.INFO)
上面假定日志记录已在外部配置。如果不是这种情况，必须使用类似于 logging.basicConfig() 的配置：
import logging logging.basicConfig() # log messages to stdout logging.getLogger('sqlalchemy.dialects.postgresql').setLevel(logging.INFO)
另请参阅
日志指南 - 在 python.org 网站上
HSTORE 类型
psycopg2 DBAPI 包括一个扩展来原生处理 HSTORE 类型的编组。当使用 psycopg2 版本 2.4 或更高版本，并且检测到目标数据库设置了 HSTORE 类型以供使用时，SQLAlchemy psycopg2 方言将默认启用此扩展。换句话说，当方言建立第一个连接时，会执行以下序列：
- 使用
psycopg2.extras.HstoreAdapter.get_oids()请求可用的 HSTORE oids。如果此函数返回一个 HSTORE 标识符列表，则我们确定HSTORE扩展已存在。如果安装的 psycopg2 版本低于 2.4，则将跳过此函数。 - 如果
use_native_hstore标志处于其默认值True，并且我们已经检测到HSTOREoids 可用，那么对于所有连接，将调用psycopg2.extensions.register_hstore()扩展。
register_hstore() 扩展的效果是 所有 Python 字典都被接受为参数，而不管 SQL 中目标列的类型是什么。这些字典由此扩展转换为文本 HSTORE 表达式。如果不希望这种行为，可以通过将 use_native_hstore 设置为 False 来禁用 hstore 扩展：
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test", use_native_hstore=False)
当未使用psycopg2.extensions.register_hstore()扩展时，HSTORE类型仍然受支持。 这意味着 SQLAlchemy 自身的编组逻辑将在参数端和结果端都发生 Python 字典与 HSTORE 字符串格式之间的强制转换，并不是psycopg2的逻辑，后者可能性能更好。 ## psycopg
通过 psycopg（又名 psycopg 3）驱动程序支持 PostgreSQL 数据库。
DBAPI
有关 psycopg（又名 psycopg 3）的文档和下载信息可在此处获取：pypi.org/project/psycopg/
连接
连接字符串：
postgresql+psycopg://user:password@host:port/dbname[?key=value&key=value...]
psycopg 是版本 3 的 psycopg 数据库驱动程序的包和模块名称，以前称为 psycopg2。 这个驱动程序与其psycopg2前身有足够的不同，以至于 SQLAlchemy 通过完全不同的方言支持它；预计只要该软件包继续为现代 Python 版本提供支持，并且仍然是postgresql://方言系列的默认方言，就会继续支持psycopg2。
SQLAlchemy psycopg 方言在同一方言名称下提供同步和异步实现。 根据引擎创建方式选择正确的版本：
- 使用
postgresql+psycopg://...调用create_engine()将自动选择同步版本，例如：
from sqlalchemy import create_engine sync_engine = create_engine("postgresql+psycopg://scott:tiger@localhost/test")
- 使用
postgresql+psycopg://...调用create_async_engine()将自动选择异步版本，例如：
from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine("postgresql+psycopg://scott:tiger@localhost/test")
可以明确指定方言的 asyncio 版本，如下所示：
from sqlalchemy.ext.asyncio import create_async_engine asyncio_engine = create_async_engine("postgresql+psycopg_async://scott:tiger@localhost/test")
另请参见
psycopg2 - SQLAlchemy psycopg 方言与 psycopg2 方言大部分行为相同。 更多文档请参阅此处。
使用不同的 Cursor 类
psycopg和旧版本psycopg2之间的一个区别是如何处理绑定参数：psycopg2会在客户端绑定它们，而psycopg默认情况下会在服务器端绑定它们。
可以通过在创建引擎时指定cursor_factory为ClientCursor来配置psycopg以执行客户端绑定：
from psycopg import ClientCursor client_side_engine = create_engine( "postgresql+psycopg://...", connect_args={"cursor_factory": ClientCursor}, )
同样，使用异步引擎时，可以指定AsyncClientCursor：
from psycopg import AsyncClientCursor client_side_engine = create_async_engine( "postgresql+psycopg://...", connect_args={"cursor_factory": AsyncClientCursor}, )
另请参见
客户端绑定游标 ## pg8000
通过 pg8000 驱动程序支持 PostgreSQL 数据库。
DBAPI
有关 pg8000 的文档和下载信息（如果适用）可在此处获取：pypi.org/project/pg8000/
连接
连接字符串：
postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...]
1.4 版本中的更改：pg8000 方言已更新至 1.16.6 及更高版本，并再次成为 SQLAlchemy 与完整功能支持的持续集成的一部分。
Unicode
pg8000 将使用 PostgreSQL 的client_encoding参数在其与服务器之间对字符串值进行编码/解码；默认情况下，这是postgresql.conf文件中的值，通常默认为SQL_ASCII。通常可以将其更改为utf-8，作为更有用的默认值：
#client_encoding = sql_ascii # actually, defaults to database # encoding client_encoding = utf8
client_encoding可以通过执行以下 SQL 语句在会话中被覆盖：
SET CLIENT_ENCODING TO ‘utf8’;
SQLAlchemy 将根据传递给create_engine()的值在所有新连接上执行此 SQL，使用client_encoding参数：
engine = create_engine( "postgresql+pg8000://user:pass@host/dbname", client_encoding='utf8') ```### SSL 连接 pg8000 接受可以使用`create_engine.connect_args`字典指定的 Python `SSLContext`对象： ```py import ssl ssl_context = ssl.create_default_context() engine = sa.create_engine( "postgresql+pg8000://scott:tiger@192.168.0.199/test", connect_args={"ssl_context": ssl_context}, )
如果服务器使用自动生成的自签名证书或与主机名不匹配（从客户端看），可能还需要禁用主机名检查：
import ssl ssl_context = ssl.create_default_context() ssl_context.check_hostname = False ssl_context.verify_mode = ssl.CERT_NONE engine = sa.create_engine( "postgresql+pg8000://scott:tiger@192.168.0.199/test", connect_args={"ssl_context": ssl_context}, ) ```### pg8000 事务隔离级别 pg8000 方言提供与 psycopg2 方言相同的隔离级别设置： + `READ COMMITTED` + `READ UNCOMMITTED` + `REPEATABLE READ` + `SERIALIZABLE` + `AUTOCOMMIT` 另请参见 事务隔离级别 Psycopg2 事务隔离级别 ## asyncpg 通过 asyncpg 驱动程序支持 PostgreSQL 数据库。 ### DBAPI asyncpg 的文档和下载信息（如果适用）可在以下网址找到：[`magicstack.github.io/asyncpg/`](https://magicstack.github.io/asyncpg/) ### 连接 连接字符串： ```py postgresql+asyncpg://user:password@host:port/dbname[?key=value&key=value...]
asyncpg 方言是 SQLAlchemy 的第一个 Python asyncio 方言。
使用特殊的 asyncio 中介层，asyncpg 方言可用作 SQLAlchemy asyncio 扩展包的后端。
此方言通常仅应与create_async_engine()引擎创建函数一起使用：
from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("postgresql+asyncpg://user:pass@hostname/dbname")
1.4 版本中的新功能。
注意
默认情况下，asyncpg 不解码json和jsonb类型，并将它们作为字符串返回。SQLAlchemy 使用内置的json.loads函数为json和jsonb类型设置默认类型解码器。可以通过在使用create_engine()或create_async_engine()创建引擎时设置json_deserializer属性来更改所使用的 json 实现。
多主机连接
asyncpg 方言支持多个备用主机，与 psycopg2 和 psycopg 方言的方式相同。 语法相同，使用 host=: 组合作为额外的查询字符串参数；然而，没有默认端口，因此所有主机必须具有完整的端口号，否则将引发异常：
engine = create_async_engine( "postgresql+asyncpg://user:password@/dbname?host=HostA:5432&host=HostB:5432&host=HostC:5432" )
有关此语法的完整背景，请参阅 指定多个备用主机。
版本 2.0.18 中的新功能。
另请参见
指定多个备用主机 ### 准备语句缓存
asyncpg SQLAlchemy 方言对所有语句使用 asyncpg.connection.prepare()。 准备的语句对象在构造后被缓存，这似乎为语句调用提供了 10% 或更多的性能改进。 缓存是基于每个 DBAPI 连接的，这意味着准备语句的主要存储在连接池中的 DBAPI 连接内。 此缓存的大小默认为每个 DBAPI 连接 100 个语句，并且可以使用 prepared_statement_cache_size DBAPI 参数进行调整（请注意，虽然 SQLAlchemy 实现了此参数，但它是 asyncpg 方言的 DBAPI 模拟部分的一部分，因此将其处理为 DBAPI 参数，而不是方言参数）：
engine = create_async_engine("postgresql+asyncpg://user:pass@hostname/dbname?prepared_statement_cache_size=500")
要禁用准备语句缓存，请使用零值：
engine = create_async_engine("postgresql+asyncpg://user:pass@hostname/dbname?prepared_statement_cache_size=0")
版本 1.4.0b2 中的新功能：为 asyncpg 添加了 prepared_statement_cache_size。
警告
asyncpg 数据库驱动程序必须使用 PostgreSQL 类型 OID 的缓存，在通过 DDL 操作更改自定义 PostgreSQL 数据类型（如 ENUM 对象）时会变得过时。 此外，如上所述，由 SQLAlchemy 驱动程序可选缓存的准备语句本身在发出修改特定准备语句涉及的表或其他对象的 DDL 到 PostgreSQL 数据库时也可能变得“过时”。
SQLAlchemy 的 asyncpg 方言在本地进程中发出代表 DDL 的语句时将使这些缓存失效，但这仅在单个 Python 进程/数据库引擎中可控。 如果从其他数据库引擎和/或进程进行 DDL 更改，则正在运行的应用程序可能会遇到 InvalidCachedStatementError 和/或 InternalServerError("cache lookup failed for type ") 异常，如果它引用了之前的结构上操作的池化数据库连接。 SQLAlchemy 的 asyncpg 方言将在驱动程序引发这些异常时通过清除其内部缓存以及响应它们的 asyncpg 驱动程序的缓存来从这些错误情况中恢复，但如果缓存的准备语句或 asyncpg 类型缓存已过时，则无法防止它们首次引发，也无法在发生这些错误时重试语句，因为当这些错误发生时，PostgreSQL 事务将无效。 ### 使用 PGBouncer 的准备语句名称
默认情况下，asyncpg 按数字顺序枚举预处理语句，如果名称已被另一个预处理语句占用，则可能导致错误。如果您的应用程序使用数据库代理（如 PgBouncer）来处理连接，则可能会出现此问题。一个可能的解决方法是使用动态预处理语句名称，asyncpg 现在通过语句名称的可选 name 值支持此功能。这允许您生成自己的唯一名称，不会与现有名称冲突。为此，您可以提供一个函数，每次准备预处理语句时都会调用该函数：
from uuid import uuid4 engine = create_async_engine( "postgresql+asyncpg://user:pass@somepgbouncer/dbname", poolclass=NullPool, connect_args={ 'prepared_statement_name_func': lambda: f'__asyncpg_{uuid4()}__', }, )
另请参阅
github.com/MagicStack/asyncpg/issues/837
github.com/sqlalchemy/sqlalchemy/issues/6467
警告
在使用 PGBouncer 时，为了防止应用程序中无用的预处理语句的积累，重要的是使用 NullPool 池类，并配置 PgBouncer 在返回连接时使用 DISCARD。DISCARD 命令用于释放由数据库连接持有的资源，包括预处理语句。如果没有正确设置，预处理语句可能会迅速积累并导致性能问题。
禁用 PostgreSQL JIT 以改善 ENUM 数据类型处理
使用 PostgreSQL ENUM 数据类型时，asyncpg 存在一个 问题，在创建新的数据库连接时，可能会发出一个昂贵的查询，以检索有关自定义类型的元数据，这已被证明对性能产生负面影响。为了缓解这个问题，可以通过传递给 create_async_engine() 的设置来禁用客户端的 PostgreSQL “jit” 设置：
engine = create_async_engine( "postgresql+asyncpg://user:password@localhost/tmp", connect_args={"server_settings": {"jit": "off"}}, )
另请参阅
github.com/MagicStack/asyncpg/issues/727 ## psycopg2cffi
通过 psycopg2cffi 驱动程序支持 PostgreSQL 数据库。
DBAPI
psycopg2cffi 的文档和下载信息（如果适用）可在此处找到：pypi.org/project/psycopg2cffi/
连接
连接字符串：
postgresql+psycopg2cffi://user:password@host:port/dbname[?key=value&key=value...]
psycopg2cffi 是 psycopg2 的改编版本，使用 CFFI 作为 C 层。这使得它适用于例如 PyPy 的使用。文档与 psycopg2 相同。
另请参阅
sqlalchemy.dialects.postgresql.psycopg2
对 PostgreSQL 数据库的支持。
以下表格总结了当前数据库版本的支持级别。
支持的 PostgreSQL 版本
| 支持类型 | 版本 |
| 完全在 CI 中测试 | 12, 13, 14, 15 |
| Normal support | 9.6+ |
| Best effort | 9+ |
DBAPI 支持
以下方言/DBAPI 选项可用。请参阅各个 DBAPI 部分以获取连接信息。
- psycopg2
- psycopg（又名 psycopg 3）
- pg8000
- asyncpg
- psycopg2cffi
序列/SERIAL/IDENTITY
PostgreSQL 支持序列，并且 SQLAlchemy 将其作为创建基于整数的主键列的新主键值的默认方式。在创建表时，SQLAlchemy 会为整数型主键列发出SERIAL数据类型，这会生成一个序列和对应于该列的服务器端默认值。
要指定用于主键生成的特定命名序列，请使用Sequence()构造：
Table( "sometable", metadata, Column( "id", Integer, Sequence("some_id_seq", start=1), primary_key=True ) )
当 SQLAlchemy 发出单个 INSERT 语句以满足“最后插入标识符”可用的合同时，将在 INSERT 语句中添加一个 RETURNING 子句，该子句指定在语句完成后应返回主键列。仅当使用 PostgreSQL 8.2 或更高版本时，才会使用 RETURNING 功能。作为备用方法，不管是显式指定还是隐式通过SERIAL指定，序列都会提前独立执行，返回的值将用于后续插入。请注意，当使用“executemany”语义执行insert()构造时，“最后插入的标识符”功能不适用；在这种情况下，不会发出 RETURNING 子句，也不会预先执行序列。
PostgreSQL 10 及以上的 IDENTITY 列
PostgreSQL 10 及以上版本具有新的 IDENTITY 功能，取代了 SERIAL 的使用。在Column中的Identity构造可用于控制其行为：
from sqlalchemy import Table, Column, MetaData, Integer, Computed metadata = MetaData() data = Table( "data", metadata, Column( 'id', Integer, Identity(start=42, cycle=True), primary_key=True ), Column('data', String) )
以上Table对象的 CREATE TABLE 将是：
CREATE TABLE data ( id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 42 CYCLE), data VARCHAR, PRIMARY KEY (id) )
在 1.4 版本中更改：在Column中添加Identity构造以指定自增列的选项。
注意
以前的 SQLAlchemy 版本不具有内置的 IDENTITY 呈现支持，并且可以使用以下编译钩子来将 SERIAL 的出现替换为 IDENTITY：
from sqlalchemy.schema import CreateColumn from sqlalchemy.ext.compiler import compiles @compiles(CreateColumn, 'postgresql') def use_identity(element, compiler, **kw): text = compiler.visit_create_column(element, **kw) text = text.replace( "SERIAL", "INT GENERATED BY DEFAULT AS IDENTITY" ) return text
使用以上内容，类似以下的表：
t = Table( 't', m, Column('id', Integer, primary_key=True), Column('data', String) )
在后端数据库上将生成：
CREATE TABLE t ( id INT GENERATED BY DEFAULT AS IDENTITY, data VARCHAR, PRIMARY KEY (id) )
PostgreSQL 10 及以上版本的 IDENTITY 列
PostgreSQL 10 及以上版本具有一个新的 IDENTITY 功能，取代了 SERIAL 的使用。在Column中的Identity构造可以用来控制其行为：
from sqlalchemy import Table, Column, MetaData, Integer, Computed metadata = MetaData() data = Table( "data", metadata, Column( 'id', Integer, Identity(start=42, cycle=True), primary_key=True ), Column('data', String) )
上述Table对象的 CREATE TABLE 将是：
CREATE TABLE data ( id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 42 CYCLE), data VARCHAR, PRIMARY KEY (id) )
从版本 1.4 开始更改：在Column中添加了Identity构造，以指定自动递增列的选项。
注意
SQLAlchemy 的旧版本没有内置支持 IDENTITY 的渲染，可以使用以下编译钩子来将 SERIAL 替换为 IDENTITY：
from sqlalchemy.schema import CreateColumn from sqlalchemy.ext.compiler import compiles @compiles(CreateColumn, 'postgresql') def use_identity(element, compiler, **kw): text = compiler.visit_create_column(element, **kw) text = text.replace( "SERIAL", "INT GENERATED BY DEFAULT AS IDENTITY" ) return text
使用上述内容，一个表如下：
t = Table( 't', m, Column('id', Integer, primary_key=True), Column('data', String) )
在后端数据库上生成如下内容：
CREATE TABLE t ( id INT GENERATED BY DEFAULT AS IDENTITY, data VARCHAR, PRIMARY KEY (id) )
服务器端游标
psycopg2、asyncpg 方言支持服务器端游标，并且可能也适用于其他方言。
通过使用Connection.execution_options.stream_results连接执行选项，可以在每个语句基础上启用服务器端游标：
with engine.connect() as conn: result = conn.execution_options(stream_results=True).execute(text("select * from table"))
请注意，某些类型的 SQL 语句可能不支持服务器端游标；通常，只有返回行的 SQL 语句应与此选项一起使用。
从版本 1.4 开始弃用：dialect 级别的 server_side_cursors 标志已弃用，并将在将来的版本中删除。请使用Connection.stream_results执行选项以支持无缓冲游标。
另请参阅
使用服务器端游标（也称为流式结果）
SqlAlchemy 2.0 中文文档（四十八）（3）https://developer.aliyun.com/article/1563009
