Support for the PostgreSQL database.
The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.
PostgreSQL支持序列,SQLAlchemy使用这些作为为基于整数的主键列创建新主键值的默认方法。创建表时,SQLAlchemy将发出 SERIAL
基于整数的主键列的数据类型,它生成与该列对应的序列和服务器端默认值。
要指定用于生成主键的特定命名序列,请使用 Sequence()
结构:
Table('sometable', metadata,
Column('id', Integer, Sequence('some_id_seq'), primary_key=True)
)
当sqlAlchemy发出单个insert语句时,为了满足“last insert identifier”可用的约定,在insert语句中添加了一个返回子句,指定在语句完成后应返回主键列。返回功能仅在使用PostgreSQL 8.2或更高版本时发生。作为回退方法,序列,无论是通过 SERIAL
,是预先独立执行的,返回的值将在随后的插入中使用。注意,当 insert()
使用“ExecuteMany”语义执行构造,不应用“Last Inserted Identifier”功能;不会发出返回子句,在这种情况下也不会预先执行序列。
若要强制使用默认返回,请指定标志 implicit_returning=False
到 create_engine()
.
PostgreSQL 10有一个新的标识功能,取代了串行的使用。尚未提供用于呈现标识的内置支持,但是可以使用以下编译挂钩将出现的序列替换为标识:
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 NOT NULL,
data VARCHAR,
PRIMARY KEY (id)
)
所有PostgreSQL方言都支持通过方言特定参数设置事务隔离级别。 create_engine.isolation_level
被接受 create_engine()
以及 Connection.execution_options.isolation_level
传递给的参数 Connection.execution_options()
. 使用非psycopg2方言时,此功能通过发出命令来工作 SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level>
对于每个新连接。对于特殊的自动提交隔离级别,使用DBAPI特定的技术。
要设置隔离级别,请使用 create_engine()
::
engine = create_engine(
"postgresql+pg8000://scott:tiger@localhost/test",
isolation_level="READ UNCOMMITTED"
)
使用每个连接执行选项进行设置:
connection = engine.connect()
connection = connection.execution_options(
isolation_level="READ COMMITTED"
)
的有效值 isolation_level
包括:
READ COMMITTED
READ UNCOMMITTED
REPEATABLE READ
SERIALIZABLE
AUTOCOMMIT
-仅在psycopg2/pg8000上
TL;DR; 保持 search_path
变量设置为默认值 public
命名模式 其他 比 public
明确在 Table
定义。
PostgreSQL方言可以反映任何模式中的表。这个 Table.schema
争论,或者 MetaData.reflect.schema
参数确定要搜索表的架构。反映出来的 Table
在任何情况下,对象都将保留此 .schema
指定的属性。但是,关于这些 Table
对象通过外键约束引用,必须决定 .schema
在这些远程表中表示,如果该远程架构名称也是当前的 PostgreSQL search path .
默认情况下,PostgreSQL方言模仿PostgreSQL自己鼓励的行为。 pg_get_constraintdef()
内置程序。此函数返回特定外键约束的示例定义,当该名称也在PostgreSQL模式搜索路径中时,省略该定义中引用的架构名称。下面的交互说明了这种行为:
test=> CREATE TABLE test_schema.referred(id INTEGER PRIMARY KEY);
CREATE TABLE
test=> CREATE TABLE referring(
test(> id INTEGER PRIMARY KEY,
test(> referred_id INTEGER REFERENCES test_schema.referred(id));
CREATE TABLE
test=> SET search_path TO public, test_schema;
test=> SELECT pg_catalog.pg_get_constraintdef(r.oid, true) FROM
test-> pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n
test-> ON n.oid = c.relnamespace
test-> JOIN pg_catalog.pg_constraint r ON c.oid = r.conrelid
test-> WHERE c.relname='referring' AND r.contype = 'f'
test-> ;
pg_get_constraintdef
---------------------------------------------------
FOREIGN KEY (referred_id) REFERENCES referred(id)
(1 row)
上面,我们创建了一个表 referred
作为远程架构的成员 test_schema
但是,当我们添加 test_schema
到PG search_path
然后问 pg_get_constraintdef()
对于 FOREIGN KEY
语法, test_schema
未包含在函数的输出中。
另一方面,如果我们将搜索路径设置回 public
::
test=> SET search_path TO public;
SET
相同的查询 pg_get_constraintdef()
现在为我们返回完全模式限定名::
test=> SELECT pg_catalog.pg_get_constraintdef(r.oid, true) FROM
test-> pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n
test-> ON n.oid = c.relnamespace
test-> JOIN pg_catalog.pg_constraint r ON c.oid = r.conrelid
test-> WHERE c.relname='referring' AND r.contype = 'f';
pg_get_constraintdef
---------------------------------------------------------------
FOREIGN KEY (referred_id) REFERENCES test_schema.referred(id)
(1 row)
默认情况下,SQLAlchemy将使用 pg_get_constraintdef()
以确定远程架构名称。也就是说,如果我们 search_path
设置为包括 test_schema
,我们调用了一个表反射过程,如下所示:
>>> from sqlalchemy import Table, MetaData, create_engine
>>> engine = create_engine("postgresql://scott:tiger@localhost/test")
>>> with engine.connect() as conn:
... conn.execute("SET search_path TO test_schema, public")
... meta = MetaData()
... referring = Table('referring', meta,
... autoload=True, autoload_with=conn)
...
<sqlalchemy.engine.result.ResultProxy object at 0x101612ed0>
上述流程将交付给 MetaData.tables
收集 referred
表命名 没有 模式:
>>> meta.tables['referred'].schema is None
True
改变反射的行为,使所引用的模式保持不变,而不管 search_path
设置,使用 postgresql_ignore_search_path
选项,可以将其指定为 Table
以及 MetaData.reflect()
::
>>> with engine.connect() as conn:
... conn.execute("SET search_path TO test_schema, public")
... meta = MetaData()
... referring = Table('referring', meta, autoload=True,
... autoload_with=conn,
... postgresql_ignore_search_path=True)
...
<sqlalchemy.engine.result.ResultProxy object at 0x1016126d0>
我们现在就要 test_schema.referred
存储为架构限定::
>>> meta.tables['test_schema.referred'].schema
'test_schema'
注意 在所有情况下 “默认”模式始终反映为 None
. PostgreSQL上的“默认”模式是PostgreSQL返回的模式。 current_schema()
功能。在典型的PostgreSQL安装中,这是 public
. 所以一个表引用了 public
(即默认)模式将始终具有 .schema
属性设置为 None
.
0.9.2 新版功能: 增加了 postgresql_ignore_search_path
方言级别选项被接受 Table
和 MetaData.reflect()
.
参见
The Schema Search Path -在PostgreSQL网站上。
方言支持第8.2页 INSERT..RETURNING
, UPDATE..RETURNING
和 DELETE..RETURNING
句法。 INSERT..RETURNING
默认情况下用于单行insert语句,以便获取新生成的主键标识符。指定显式 RETURNING
子句,使用 _UpdateBase.returning()
每个语句的方法:
# INSERT..RETURNING
result = table.insert().returning(table.c.col1, table.c.col2).\
values(name='foo')
print result.fetchall()
# UPDATE..RETURNING
result = table.update().returning(table.c.col1, table.c.col2).\
where(table.c.name=='foo').values(name='bar')
print result.fetchall()
# DELETE..RETURNING
result = table.delete().returning(table.c.col1, table.c.col2).\
where(table.c.name=='foo')
print result.fetchall()
从9.5版开始,PostgreSQL允许通过 ON CONFLICT
条款 INSERT
语句。只有当候选行不违反任何唯一约束时,才会插入该行。在违反唯一约束的情况下,可能会发生第二个操作,该操作可以是“do update”(执行更新),表示应更新目标行中的数据,也可以是“do nothing”(不执行任何操作),表示静默跳过此行。
使用现有的唯一约束和索引来确定冲突。这些约束可以使用DDL中指定的名称来标识,也可以是 推断 通过说明包含索引的列和条件。
SQLAlchemy提供 ON CONFLICT
通过特定于PostgreSQL的支持 postgresql.dml.insert()
函数,提供生成方法 on_conflict_do_update()
和 on_conflict_do_nothing()
::
from sqlalchemy.dialects.postgresql import insert
insert_stmt = insert(my_table).values(
id='some_existing_id',
data='inserted value')
do_nothing_stmt = insert_stmt.on_conflict_do_nothing(
index_elements=['id']
)
conn.execute(do_nothing_stmt)
do_update_stmt = insert_stmt.on_conflict_do_update(
constraint='pk_my_table',
set_=dict(data='updated value')
)
conn.execute(do_update_stmt)
这两种方法都使用命名约束或列推理来提供冲突的“目标”:
这个 Insert.on_conflict_do_update.index_elements
参数指定包含字符串列名的序列, Column
对象和/或SQL表达式元素,它们将标识唯一索引::
do_update_stmt = insert_stmt.on_conflict_do_update(
index_elements=['id'],
set_=dict(data='updated value')
)
do_update_stmt = insert_stmt.on_conflict_do_update(
index_elements=[my_table.c.id],
set_=dict(data='updated value')
)
使用时 Insert.on_conflict_do_update.index_elements
要推断索引,还可以通过指定使用 Insert.on_conflict_do_update.index_where
参数::
from sqlalchemy.dialects.postgresql import insert
stmt = insert(my_table).values(user_email='a@b.com', data='inserted data')
stmt = stmt.on_conflict_do_update(
index_elements=[my_table.c.user_email],
index_where=my_table.c.user_email.like('%@gmail.com'),
set_=dict(data=stmt.excluded.data)
)
conn.execute(stmt)
这个 Insert.on_conflict_do_update.constraint
参数用于直接指定索引,而不是推断索引。这可以是唯一约束、主键约束或索引的名称:
do_update_stmt = insert_stmt.on_conflict_do_update(
constraint='my_table_idx_1',
set_=dict(data='updated value')
)
do_update_stmt = insert_stmt.on_conflict_do_update(
constraint='my_table_pk',
set_=dict(data='updated value')
)
这个 Insert.on_conflict_do_update.constraint
参数还可以引用表示约束的sqlAlchemy构造,例如 UniqueConstraint
, PrimaryKeyConstraint
, Index
或 ExcludeConstraint
. 在这种用法中,如果约束有名称,则直接使用它。否则,如果约束未命名,则将使用推理,其中表达式和约束的可选WHERE子句将在构造中拼写出来。这种用法特别方便地引用 Table
使用 Table.primary_key
属性:
do_update_stmt = insert_stmt.on_conflict_do_update(
constraint=my_table.primary_key,
set_=dict(data='updated value')
)
ON CONFLICT...DO UPDATE
用于执行已存在行的更新,使用新值和建议插入的值的任意组合。这些值是使用 Insert.on_conflict_do_update.set_
参数。此参数接受包含要更新的直接值的字典::
from sqlalchemy.dialects.postgresql import insert
stmt = insert(my_table).values(id='some_id', data='inserted value')
do_update_stmt = stmt.on_conflict_do_update(
index_elements=['id'],
set_=dict(data='updated value')
)
conn.execute(do_update_stmt)
警告
这个 Insert.on_conflict_do_update()
方法做 not 考虑到python端的默认更新值或生成函数,例如使用 Column.onupdate
. 除非在 Insert.on_conflict_do_update.set_
字典。
为了引用建议的插入行,特殊别名 excluded
在上作为属性提供 postgresql.dml.Insert
对象;此对象是 ColumnCollection
哪个别名包含目标表的所有列::
from sqlalchemy.dialects.postgresql import insert
stmt = insert(my_table).values(
id='some_id',
data='inserted value',
author='jlh')
do_update_stmt = stmt.on_conflict_do_update(
index_elements=['id'],
set_=dict(data='updated value', author=stmt.excluded.author)
)
conn.execute(do_update_stmt)
这个 Insert.on_conflict_do_update()
方法还接受使用 Insert.on_conflict_do_update.where
参数,它将限制接收更新的行:
from sqlalchemy.dialects.postgresql import insert
stmt = insert(my_table).values(
id='some_id',
data='inserted value',
author='jlh')
on_update_stmt = stmt.on_conflict_do_update(
index_elements=['id'],
set_=dict(data='updated value', author=stmt.excluded.author)
where=(my_table.c.status == 2)
)
conn.execute(on_update_stmt)
ON CONFLICT
如果与唯一约束或排除约束发生冲突,也可用于跳过完全插入行;下面使用 on_conflict_do_nothing()
方法:
from sqlalchemy.dialects.postgresql import insert
stmt = insert(my_table).values(id='some_id', data='inserted value')
stmt = stmt.on_conflict_do_nothing(index_elements=['id'])
conn.execute(stmt)
如果 DO NOTHING
在不指定任何列或约束的情况下使用,它的作用是跳过插入,以避免出现任何唯一或排除约束冲突:
from sqlalchemy.dialects.postgresql import insert
stmt = insert(my_table).values(id='some_id', data='inserted value')
stmt = stmt.on_conflict_do_nothing()
conn.execute(stmt)
1.1 新版功能: 增加了对冲突子句的PostgreSQL支持
参见
INSERT .. ON CONFLICT -在PostgreSQL文档中。
SQLAlchemy提供PostgreSQL @@
操作符通过 ColumnElement.match()
任何文本列表达式的方法。在PostgreSQL方言中,有如下表达式:
select([sometable.c.text.match("search string")])
将发送到数据库::
SELECT text @@ to_tsquery('search string') FROM table
PostgreSQL文本搜索功能,例如 to_tsquery()
和 to_tsvector()
明确使用标准 func
构建。例如::
select([
func.to_tsvector('fat cats ate rats').match('cat & rat')
])
发射相当于:
SELECT to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')
这个 postgresql.TSVECTOR
类型不能提供显式强制转换::
from sqlalchemy.dialects.postgresql import TSVECTOR
from sqlalchemy import select, cast
select([cast("some text", TSVECTOR)])
生成等价于以下内容的语句:
SELECT CAST('some text' AS TSVECTOR) AS anon_1
PostgreSQL中的全文搜索受以下组合的影响:PostgreSQL设置 default_text_search_config
, the regconfig
用于构建GIN/GIST索引,以及 regconfig
在查询期间可选传入。
当对已经预先计算了GIN或GIST索引(在全文搜索中很常见)的列执行全文搜索时,可能需要显式传递特定的PostgreSQL regconfig
值以确保查询规划器使用索引,并且不会根据需要重新计算列。
为了提供这种明确的查询计划,或者使用不同的搜索策略,可以使用 match
方法接受 postgresql_regconfig
关键字参数:
select([mytable.c.id]).where(
mytable.c.title.match('somestring', postgresql_regconfig='english')
)
发射相当于:
SELECT mytable.id FROM mytable
WHERE mytable.title @@ to_tsquery('english', 'somestring')
你也可以通过 'regconfig' 价值 to_tsvector()
作为初始参数的命令:
select([mytable.c.id]).where(
func.to_tsvector('english', mytable.c.title )\
.match('somestring', postgresql_regconfig='english')
)
生成等价于以下内容的语句:
SELECT mytable.id FROM mytable
WHERE to_tsvector('english', mytable.title) @@
to_tsquery('english', 'somestring')
建议您使用 EXPLAIN ANALYZE...
PostgreSQL中的工具,以确保使用sqlAlchemy生成的查询充分利用了为全文搜索创建的任何索引。
方言支持PostgreSQL的唯一关键字,只针对继承层次结构中的特定表。这可用于生产 SELECT ... FROM ONLY
, UPDATE ONLY ...
, and DELETE FROM ONLY ...
句法。它使用sqlAlchemy的提示机制:
# SELECT ... FROM ONLY ...
result = table.select().with_hint(table, 'ONLY', 'postgresql')
print result.fetchall()
# UPDATE ONLY ...
table.update(values=dict(foo='bar')).with_hint('ONLY',
dialect_name='postgresql')
# DELETE FROM ONLY ...
table.delete().with_hint('ONLY', dialect_name='postgresql')
对 Index
构造是可用的,特定于PostgreSQL方言。
部分索引向索引定义添加条件,以便将索引应用于行的子集。这些可以在上指定 Index
使用 postgresql_where
关键字参数:
Index('my_index', my_table.c.id, postgresql_where=my_table.c.value > 10)
PostgreSQL允许指定 运算符类 对于索引的每一列(请参见http://www.postgresql.org/docs/8.3/interactive/indexes opclass.html)。这个 Index
构造允许通过 postgresql_ops
关键字参数:
Index(
'my_index', my_table.c.id, my_table.c.data,
postgresql_ops={
'data': 'text_pattern_ops',
'id': 'int4_ops'
})
请注意 postgresql_ops
字典是 Column
,即用于从 .c
收藏 Table
,可以将其配置为与数据库中表示的列的实际名称不同。
如果 postgresql_ops
要用于复杂的SQL表达式(如函数调用),然后要应用于该列,必须为该列提供一个标签,该标签在字典中按名称标识,例如::
Index(
'my_index', my_table.c.id,
func.lower(my_table.c.data).label('data_lower'),
postgresql_ops={
'data_lower': 'text_pattern_ops',
'id': 'int4_ops'
})
PostgreSQL提供了几种索引类型:B-Tree、哈希、GIST和GIN,以及用户创建自己的索引的能力(请参见http://www.postgresql.org/docs/8.3/static/indexes types.html)。这些可以在上指定 Index
使用 postgresql_using
关键字参数:
Index('my_index', my_table.c.data, postgresql_using='gin')
传递给关键字参数的值将简单地传递给底层的create index命令,因此 must 为您的PostgreSQL版本提供有效的索引类型。
PostgreSQL允许对索引设置存储参数。可用的存储参数取决于索引使用的索引方法。可以在上指定存储参数 Index
使用 postgresql_with
关键字参数:
Index('my_index', my_table.c.data, postgresql_with={"fillfactor": 50})
1.0.6 新版功能.
PostgreSQL允许定义创建索引的表空间。可以在上指定表空间 Index
使用 postgresql_tablespace
关键字参数:
Index('my_index', my_table.c.data, postgresql_tablespace='my_tablespace')
1.1 新版功能.
请注意,相同的选项在上可用 Table
也。
传递标志同时支持PostgreSQL索引选项 postgresql_concurrently
到 Index
结构:
tbl = Table('testtbl', m, Column('data', Integer))
idx1 = Index('test_idx1', tbl.c.data, postgresql_concurrently=True)
如果检测到PostgreSQL 8.2或更高版本,或者检测到无连接方言,上述索引结构将为create index呈现DDL,如下所示:
CREATE INDEX CONCURRENTLY test_idx1 ON testtbl (data)
对于drop index,假设检测到PostgreSQL 9.2或更高版本,或者对于无连接的方言,它将发出:
DROP INDEX CONCURRENTLY test_idx1
1.1 新版功能: 支持同时删除索引。只有在连接上检测到足够高的PostgreSQL版本(或对于无连接方言)时,才会发出concurrent关键字。
同时使用时,PostgreSQL数据库要求在事务块之外调用该语句。python dbapi强制即使对于单个语句,也存在事务,因此要使用此构造,必须使用dbapi的“autocommit”模式:
metadata = MetaData()
table = Table(
"foo", metadata,
Column("id", String))
index = Index(
"foo_idx", table.c.id, postgresql_concurrently=True)
with engine.connect() as conn:
with conn.execution_options(isolation_level='AUTOCOMMIT'):
table.create(conn)
参见
每当使用unique约束构造时,postgresql数据库就会隐式地创建一个惟一索引。检查表格时使用 Inspector
, the Inspector.get_indexes()
以及 Inspector.get_unique_constraints()
将清楚地报告这两个构造;对于索引,键 duplicates_constraint
如果被检测为镜像约束,则将出现在索引项中。执行反射时使用 Table(..., autoload=True)
,唯一索引是 not 返回 Table.indexes
当它被检测为镜像时 UniqueConstraint
在 Table.constraints
收集。
在 1.0.0 版更改: - Table
reflection now includes
UniqueConstraint
objects present in the Table.constraints
collection; the PostgreSQL backend will no longer include a "mirrored"
Index
construct in Table.indexes
if it is detected
as corresponding to a unique constraint.
这个 Inspector
用于PostgreSQL后端的是 PGInspector
,提供了其他方法:
from sqlalchemy import create_engine, inspect
engine = create_engine("postgresql+psycopg2://localhost/test")
insp = inspect(engine) # will be a PGInspector
print(insp.get_enums())
sqlalchemy.dialects.postgresql.base.
PGInspector
(conn)¶基地: sqlalchemy.engine.reflection.Inspector
get_enums
(schema=None)¶返回枚举对象列表。
每个成员都是包含以下字段的字典:
name-枚举的名称
schema-枚举的架构名称。
可见-布尔值,无论此枚举在默认搜索路径中是否可见。
标签-应用于枚举的字符串标签列表。
schema¶ -- 架构名称。如果没有,则使用默认架构(通常为“public”)。也可以设置为“*”以指示所有架构的加载枚举。
1.0.0 新版功能.
get_foreign_table_names
(schema=None)¶返回外部表名列表。
行为类似于 Inspector.get_table_names()
,但列表仅限于报告 relkind
价值 f
.
1.0.0 新版功能.
get_table_oid
(table_name, schema=None)¶返回给定表名的OID。
get_view_names
(schema=None, include=('plain', 'materialized'))¶返回所有视图名称 schema .
schema¶ -- 可选,从非默认架构中检索名称。对于特殊报价,使用 quoted_name
.
include¶ -- 指定要返回的视图类型。作为字符串值(对于单个类型)或元组(对于任意数量的类型)传递。默认为 ('plain', 'materialized')
. …添加的版本:1.1
PostgreSQL方言与 Table
构建:
TABLESPACE
::
Table("some_table", metadata, ..., postgresql_tablespace='some_tablespace')
上述选项也可在 Index
构造。
ON COMMIT
::
Table("some_table", metadata, ..., postgresql_on_commit='PRESERVE ROWS')
WITH OIDS
::
Table("some_table", metadata, ..., postgresql_with_oids=True)
WITHOUT OIDS
::
Table("some_table", metadata, ..., postgresql_with_oids=False)
INHERITS
::
Table("some_table", metadata, ..., postgresql_inherits="some_supertable")
Table("some_table", metadata, ..., postgresql_inherits=("t1", "t2", ...))
.. versionadded:: 1.0.0
PARTITION BY
::
Table("some_table", metadata, ...,
postgresql_partition_by='LIST (part_column)')
.. versionadded:: 1.2.6
PostgreSQL方言支持数组,既支持多维列类型,也支持数组文字:
postgresql.ARRAY
-数组数据类型
postgresql.array
数组文字
postgresql.array_agg()
-数组agg sql函数
postgresql.aggregate_order_by
-pg的order by aggregate函数语法助手。
PostgreSQL方言支持JSON和JSONB数据类型,包括psycopg2的本地支持和对PostgreSQL所有特殊运算符的支持:
PostgreSQL有一个独立可创建的类型结构,用于实现枚举类型。这种方法在SQLAlchemy方面引入了显著的复杂性,即何时应该创建和删除此类型。类型对象也是一个独立的可反射实体。应参考以下章节:
postgresql.ENUM
-对枚举的DDL和键入支持。
PGInspector.get_enums()
-检索当前枚举类型的列表
postgresql.ENUM.create()
, postgresql.ENUM.drop()
-用于枚举的单个创建和删除命令。
目前后端dbapis不直接支持枚举和数组的组合。为了发送和接收枚举数组,请使用以下变通类型,该类型修饰 postgresql.ARRAY
数据类型。
from sqlalchemy import TypeDecorator
from sqlalchemy.dialects.postgresql import ARRAY
class ArrayOfEnum(TypeDecorator):
impl = ARRAY
def bind_expression(self, bindvalue):
return sa.cast(bindvalue, self)
def result_processor(self, dialect, coltype):
super_rp = super(ArrayOfEnum, self).result_processor(
dialect, coltype)
def handle_raw_string(value):
inner = re.match(r"^{(.*)}$", value).group(1)
return inner.split(",") if inner else []
def process(value):
if value is None:
return None
return super_rp(handle_raw_string(value))
return process
例如。::
Table(
'mydata', metadata,
Column('id', Integer, primary_key=True),
Column('data', ArrayOfEnum(ENUM('a', 'b, 'c', name='myenum')))
)
此类型不作为内置类型包括在内,因为它与突然决定在新版本中直接支持枚举数组的DBAPI不兼容。
与使用枚举类似,对于json/jsonb数组,我们需要呈现适当的强制转换,但是当前的psycopg2驱动程序似乎自动处理json数组的结果,因此类型更简单:
class CastingArray(ARRAY):
def bind_expression(self, bindvalue):
return sa.cast(bindvalue, self)
例如。::
Table(
'mydata', metadata,
Column('id', Integer, primary_key=True),
Column('data', CastingArray(JSONB))
)
与所有的sqlAlchemy方言一样,已知对postgresql有效的所有大写类型都可以从顶级方言导入,无论它们是否源自 sqlalchemy.types
或者来自当地方言:
from sqlalchemy.dialects.postgresql import \
ARRAY, BIGINT, BIT, BOOLEAN, BYTEA, CHAR, CIDR, DATE, \
DOUBLE_PRECISION, ENUM, FLOAT, HSTORE, INET, INTEGER, \
INTERVAL, JSON, JSONB, MACADDR, MONEY, NUMERIC, OID, REAL, SMALLINT, TEXT, \
TIME, TIMESTAMP, UUID, VARCHAR, INT4RANGE, INT8RANGE, NUMRANGE, \
DATERANGE, TSRANGE, TSTZRANGE, TSVECTOR
特定于PostgreSQL或具有特定于PostgreSQL的构造参数的类型如下:
sqlalchemy.dialects.postgresql.
aggregate_order_by
(target, *order_by)¶基地: sqlalchemy.sql.expression.ColumnElement
按表达式表示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.1 新版功能.
在 1.2.13 版更改: -order by参数可以是多个术语
参见
sqlalchemy.dialects.postgresql.
array
(clauses, **kw)¶基地: sqlalchemy.sql.expression.Tuple
PostgreSQL数组文本。
这用于在SQL表达式中生成数组文本,例如:
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)
sqlalchemy.dialects.postgresql.
ARRAY
(item_type, as_tuple=False, dimensions=None, zero_indexes=False)¶PostgreSQL数组类型。
在 1.1 版更改: 这个 postgresql.ARRAY
类型现在是核心的子类 types.ARRAY
类型。
这个 postgresql.ARRAY
类型的构造方式与核心相同 types.ARRAY
类型;成员类型是必需的,如果类型要用于多个维度,则建议使用多个维度:
from sqlalchemy.dialects import postgresql
mytable = Table("mytable", metadata,
Column("data", postgresql.ARRAY(Integer, dimensions=2))
)
这个 postgresql.ARRAY
类型提供在核心上定义的所有操作 types.ARRAY
类型,包括对“维度”、索引访问和简单匹配的支持,例如 types.ARRAY.Comparator.any()
和 types.ARRAY.Comparator.all()
. postgresql.ARRAY
类还为包含操作提供PostgreSQL特定的方法,包括 postgresql.ARRAY.Comparator.contains()
postgresql.ARRAY.Comparator.contained_by()
和 postgresql.ARRAY.Comparator.overlap()
,例如:
mytable.c.data.contains([1, 2])
这个 postgresql.ARRAY
可能不支持所有PostgreSQL DBAPIS上的类型;目前已知它仅在PSycopg2上工作。
另外, postgresql.ARRAY
类型不直接与 ENUM
类型。有关解决方法,请参见 将枚举与数组一起使用 .
Comparator
(expr)¶基地: sqlalchemy.types.Comparator
为定义比较操作 ARRAY
.
请注意,这些操作是对基地提供的操作的补充 types.ARRAY.Comparator
类,包括 types.ARRAY.Comparator.any()
和 types.ARRAY.Comparator.all()
.
contained_by
(other)¶布尔表达式。测试元素是否是参数数组表达式元素的适当子集。
contains
(other, **kwargs)¶布尔表达式。测试元素是否是参数数组表达式元素的超集。
overlap
(other)¶布尔表达式。测试数组是否具有与参数数组表达式相同的元素。
__init__
(item_type, as_tuple=False, dimensions=None, zero_indexes=False)¶构造数组。
例如。::
Column('myarray', ARRAY(Integer))
论点是:
item_type¶ -- 此数组项的数据类型。注意维数在这里是不相关的,所以多维数组 INTEGER[][]
,构造为 ARRAY(Integer)
,而不是 ARRAY(ARRAY(Integer))
或者这样。
as_tuple=False¶ -- 指定是否应将返回结果从列表转换为元组。默认情况下,dbapis(如psycopg2)返回列表。当返回元组时,结果是可哈希的。
dimensions¶ -- 如果非“无”,则数组将采用固定数量的维度。这将导致为此数组发出的DDL包含括号子句的确切数目。 []
同时也将优化该类型的整体性能。请注意,pg数组总是隐式地“无维度”,这意味着无论如何声明,它们都可以存储任意数量的维度。
zero_indexes=False¶ -- 如果为true,则索引值将在基于python零的索引和基于postgresql一的索引之间转换,例如,在传递到数据库之前,将向所有索引值添加一个值。…添加的版本:0.9.5
sqlalchemy.dialects.postgresql.
array_agg
(*arg, **kw)¶PostgreSQL特定形式的 array_agg
,确保返回类型为 postgresql.ARRAY
而不是平原 types.ARRAY
,除非 type_
通过。
1.1 新版功能.
sqlalchemy.dialects.postgresql.
Any
(other, arrexpr, operator=<built-in function eq>)¶的同义词 ARRAY.Comparator.any()
方法。
这个方法是遗留的,在这里是为了向后兼容。
sqlalchemy.dialects.postgresql.
All
(other, arrexpr, operator=<built-in function eq>)¶的同义词 ARRAY.Comparator.all()
方法。
这个方法是遗留的,在这里是为了向后兼容。
sqlalchemy.dialects.postgresql.
BIT
(length=None, varying=False)¶sqlalchemy.dialects.postgresql.
BYTEA
(length=None)¶基地: sqlalchemy.types.LargeBinary
__init__
(length=None)¶继承 __init__()
方法 LargeBinary
构造一个大二进制类型。
length¶ -- 可选,用于ddl语句中的列的长度,用于接受长度的二进制类型,例如mysql blob类型。
sqlalchemy.dialects.postgresql.
CIDR
¶sqlalchemy.dialects.postgresql.
DOUBLE_PRECISION
(precision=None, asdecimal=False, decimal_return_scale=None)¶__init__
(precision=None, asdecimal=False, decimal_return_scale=None)¶继承 __init__()
方法 Float
构造一个浮点。
precision¶ -- 用于DDL的数字精度 CREATE TABLE
.
asdecimal¶ -- 与…相同的标志 Numeric
,但默认为 False
. 请注意,将此标志设置为 True
导致浮点转换。
decimal_return_scale¶ -- 从浮点转换为python小数时使用的默认小数位数。由于小数点不准确,浮点值通常要长得多,而且大多数浮点数据库类型没有“小数位数”的概念,因此默认情况下,浮点类型在转换时查找前十位小数。指定此值将覆盖该长度。注意,如果没有另外指定,mysql float类型(包括“scale”)将使用“scale”作为decimal_return_scale的默认值。…版本已添加::0.9.0
sqlalchemy.dialects.postgresql.
ENUM
(*enums, **kw)¶基地: sqlalchemy.types.NativeForEmulated
, sqlalchemy.types.Enum
PostgreSQL枚举类型。
这是 types.Enum
包括对PG的支持 CREATE TYPE
和 DROP TYPE
.
当内置类型 types.Enum
使用和 Enum.native_enum
标志的默认值为true,PostgreSQL后端将使用 postgresql.ENUM
键入作为实现,因此将使用特殊的创建/删除规则。
枚举的创建/删除行为必然是复杂的,因为枚举类型与父表之间的关系很糟糕,因为它可能只由一个表“拥有”,也可能在多个表之间共享。
使用时 types.Enum
或 postgresql.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
要在多个表之间使用通用的枚举类型,最佳做法是声明 types.Enum
或 postgresql.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)
)
使用此模式时,必须在创建的单个表的级别上小心。在不指定的情况下发出创建表 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)
使用元数据级枚举类型时,如果调用元数据范围的create/drop,则始终创建并删除该类型::
metadata.create_all(engine) # will emit CREATE TYPE
metadata.drop_all(engine) # will emit DROP TYPE
也可以直接创建和删除类型:
my_enum.create(engine)
my_enum.drop(engine)
在 1.0.0 版更改: 邮报 postgresql.ENUM
类型现在在创建/删除方面的行为更加严格。将仅在元数据级别(而不是表级别)创建和删除元数据级别枚举类型,但 table.create(checkfirst=True)
. 这个 table.drop()
调用现在将为表级枚举类型发出一个DROP类型。
__init__
(*enums, **kw)¶构建一个 ENUM
.
参数与 types.Enum
,也包括以下参数。
sqlalchemy.dialects.postgresql.
HSTORE
(text_type=None)¶基地: sqlalchemy.types.Indexable
, sqlalchemy.types.Concatenable
, sqlalchemy.types.TypeEngine
表示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"}
有关特殊方法的完整列表,请参见 HSTORE.comparator_factory
.
对于与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()
功能。
Comparator
(expr)¶基地: sqlalchemy.types.Comparator
, sqlalchemy.types.Comparator
为定义比较操作 HSTORE
.
array
()¶文本数组表达式。返回交替键和值的数组。
contained_by
(other)¶布尔表达式。测试键是否是参数jsonb表达式键的适当子集。
contains
(other, **kwargs)¶布尔表达式。测试键(或数组)是否是参数jsonb表达式的键的超集/包含键。
defined
(key)¶布尔表达式。测试键是否存在非空值。注意,键可能是一个sqla表达式。
delete
(key)¶hstore表达式。返回已删除给定密钥的hstore的内容。注意,键可能是一个sqla表达式。
has_all
(other)¶布尔表达式。测试jsonb中是否存在所有密钥
has_any
(other)¶布尔表达式。测试JSONB中是否存在任何密钥
has_key
(other)¶布尔表达式。测试是否存在密钥。注意,键可能是一个sqla表达式。
keys
()¶文本数组表达式。返回键数组。
matrix
()¶文本数组表达式。返回数组 [价值键] 对。
slice
(array)¶hstore表达式。返回由键数组定义的hstore的子集。
vals
()¶文本数组表达式。返回值数组。
__init__
(text_type=None)¶构建新的 HSTORE
.
text_type¶ -- 应用于索引值的类型。默认为 types.Text
. …添加的版本:1.1.0
bind_processor
(dialect)¶返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None
.
dialect¶ -- 方言实例正在使用中。
comparator_factory
¶sqlalchemy.dialects.postgresql.
hstore
(*args, **kwargs)¶基地: sqlalchemy.sql.functions.GenericFunction
使用PostgreSQL在SQL表达式中构造一个hstore值 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
数据类型。
sqlalchemy.dialects.postgresql.
INET
¶sqlalchemy.dialects.postgresql.
INTERVAL
(precision=None, fields=None)¶基地: sqlalchemy.types.NativeForEmulated
, sqlalchemy.types._AbstractInterval
PostgreSQL间隔类型。
所有dbapis上可能不支持间隔类型。众所周知,它在psycopg2上工作,而不是pg8000或zxjdbc。
sqlalchemy.dialects.postgresql.
JSON
(none_as_null=False, astext_type=None)¶表示PostgreSQL JSON类型。
这种类型是核心级别的专门化 types.JSON
类型。一定要阅读文档 types.JSON
有关空值处理和ORM使用的重要提示。
在 1.1 版更改: postgresql.JSON
现在是PostgreSQL特有的新的专门化 types.JSON
类型。
PostgreSQL版本提供的运算符 JSON
包括:
索引操作 ->
操作符):
data_table.c.data['some key']
data_table.c.data[5]
返回文本的索引操作 ->>
操作符):
data_table.c.data['some key'].astext == 'some value'
带cast的索引操作(相当于 CAST(col ->> ['some key'] AS <type>)
):
data_table.c.data['some key'].astext.cast(Integer) == 5
路径索引操作 #>
操作符):
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'
在 1.1 版更改: 这个 ColumnElement.cast()
JSON对象上的运算符现在要求 JSON.Comparator.astext
如果强制转换仅从文本字符串起作用,则显式调用修饰符。
索引操作返回类型默认为的表达式对象 JSON
默认情况下,这样可以对结果类型调用更多面向JSON的指令。
自定义序列化程序和反序列化程序是在方言级别指定的,即使用 create_engine()
. 原因是,当使用psycopg2时,DBAPI只允许在每个光标或每个连接级别使用序列化程序。例如。::
engine = create_engine("postgresql://scott:tiger@localhost/test",
json_serializer=my_serialize_fn,
json_deserializer=my_deserialize_fn
)
当使用psycopg2方言时,json_反序列化程序使用 psycopg2.extras.register_default_json
.
Comparator
(expr)¶基地: sqlalchemy.types.Comparator
为定义比较操作 JSON
.
astext
¶在索引表达式上,在SQL中呈现时使用“astext”(例如“->>”)转换。
例如。::
select([data_table.c.data['some key'].astext])
__init__
(none_as_null=False, astext_type=None)¶构建一个 JSON
类型。
none_as_null¶ -- 如果为真,则保持该值 None
作为SQL空值,而不是 null
. 请注意,当此标志为false时, null()
构造仍可以用于持久化空值::from sqlAlchemy import null conn.execute(table.insert(),data=null())。。版本已更改::0.9.8-已添加 none_as_null
和 null()
现在支持以保持空值。…参阅: JSON.NULL
astext_type¶ -- 用于的类型 JSON.Comparator.astext
索引属性上的访问器。默认为 types.Text
. …添加的版本:1.1
comparator_factory
¶JSON.Comparator
的别名
sqlalchemy.dialects.postgresql.
JSONB
(none_as_null=False, astext_type=None)¶基地: sqlalchemy.dialects.postgresql.json.JSON
表示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的其他运算符,包括 JSONB.Comparator.has_key()
, JSONB.Comparator.has_all()
, JSONB.Comparator.has_any()
, JSONB.Comparator.contains()
和 JSONB.Comparator.contained_by()
.
像 JSON
类型 JSONB
当与ORM一起使用时,类型不检测就地更改,除非 sqlalchemy.ext.mutable
使用扩展名。
自定义序列化程序和反序列化程序与共享 JSON
类,使用 json_serializer
和 json_deserializer
关键字参数。必须在方言级别使用 create_engine()
. 使用psycopg2时,序列化程序与使用 psycopg2.extras.register_default_jsonb
在每个连接的基础上,以相同的方式 psycopg2.extras.register_default_json
用于用JSON类型注册这些处理程序。
0.9.7 新版功能.
参见
Comparator
(expr)¶基地: sqlalchemy.dialects.postgresql.json.Comparator
为定义比较操作 JSON
.
contained_by
(other)¶布尔表达式。测试键是否是参数jsonb表达式键的适当子集。
contains
(other, **kwargs)¶布尔表达式。测试键(或数组)是否是参数jsonb表达式的键的超集/包含键。
has_all
(other)¶布尔表达式。测试jsonb中是否存在所有密钥
has_any
(other)¶布尔表达式。测试JSONB中是否存在任何密钥
has_key
(other)¶布尔表达式。测试是否存在密钥。注意,键可能是一个sqla表达式。
comparator_factory
¶JSONB.Comparator
的别名
sqlalchemy.dialects.postgresql.
MACADDR
¶sqlalchemy.dialects.postgresql.
MONEY
¶基地: sqlalchemy.types.TypeEngine
提供PostgreSQL货币类型。
1.2 新版功能.
sqlalchemy.dialects.postgresql.
OID
¶基地: sqlalchemy.types.TypeEngine
提供PostgreSQL OID类型。
0.9.5 新版功能.
sqlalchemy.dialects.postgresql.
REAL
(precision=None, asdecimal=False, decimal_return_scale=None)¶SQL实数类型。
__init__
(precision=None, asdecimal=False, decimal_return_scale=None)¶继承 __init__()
方法 Float
构造一个浮点。
precision¶ -- 用于DDL的数字精度 CREATE TABLE
.
asdecimal¶ -- 与…相同的标志 Numeric
,但默认为 False
. 请注意,将此标志设置为 True
导致浮点转换。
decimal_return_scale¶ -- 从浮点转换为python小数时使用的默认小数位数。由于小数点不准确,浮点值通常要长得多,而且大多数浮点数据库类型没有“小数位数”的概念,因此默认情况下,浮点类型在转换时查找前十位小数。指定此值将覆盖该长度。注意,如果没有另外指定,mysql float类型(包括“scale”)将使用“scale”作为decimal_return_scale的默认值。…版本已添加::0.9.0
sqlalchemy.dialects.postgresql.
REGCLASS
¶基地: sqlalchemy.types.TypeEngine
提供PostgreSQL RegClass类型。
1.2.7 新版功能.
sqlalchemy.dialects.postgresql.
TSVECTOR
¶基地: sqlalchemy.types.TypeEngine
这个 postgresql.TSVECTOR
类型实现PostgreSQL文本搜索类型tsvector。
它可以用于对自然语言文档进行全文查询。
0.9.0 新版功能.
参见
sqlalchemy.dialects.postgresql.
UUID
(as_uuid=False)¶基地: sqlalchemy.types.TypeEngine
PostgreSQL UUID类型。
表示uuid列类型,将数据解释为dbapi本机返回的或python uuid对象。
所有DBAPI上可能不支持UUID类型。已知它在psycopg2上工作,而不是pg8000。
PostgreSQL 9.2以后版本中的新范围列类型由以下类型提供:
sqlalchemy.dialects.postgresql.
INT4RANGE
¶基地: sqlalchemy.dialects.postgresql.ranges.RangeOperators
, sqlalchemy.types.TypeEngine
表示PostgreSQL Int4Range类型。
sqlalchemy.dialects.postgresql.
INT8RANGE
¶基地: sqlalchemy.dialects.postgresql.ranges.RangeOperators
, sqlalchemy.types.TypeEngine
表示PostgreSQL Int8Range类型。
sqlalchemy.dialects.postgresql.
NUMRANGE
¶基地: sqlalchemy.dialects.postgresql.ranges.RangeOperators
, sqlalchemy.types.TypeEngine
表示PostgreSQL NumRange类型。
sqlalchemy.dialects.postgresql.
DATERANGE
¶基地: sqlalchemy.dialects.postgresql.ranges.RangeOperators
, sqlalchemy.types.TypeEngine
表示PostgreSQL日期范围类型。
sqlalchemy.dialects.postgresql.
TSRANGE
¶基地: sqlalchemy.dialects.postgresql.ranges.RangeOperators
, sqlalchemy.types.TypeEngine
表示PostgreSQL tsrange类型。
sqlalchemy.dialects.postgresql.
TSTZRANGE
¶基地: sqlalchemy.dialects.postgresql.ranges.RangeOperators
, sqlalchemy.types.TypeEngine
表示PostgreSQL TSZrange类型。
上述类型的大部分功能都来自以下混音器:
sqlalchemy.dialects.postgresql.ranges.
RangeOperators
¶该混音器为表9-44中列出的测距仪提供了功能。 `postgres documentation`_ _用于范围函数和运算符。它由中提供的所有范围类型使用 postgres
方言,可能用于您自己创建的任何范围类型。
Postgres文档表9-45中列出的范围函数不提供额外的支持。对于这些,正常 func()
应使用对象。
comparator_factory
(expr)¶基地: sqlalchemy.types.Comparator
定义范围类型的比较操作。
__ne__
(other)¶布尔表达式。如果两个范围不相等,则返回“真”
adjacent_to
(other)¶布尔表达式。如果列中的范围与操作数中的范围相邻,则返回true。
contained_by
(other)¶布尔表达式。如果列包含在右侧操作数中,则返回true。
contains
(other, **kw)¶布尔表达式。如果列中包含右操作数(可以是元素或范围),则返回true。
not_extend_left_of
(other)¶布尔表达式。如果列中的范围未扩展到操作数范围的左侧,则返回true。
not_extend_right_of
(other)¶布尔表达式。如果列中的范围不扩展到操作数范围的右侧,则返回true。
overlaps
(other)¶布尔表达式。如果列与右侧操作数重叠(具有相同的点),则返回true。
strictly_left_of
(other)¶布尔表达式。如果列严格位于右侧操作数的左侧,则返回true。
strictly_right_of
(other)¶布尔表达式。如果列严格位于右侧操作数的右边,则返回true。
警告
范围类型DDL支持应该与任何PostgreSQL DBAPI驱动程序一起工作,但是返回的数据类型可能会有所不同。如果您正在使用 psycopg2
,建议在使用这些列类型之前升级到2.5版或更高版本。
在实例化使用这些列类型的模型时,您应该传递您用于该列类型的DBAPI驱动程序所期望的任何数据类型。为了 psycopg2
这些是 psycopg2.extras.NumericRange
, psycopg2.extras.DateRange
, psycopg2.extras.DateTimeRange
和 psycopg2.extras.DateTimeTZRange
或者你注册的班级 psycopg2.extras.register_range
.
例如:
from psycopg2.extras import DateTimeRange
from sqlalchemy.dialects.postgresql import TSRANGE
class RoomBooking(Base):
__tablename__ = 'room_booking'
room = Column(Integer(), primary_key=True)
during = Column(TSRANGE())
booking = RoomBooking(
room=101,
during=DateTimeRange(datetime(2013, 3, 23), None)
)
SQLAlchemy支持PostgreSQL通过 ExcludeConstraint
班级:
sqlalchemy.dialects.postgresql.
ExcludeConstraint
(*elements, **kw)¶基地: sqlalchemy.schema.ColumnCollectionConstraint
表级排除约束。
定义排除约束,如中所述 `postgres documentation`_ _.
__init__
(*elements, **kw)¶创建一个 ExcludeConstraint
对象。
例如。::
const = ExcludeConstraint(
(Column('period'), '&&'),
(Column('group'), '='),
where=(Column('group') != 'some group')
)
约束通常嵌入到 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'
)
)
*elements¶ -- 形式的两个元组的序列 (column, operator)
其中“column”是SQL表达式元素或原始SQL字符串,通常是 Column
对象,“operator”是包含要使用的运算符的字符串。以便在 Column
对象不可用,在确保任何必要的引用规则生效的同时,临时 Column
或 sql.expression.column()
应使用对象。
name¶ -- 可选,此约束的数据库内名称。
deferrable¶ -- 可选布尔值。如果设置了,则在为该约束发出DDL时发出“可延迟”或“不可延迟”。
initially¶ -- 可选字符串。如果已设置,则在为此约束发出DDL时最初发出<value>。
using¶ -- 可选字符串。如果设置,则在为此约束发出DDL时使用<index_method>发出。默认为“gist”。
where¶ -- 可选的SQL表达式构造或文本SQL字符串。如果设置,则在为此约束发出ddl时发出where<predicate>。…警告:: ExcludeConstraint.where
参数 ExcludeConstraint
可以作为python字符串参数传递,该参数将被视为 可信SQL文本 并按规定呈现。 不要将不受信任的输入传递给此参数 .
例如::
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', '&&')),
)
sqlalchemy.dialects.postgresql.dml.
insert
(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)¶构建新的 Insert
对象。
此构造函数被镜像为公共API函数;请参见 insert()
完整的用法和参数描述。
sqlalchemy.dialects.postgresql.dml.
Insert
(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)¶基地: sqlalchemy.sql.expression.Insert
PostgreSQL特定的insert实现。
为pg特定语法添加方法,如on conflict。
1.1 新版功能.
excluded
¶提供 excluded
冲突语句的命名空间
pg的on conflict子句允许引用将要插入的行,称为 excluded
. 此属性提供此行中的所有列都是可引用的。
参见
冲突时插入(向上插入) - example of how
to use Insert.excluded
on_conflict_do_nothing
(constraint=None, index_elements=None, index_where=None)¶为on conflict子句指定不做任何操作。
这个 constraint
和 index_elements
参数是可选的,但只能指定其中一个。
参见
on_conflict_do_update
(constraint=None, index_elements=None, index_where=None, set_=None, where=None)¶为on conflict子句指定do update set操作。
要么 constraint
或 index_elements
参数是必需的,但只能指定其中一个。
constraint¶ -- 表上唯一约束或排除约束的名称,或者约束对象本身(如果它具有.name属性)。
index_elements¶ -- 由字符串列名组成的序列, Column
对象或其他将用于推断目标索引的列表达式对象。
index_where¶ -- 可用于推断条件目标索引的附加Where条件。
set_¶ -- 必需参数。以列名为键、表达式或文本为值的字典或其他映射对象,指定 SET
要采取的行动。如果目标 Column
指定与列名不同的“.key”属性,应使用该键。…警告::此词典有 not 考虑到python指定的默认更新值或生成函数,例如使用 Column.onupdate
. 除非在 Insert.on_conflict_do_update.set_
字典。
where¶ -- 可选参数。如果存在,则可以是文本SQL字符串或 WHERE
限制受影响的行的子句 DO UPDATE SET
. 行不符合 WHERE
不会更新条件(有效地 DO NOTHING
对于那些行)。…添加的版本:1.1
参见
Support for the PostgreSQL database via the psycopg2 driver.
Documentation and download information (if applicable) for psycopg2 is available at: http://pypi.python.org/pypi/psycopg2/
Connect String:
postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]
psycopg2接受的特定关键字参数 create_engine()
是:
server_side_cursors
:为支持此功能的SQL语句启用“服务器端游标”。从psycopg2的角度来看,这本质上意味着光标是使用名称创建的,例如 connection.cursor('some name')
它的作用是,结果行不会在语句执行后立即预取和缓冲,而是保留在服务器上,仅在需要时检索。SQLAlchemy ResultProxy
当启用此功能时,使用特殊的行缓冲行为,这样一次100行的组就可以通过线路获取,以减少会话开销。请注意 Connection.execution_options.stream_results
执行选项是在每次执行的基础上启用此模式的更具针对性的方法。
use_native_unicode
:启用每个连接使用psycopg2“本机Unicode”模式。默认为true。
参见
isolation_level
:此选项适用于所有PostgreSQL方言,包括 AUTOCOMMIT
使用psycopg2方言时的隔离级别。
client_encoding
:使用psycopg2以libpq不可知方式设置客户端编码 set_client_encoding()
方法。
use_batch_mode
:此标志允许 psycopg2.extras.execute_batch
对于 cursor.executemany()
由执行的调用 Engine
. 它目前是实验性的,但在默认情况下很可能成为真实的,因为它对执行人员的性能至关重要。
psycopg2支持通过Unix域连接进行连接。当 host
URL的一部分被省略,SQLAlchemy传递 None
到psycopg2,它指定Unix域通信而不是TCP/IP通信:
create_engine("postgresql+psycopg2://user:password@/dbname")
默认情况下,使用的套接字文件是连接到 /tmp
或者在构建PostgreSQL时指定的任何套接字目录。可以通过将路径名传递给psycopg2来重写此值,方法是使用 host
作为附加关键字参数::
create_engine("postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql")
psycopg2 dbapi可以通过向libpq客户机库传递一个空的dsn连接到postgresql,默认情况下,libpq客户机库指示连接到为“trust”连接打开的localhost postgresql数据库。可以使用一组特定的环境变量进一步定制这种行为,这些环境变量的前缀为 PG_...
,由消耗 libpq
替换连接字符串的任何或所有元素。
对于此表单,可以不使用初始方案以外的任何元素传递URL::
engine = create_engine('postgresql+psycopg2://')
在上面的表单中,一个空白的“dsn”字符串被传递给 psycopg2.connect()
函数,它依次表示传递给libpq的空DSN。
1.3.2 新版功能: 支持与psycopg2的无参数连接。
参见
Environment Variables -关于如何使用的PostgreSQL文档 PG_...
连接的环境变量。
与一起使用时,将遵循以下特定于DBAPI的选项 Connection.execution_options()
, Executable.execution_options()
, Query.execution_options()
,除了那些不特定于DBAPIS的:
isolation_level
-设置事务隔离级别 Connection
(只能在连接上设置,不能在语句或查询上设置)。见 psycopg2事务隔离级别 .
stream_results
-启用或禁用psycopg2服务器端游标-此功能结合使用“命名”游标和特殊的结果处理方法,以使结果行没有完全缓冲。如果 None
或不设置 server_side_cursors
选择权 Engine
使用。
max_row_buffer
-当使用时 stream_results
,一个整数值,指定一次要缓冲的最大行数。这由 BufferedRowResultProxy
,如果忽略,缓冲区将增长到最终一次存储1000行。
1.0.6 新版功能.
现代版本的psycopg2包括一个被称为 Fast Execution Helpers 这一点已经在基准测试中显示,可以通过多个数量级的插入来提高psycopg2的executeMany()性能。SQLAlchemy允许将此扩展用于所有 executemany()
由调用的样式调用 Engine
当使用时 multiple parameter sets ,通过添加 use_batch_mode
旗到 create_engine()
::
engine = create_engine(
"postgresql+psycopg2://scott:tiger@host/dbname",
use_batch_mode=True)
批处理模式被认为是 实验的 但此时,在将来的版本中可能会默认启用。
参见
执行多个语句 -演示如何使用DBAPI executemany()
与 Connection
对象。
1.2.0 新版功能.
默认情况下,psycopg2驱动程序使用 psycopg2.extensions.UNICODE
扩展名,这样DBAPI直接接收并返回所有字符串作为python unicode对象—sqlAlchemy不做任何更改地传递这些值。这里的psycopg2将根据当前的“客户端编码”设置对字符串值进行编码/解码;默认情况下,这是 postgresql.conf
文件,通常默认为 SQL_ASCII
. 通常,可以将其更改为 utf8
,作为更有用的默认值:
# postgresql.conf file
# client_encoding = sql_ascii # actually, defaults to database
# encoding
client_encoding = utf8
影响客户端编码的第二种方法是在本地psycopg2中设置它。sqlAlchemy将调用psycopg2 psycopg2:connection.set_client_encoding()
基于传递给的值的所有新连接的方法 create_engine()
使用 client_encoding
参数::
# set_client_encoding() setting;
# works for *all* PostgreSQL versions
engine = create_engine("postgresql://user:pass@host/dbname",
client_encoding='utf8')
这将覆盖PostgreSQL客户机配置中指定的编码。以这种方式使用参数时,psycopg2驱动程序将发出 SET client_encoding TO 'utf8'
在连接上显式,并在所有PostgreSQL版本中工作。
请注意 client_encoding
传递到的设置 create_engine()
是 不一样 正如最近增加的 client_encoding
参数现在由libpq直接支持。当 client_encoding
直接传递给 psycopg2.connect()
,并使用 create_engine.connect_args
参数::
engine = create_engine(
"postgresql://user:pass@host/dbname",
connect_args={'client_encoding': 'utf8'})
# using the query string is equivalent
engine = create_engine("postgresql://user:pass@host/dbname?client_encoding=utf8")
以上参数仅在PostgreSQL 9.1版本中添加到libpq中,因此使用前面的方法更好地支持跨版本。
也可以指示sqlAlchemy跳过psycopg2的用法。 UNICODE
扩展和使用自己的Unicode编码/解码服务,这些服务通常只保留给那些不完全支持Unicode的DBAPI。经过 use_native_unicode=False
到 create_engine()
将禁用 psycopg2.extensions.UNICODE
. sqlAlchemy将使用 create_engine()
encoding
参数,默认为 utf-8
. 由于大多数DBAPI现在完全支持Unicode,SQLAlchemy自己的Unicode编码/解码功能正逐渐过时。
psycopg2方言的默认参数样式是“pyformat”,其中使用 %(paramname)s
风格。此格式有一个限制,即它不适应实际包含百分号或括号符号的参数名称的异常情况;由于SQLAlchemy在许多情况下根据列的名称生成绑定参数名称,因此列名称中存在这些字符可能会导致问题。
有两种方法可以解决 schema.Column
它的名称中包含这些字符之一。一是具体说明 schema.Column.key
对于具有此类名称的列:
measurement = Table('measurement', metadata,
Column('Size (meters)', Integer, key='size_meters')
)
上面的插入语句,例如 measurement.insert()
将使用 size_meters
作为参数名和SQL表达式,例如 measurement.c.size_meters > 10
将从 size_meters
也是关键。
在 1.0.0 版更改: -SQL表达式将使用 Column.key
作为在SQL表达式中创建匿名绑定参数时的命名源;以前,此行为仅适用于 Table.insert()
和 Table.update()
参数名称。
另一种解决方案是使用位置格式;psycopg2允许使用“format”参数样式,可以将其传递给 create_engine.paramstyle
::
engine = create_engine(
'postgresql://scott:tiger@localhost:5432/test', paramstyle='format')
使用上面的引擎,而不是像这样的语句:
INSERT INTO measurement ("Size (meters)") VALUES (%(Size (meters))s)
{'Size (meters)': 1}
相反,我们看到:
INSERT INTO measurement ("Size (meters)") VALUES (%s)
(1, )
在上面的位置,字典样式转换为具有位置样式的元组。
psycopg2方言完全支持保存点和两阶段提交操作。
正如在 事务隔离级别 ,所有PostgreSQL方言都支持通过 isolation_level
传递给的参数 create_engine()
以及 isolation_level
参数使用者 Connection.execution_options()
. 当使用psycopg2方言时,这些选项使用psycopg2的 set_isolation_level()
连接方法,而不是发出postgresql指令;这是因为在任何情况下,psycopg2的api级别设置总是在每个事务开始时发出。
psycopg2方言支持隔离级别的这些常量:
READ COMMITTED
READ UNCOMMITTED
REPEATABLE READ
SERIALIZABLE
AUTOCOMMIT
psycopg2方言将通过 sqlalchemy.dialects.postgresql
记录仪:
import logging
logging.getLogger('sqlalchemy.dialects.postgresql').setLevel(logging.INFO)
这个 psycopg2
DBAPI包括对hstore类型的本机处理编组的扩展。当使用psycopg2.4或更高版本时,sqlAlchemy psycopg2方言将默认启用此扩展,并且检测到目标数据库设置了hstore类型以供使用。换句话说,当方言进行第一次连接时,将执行如下顺序:
使用 psycopg2.extras.HstoreAdapter.get_oids()
. 如果此函数返回一个hstore标识符列表,那么我们将确定 HSTORE
存在扩展。此功能是 跳过 如果安装的psycopg2版本低于2.4版。
如果 use_native_hstore
标志默认为 True
我们发现 HSTORE
有可用的OID, psycopg2.extensions.register_hstore()
对所有连接调用扩展。
这个 register_hstore()
扩展具有以下效果 接受所有python字典作为参数,而不管SQL中目标列的类型如何。 . 该扩展将字典转换为文本hstore表达式。如果不需要此行为,请通过设置禁用hstore扩展 use_native_hstore
到 False
如下:
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test",
use_native_hstore=False)
这个 HSTORE
类型是 仍然支持 当 psycopg2.extensions.register_hstore()
未使用扩展名。这仅仅意味着在参数端和结果端,python字典和hstore字符串格式之间的强制将发生在sqlachemy自己的编组逻辑中,而不是 psycopg2
这可能更有效。
Support for the PostgreSQL database via the pg8000 driver.
Documentation and download information (if applicable) for pg8000 is available at: https://pythonhosted.org/pg8000/
Connect String:
postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...]
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来重写会话:
将客户机编码设置为“utf8”;
SQLAlchemy将根据传递给的值对所有新连接执行此SQL create_engine()
使用 client_encoding
参数::
engine = create_engine(
"postgresql+pg8000://user:pass@host/dbname", client_encoding='utf8')
Support for the PostgreSQL database via the psycopg2cffi driver.
Documentation and download information (if applicable) for psycopg2cffi is available at: http://pypi.python.org/pypi/psycopg2cffi/
Connect String:
postgresql+psycopg2cffi://user:password@host:port/dbname[?key=value&key=value...]
psycopg2cffi
是对 psycopg2
,对C层使用CFFI。这使得它适合用于例如pypy。文件依据 psycopg2
.
1.0.0 新版功能.
Support for the PostgreSQL database via the py-postgresql driver.
Documentation and download information (if applicable) for py-postgresql is available at: http://python.projects.pgfoundry.org/
Connect String:
postgresql+pypostgresql://user:password@host:port/dbname[?key=value&key=value...]
Support for the PostgreSQL database via the pygresql driver.
Documentation and download information (if applicable) for pygresql is available at: http://www.pygresql.org/
Connect String:
postgresql+pygresql://user:password@host:port/dbname[?key=value&key=value...]
Support for the PostgreSQL database via the zxJDBC for Jython driver.
Drivers for this database are available at: http://jdbc.postgresql.org/