版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

的PostgreSQL ¶ T0>

支持PostgreSQL数据库。

DBAPI支持

以下dialect / DBAPI选项可用。有关连接信息,请参阅各个DBAPI部分。

序列/ SERIAL ¶ T0>

PostgreSQL支持序列,而SQLAlchemy使用这些作为为基于整数的主键列创建新的主键值的默认方法。在创建表时,SQLAlchemy将针对基于整数的主键列发出SERIAL数据类型,从而生成对应于该列的序列和服务器端默认值。

要指定要用于主键生成的特定命名序列,请使用Sequence()结构:

Table('sometable', metadata,
        Column('id', Integer, Sequence('some_id_seq'), primary_key=True)
    )

当SQLAlchemy发出单个INSERT语句时,为了履行使“最后一个插入标识符”可用的合同,将一个RETURNING子句添加到INSERT语句中,该语句指定在语句完成后应该返回主键列。仅当使用Postgresql 8.2或更高版本时才会执行RETURNING功能。作为后备方法,无论是通过SERIAL明确指定还是隐式指定,序列都是事先独立执行的,返回的值将在后续插入中使用。请注意,当使用“executemany”语义执行insert()结构时,“最后插入的标识符”功能不适用;在这种情况下,不会返回RETURNING子句,也不会执行序列。

要在默认情况下强制使用RETURNING,请将标志implicit_returning=False指定为create_engine()

事务隔离级别

All Postgresql dialects support setting of transaction isolation level both via a dialect-specific parameter create_engine.isolation_level accepted by create_engine(), as well as the Connection.execution_options.isolation_level argument as passed to Connection.execution_options(). When using a non-psycopg2 dialect, this feature works by issuing the command SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level> for each new connection. 对于特殊的AUTOCOMMIT隔离级别,使用特定于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 - on psycopg2 / pg8000 only

Remote-Schema Table Introspection和Postgresql search_path

Postgresql方言可以反映来自任何模式的表格。Table.schema参数或者MetaData.reflect.schema参数决定了将要为表或表搜索哪个模式。反映的Table对象在所有情况下都会按照指定的方式保留这个.schema属性。但是,对于这些Table对象通过外键约束引用的表,必须确定.schema在这些远程表中的表示方式,该远程模式名称也是当前Postgresql搜索路径的成员。

默认情况下,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)

Above, we created a table referred as a member of the remote schema test_schema, however when we added test_schema to the PG search_path and then asked pg_get_constraintdef() for the FOREIGN KEY syntax, test_schema was not included in the output of the function.

另一方面,如果我们将搜索路径设置为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>

The above process would deliver to the MetaData.tables collection referred table named without the schema:

>>> meta.tables['referred'].schema is None
True

To alter the behavior of reflection such that the referred schema is maintained regardless of the search_path setting, use the postgresql_ignore_search_path option, which can be specified as a dialect-specific argument to both Table as well as 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>

We will now have test_schema.referred stored as schema-qualified:

>>> meta.tables['test_schema.referred'].schema
'test_schema'

请注意,在所有情况下,“默认”模式总是反映为NonePostgresql上的“默认”模式是由Postgresql current_schema()函数返回的模式。在典型的Postgresql安装中,这是public的名称。因此,引用另一个表的public(即默认)模式的表总是将.schema属性设置为None

New in version 0.9.2: Added the postgresql_ignore_search_path dialect-level option accepted by Table and MetaData.reflect().

也可以看看

架构搜索路径 - 在Postgresql网站上。

INSERT / UPDATE ... RETURNING ¶ T0>

The dialect supports PG 8.2’s INSERT..RETURNING, UPDATE..RETURNING and DELETE..RETURNING syntaxes. INSERT..RETURNING is used by default for single-row INSERT statements in order to fetch newly generated primary key identifiers. 要指定显式的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()

INSERT ... ON CONFLICT(Upsert)

Starting with version 9.5, PostgreSQL allows “upserts” (update or insert) of rows into a table via the ON CONFLICT clause of the INSERT statement. 一个候选行只会被插入,如果该行不违反任何唯一的约束。在违反唯一约束条件的情况下,可能发生的次要操作可以是“DO UPDATE”,表示目标行中的数据应该更新,或者“DO NOTHING”,表示无声地跳过该行。

冲突是使用现有的唯一约束和索引来确定的。These constraints may be identified either using their name as stated in DDL, or they may be inferred by stating the columns and conditions that comprise the indexes.

SQLAlchemy provides ON CONFLICT support via the Postgresql-specific postgresql.dml.insert() function, which provides the generative methods on_conflict_do_update() and 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参数用于直接指定索引,而不是推断它。这可以是UNIQUE约束,PRIMARY KEY约束或INDEX的名称:

    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')
    )
  • The Insert.on_conflict_do_update.constraint argument may also refer to a SQLAlchemy construct representing a constraint, e.g. UniqueConstraint, PrimaryKeyConstraint, Index, or ExcludeConstraint. 在这个使用中,如果约束有一个名字,那就直接使用。否则,如果约束未命名,则将使用推理,其中约束的表达式和可选的WHERE子句将在结构中拼写出来。这个用法使用Table.primary_key属性引用Table的已命名或未命名主键是特别方便的:

    do_update_stmt = insert_stmt.on_conflict_do_update(
        constraint=my_table.primary_key,
        set_=dict(data='updated value')
    )

ON CONFLICT...DO UPDATE is used to perform an update of the already existing row, using any combination of new values as well as values from the proposed insertion. 这些值是使用Insert.on_conflict_do_update.set_参数指定的。该参数接受一个包含UPDATE的直接值的字典:

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)

警告

The Insert.on_conflict_do_update() method does not take into account Python-side default UPDATE values or generation functions, e.g. e.g. those specified using Column.onupdate. 除非在Insert.on_conflict_do_update.set_字典中手动指定这些值,否则这些值不会用于ON CONFLICT样式的UPDATE。

为了引用建议的插入行,特殊别名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参数接受WHERE子句,这将限制那些接收UPDATE的行:

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 may also be used to skip inserting a row entirely if any conflict with a unique or exclusion constraint occurs; below this is illustrated using the on_conflict_do_nothing() method:

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 ON CONFLICT子句的支持

也可以看看

INSERT .. ON CONFLICT - in the Postgresql documentation.

仅从...

该方言支持PostgreSQL的ONLY关键字,仅用于定位继承层次结构中的特定表。This can be used to produce the SELECT ... FROM ONLY, UPDATE ONLY ..., and DELETE FROM ONLY ... syntaxes. 它使用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')

Postgresql特定的索引选项

对于Index结构的几个扩展是可用的,特定于PostgreSQL方言。

部分索引

部分索引为索引定义添加标准,以便将索引应用于行的子集。这些可以在Index中使用postgresql_where关键字参数指定:

Index('my_index', my_table.c.id, postgresql_where=tbl.c.value > 10)

运算符类

PostgreSQL允许为索引的每一列指定一个操作符类(参见http://www.postgresql.org/docs/8.3/interactive/indexes-opclass.html t1 >)。Index结构允许通过postgresql_ops关键字参数指定这些参数:

Index('my_index', my_table.c.id, my_table.c.data,
                        postgresql_ops={
                            'data': 'text_pattern_ops',
                            'id': 'int4_ops'
                        })

0.7.2版新增: postgresql_ops关键字参数到Index结构。

Note that the keys in the postgresql_ops dictionary are the “key” name of the Column, i.e. the name used to access it from the .c collection of Table, which can be configured to be different than the actual name of the column as expressed in the database.

索引类型

PostgreSQL提供了几种索引类型:B-Tree,Hash,GiST和GIN,以及用户创建自己的能力(参见http://www.postgresql.org/docs/8.3/static/indexes -types.html T0>)。这些可以在Index中使用postgresql_using关键字参数指定:

Index('my_index', my_table.c.data, postgresql_using='gin')

The value passed to the keyword argument will be simply passed through to the underlying CREATE INDEX command, so it must be a valid index type for your version of PostgreSQL.

索引存储参数

PostgreSQL允许在索引上设置存储参数。可用的存储参数取决于索引使用的索引方法。可以使用postgresql_with关键字参数在Index中指定存储参数:

Index('my_index', my_table.c.data, postgresql_with={"fillfactor": 50})

新版本1.0.6.

PostgreSQL允许定义创建索引的表空间。可以使用postgresql_tablespace关键字参数在Index上指定表空间:

Index('my_index', my_table.c.data, postgresql_tablespace='my_tablespace')

版本1.1中的新功能

请注意,Table上也有相同的选项。

与当前索引

通过将标志postgresql_concurrently传递给Index结构来支持PostgreSQL索引选项CONCURRENTLY:

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版本的新功能支持DROP INDEX上的CONCURRENTLY。CONCURRENTLY关键字现在只有在连接上检测到足够高的Postgresql版本(或者无连接方言)时才会发出。

Postgresql索引反射

只要使用UNIQUE CONSTRAINT结构,Postgresql数据库就会隐式地创建一个UNIQUE INDEX。When inspecting a table using Inspector, the Inspector.get_indexes() and the Inspector.get_unique_constraints() will report on these two constructs distinctly; in the case of the index, the key duplicates_constraint will be present in the index entry if it is detected as mirroring a constraint. When performing reflection using Table(..., autoload=True), the UNIQUE INDEX is not returned in Table.indexes when it is detected as mirroring a UniqueConstraint in the Table.constraints collection.

Changed in version 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.

特殊反射选项

用于Postgresql后端的InspectorPGInspector的一个实例,它提供了其他方法:

from sqlalchemy import create_engine, inspect

engine = create_engine("postgresql+psycopg2://localhost/test")
insp = inspect(engine)  # will be a PGInspector

print(insp.get_enums())
class sqlalchemy.dialects.postgresql.base.PGInspector(conn)

基础:sqlalchemy.engine.reflection.Inspector

get_enums T0> ( T1> 架构=无 T2> ) T3> ¶ T4>

返回ENUM对象的列表。

每个成员都是包含这些字段的字典:

  • 名称 - 枚举的名称
  • 架构 - 枚举的架构名称。
  • 可见 - 布尔值,不管这个枚举在默认搜索路径中是否可见。
  • 标签 - 适用于枚举的字符串标签的列表。
参数:schema – schema name. 如果没有,则使用默认模式(通常是“公共”)。也可以设置为'*'来表示所有模式的加载枚举。

版本1.0.0中的新功能

get_foreign_table_names T0> ( T1> 架构=无 T2> ) T3> ¶ T4>

返回FOREIGN TABLE名称的列表。

Behavior is similar to that of Inspector.get_table_names(), except that the list is limited to those tables tha report a relkind value of f.

版本1.0.0中的新功能

get_table_oid table_nameschema =无 t5 >

返回给定表名称的OID。

get_view_names(schema=None, include=('plain', 'materialized'))

返回schema中的所有视图名称。

参数:
  • schema – Optional, retrieve names from a non-default schema. 对于特殊的引用,请使用quoted_name
  • include -

    指定要返回哪些类型的视图。作为字符串值(对于单一类型)或元组(对于任意数量的类型)传递。默认为('plain', 'materialized')

    版本1.1中的新功能

PostgreSQL表选项

PostgreSQL方言直接支持CREATE TABLE的几个选项和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", ...))

版本1.0.0中的新功能

ARRAY类型

Postgresql方言支持数组,既可以是多维列类型也可以是数组文字:

JSON类型

Postgresql方言同时支持JSON和JSONB数据类型,包括psycopg2对本地所有PostgreSQL的特殊操作符的本地支持和支持:

HSTORE类型

支持Postgresql HSTORE类型以及hstore文字:

ENUM类型

Postgresql有一个可独立创建的TYPE结构,用于实现枚举类型。这种方法在SQLAlchemy方面应该是CREATE和DROPPED的时候会引入很大的复杂性。类型对象也是一个独立反映的实体。以下部分应参考:

使用带ARRAY的ENUM

ENUM和ARRAY的组合目前并不直接支持后端DBAPI。为了发送和接收ENUM ARRAY,请使用以下解决方法类型:

class ArrayOfEnum(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')))

)

此类型不作为内置类型包含,因为它将与突然决定在新版本中直接支持ENUM的ARRAY的DBAPI不兼容。

PostgreSQL数据类型

与所有的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, NUMERIC, OID, REAL, SMALLINT, TEXT, \
    TIME, TIMESTAMP, UUID, VARCHAR, INT4RANGE, INT8RANGE, NUMRANGE, \
    DATERANGE, TSRANGE, TSTZRANGE, TSVECTOR

特定于PostgreSQL的类型,或者具有特定于PostgreSQL的构造参数,如下所示:

class sqlalchemy.dialects.postgresql。 aggregate_order_by target T5> ) T6> ¶ T7>

基础: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中的新功能

也可以看看

array_agg

class sqlalchemy.dialects.postgresql.array(clauses, **kw)

基础:sqlalchemy.sql.expression.Tuple

一个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)

0.8版新增:添加了array文字类型。

也可以看看:

postgresql.ARRAY

class sqlalchemy.dialects.postgresql.ARRAY(item_type, as_tuple=False, dimensions=None, zero_indexes=False)

基础:sqlalchemy.sql.expression.SchemaEventTargetsqlalchemy.types.ARRAY

Postgresql ARRAY类型。

在版本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 class also provides PostgreSQL-specific methods for containment operations, including postgresql.ARRAY.Comparator.contains() postgresql.ARRAY.Comparator.contained_by(), and postgresql.ARRAY.Comparator.overlap(), e.g.:

mytable.c.data.contains([1, 2])

所有PostgreSQL DBAPI可能不支持postgresql.ARRAY类型;目前只知道在psycopg2上工作。

此外,postgresql.ARRAY类型不能直接与ENUM类型结合使用。有关解决方法,请参阅Using ENUM with ARRAY中的特殊类型。

也可以看看

types.ARRAY - 基本数组类型

postgresql.array - produces a literal array value.

class Comparator expr

基础:sqlalchemy.types.Comparator

定义ARRAY的比较操作。

请注意,这些操作除了由types.ARRAY.Comparator类提供的操作之外,还包括types.ARRAY.Comparator.any()types.ARRAY.Comparator.all()

contained_by T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试元素是否是参数数组表达式的元素的适当子集。

包含 其他** kwargs >

布尔表达式。测试元素是否是参数数组表达式元素的超集。

重叠 T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试数组是否具有与参数数组表达式相同的元素。

ARRAY tt> item_typeas_tuple = False尺寸=无zero_indexes = False

构建一个ARRAY。

例如。:

Column('myarray', ARRAY(Integer))

参数是:

参数:
  • item_type – The data type of items of this array. 请注意,这里的维度是不相关的,因此像INTEGER[][]这样的多维数组被构造为ARRAY(Integer),而不是ARRAY(ARRAY(Integer))等等。
  • as_tuple=False – Specify whether return results should be converted to tuples from lists. 诸如psycopg2的DBAPI默认返回列表。当元组返回时,结果是可散列的。
  • dimensions – if non-None, the ARRAY will assume a fixed number of dimensions. This will cause the DDL emitted for this ARRAY to include the exact number of bracket clauses [], and will also optimize the performance of the type overall. 请注意,PG数组总是隐含的“无量纲”,这意味着无论它们是如何声明的,它们都可以存储任意数量的维度。
  • zero_indexes = False -

    当为True时,索引值将在基于Python的零和基于Postgresql one的索引之间转换。在传递到数据库之前,所有索引值都会添加一个值。

    版本0.9.5中的新功能

sqlalchemy.dialects.postgresql.array_agg(*arg, **kw)

确保返回类型是postgresql.ARRAY,而不是普通的types.ARRAY类型的array_agg的Postgresql特定形式。

版本1.1中的新功能

sqlalchemy.dialects.postgresql.Any(other, arrexpr, operator=<built-in function eq>)

ARRAY.Comparator.any()方法的同义词。

这种方法是遗留的,在这里是为了向后兼容。

也可以看看

expression.any_()

sqlalchemy.dialects.postgresql.All(other, arrexpr, operator=<built-in function eq>)

ARRAY.Comparator.all()方法的同义词。

这种方法是遗留的,在这里是为了向后兼容。

也可以看看

expression.all_()

class sqlalchemy.dialects.postgresql.BIT(length=None, varying=False)

基础:sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.postgresql.BYTEA(length=None)

基础:sqlalchemy.types.LargeBinary

__初始化__ T0> ( T1> 长度=无 T2> ) T3> ¶ T4>
inherited from the __init__() method of LargeBinary

构建一个LargeBinary类型。

参数:length – optional, a length for the column for use in DDL statements, for those binary types that accept a length, such as the MySQL BLOB type.
class sqlalchemy.dialects.postgresql。 CIDR

基础:sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.postgresql.DOUBLE_PRECISION(precision=None, asdecimal=False, decimal_return_scale=None, **kwargs)

基础:sqlalchemy.types.Float

__init__(precision=None, asdecimal=False, decimal_return_scale=None, **kwargs)
inherited from the __init__() method of Float

构建一个浮动。

参数:
  • precision – the numeric precision for use in DDL CREATE TABLE.
  • asdecimal – the same flag as that of Numeric, but defaults to False. 请注意,将此标志设置为True会导致浮点转换。
  • decimal_return_scale -

    从浮点数转换为Python小数时使用的默认缩放比例。由于十进制的不准确性,浮点值通常会长得多,而且大多数浮点数据库类型没有“scale”的概念,所以默认情况下float类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意,如果未指定,那么包含“scale”的MySQL浮点类型将使用“scale”作为decimal_return_scale的默认值。

    版本0.9.0中新增。

  • ** kwargs - 不建议使用。这里的其他参数被默认的Float类型忽略。对于支持额外参数的特定于数据库的浮点数,请参阅该方言的文档以获取详细信息,例如sqlalchemy.dialects.mysql.FLOAT
class sqlalchemy.dialects.postgresql.ENUM(*enums, **kw)

基础:sqlalchemy.types.Enum

Postgresql的ENUM类型。

这是types.Enum的一个子类,它包括对PG的CREATE TYPEDROP TYPE

当使用内置类型types.Enum并且Enum.native_enum标志保留为默认值时,Postgresql后端将使用postgresql.ENUM

ENUM的创建/删除行为必然是错综复杂的,因为ENUM类型与父表关系的关系很尴尬,因为它可能仅由一个表“拥有”,或者可能在许多表中共享。

When using types.Enum or postgresql.ENUM in an “inline” fashion, the CREATE TYPE and DROP TYPE is emitted corresponding to when the Table.create() and Table.drop() methods are called:

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.Enumpostgresql.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的情况下发送CREATE TABLE仍然会导致问题:

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)

在版本1.0.0中更改:现在,Postgresql postgresql.ENUM类型对于CREATE / DROP的行为更为严格。除了table.create(checkfirst=True)之外,元数据级ENUM类型只能在元数据级别而不是表级别创建和删除。The table.drop() call will now emit a DROP TYPE for a table-level enumerated type.

__init__(*enums, **kw)

构建一个ENUM

参数与types.Enum的参数相同,但也包括以下参数。

参数: create_type -

默认为True。Indicates that CREATE TYPE should be emitted, after optionally checking for the presence of the type, when the parent table is being created; and additionally that DROP TYPE is called when the table is dropped. When False, no check will be performed and no CREATE TYPE or DROP TYPE is emitted, unless create() or drop() are called directly. create()drop()中调用一个创建方案到一个没有访问实际数据库的SQL文件时,设置为False方法可用于将SQL发送到目标绑定。

0.7.4版本的新功能

create(bind=None, checkfirst=True)

Emit CREATE TYPE for this ENUM.

如果底层方言不支持Postgresql CREATE TYPE,则不采取任何操作。

参数:
  • bind – a connectable Engine, Connection, or similar object to emit SQL.
  • checkfirst – if True, a query against the PG catalog will be first performed to see if the type does not exist already before creating.
drop(bind=None, checkfirst=True)

Emit DROP TYPE for this ENUM.

如果底层方言不支持Postgresql DROP TYPE,则不采取任何操作。

参数:
  • bind – a connectable Engine, Connection, or similar object to emit SQL.
  • checkfirst – if True, a query against the PG catalog will be first performed to see if the type actually exists before dropping.
class sqlalchemy.dialects.postgresql。 HSTORE text_type = None ) T5> ¶ T6>

基础:sqlalchemy.types.Indexablesqlalchemy.types.Concatenablesqlalchemy.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 provides for a wide range of operations, including:

  • 索引操作:

    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扩展名时,除非该字典值被重新分配给HSTORE属性本身,否则ORM不会被提示对现有字典的内容进行任何更改,从而产生变化事件。

0.8版本中的新功能

也可以看看

hstore - render the Postgresql hstore() function.

class Comparator expr

基础:sqlalchemy.types.Comparatorsqlalchemy.types.Comparator

定义HSTORE的比较操作。

阵列 T0> ( T1> ) T2> ¶ T3>

文本数组表达式。返回交替键和值的数组。

contained_by T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试键是否是参数jsonb表达式的键的正确子集。

包含 其他** kwargs >

布尔表达式。测试键(或数组)是否是包含参数jsonb表达式的键的超集。

定义 T0> ( T1> 键 T2> ) T3> ¶ T4>

布尔表达式。测试密钥是否存在非NULL值。请注意,该键可能是一个SQLA表达式。

删除 T0> ( T1> 键 T2> ) T3> ¶ T4>

HStore表达式。返回此hstore的内容,删除给定的密钥。请注意,该键可能是一个SQLA表达式。

has_all T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试jsonb中所有键的存在

has_any T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试jsonb中是否存在任何密钥

对象的has_key T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试密钥的存在。请注意,该键可能是一个SQLA表达式。

键 T0> ( T1> ) T2> ¶ T3>

文本数组表达式。返回键数组。

矩阵 T0> ( T1> ) T2> ¶ T3>

文本数组表达式。返回[key,value]对的数组。

片 T0> ( T1> 阵列 T2> ) T3> ¶ T4>

HStore表达式。返回由key数组定义的hstore的子集。

瓦尔斯 T0> ( T1> ) T2> ¶ T3>

文本数组表达式。返回值数组。

HSTORE。 T0> __初始化__ T1> ( T2> text_type =无 T3> ) T4> ¶ T5 >

构建一个新的HSTORE

参数: text_type -

应该用于索引值的类型。默认为types.Text

版本1.1.0新增

HSTORE。 T0> comparator_factory T1> ¶ T2>

Comparator的别名

class sqlalchemy.dialects.postgresql.hstore(*args, **kwargs)

基础:sqlalchemy.sql.functions.GenericFunction

使用Postgresql hstore()函数在SQL表达式内构建一个hstore值。

The hstore function accepts one or two arguments as described in the Postgresql documentation.

例如。:

from sqlalchemy.dialects.postgresql import array, hstore

select([hstore('key1', 'value1')])

select([
        hstore(
            array(['key1', 'key2', 'key3']),
            array(['value1', 'value2', 'value3'])
        )
    ])

0.8版本中的新功能

也可以看看

HSTORE - the Postgresql HSTORE datatype.

型 T0> ¶ T1>

HSTORE的别名

class sqlalchemy.dialects.postgresql。 INET

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.postgresql。 INTERVAL precision = None ) T5> ¶ T6>

基础:sqlalchemy.types.TypeEngine

Postgresql INTERVAL类型。

所有DBAPI可能不支持INTERVAL类型。已知在psycopg2上工作,而不是在pg8000或zxjdbc上工作。

class sqlalchemy.dialects.postgresql。 JSON none_as_null = False astext_type =无 T5> ) T6> ¶ T7>

基础:sqlalchemy.types.JSON

表示Postgresql JSON类型。

这种类型是核心级types.JSON类型的特化。请务必阅读types.JSON的文档以获取有关处理NULL值和ORM使用的重要提示。

在版本1.1中改变: postgresql.JSON现在是新的types.JSON类型的特定于Postgresql的特化。

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 - >&gt;> ['some key' t4> AS &lt; type&gt;)):

    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中更改: JSON对象上的ColumnElement.cast()运算符现在要求明确调用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方言时,使用psycopg2.extras.register_default_json对数据库注册json_deserializer。

也可以看看

types.JSON - 核心级JSON类型

JSONB

class Comparator expr

基础:sqlalchemy.types.Comparator

定义JSON的比较操作。

astext T0> ¶ T1>

在索引表达式中,在SQL中呈现时,使用“astext”(例如“ - >>”)转换。

例如。:

select([data_table.c.data['some key'].astext])

也可以看看

ColumnElement.cast()

JSON tt> __ init __ none_as_null = Falseastext_type =无 ) T5> ¶ T6>

构建一个JSON类型。

参数:
  • none_as_null -

    如果为True,则将None值保留为SQL NULL值,而不是null的JSON编码。请注意,如果此标志为False,则仍然可以使用null()构造来保留NULL值:

    from sqlalchemy import null
    conn.execute(table.insert(), data=null())

    更改为0.9.8版: - 增加了none_as_null,并且现在支持null()以保留NULL值。

    也可以看看

    JSON.NULL

  • astext_type -

    在索引属性上用于JSON.Comparator.astext访问器的类型。默认为types.Text

    版本1.1中的新功能

JSON。 T0> comparator_factory T1> ¶ T2>

Comparator的别名

class sqlalchemy.dialects.postgresql。 JSONB none_as_null = False astext_type =无 T5> ) T6> ¶ T7>

基础:sqlalchemy.dialects.postgresql.json.JSON

表示Postgresql JSONB类型。

The JSONB type stores arbitrary JSONB format data, e.g.:

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提供的所有操作,包括索引操作的相同行为。It also adds additional operators specific to JSONB, including JSONB.Comparator.has_key(), JSONB.Comparator.has_all(), JSONB.Comparator.has_any(), JSONB.Comparator.contains(), and JSONB.Comparator.contained_by().

JSON类型类似,除非sqlalchemy.ext.mutable扩展名使用,否则JSONB类型不检测与ORM一起使用的就地更改用来。

自定义序列化器和反序列化器使用json_serializerjson_deserializer关键字参数与JSON类共享。这些必须使用create_engine()在方言级别指定。当使用psycopg2时,序列化器使用基于每个连接的psycopg2.extras.register_default_jsonb与jsonb类型相关联,与psycopg2.extras.register_default_json相同用于使用json类型注册这些处理程序。

新版本0.9.7.

也可以看看

JSON

class Comparator expr

基础:sqlalchemy.dialects.postgresql.json.Comparator

定义JSON的比较操作。

contained_by T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试键是否是参数jsonb表达式的键的正确子集。

包含 其他** kwargs >

布尔表达式。测试键(或数组)是否是包含参数jsonb表达式的键的超集。

has_all T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试jsonb中所有键的存在

has_any T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试jsonb中是否存在任何密钥

对象的has_key T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。测试密钥的存在。请注意,该键可能是一个SQLA表达式。

JSONB。 T0> comparator_factory T1> ¶ T2>

Comparator的别名

class sqlalchemy.dialects.postgresql。 MACADDR

基础:sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.postgresql。 OID

基础:sqlalchemy.types.TypeEngine

提供Postgresql OID类型。

版本0.9.5中的新功能

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.postgresql.REAL(precision=None, asdecimal=False, decimal_return_scale=None, **kwargs)

基础:sqlalchemy.types.Float

SQL REAL类型。

__init__(precision=None, asdecimal=False, decimal_return_scale=None, **kwargs)
inherited from the __init__() method of Float

构建一个浮动。

参数:
  • precision – the numeric precision for use in DDL CREATE TABLE.
  • asdecimal – the same flag as that of Numeric, but defaults to False. 请注意,将此标志设置为True会导致浮点转换。
  • decimal_return_scale -

    从浮点数转换为Python小数时使用的默认缩放比例。由于十进制的不准确性,浮点值通常会长得多,而且大多数浮点数据库类型没有“scale”的概念,所以默认情况下float类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意,如果未指定,那么包含“scale”的MySQL浮点类型将使用“scale”作为decimal_return_scale的默认值。

    版本0.9.0中新增。

  • ** kwargs - 不建议使用。这里的其他参数被默认的Float类型忽略。对于支持额外参数的特定于数据库的浮点数,请参阅该方言的文档以获取详细信息,例如sqlalchemy.dialects.mysql.FLOAT
class sqlalchemy.dialects.postgresql。 TSVECTOR

基础:sqlalchemy.types.TypeEngine

postgresql.TSVECTOR类型实现了Postgresql文本搜索类型TSVECTOR。

它可以用来对自然语言文档进行全文查询。

版本0.9.0中新增。

也可以看看

Full Text Search

__初始化__ T0> ¶ T1>
inherited from the __init__ attribute of object

x .__ init __(...)初始化x;请参阅帮助(键入(x))进行签名

class sqlalchemy.dialects.postgresql.UUID(as_uuid=False)

基础:sqlalchemy.types.TypeEngine

Postgresql UUID类型。

表示UUID列类型,可以将数据解释为由DBAPI本机返回或作为Python uuid对象。

所有DBAPI可能不支持UUID类型。已知psycopg2而不是pg8000。

__初始化__ T0> ( T1> as_uuid =假 T2> ) T3> ¶ T4>

构建一个UUID类型。

参数:as_uuid=False – if True, values will be interpreted as Python uuid objects, converting to/from string via the DBAPI.

范围类型

PostgreSQL 9.2以后的新的范围列类型可以通过以下类型来实现:

class sqlalchemy.dialects.postgresql。 INT4RANGE

基础:sqlalchemy.dialects.postgresql.ranges.RangeOperatorssqlalchemy.types.TypeEngine

表示Postgresql的INT4RANGE类型。

0.8.2版本中的新功能

class sqlalchemy.dialects.postgresql。 INT8RANGE

基础:sqlalchemy.dialects.postgresql.ranges.RangeOperatorssqlalchemy.types.TypeEngine

表示Postgresql INT8RANGE类型。

0.8.2版本中的新功能

class sqlalchemy.dialects.postgresql。 NUMRANGE

基础:sqlalchemy.dialects.postgresql.ranges.RangeOperatorssqlalchemy.types.TypeEngine

表示Postgresql的NUMRANGE类型。

0.8.2版本中的新功能

class sqlalchemy.dialects.postgresql。 DATERANGE

基础:sqlalchemy.dialects.postgresql.ranges.RangeOperatorssqlalchemy.types.TypeEngine

表示Postgresql DATERANGE类型。

0.8.2版本中的新功能

class sqlalchemy.dialects.postgresql。 TSRANGE

基础:sqlalchemy.dialects.postgresql.ranges.RangeOperatorssqlalchemy.types.TypeEngine

表示Postgresql TSRANGE类型。

0.8.2版本中的新功能

class sqlalchemy.dialects.postgresql。 TSTZRANGE

基础:sqlalchemy.dialects.postgresql.ranges.RangeOperatorssqlalchemy.types.TypeEngine

表示Postgresql TSTZRANGE类型。

0.8.2版本中的新功能

上面的类型从下面的mixin中获得了大部分的功能:

class sqlalchemy.dialects.postgresql.ranges。 RangeOperators

该混合为范围函数和操作符的postgres文档的表9-44中列出的范围操作符提供了功能。它被postgres方言中提供的所有范围类型使用,并可能用于您自己创建的任何范围类型。

对postgres文档的表9-45中列出的范围函数没有提供额外的支持。对于这些,应该使用正常的func()对象。

0.8.2版新增功能:支持Postgresql RANGE操作。

class comparator_factory expr

基础:sqlalchemy.types.Comparator

定义范围类型的比较操作。

__ NE __ T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果两个范围不相等,则返回true

adjacent_to T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列中的范围与操作数中的范围相邻,则返回true。

contained_by T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列包含在右侧操作数中,则返回true。

包含 其他** kw >

布尔表达式。如果右侧操作数(可以是元素或范围)包含在列中,则返回true。

not_extend_left_of T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列中的范围不在操作数范围的左侧,则返回true。

not_extend_right_of T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列中的范围不扩展到操作数范围的右侧,则返回true。

重叠 T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列重叠(与右边的操作数有共同点),则返回true。

strictly_left_of T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列严格留在右侧操作数上,则返回true。

strictly_right_of T0> ( T1> 其他 T2> ) T3> ¶ T4>

布尔表达式。如果列严格右手边操作数的右边,则返回true。

警告

范围类型DDL支持应该适用于任何Postgres DBAPI驱动程序,但返回的数据类型可能会有所不同。如果您使用psycopg2,建议在使用这些列类型之前升级到版本2.5或更高版本。

在实例化使用这些列类型的模型时,您应该传递您为列类型使用的DBAPI驱动程序所期望的任何数据类型。对于psycopg2这些是NumericRangeDateRangeDateTimeRangeDateTimeTZRange已经用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)
)

PostgreSQL约束类型

SQLAlchemy通过ExcludeConstraint类支持Postgresql EXCLUDE约束:

class sqlalchemy.dialects.postgresql.ExcludeConstraint(*elements, **kw)

基础:sqlalchemy.schema.ColumnCollectionConstraint

表级EXCLUDE约束。

定义一个EXCLUDE约束,如postgres文档中所述。

__init__(*elements, **kw)
参数:
  • *elements – A sequence of two tuples of the form (column, operator) where column must be a column name or Column object and operator must be a string containing the operator to use.
  • name – Optional, the in-database name of this constraint.
  • 可延迟 - 可选的bool。如果设置,则在为此约束发出DDL时发出DEFERRABLE或NOT DEFERRABLE。
  • 最初 - 可选字符串。如果设置,则在为此约束发出DDL时发出INITIALLY
  • 使用 - 可选字符串。如果设置,则在为此约束发出DDL时发出USING 。 T0>默认为“主旨”。
  • where – Optional string. 如果设置,则在为此约束发出DDL时发出WHERE

例如:

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构造

sqlalchemy.dialects.postgresql.dml.insert(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

构建一个新的Insert对象。

这个构造函数被镜像为公共API函数;有关完整的用法和参数说明,请参见insert()

class 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

INSERT的PostgreSQL特定的实现。

为诸如ON CONFLICT之类的PG特定语法添加方法。

版本1.1中的新功能

排除 T0> ¶ T1>

为ON CONFLICT语句提供excluded名称空间

PG的ON CONFLICT子句允许引用将被插入的行,被称为excluded此属性提供此行中的所有列以供引用。

也可以看看

INSERT...ON CONFLICT (Upsert) - 如何使用Insert.excluded

on_conflict_do_nothing 约束=无index_elements =无index_where =无 ) T5> ¶ T6>

为ON CONFLICT子句指定DO NOTHING操作。

constraintindex_elements参数是可选的,但只能指定其中的一个参数。

参数: 约束 -

表上的唯一或排除约束的名称,或约束对象本身(如果它具有.name属性)。

参数: index_elements -

由字符串列名,Column对象或将用于推断目标索引的其他列表达式对象组成的序列。

参数: index_where -

额外的WHERE标准可以用来推断一个条件目标索引。

版本1.1中的新功能

on_conflict_do_update(constraint=None, index_elements=None, index_where=None, set_=None, where=None)

指定ON CONFLICT子句的DO UPDATE SET操作。

参数constraintindex_elements是必需的,但只能指定其中的一个。

参数: 约束 -

表上的唯一或排除约束的名称,或约束对象本身(如果它具有.name属性)。

参数: index_elements -

由字符串列名,Column对象或将用于推断目标索引的其他列表达式对象组成的序列。

参数: index_where -

额外的WHERE标准可以用来推断一个条件目标索引。

参数: set _ -

必需的参数。字典或其他映射对象,列名称作为键和表达式或文字作为值,指定要执行的SET动作。

警告

这个字典并不考虑Python指定的默认UPDATE值或生成函数,例如。使用Column.onupdate指定的那些。除非在Insert.on_conflict_do_update.set_字典中手动指定这些值,否则这些值不会用于ON CONFLICT样式的UPDATE。

参数: 其中 -

可选参数。If present, can be a literal SQL string or an acceptable expression for a WHERE clause that restricts the rows affected by DO UPDATE SET. 行不符合WHERE条件将不被更新(对于这些行,实际上是一个DO NOTHING)。

版本1.1中的新功能

psycopg2 ¶ T0>

通过psycopg2驱动程序支持PostgreSQL数据库。

DBAPI ¶ T0>

psycopg2的文档和下载信息(如果适用)可在以下网址获得:http://pypi.python.org/pypi/psycopg2/

连接¶ T0>

连接字符串:

postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]

psycopg2连接参数

create_engine()接受的psycopg2特定的关键字参数是:

  • server_side_cursors:为支持此功能的SQL语句启用“服务器端游标”。从psycopg2的观点来看,这实质上意味着游标是使用名称创建的,例如, connection.cursor('some name'),其结果是结果行不会在语句执行后立即被预取和缓冲,而是留在服务器上,只根据需要进行检索。当启用此功能时,SQLAlchemy的ResultProxy使用特殊的行缓冲行为,从而一次可以获取100行的组,以减少会话开销。请注意,stream_results=True执行选项是以每个执行为基础启用此模式的更有针对性的方式。

  • use_native_unicode是默认的。

  • isolation_level: This option, available for all PostgreSQL dialects, includes the AUTOCOMMIT isolation level when using the psycopg2 dialect.

  • client_encoding: sets the client encoding in a libpq-agnostic way, using psycopg2’s set_client_encoding() method.

    也可以看看

    Unicode with Psycopg2

Unix域连接

psycopg2支持通过Unix域连接进行连接。当URL的host部分被省略时,SQLAlchemy将None传递给psycopg2,psycopg2指定了Unix域通信而不是TCP / IP通信:

create_engine("postgresql+psycopg2://user:password@/dbname")

默认情况下,使用的套接字文件是连接到/tmp中的Unix域套接字,或者是在构建PostgreSQL时指定的任何套接字目录。通过使用host作为附加关键字参数传递路径名到psycopg2,可以覆盖该值。

create_engine("postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql")

也可以看看:

PQconnectdbParams T0>

每个语句/连接执行选项

Connection.execution_options()Executable.execution_options()Query.execution_options()一起使用时,会遵守以下DBAPI特定的选项。除了那些不是特定于DBAPI的:

  • isolation_level - 为Connection的生命周期设置事务隔离级别(只能在连接上设置,而不能在语句或查询中设置)。请参阅Psycopg2 Transaction Isolation Level

  • stream_results - 启用或禁用psycopg2服务器端游标的使用 - 此功能使用“命名”游标与特殊结果处理方法结合使用,以便结果行不被完全缓冲。如果None或未设置,则使用Engineserver_side_cursors选项。

  • max_row_buffer - 使用stream_results时,是一个整数值,指定一次缓冲的最大行数。这由BufferedRowResultProxy解释,如果省略,缓冲区将增长,最终一次存储1000行。

    新版本1.0.6.

Unicode与Psycopg2

默认情况下,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将根据传递给create_engine()使用client_encoding参数的值在所有新连接上调用psycopg2的connection.set_client_encoding()

# set_client_encoding() setting;
# works for *all* Postgresql versions
engine = create_engine("postgresql://user:pass@host/dbname",
                       client_encoding='utf8')

这将覆盖Postgresql客户端配置中指定的编码。When using the parameter in this way, the psycopg2 driver emits SET client_encoding TO 'utf8' on the connection explicitly, and works in all Postgresql versions.

请注意,传递给create_engine()client_encoding设置与最近添加的client_encoding参数不同现在直接由libpq支持。client_encoding直接传递给psycopg2.connect(),并且使用create_engine.connect_args参数从SQLAlchemy传递时,

# libpq direct parameter setting;
# only works for Postgresql **9.1 and above**
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中,所以使用前面的方法更适合跨版本的支持。

禁用本机Unicode

还可以指示SQLAlchemy跳过psycopg2 UNICODE扩展名的使用,而使用自己的unicode编码/解码服务,这些服务通常只保留给那些不直接完全支持unicode的DBAPI。use_native_unicode=False传递给create_engine()将禁止使用psycopg2.extensions.UNICODESQLAlchemy将使用create_engine() encoding参数的值,将数据本身编码为Python中的字节串,并在返回的字节中强制返回,默认值为utf-8由于大多数DBAPI现在完全支持unicode,所以SQLAlchemy自己的unicode编码/解码功能正在逐渐过时。

绑定参数样式

psycopg2方言的默认参数样式是“pyformat”,其中SQL使用%(paramname)s样式呈现。这种格式有其局限性,它不适应实际上包含百分号或括号符号的参数名称的不寻常情况;因为SQLAlchemy在许多情况下会根据列的名称生成绑定参数名称,所以在列名中出现这些字符会导致问题。

对于schema.Column的问题有两种解决方案,其名称中包含这些字符之一。一个是为具有这种名称的列指定schema.Column.key

measurement = Table('measurement', metadata,
    Column('Size (meters)', Integer, key='size_meters')
)

Above, an INSERT statement such as measurement.insert() will use size_meters as the parameter name, and a SQL expression such as measurement.c.size_meters > 10 will derive the bound parameter name from the size_meters key as well.

版本1.0.0更改: - 当SQL表达式中创建匿名绑定参数时,SQL表达式将使用Column.key作为命名的来源;此前,此行为仅适用于Table.insert()Table.update()参数名称。

另一种解决方案是使用位置格式; psycopg2允许使用“格式”参数样式,它可以传递给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, )

如上所述,字典样式被转换成具有位置样式的元组。

交易¶ T0>

psycopg2方言完全支持SAVEPOINT和两阶段提交操作。

Psycopg2事务隔离级别

As discussed in Transaction Isolation Level, all Postgresql dialects support setting of transaction isolation level both via the isolation_level parameter passed to create_engine(), as well as the isolation_level argument used by Connection.execution_options(). 当使用psycopg2方言时,这些选项使用psycopg2的set_isolation_level()连接方法,而不是发出Postgresql指令;这是因为在任何情况下,psycopg2的API级别设置总是在每个事务开始时发出。

psycopg2方言支持这些常量的隔离级别:

  • READ COMMITTED
  • READ UNCOMMITTED
  • REPEATABLE READ
  • SERIALIZABLE
  • AUTOCOMMIT

0.8.2版新增:在使用psycopg2时支持AUTOCOMMIT隔离级别。

注意记录

psycopg2方言将通过sqlalchemy.dialects.postgresql记录器记录Postgresql NOTICE消息:

import logging
logging.getLogger('sqlalchemy.dialects.postgresql').setLevel(logging.INFO)

HSTORE类型

psycopg2 DBAPI包含一个本地处理HSTORE类型编组的扩展。当使用psycopg2版本2.4或更高版本时,SQLAlchemy psycopg2方言将在默认情况下启用此扩展,并且检测到目标数据库具有设置为使用的HSTORE类型。换句话说,当方言进行第一次连接时,执行如下的一个序列:

  1. 使用psycopg2.extras.HstoreAdapter.get_oids()请求可用的HSTORE oid。如果这个函数返回一个HSTORE标识符列表,那么我们确定存在HSTORE扩展名。This function is skipped if the version of psycopg2 installed is less than version 2.4.
  2. If the use_native_hstore flag is at its default of True, and we’ve detected that HSTORE oids are available, the psycopg2.extensions.register_hstore() extension is invoked for all connections.

无论SQL中的目标列的类型如何,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类型它仅仅意味着Python字典和HSTORE字符串格式之间的强制,在参数端和结果端都将在SQLAlchemy自己的编组逻辑中发生,而不是psycopg2,可能更多高性能。

pg8000 ¶ T0>

通过pg8000驱动程序支持PostgreSQL数据库。

DBAPI ¶ T0>

有关pg8000的文档和下载信息(如果适用),请访问:https://pythonhosted.org/pg8000/

连接¶ T0>

连接字符串:

postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...]

Unicode的¶ T0>

pg8000将使用PostgreSQL client_encoding参数对它和服务器之间的字符串值进行编码/解码;默认情况下,这是postgresql.conf文件中的值,通常默认为SQL_ASCII通常,这可以更改为utf-8,作为更有用的默认值:

#client_encoding = sql_ascii # actually, defaults to database
                             # encoding
client_encoding = utf8

通过执行SQL,client_encoding可以为会话重写:

将CLIENT_ENCODING设置为“utf8”;

SQLAlchemy将基于使用client_encoding参数传递给create_engine()的所有新连接执行此SQL:

engine = create_engine(
    "postgresql+pg8000://user:pass@host/dbname", client_encoding='utf8')

pg8000事务隔离级别

pg8000方言提供与psycopg2方言相同的隔离级别设置:

  • READ COMMITTED
  • READ UNCOMMITTED
  • REPEATABLE READ
  • SERIALIZABLE
  • AUTOCOMMIT

0.9.5版新增:在使用pg8000时支持AUTOCOMMIT隔离级别。

psycopg2cffi ¶ T0>

通过psycopg2cffi驱动程序支持PostgreSQL数据库。

DBAPI ¶ T0>

psycopg2cffi的文档和下载信息(如果适用)可在以下网址获得:http://pypi.python.org/pypi/psycopg2cffi/

连接¶ T0>

连接字符串:

postgresql+psycopg2cffi://user:password@host:port/dbname[?key=value&key=value...]

psycopg2cffi is an adaptation of psycopg2, using CFFI for the C layer. 这使得它适用于例如PyPy。文档符合psycopg2

版本1.0.0中的新功能

PY-的PostgreSQL ¶ T0>

通过py-postgresql驱动程序支持PostgreSQL数据库。

DBAPI ¶ T0>

Documentation and download information (if applicable) for py-postgresql is available at: http://python.projects.pgfoundry.org/

连接¶ T0>

连接字符串:

postgresql+pypostgresql://user:password@host:port/dbname[?key=value&key=value...]

pygresql ¶ T0>

通过pygresql驱动程序支持PostgreSQL数据库。

DBAPI ¶ T0>

有关pygresql的文档和下载信息(如果适用)可在以下网址获得:http://www.pygresql.org/

连接¶ T0>

连接字符串:

postgresql+pygresql://user:password@host:port/dbname[?key=value&key=value...]

zxjdbc ¶ T0>

通过zxJDBC为Jython驱动程序支持PostgreSQL数据库。

DBAPI ¶ T0>

这个数据库的驱动程序可以在http://jdbc.postgresql.org/找到

连接¶ T0>

连接字符串:

postgresql+zxjdbc://scott:tiger@localhost/db