的PostgreSQL ¶ T0>

支持PostgreSQL数据库。

DBAPI支持¶

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

• psycopg2 T0>
• pg8000 T0>
• psycopg2cffi T0>
• PY-的PostgreSQL T0>
• pygresql T0>
• Jython的zxJDBC

序列/ 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

要改变反射的行为，使得不管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。

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)

两种方法都使用命名约束或列推断来提供冲突的“目标”：

• The Insert.on_conflict_do_update.index_elements argument specifies a sequence containing string column names, Column objects, and/or SQL expression elements, which would identify a unique index:

  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')
  )

• Insert.on_conflict_do_update.constraint参数也可以引用表示约束的SQLAlchemy构造，例如， UniqueConstraint，PrimaryKeyConstraint，Index或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)

为了引用建议的插入行，特殊别名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，它会跳过INSERT， ：

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)

全文检索¶

SQLAlchemy makes available the Postgresql @@ operator via the ColumnElement.match() method on any textual column expression. 在Postgresql方言中，表达式如下所示：

select([sometable.c.text.match("search string")])

将发射到数据库：

SELECT text @@ to_tsquery('search string') FROM table

使用标准的func结构显式使用Postgresql文本搜索函数，如to_tsquery()和to_tsvector()。例如：

select([
    func.to_tsvector('fat cats ate rats').match('cat & rat')
])

发出相当于：

SELECT to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat')

postgresql.TSVECTOR类型可以提供显式CAST：

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中的全文搜索受以下组合的影响：default_text_search_config的PostgresSQL设置，用于构建GIN / GiST索引的regconfig以及regconfig

对具有已经预先计算的GIN或GiST索引的列执行全文搜索时（全文搜索中常见），可能需要显式传递特定的PostgresSQL 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')

建议您使用PostgresSQL的EXPLAIN ANALYZE ...工具，以确保您使用SQLAlchemy生成查询，以充分利用您可能为全文搜索创建的任何索引。

仅从... ¶

该方言支持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('my_index', my_table.c.id, postgresql_where=tbl.c.value > 10)

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

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

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

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

tbl = Table('testtbl', m, Column('data', Integer))

idx1 = Index('test_idx1', tbl.c.data, postgresql_concurrently=True)

CREATE INDEX CONCURRENTLY test_idx1 ON testtbl (data)

DROP INDEX CONCURRENTLY test_idx1

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.

特殊反射选项¶

用于Postgresql后端的Inspector是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())

class sqlalchemy.dialects.postgresql.base。 PGInspector （ conn ） T5> ¶ T6>

基础：sqlalchemy.engine.reflection.Inspector

get_enums T0> （ T1> 架构=无 T2> ） T3> ¶ T4>

返回ENUM对象的列表。

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

• 名称 - 枚举的名称
• 模式 - 枚举的模式名称。
• visible - 布尔值，无论此枚举是否在默认搜索路径中可见。
• 标签 - 适用于枚举的字符串标签列表。

参数：	架构 ¶ - 架构名称。如果没有，则使用默认模式（通常是“公共”）。也可以设置为'*'来表示所有模式的加载枚举。

版本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_name，schema =无 ） t5 >

返回给定表名称的OID。

get_view_names （ schema = None，include =（'plain'，'materialized' T4> ） T5> ¶ T6>

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

参数：	schema¶ – Optional, retrieve names from a non-default schema. 对于特殊引用，请使用quoted_name。 include ¶ - 指定要返回哪些类型的视图。作为字符串值（对于单一类型）或元组（对于任意数量的类型）传递。默认为（'plain'， 'materialized'）。 版本1.1中的新功能

PostgreSQL表选项¶

PostgreSQL方言结合Table结构直接支持CREATE 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", ...))

ARRAY类型¶

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

• postgresql.ARRAY - ARRAY数据类型
• postgresql.array - 数组字面量
• postgresql.array_agg() - ARRAY_AGG SQL函数
• postgresql.aggregate_order_by - PG的ORDER BY聚合函数语法的助手。

JSON类型¶

Postgresql方言支持JSON和JSONB数据类型，包括psycopg2的本地支持和对Postgresql所有特殊操作符的支持：

• postgresql.JSON
• postgresql.JSONB

HSTORE类型¶

支持Postgresql HSTORE类型以及hstore字面值：

• postgresql.HSTORE - HSTORE数据类型
• postgresql.hstore - hstore文字

ENUM类型¶

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

• postgresql.ENUM - DDL并输入ENUM的支持。
• PGInspector.get_enums() - 检索当前ENUM类型的列表
• postgresql.ENUM.create() , postgresql.ENUM.drop() - individual CREATE and DROP commands for ENUM.

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')))

)

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，order_by 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.SchemaEventTarget，sqlalchemy.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 - 产生一个文字数组值。

class 比较器 （ 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> __ init __ （ item_type，as_tuple = False，dimensions =无，zero_indexes = False ） ¶

构建一个ARRAY。

例如。：

Column('myarray', ARRAY(Integer))

参数是：

参数：

item_type ¶ - 此数组项目的数据类型。请注意，这里的维数是不相关的，所以像INTEGER[][]这样的多维数组被构造为ARRAY(Integer)，而不是ARRAY(ARRAY(Integer))等等。 as_tuple = False ¶ - 指定返回结果是否应该从列表转换为元组。诸如psycopg2的DBAPI默认返回列表。当元组返回时，结果是可散列的。 dimensions¶ – if non-None, the ARRAY will assume a fixed number of dimensions. 这将导致为此ARRAY发出的DDL包含确切数量的括号子句[]，并且还会优化整体类型的性能。请注意，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，变化=假 T5> ） T6> ¶ T7>

基础：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 ¶ - 从float到Python小数转换时使用的默认缩放比例。由于十进制不准确性，浮点值通常会长得多，并且大多数浮点数据库类型没有“缩放”的概念，所以默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，包含“scale”的MySQL浮点类型将使用“scale”作为decimal_return_scale的默认值（如果未另外指定）。 版本0.9.0中的新功能 ** kwargs ¶ - 不建议使用。其他参数在这里被默认的Float类型忽略。对于支持附加参数的特定于数据库的浮点数，请参阅该方言的文档以获取详细信息，例如sqlalchemy.dialects.mysql.FLOAT。

class sqlalchemy.dialects.postgresql。 ENUM （ * enums，**千瓦 T5> ） T6> ¶ T7>

基础：sqlalchemy.types.Enum

Postgresql的ENUM类型。

这是types.Enum的一个子类，它包含对PG的CREATE TYPE和DROP TYPE。

当使用内建类型types.Enum并且Enum.native_enum标志保留其默认值为True时，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.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的情况下发送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 ） T5>

构建一个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. 设置为False在创建方案调用SQL文件而不访问实际数据库时很有用 - create()和drop()方法可用于将SQL发送到目标绑定。 New in version 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)¶

基础：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 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 - 呈现Postgresql hstore()函数。

class 比较器 （ expr ） ¶

基础：sqlalchemy.types.Comparator，sqlalchemy.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 T5> ） T6> ¶ T7>

基础：sqlalchemy.sql.functions.GenericFunction

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

hstore函数接受Postgresql文档中描述的一个或两个参数。

例如。：

from sqlalchemy.dialects.postgresql import array, hstore

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

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

0.8版本中的新功能

也可以看看

HSTORE - the Postgresql HSTORE datatype.

型 T0> ¶ T1>

HSTORE的别名

class sqlalchemy.dialects.postgresql。 INET ¶

基础：sqlalchemy.types.TypeEngine

__初始化__ T0> ¶ T1>

继承自 __init__ 属性 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；>＆lt； / t2> ['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 比较器 （ expr ） ¶

基础：sqlalchemy.types.Comparator

为JSON定义比较操作。

astext T0> ¶ T1>

在索引表达式中，使用SQL中呈现时的“astext”（例如“ - >>”）转换。

例如。：

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

也可以看看

ColumnElement.cast()

JSON。 __ init __ （ none_as_null = False，astext_type = None ） 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类型。

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提供的所有操作，包括索引操作的相同行为。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类型类似，当与ORM一起使用时，JSONB类型不检测就地更改，除非sqlalchemy.ext.mutable扩展用来。

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

版本0.9.7中的新功能

也可以看看

JSON

class 比较器 （ 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>

继承自 __init__ 属性 object

x .__ init __（...）初始化x；请参阅帮助（类型（x））进行签名

class sqlalchemy.dialects.postgresql。 OID ¶

基础：sqlalchemy.types.TypeEngine

提供Postgresql OID类型。

版本0.9.5中的新功能

__初始化__ T0> ¶ T1>

继承自 __init__ 属性 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 ¶ - 从float到Python小数转换时使用的默认缩放比例。由于十进制不准确性，浮点值通常会长得多，并且大多数浮点数据库类型没有“缩放”的概念，所以默认情况下，浮点类型在转换时会查找前十个小数位。指定此值将覆盖该长度。请注意，包含“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>

继承自 __init__ 属性 object

x .__ init __（...）初始化x；请参阅帮助（类型（x））进行签名

class sqlalchemy.dialects.postgresql。 UUID （ as_uuid = False ） T5> ¶ T6>

基础：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.

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>默认为'gist'。 其中 ¶ - 可选字符串。如果设置，则在为此约束发出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特定实现。

为特定于PG的语法添加方法，如ON CONFLICT。

版本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操作。

constraint和index_elements参数是可选的，但只能指定其中的一个参数。

参数：	约束 ¶ -

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

参数：	index_elements ¶ -

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

参数：	index_where ¶ -

附加的WHERE标准可用于推断条件目标索引。

版本1.1中的新功能

也可以看看

INSERT...ON CONFLICT (Upsert)

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

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

要么使用constraint或index_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中的新功能

也可以看看

INSERT...ON CONFLICT (Upsert)

psycopg2 ¶ T0>

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

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

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

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

# postgresql.conf file

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

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

# 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")

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

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, )

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

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test",
            use_native_hstore=False)

pg8000 ¶ T0>

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

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

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

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

psycopg2cffi ¶ T0>

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

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。

PY-的PostgreSQL ¶ T0>

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

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

pygresql ¶ T0>

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

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

zxjdbc ¶ T0>

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

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