SqlAlchemy 2.0 中文文档（四十八）（4）https://developer.aliyun.com/article/1563010
PostgreSQL SQL 元素和函数
| 对象名称 | 描述 |
| aggregate_order_by | 表示 PostgreSQL 聚合排序表达式。 |
| All(other, arrexpr[, operator]) | 是 Comparator.all() 方法在数组层面的同义词。详情请参阅该方法。 |
| Any(other, arrexpr[, operator]) | 是 Comparator.any() 方法在数组层面的同义词。详情请参阅该方法。 |
| array | 一个 PostgreSQL 数组字面量。 |
| array_agg(*arg, **kw) | PostgreSQL 特定形式的 array_agg，确保返回类型是 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 聚合排序表达式。
例如：
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
类签名
class sqlalchemy.dialects.postgresql.array (sqlalchemy.sql.expression.ExpressionClauseList)
function sqlalchemy.dialects.postgresql.array_agg(*arg, **kw)
PostgreSQL 特定形式的array_agg，确保返回类型为ARRAY而不是普通的ARRAY，除非传递了显式的type_。
function sqlalchemy.dialects.postgresql.Any(other, arrexpr, operator=<built-in function eq>)
一个 ARRAY 级别的Comparator.any()方法的同义词。有关详细信息，请参阅该方法。
function sqlalchemy.dialects.postgresql.All(other, arrexpr, operator=<built-in function eq>)
ARRAY 级别的Comparator.all()方法的同义词。有关详细信息，请参阅该方法。
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
类签名
class sqlalchemy.dialects.postgresql.hstore (sqlalchemy.sql.functions.GenericFunction)
attribute inherit_cache: bool | None = True
指示此HasCacheKey实例是否应该使用其直接超类使用的缓存键生成方案。
该属性默认为None，表示构造尚未考虑是否适合参与缓存；这在功能上等同于将值设置为False，只是还会发出警告。
如果与此类本地属性而不是其超类有关的属性不会更改对象对应的 SQL，则可以在特定类上将此标志设置为True。
另请参阅
为自定义构造启用缓存支持](…/core/compiler.html#compilerext-caching) - 为第三方或用户定义的 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 字符串参数传递，该参数将被视为受信任的 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
PostgreSQL 特定的 INSERT 实现。
添加了针对 PG 特定语法的方法，例如 ON CONFLICT。
Insert 对象是使用 sqlalchemy.dialects.postgresql.insert() 函数创建的。
成员
排除, 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）。
另请参阅
INSERT…ON CONFLICT（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：以与 libpq 无关的方式设置客户端编码，使用 psycopg2 的set_client_encoding()方法。
另请参见
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，这指定了 Unix 域通信而不是 TCP/IP 通信：
create_engine("postgresql+psycopg2://user:password@/dbname")
默认情况下，用于连接到 Unix 域套接字的套接字文件位于 /tmp 中，或者在构建 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 可以通过将空 DSN 传递给 libpq 客户端库来连接到 PostgreSQL，默认情况下表示连接到打开“信任”连接的本地主机 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 版本中的新功能：用本机 SQLAlchemy 机制 insertmanyvalues 替换了 psycopg2 的execute_values()快速执行助手。
psycopg2 方言保留了使用 psycopg2 特定的execute_batch()功能的能力，尽管不太可能广泛使用此功能。可以使用executemany_mode标志启用此扩展，该标志可以传递给create_engine()：
engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode='values_plus_batch')
executemany_mode的可能选项包括：
values_only- 这是默认值。SQLAlchemy 的本机 insertmanyvalues 处理程序用于限定 INSERT 语句，假设create_engine.use_insertmanyvalues保持默认值True。该处理程序重写简单的 INSERT 语句，以包含多个 VALUES 子句，以便可以使用一个语句插入多个参数集。'values_plus_batch'- SQLAlchemy 的本机 insertmanyvalues 处理程序用于限定 INSERT 语句，假设create_engine.use_insertmanyvalues保持默认值True。然后，当使用多个参数集执行 UPDATE 和 DELETE 语句时，使用 psycopg2 的execute_batch()处理程序进行限定。在使用此模式时，CursorResult.rowcount属性将不会包含对 UPDATE 和 DELETE 语句进行 executemany-style 执行的行数。
2.0 版本中的更改：从 psycopg2 的executemany_mode中删除了'batch'和'None'选项。现在，INSERT 语句的批处理控制是通过create_engine.use_insertmanyvalues引擎级参数配置的。
“限定语句”一词指的是正在执行的语句是一个 Core insert()、update()或delete()构造，而不是一个简单的文本 SQL 字符串或使用text()构造的字符串。它也可能不是一个特殊的“扩展”语句，比如“ON CONFLICT”“upsert”语句。在使用 ORM 时，ORM 刷新过程中使用的所有插入/更新/删除语句都是限定的。
使用 executemany_batch_page_size 参数可以影响 psycopg2 的 “batch” 策略的 “页面大小”，默认为 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 Many Values” Behavior for INSERT statements - 关于“insertmanyvalues”的背景信息
发送多个参数 - 关于使用 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 字典都被接受为参数，无论目标列的类型是什么。这些字典由此扩展转换为文本 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的编组逻辑，后者可能更有效率。
DBAPI
psycopg2 的文档和下载信息（如适用）可在此处获取：pypi.org/project/psycopg2/
连接
Connect String:
postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]
psycopg2 连接参数
与 SQLAlchemy psycopg2 方言特定的关键字参数可以传递给create_engine()，包括以下内容：
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，这指定了 Unix 域通信而不是 TCP/IP 通信：
create_engine("postgresql+psycopg2://user:password@/dbname")
默认情况下，用于连接的套接字文件是连接到 Unix 域套接字的/tmp，或者在构建 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”连接的 localhost PostgreSQL 数据库。这种行为可以通过一组特定的环境变量进一步定制，这些环境变量以 PG_... 为前缀，并由 libpq 使用，以取代连接字符串的任何或所有元素。
对于此形式，URL 可以在没有除了初始方案之外的任何元素的情况下传递：
engine = create_engine('postgresql+psycopg2://')
在上述形式中，将空的“dsn”字符串传递给psycopg2.connect()函数，该函数反过来表示传递给 libpq 的空 DSN。
1.3.2 版中的新功能：支持与 psycopg2 无参数连接。
另请参见
环境变量 - 有关如何使用 PG_... 环境变量进行连接的 PostgreSQL 文档。
每条语句 / 连接执行选项
当与 Connection.execution_options()、Executable.execution_options()、Query.execution_options() 一起使用时，以下 DBAPI 特定选项也会被尊重，除了那些不特定于 DBAPI 的选项：
isolation_level- 设置Connection的事务隔离级别的寿命（只能在连接上设置，而不是在语句或查询上设置）。参见 Psycopg2 事务隔离级别。
emy 实现了一种原生形式的“插入多个值”处理程序，它会重写单行的 INSERT 语句以适应一次在扩展的 VALUES 子句中插入多个值；此处理程序相当于 psycopg2 的 execute_values() 处理程序；有关此功能及其配置的概述在 “插入多个值”行为对于 INSERT 语句。
2.0 版本中的新功能：用本机 SQLAlchemy 机制 insertmanyvalues 替换了 psycopg2 的execute_values()快速执行助手。
psycopg2 方言保留了使用 psycopg2 特定的execute_batch()功能的能力，尽管不太可能广泛使用此功能。可以使用executemany_mode标志启用此扩展，该标志可以传递给create_engine()：
engine = create_engine( "postgresql+psycopg2://scott:tiger@host/dbname", executemany_mode='values_plus_batch')
executemany_mode的可能选项包括：
values_only- 这是默认值。SQLAlchemy 的本机 insertmanyvalues 处理程序用于限定 INSERT 语句，假设create_engine.use_insertmanyvalues保持默认值True。该处理程序重写简单的 INSERT 语句，以包含多个 VALUES 子句，以便可以使用一个语句插入多个参数集。'values_plus_batch'- SQLAlchemy 的本机 insertmanyvalues 处理程序用于限定 INSERT 语句，假设create_engine.use_insertmanyvalues保持默认值True。然后，当使用多个参数集执行 UPDATE 和 DELETE 语句时，使用 psycopg2 的execute_batch()处理程序进行限定。在使用此模式时，CursorResult.rowcount属性将不会包含对 UPDATE 和 DELETE 语句进行 executemany-style 执行的行数。
2.0 版本中的更改：从 psycopg2 的executemany_mode中删除了'batch'和'None'选项。现在，INSERT 语句的批处理控制是通过create_engine.use_insertmanyvalues引擎级参数配置的。
“限定语句”一词指的是正在执行的语句是一个 Core insert()、update()或delete()构造，而不是一个简单的文本 SQL 字符串或使用text()构造的字符串。它也可能不是一个特殊的“扩展”语句，比如“ON CONFLICT”“upsert”语句。在使用 ORM 时，ORM 刷新过程中使用的所有插入/更新/删除语句都是限定的。
使用 executemany_batch_page_size 参数可以影响 psycopg2 的 “batch” 策略的 “页面大小”，默认为 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 Many Values” Behavior for INSERT statements - 关于“insertmanyvalues”的背景信息
发送多个参数 - 关于使用 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 字典都被接受为参数，无论目标列的类型是什么。这些字典由此扩展转换为文本 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的编组逻辑，后者可能更有效率。
DBAPI
psycopg2 的文档和下载信息（如适用）可在此处获取：pypi.org/project/psycopg2/
连接
Connect String:
postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]
psycopg2 连接参数
与 SQLAlchemy psycopg2 方言特定的关键字参数可以传递给create_engine()，包括以下内容：
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，这指定了 Unix 域通信而不是 TCP/IP 通信：
create_engine("postgresql+psycopg2://user:password@/dbname")
默认情况下，用于连接的套接字文件是连接到 Unix 域套接字的/tmp，或者在构建 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”连接的 localhost PostgreSQL 数据库。这种行为可以通过一组特定的环境变量进一步定制，这些环境变量以 PG_... 为前缀，并由 libpq 使用，以取代连接字符串的任何或所有元素。
对于此形式，URL 可以在没有除了初始方案之外的任何元素的情况下传递：
engine = create_engine('postgresql+psycopg2://')
在上述形式中，将空的“dsn”字符串传递给psycopg2.connect()函数，该函数反过来表示传递给 libpq 的空 DSN。
1.3.2 版中的新功能：支持与 psycopg2 无参数连接。
另请参见
环境变量 - 有关如何使用 PG_... 环境变量进行连接的 PostgreSQL 文档。
每条语句 / 连接执行选项
当与 Connection.execution_options()、Executable.execution_options()、Query.execution_options() 一起使用时，以下 DBAPI 特定选项也会被尊重，除了那些不特定于 DBAPI 的选项：
isolation_level- 设置Connection的事务隔离级别的寿命（只能在连接上设置，而不是在语句或查询上设置）。参见 Psycopg2 事务隔离级别。stream_results- 启用或禁用 psycopg2 服务器端游标的使用 - 此功能结合了“命名”游标和特殊的结果处理方法，以便结果
