PostgreSQL — SQLAlchemy 1.3 Documentation

Release: 1.3.20 | Release Date: October 12, 2020

# SQLAlchemy 1.3 Documentation

# PostgreSQL

Support for the PostgreSQL database.

## DBAPI Support

The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.

- psycopg2

- pg8000

- psycopg2cffi

- py-postgresql

- pygresql

- zxJDBC for Jython

## Sequences/SERIAL/IDENTITY

PostgreSQL supports sequences, and SQLAlchemy uses these as the default means of creating new primary key values for integer-based primary key columns. When creating tables, SQLAlchemy will issue the `SERIAL` datatype for integer-based primary key columns, which generates a sequence and server side default corresponding to the column.

To specify a specific named sequence to be used for primary key generation, use the `Sequence()` construct:

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

When SQLAlchemy issues a single INSERT statement, to fulfill the contract of having the “last insert identifier” available, a RETURNING clause is added to the INSERT statement which specifies the primary key columns should be returned after the statement completes. The RETURNING functionality only takes place if PostgreSQL 8.2 or later is in use. As a fallback approach, the sequence, whether specified explicitly or implicitly via `SERIAL`, is executed independently beforehand, the returned value to be used in the subsequent insert. Note that when an `insert()` construct is executed using “executemany” semantics, the “last inserted identifier” functionality does not apply; no RETURNING clause is emitted nor is the sequence pre-executed in this case.

To force the usage of RETURNING by default off, specify the flag `implicit_returning=False` to `create_engine()`.

### PostgreSQL 10 IDENTITY columns

PostgreSQL 10 has a new IDENTITY feature that supersedes the use of SERIAL. Built-in support for rendering of IDENTITY is not available yet, however the following compilation hook may be used to replace occurrences of SERIAL with IDENTITY:

    from sqlalchemy.schema import CreateColumn
    from sqlalchemy.ext.compiler import compiles

    @compiles(CreateColumn, 'postgresql')
    def use_identity(element, compiler, **kw):
        text = compiler.visit_create_column(element, **kw)
        text = text.replace("SERIAL", "INT GENERATED BY DEFAULT AS IDENTITY")
        return text

Using the above, a table such as:

    t = Table(
        't', m,
        Column('id', Integer, primary_key=True),
        Column('data', String)
    )

Will generate on the backing database as:

    CREATE TABLE t (
        id INT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
        data VARCHAR,
        PRIMARY KEY (id)
    )

## Transaction Isolation Level

Most SQLAlchemy dialects support setting of transaction isolation level using the `create_engine.execution_options` parameter at the `create_engine()` level, and at the `Connection` level via the `Connection.execution_options.isolation_level` parameter.

For PostgreSQL dialects, this feature works either by making use of the DBAPI-specific features, such as psycopg2’s isolation level flags which will embed the isolation level setting inline with the `"BEGIN"` statement, or for DBAPIs with no direct support by emitting `SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level>` ahead of the `"BEGIN"` statement emitted by the DBAPI. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used which is typically an `.autocommit` flag on the DBAPI connection object.

To set isolation level using `create_engine()`:

    engine = create_engine(
        "postgresql+pg8000://scott:tiger@localhost/test",
        execution_options={
            "isolation_level": "REPEATABLE READ"
        }
    )

To set using per-connection execution options:

    with engine.connect() as conn:
        conn = conn.execution_options(
            isolation_level="REPEATABLE READ"
        )
        with conn.begin():
            # ... work with transaction

Valid values for `isolation_level` on most PostgreSQL dialects include:

- `READ COMMITTED`

- `READ UNCOMMITTED`

- `REPEATABLE READ`

- `SERIALIZABLE`

- `AUTOCOMMIT`

See also

Setting Transaction Isolation Levels including DBAPI Autocommit

Psycopg2 Transaction Isolation Level

pg8000 Transaction Isolation Level

## Remote-Schema Table Introspection and PostgreSQL search_path

TL;DR;: keep the `search_path` variable set to its default of `public`, name schemas other than `public` explicitly within `Table` definitions.

The PostgreSQL dialect can reflect tables from any schema. The `Table.schema` argument, or alternatively the `MetaData.reflect.schema` argument determines which schema will be searched for the table or tables. The reflected `Table` objects will in all cases retain this `.schema` attribute as was specified. However, with regards to tables which these `Table` objects refer to via foreign key constraint, a decision must be made as to how the `.schema` is represented in those remote tables, in the case where that remote schema name is also a member of the current PostgreSQL search path.

By default, the PostgreSQL dialect mimics the behavior encouraged by PostgreSQL’s own `pg_get_constraintdef()` builtin procedure. This function returns a sample definition for a particular foreign key constraint, omitting the referenced schema name from that definition when the name is also in the PostgreSQL schema search path. The interaction below illustrates this behavior:

    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.

On the other hand, if we set the search path back to the typical default of `public`:

    test=> SET search_path TO public;
    SET

The same query against `pg_get_constraintdef()` now returns the fully schema-qualified name for us:

    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 will by default use the return value of `pg_get_constraintdef()` in order to determine the remote schema name. That is, if our `search_path` were set to include `test_schema`, and we invoked a table reflection process as follows:

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

Note that in all cases, the “default” schema is always reflected as `None`. The “default” schema on PostgreSQL is that which is returned by the PostgreSQL `current_schema()` function. On a typical PostgreSQL installation, this is the name `public`. So a table that refers to another which is in the `public` (i.e. default) schema will always have the `.schema` attribute set to `None`.

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

See also

The Schema Search Path - on the PostgreSQL website.

## INSERT/UPDATE…RETURNING

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. To specify an explicit `RETURNING` clause, use the `_UpdateBase.returning()` method on a per-statement basis:

    # 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. A candidate row will only be inserted if that row does not violate any unique constraints. In the case of a unique constraint violation, a secondary action can occur which can be either “DO UPDATE”, indicating that the data in the target row should be updated, or “DO NOTHING”, which indicates to silently skip this row.

Conflicts are determined using existing unique constraints and indexes. 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 `insert()` function, which provides the generative methods `Insert.on_conflict_do_update()` and `Insert.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)

Both methods supply the “target” of the conflict using either the named constraint or by column inference:

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

- When using `Insert.on_conflict_do_update.index_elements` to infer an index, a partial index can be inferred by also specifying the use the `Insert.on_conflict_do_update.index_where` parameter:

      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)

- The `Insert.on_conflict_do_update.constraint` argument is used to specify an index directly rather than inferring it. This can be the name of a UNIQUE constraint, a PRIMARY KEY constraint, or an 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`. In this use, if the constraint has a name, it is used directly. Otherwise, if the constraint is unnamed, then inference will be used, where the expressions and optional WHERE clause of the constraint will be spelled out in the construct. This use is especially convenient to refer to the named or unnamed primary key of a `Table` using the `Table.primary_key` attribute:

      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. These values are specified using the `Insert.on_conflict_do_update.set_` parameter. This parameter accepts a dictionary which consists of direct values for 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)

Warning

The `Insert.on_conflict_do_update()` method does not take into account Python-side default UPDATE values or generation functions, e.g. those specified using `Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the `Insert.on_conflict_do_update.set_` dictionary.

In order to refer to the proposed insertion row, the special alias `Insert.excluded` is available as an attribute on the `Insert` object; this object is a `ColumnCollection` which alias contains all columns of the target table:

    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)

The `Insert.on_conflict_do_update()` method also accepts a WHERE clause using the `Insert.on_conflict_do_update.where` parameter, which will limit those rows which receive an 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 `Insert.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)

If `DO NOTHING` is used without specifying any columns or constraint, it has the effect of skipping the INSERT for any unique or exclusion constraint violation which occurs:

    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)

New in version 1.1: Added support for PostgreSQL ON CONFLICT clauses

See also

INSERT .. ON CONFLICT - in the PostgreSQL documentation.

## Full Text Search

SQLAlchemy makes available the PostgreSQL `@@` operator via the `ColumnElement.match()` method on any textual column expression. On a PostgreSQL dialect, an expression like the following:

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

will emit to the database:

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

The PostgreSQL text search functions such as `to_tsquery()` and `to_tsvector()` are available explicitly using the standard `func` construct. For example:

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

Emits the equivalent of:

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

The `TSVECTOR` type can provide for explicit CAST:

    from sqlalchemy.dialects.postgresql import TSVECTOR
    from sqlalchemy import select, cast
    select([cast("some text", TSVECTOR)])

produces a statement equivalent to:

    SELECT CAST('some text' AS TSVECTOR) AS anon_1

Full Text Searches in PostgreSQL are influenced by a combination of: the PostgreSQL setting of `default_text_search_config`, the `regconfig` used to build the GIN/GiST indexes, and the `regconfig` optionally passed in during a query.

When performing a Full Text Search against a column that has a GIN or GiST index that is already pre-computed (which is common on full text searches) one may need to explicitly pass in a particular PostgreSQL `regconfig` value to ensure the query-planner utilizes the index and does not re-compute the column on demand.

In order to provide for this explicit query planning, or to use different search strategies, the `match` method accepts a `postgresql_regconfig` keyword argument:

    select([mytable.c.id]).where(
        mytable.c.title.match('somestring', postgresql_regconfig='english')
    )

Emits the equivalent of:

    SELECT mytable.id FROM mytable
    WHERE mytable.title @@ to_tsquery('english', 'somestring')

One can also specifically pass in a ‘regconfig’ value to the `to_tsvector()` command as the initial argument:

    select([mytable.c.id]).where(
            func.to_tsvector('english', mytable.c.title )\
            .match('somestring', postgresql_regconfig='english')
        )

produces a statement equivalent to:

    SELECT mytable.id FROM mytable
    WHERE to_tsvector('english', mytable.title) @@
        to_tsquery('english', 'somestring')

It is recommended that you use the `EXPLAIN ANALYZE...` tool from PostgreSQL to ensure that you are generating queries with SQLAlchemy that take full advantage of any indexes you may have created for full text search.

## FROM ONLY …

The dialect supports PostgreSQL’s ONLY keyword for targeting only a particular table in an inheritance hierarchy. This can be used to produce the `SELECT ... FROM ONLY`, `UPDATE ONLY ...`, and `DELETE FROM ONLY ...` syntaxes. It uses SQLAlchemy’s hints mechanism:

    # 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-Specific Index Options

Several extensions to the `Index` construct are available, specific to the PostgreSQL dialect.

### Partial Indexes

Partial indexes add criterion to the index definition so that the index is applied to a subset of rows. These can be specified on `Index` using the `postgresql_where` keyword argument:

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

### Operator Classes

PostgreSQL allows the specification of an operator class for each column of an index (see http://www.postgresql.org/docs/8.3/interactive/indexes-opclass.html). The `Index` construct allows these to be specified via the `postgresql_ops` keyword argument:

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

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.

If `postgresql_ops` is to be used against a complex SQL expression such as a function call, then to apply to the column it must be given a label that is identified in the dictionary by name, e.g.:

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

### Index Types

PostgreSQL provides several index types: B-Tree, Hash, GiST, and GIN, as well as the ability for users to create their own (see http://www.postgresql.org/docs/8.3/static/indexes-types.html). These can be specified on `Index` using the `postgresql_using` keyword argument:

    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.

### Index Storage Parameters

PostgreSQL allows storage parameters to be set on indexes. The storage parameters available depend on the index method used by the index. Storage parameters can be specified on `Index` using the `postgresql_with` keyword argument:

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

New in version 1.0.6.

PostgreSQL allows to define the tablespace in which to create the index. The tablespace can be specified on `Index` using the `postgresql_tablespace` keyword argument:

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

New in version 1.1.

Note that the same option is available on `Table` as well.

### Indexes with CONCURRENTLY

The PostgreSQL index option CONCURRENTLY is supported by passing the flag `postgresql_concurrently` to the `Index` construct:

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

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

The above index construct will render DDL for CREATE INDEX, assuming PostgreSQL 8.2 or higher is detected or for a connection-less dialect, as:

    CREATE INDEX CONCURRENTLY test_idx1 ON testtbl (data)

For DROP INDEX, assuming PostgreSQL 9.2 or higher is detected or for a connection-less dialect, it will emit:

    DROP INDEX CONCURRENTLY test_idx1

New in version 1.1: support for CONCURRENTLY on DROP INDEX. The CONCURRENTLY keyword is now only emitted if a high enough version of PostgreSQL is detected on the connection (or for a connection-less dialect).

When using CONCURRENTLY, the PostgreSQL database requires that the statement be invoked outside of a transaction block. The Python DBAPI enforces that even for a single statement, a transaction is present, so to use this construct, the DBAPI’s “autocommit” mode must be used:

    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)

See also

Transaction Isolation Level

## PostgreSQL Index Reflection

The PostgreSQL database creates a UNIQUE INDEX implicitly whenever the UNIQUE CONSTRAINT construct is used. 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.

## Special Reflection Options

The `Inspector` used for the PostgreSQL backend is an instance of `PGInspector`, which offers additional methods:

    from sqlalchemy import create_engine, inspect

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

    print(insp.get_enums())

Object Name | Description
--- | ---
`PGInspector` |

class `sqlalchemy.dialects.postgresql.base.` `PGInspector`(conn)

  Class signature

  class `sqlalchemy.dialects.postgresql.base.PGInspector` (`sqlalchemy.engine.reflection.Inspector`)

  method `sqlalchemy.dialects.postgresql.base.PGInspector.` `get_enums`(schema=None)

    Return a list of ENUM objects.

    Each member is a dictionary containing these fields:

    > - name - name of the enum

    > - schema - the schema name for the enum.

    > - visible - boolean, whether or not this enum is visible in the default search path.

    > - labels - a list of string labels that apply to the enum.

    Parameters

      schema – schema name. If None, the default schema (typically ‘public’) is used. May also be set to ‘*’ to indicate load enums for all schemas.

    New in version 1.0.0.

  method `sqlalchemy.dialects.postgresql.base.PGInspector.` `get_foreign_table_names`(schema=None)

    Return a list of FOREIGN TABLE names.

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

    New in version 1.0.0.

  method `sqlalchemy.dialects.postgresql.base.PGInspector.` `get_table_oid`(table_name, schema=None)

    Return the OID for the given table name.

  method `sqlalchemy.dialects.postgresql.base.PGInspector.` `get_view_names`(schema=None, include='plain', 'materialized')

    Return all view names in schema.

    Parameters

      - schema – Optional, retrieve names from a non-default schema. For special quoting, use `quoted_name`.

      - include –

        specify which types of views to return. Passed as a string value (for a single type) or a tuple (for any number of types). Defaults to `('plain', 'materialized')`.

        New in version 1.1.

## PostgreSQL Table Options

Several options for CREATE TABLE are supported directly by the PostgreSQL dialect in conjunction with the `Table` construct:

- `TABLESPACE`:

      Table("some_table", metadata, ..., postgresql_tablespace='some_tablespace')

  The above option is also available on the `Index` construct.

- `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

See also

PostgreSQL CREATE TABLE options

## Table values, Row and Tuple objects

### Row Types

Built-in support for rendering a `ROW` is not available yet, however the `tuple_()` may be used in its place. Another alternative is to use the `sqlalchemy.func` generator with `func.ROW`

    table.select().where(
        tuple_(table.c.id, table.c.fk) > (1,2)
    ).where(func.ROW(table.c.id, table.c.fk) < func.ROW(3, 7))

Will generate the row-wise comparison:

    SELECT *
    FROM table
    WHERE (id, fk) > (1, 2)
    AND ROW(id, fk) < ROW(3, 7)

See also

PostgreSQL Row Constructors

PostgreSQL Row Constructor Comparison

### Table Types

PostgreSQL also supports passing a table as an argument to a function. This is not available yet in sqlalchemy, however the `literal_column()` function with the name of the table may be used in its place:

    select(['*']).select_from(func.my_function(literal_column('my_table')))

Will generate the SQL:

    SELECT *
    FROM my_function(my_table)

## ARRAY Types

The PostgreSQL dialect supports arrays, both as multidimensional column types as well as array literals:

- `ARRAY` - ARRAY datatype

- `array` - array literal

- `array_agg()` - ARRAY_AGG SQL function

- `aggregate_order_by` - helper for PG’s ORDER BY aggregate function syntax.

## JSON Types

The PostgreSQL dialect supports both JSON and JSONB datatypes, including psycopg2’s native support and support for all of PostgreSQL’s special operators:

- `JSON`

- `JSONB`

## HSTORE Type

The PostgreSQL HSTORE type as well as hstore literals are supported:

- `HSTORE` - HSTORE datatype

- `hstore` - hstore literal

## ENUM Types

PostgreSQL has an independently creatable TYPE structure which is used to implement an enumerated type. This approach introduces significant complexity on the SQLAlchemy side in terms of when this type should be CREATED and DROPPED. The type object is also an independently reflectable entity. The following sections should be consulted:

- `ENUM` - DDL and typing support for ENUM.

- `PGInspector.get_enums()` - retrieve a listing of current ENUM types

- `ENUM.create()` , `ENUM.drop()` - individual CREATE and DROP commands for ENUM.

### Using ENUM with ARRAY

The combination of ENUM and ARRAY is not directly supported by backend DBAPIs at this time. Prior to SQLAlchemy 1.3.17, a special workaround was needed in order to allow this combination to work, described below.

Changed in version 1.3.17: The combination of ENUM and ARRAY is now directly handled by SQLAlchemy’s implementation without any workarounds needed.

    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

E.g.:

    Table(
        'mydata', metadata,
        Column('id', Integer, primary_key=True),
        Column('data', ArrayOfEnum(ENUM('a', 'b, 'c', name='myenum')))

    )

This type is not included as a built-in type as it would be incompatible with a DBAPI that suddenly decides to support ARRAY of ENUM directly in a new version.

### Using JSON/JSONB with ARRAY

Similar to using ENUM, prior to SQLAlchemy 1.3.17, for an ARRAY of JSON/JSONB we need to render the appropriate CAST. Current psycopg2 drivers accomodate the result set correctly without any special steps.

Changed in version 1.3.17: The combination of JSON/JSONB and ARRAY is now directly handled by SQLAlchemy’s implementation without any workarounds needed.

    class CastingArray(ARRAY):
        def bind_expression(self, bindvalue):
            return sa.cast(bindvalue, self)

E.g.:

    Table(
        'mydata', metadata,
        Column('id', Integer, primary_key=True),
        Column('data', CastingArray(JSONB))
    )

## PostgreSQL Data Types

As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with PostgreSQL are importable from the top level dialect, whether they originate from `sqlalchemy.types` or from the local dialect:

    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

Types which are specific to PostgreSQL, or have PostgreSQL-specific construction arguments, are as follows:

Object Name | Description
--- | ---
`aggregate_order_by` | Represent a PostgreSQL aggregate order by expression.
`All`(other, arrexpr[, operator]) | A synonym for the `Comparator.all()` method.
`Any`(other, arrexpr[, operator]) | A synonym for the `Comparator.any()` method.
`array` | A PostgreSQL ARRAY literal.
`ARRAY` | PostgreSQL ARRAY type.
`array_agg`(*arg, **kw) | PostgreSQL-specific form of `array_agg`, ensures return type is `ARRAY` and not the plain `ARRAY`, unless an explicit `type_` is passed.
`BIT` |
`BYTEA` |
`CIDR` |
`DOUBLE_PRECISION` |
`ENUM` | PostgreSQL ENUM type.
`HSTORE` | Represent the PostgreSQL HSTORE type.
`hstore` | Construct an hstore value within a SQL expression using the PostgreSQL `hstore()` function.
`INET` |
`INTERVAL` | PostgreSQL INTERVAL type.
`JSON` | Represent the PostgreSQL JSON type.
`JSONB` | Represent the PostgreSQL JSONB type.
`MACADDR` |
`MONEY` | Provide the PostgreSQL MONEY type.
`OID` | Provide the PostgreSQL OID type.
`REAL` | The SQL REAL type.
`REGCLASS` | Provide the PostgreSQL REGCLASS type.
`TSVECTOR` | The `TSVECTOR` type implements the PostgreSQL text search type TSVECTOR.
`UUID` | PostgreSQL UUID type.

class `sqlalchemy.dialects.postgresql.` `aggregate_order_by`(target, *order_by)

  Represent a PostgreSQL aggregate order by expression.

  E.g.:

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

  would represent the expression:

      SELECT array_agg(a ORDER BY b DESC) FROM table;

  Similarly:

      expr = func.string_agg(
          table.c.a,
          aggregate_order_by(literal_column("','"), table.c.a)
      )
      stmt = select([expr])

  Would represent:

      SELECT string_agg(a, ',' ORDER BY a) FROM table;

  New in version 1.1.

  Changed in version 1.2.13: - the ORDER BY argument may be multiple terms

  See also

  `array_agg`

  Class signature

  class `sqlalchemy.dialects.postgresql.aggregate_order_by` (`sqlalchemy.sql.expression.ColumnElement`)

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

  A PostgreSQL ARRAY literal.

  This is used to produce ARRAY literals in SQL expressions, e.g.:

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

  Produces the SQL:

      SELECT ARRAY[%(param_1)s, %(param_2)s] ||
          ARRAY[%(param_3)s, %(param_4)s, %(param_5)s]) AS anon_1

  An instance of `array` will always have the datatype `ARRAY`. The “inner” type of the array is inferred from the values present, unless the `type_` keyword argument is passed:

      array(['foo', 'bar'], type_=CHAR)

  Multidimensional arrays are produced by nesting `array` constructs. The dimensionality of the final `ARRAY` type is calculated by recursively adding the dimensions of the inner `ARRAY` type:

      stmt = select([
          array([
              array([1, 2]), array([3, 4]), array([column('q'), column('x')])
          ])
      ])
      print(stmt.compile(dialect=postgresql.dialect()))

  Produces:

      SELECT ARRAY[ARRAY[%(param_1)s, %(param_2)s],
      ARRAY[%(param_3)s, %(param_4)s], ARRAY[q, x]] AS anon_1

  New in version 1.3.6: added support for multidimensional array literals

  See also

  `ARRAY`

  Class signature

  class `sqlalchemy.dialects.postgresql.array` (`sqlalchemy.sql.expression.Tuple`)

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

  PostgreSQL ARRAY type.

  Changed in version 1.1: The `ARRAY` type is now a subclass of the core `ARRAY` type.

  The `ARRAY` type is constructed in the same way as the core `ARRAY` type; a member type is required, and a number of dimensions is recommended if the type is to be used for more than one dimension:

      from sqlalchemy.dialects import postgresql

      mytable = Table("mytable", metadata,
              Column("data", postgresql.ARRAY(Integer, dimensions=2))
          )

  The `ARRAY` type provides all operations defined on the core `ARRAY` type, including support for “dimensions”, indexed access, and simple matching such as `Comparator.any()` and `Comparator.all()`. `ARRAY` class also provides PostgreSQL-specific methods for containment operations, including `Comparator.contains()` `Comparator.contained_by()`, and `Comparator.overlap()`, e.g.:

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

  The `ARRAY` type may not be supported on all PostgreSQL DBAPIs; it is currently known to work on psycopg2 only.

  Additionally, the `ARRAY` type does not work directly in conjunction with the `ENUM` type. For a workaround, see the special type at Using ENUM with ARRAY.

  See also

  `ARRAY` - base array type

  `array` - produces a literal array value.

  Class signature

  class `sqlalchemy.dialects.postgresql.ARRAY` (`sqlalchemy.types.ARRAY`)

  class `Comparator`(expr)

    Define comparison operations for `ARRAY`.

    Note that these operations are in addition to those provided by the base `Comparator` class, including `Comparator.any()` and `Comparator.all()`.

    Class signature

    class `sqlalchemy.dialects.postgresql.ARRAY.Comparator` (`sqlalchemy.types.Comparator`)

    method `sqlalchemy.dialects.postgresql.ARRAY.Comparator.` `contained_by`(other)

      Boolean expression. Test if elements are a proper subset of the elements of the argument array expression.

    method `sqlalchemy.dialects.postgresql.ARRAY.Comparator.` `contains`(other, **kwargs)

      Boolean expression. Test if elements are a superset of the elements of the argument array expression.

    method `sqlalchemy.dialects.postgresql.ARRAY.Comparator.` `overlap`(other)

      Boolean expression. Test if array has elements in common with an argument array expression.

  method `sqlalchemy.dialects.postgresql.ARRAY.` `__init__`(item_type, as_tuple=False, dimensions=None, zero_indexes=False)

    Construct an ARRAY.

    E.g.:

        Column('myarray', ARRAY(Integer))

    Arguments are:

    Parameters

      - item_type – The data type of items of this array. Note that dimensionality is irrelevant here, so multi-dimensional arrays like `INTEGER[][]`, are constructed as `ARRAY(Integer)`, not as `ARRAY(ARRAY(Integer))` or such.

      - as_tuple=False – Specify whether return results should be converted to tuples from lists. DBAPIs such as psycopg2 return lists by default. When tuples are returned, the results are hashable.

      - 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. Note that PG arrays are always implicitly “non-dimensioned”, meaning they can store any number of dimensions no matter how they were declared.

      - zero_indexes=False –

        when True, index values will be converted between Python zero-based and PostgreSQL one-based indexes, e.g. a value of one will be added to all index values before passing to the database.

        New in version 0.9.5.

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

  PostgreSQL-specific form of `array_agg`, ensures return type is `ARRAY` and not the plain `ARRAY`, unless an explicit `type_` is passed.

  New in version 1.1.

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

  A synonym for the `Comparator.any()` method.

  This method is legacy and is here for backwards-compatibility.

  See also

  `any_()`

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

  A synonym for the `Comparator.all()` method.

  This method is legacy and is here for backwards-compatibility.

  See also

  `all_()`

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

  Class signature

  class `sqlalchemy.dialects.postgresql.BIT` (`sqlalchemy.types.TypeEngine`)

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

  Class signature

  class `sqlalchemy.dialects.postgresql.BYTEA` (`sqlalchemy.types.LargeBinary`)

  method `sqlalchemy.dialects.postgresql.BYTEA.` `__init__`(length=None)

    inherited from the `sqlalchemy.types.LargeBinary.__init__` method of `LargeBinary`

    Construct a LargeBinary type.

    Parameters

      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`

  Class signature

  class `sqlalchemy.dialects.postgresql.CIDR` (`sqlalchemy.types.TypeEngine`)

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

  Class signature

  class `sqlalchemy.dialects.postgresql.DOUBLE_PRECISION` (`sqlalchemy.types.Float`)

  method `sqlalchemy.dialects.postgresql.DOUBLE_PRECISION.` `__init__`(precision=None, asdecimal=False, decimal_return_scale=None)

    inherited from the `sqlalchemy.types.Float.__init__` method of `Float`

    Construct a Float.

    Parameters

      - precision – the numeric precision for use in DDL `CREATE TABLE`.

      - asdecimal – the same flag as that of `Numeric`, but defaults to `False`. Note that setting this flag to `True` results in floating point conversion.

      - decimal_return_scale –

        Default scale to use when converting from floats to Python decimals. Floating point values will typically be much longer due to decimal inaccuracy, and most floating point database types don’t have a notion of “scale”, so by default the float type looks for the first ten decimal places when converting. Specifying this value will override that length. Note that the MySQL float types, which do include “scale”, will use “scale” as the default for decimal_return_scale, if not otherwise specified.

        New in version 0.9.0.

class `sqlalchemy.dialects.postgresql.` `ENUM`(*enums, **kw)

  PostgreSQL ENUM type.

  This is a subclass of `Enum` which includes support for PG’s `CREATE TYPE` and `DROP TYPE`.

  When the builtin type `Enum` is used and the `Enum.native_enum` flag is left at its default of True, the PostgreSQL backend will use a `ENUM` type as the implementation, so the special create/drop rules will be used.

  The create/drop behavior of ENUM is necessarily intricate, due to the awkward relationship the ENUM type has in relationship to the parent table, in that it may be “owned” by just a single table, or may be shared among many tables.

  When using `Enum` or `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

  To use a common enumerated type between multiple tables, the best practice is to declare the `Enum` or `ENUM` independently, and associate it with the `MetaData` object itself:

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

  When this pattern is used, care must still be taken at the level of individual table creates. Emitting CREATE TABLE without also specifying `checkfirst=True` will still cause issues:

      t1.create(engine) # will fail: no such type 'myenum'

  If we specify `checkfirst=True`, the individual table-level create operation will check for the `ENUM` and create if not exists:

      # will check if enum exists, and emit CREATE TYPE if not
      t1.create(engine, checkfirst=True)

  When using a metadata-level ENUM type, the type will always be created and dropped if either the metadata-wide create/drop is called:

      metadata.create_all(engine)  # will emit CREATE TYPE
      metadata.drop_all(engine)  # will emit DROP TYPE

  The type can also be created and dropped directly:

      my_enum.create(engine)
      my_enum.drop(engine)

  Changed in version 1.0.0: The PostgreSQL `ENUM` type now behaves more strictly with regards to CREATE/DROP. A metadata-level ENUM type will only be created and dropped at the metadata level, not the table level, with the exception of `table.create(checkfirst=True)`. The `table.drop()` call will now emit a DROP TYPE for a table-level enumerated type.

  Class signature

  class `sqlalchemy.dialects.postgresql.ENUM` (`sqlalchemy.types.NativeForEmulated`, `sqlalchemy.types.Enum`)

  method `sqlalchemy.dialects.postgresql.ENUM.` `__init__`(*enums, **kw)

    Construct an `ENUM`.

    Arguments are the same as that of `Enum`, but also including the following parameters.

    Parameters

      create_type – Defaults to 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 `ENUM.create()` or `ENUM.drop()` are called directly. Setting to `False` is helpful when invoking a creation scheme to a SQL file without access to the actual database - the `ENUM.create()` and `ENUM.drop()` methods can be used to emit SQL to a target bind.

  method `sqlalchemy.dialects.postgresql.ENUM.` `create`(bind=None, checkfirst=True)

    Emit `CREATE TYPE` for this `ENUM`.

    If the underlying dialect does not support PostgreSQL CREATE TYPE, no action is taken.

    Parameters

      - 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.

  method `sqlalchemy.dialects.postgresql.ENUM.` `drop`(bind=None, checkfirst=True)

    Emit `DROP TYPE` for this `ENUM`.

    If the underlying dialect does not support PostgreSQL DROP TYPE, no action is taken.

    Parameters

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

  Represent the PostgreSQL HSTORE type.

  The `HSTORE` type stores dictionaries containing strings, e.g.:

      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:

  - Index operations:

        data_table.c.data['some key'] == 'some value'

  - Containment operations:

        data_table.c.data.has_key('some key')

        data_table.c.data.has_all(['one', 'two', 'three'])

  - Concatenation:

        data_table.c.data + {"k1": "v1"}

  For a full list of special methods see `comparator_factory`.

  For usage with the SQLAlchemy ORM, it may be desirable to combine the usage of `HSTORE` with `MutableDict` dictionary now part of the `sqlalchemy.ext.mutable` extension. This extension will allow “in-place” changes to the dictionary, e.g. addition of new keys or replacement/removal of existing keys to/from the current dictionary, to produce events which will be detected by the unit of work:

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

  When the `sqlalchemy.ext.mutable` extension is not used, the ORM will not be alerted to any changes to the contents of an existing dictionary, unless that dictionary value is re-assigned to the HSTORE-attribute itself, thus generating a change event.

  See also

  `hstore` - render the PostgreSQL `hstore()` function.

  Class signature

  class `sqlalchemy.dialects.postgresql.HSTORE` (`sqlalchemy.types.Indexable`, `sqlalchemy.types.Concatenable`, `sqlalchemy.types.TypeEngine`)

  class `Comparator`(expr)

    Define comparison operations for `HSTORE`.

    Class signature

    class `sqlalchemy.dialects.postgresql.HSTORE.Comparator` (`sqlalchemy.types.Comparator`, `sqlalchemy.types.Comparator`)

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `array`()

      Text array expression. Returns array of alternating keys and values.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `contained_by`(other)

      Boolean expression. Test if keys are a proper subset of the keys of the argument jsonb expression.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `contains`(other, **kwargs)

      Boolean expression. Test if keys (or array) are a superset of/contained the keys of the argument jsonb expression.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `defined`(key)

      Boolean expression. Test for presence of a non-NULL value for the key. Note that the key may be a SQLA expression.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `delete`(key)

      HStore expression. Returns the contents of this hstore with the given key deleted. Note that the key may be a SQLA expression.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `has_all`(other)

      Boolean expression. Test for presence of all keys in jsonb

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `has_any`(other)

      Boolean expression. Test for presence of any key in jsonb

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `has_key`(other)

      Boolean expression. Test for presence of a key. Note that the key may be a SQLA expression.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `keys`()

      Text array expression. Returns array of keys.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `matrix`()

      Text array expression. Returns array of [key, value] pairs.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `slice`(array)

      HStore expression. Returns a subset of an hstore defined by array of keys.

    method `sqlalchemy.dialects.postgresql.HSTORE.Comparator.` `vals`()

      Text array expression. Returns array of values.

  method `sqlalchemy.dialects.postgresql.HSTORE.` `__init__`(text_type=None)

    Construct a new `HSTORE`.

    Parameters

      text_type –

      the type that should be used for indexed values. Defaults to `Text`.

      New in version 1.1.0.

  method `sqlalchemy.dialects.postgresql.HSTORE.` `bind_processor`(dialect)

    Return a conversion function for processing bind values.

    Returns a callable which will receive a bind parameter value as the sole positional argument and will return a value to send to the DB-API.

    If processing is not necessary, the method should return `None`.

    Parameters

      dialect – Dialect instance in use.

  attribute `sqlalchemy.dialects.postgresql.HSTORE.` `comparator_factory`

    alias of `HSTORE.Comparator`

  method `sqlalchemy.dialects.postgresql.HSTORE.` `result_processor`(dialect, coltype)

    Return a conversion function for processing result row values.

    Returns a callable which will receive a result row column value as the sole positional argument and will return a value to return to the user.

    If processing is not necessary, the method should return `None`.

    Parameters

      - dialect – Dialect instance in use.

      - coltype – DBAPI coltype argument received in cursor.description.

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

  Construct an hstore value within a SQL expression using the PostgreSQL `hstore()` function.

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

  E.g.:

      from sqlalchemy.dialects.postgresql import array, hstore

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

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

  See also

  `HSTORE` - the PostgreSQL `HSTORE` datatype.

  Class signature

  class `sqlalchemy.dialects.postgresql.hstore` (`sqlalchemy.sql.functions.GenericFunction`)

  attribute `sqlalchemy.dialects.postgresql.hstore.` `type`

    alias of `HSTORE`

class `sqlalchemy.dialects.postgresql.` `INET`

  Class signature

  class `sqlalchemy.dialects.postgresql.INET` (`sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `INTERVAL`(precision=None, fields=None)

  PostgreSQL INTERVAL type.

  The INTERVAL type may not be supported on all DBAPIs. It is known to work on psycopg2 and not pg8000 or zxjdbc.

  Class signature

  class `sqlalchemy.dialects.postgresql.INTERVAL` (`sqlalchemy.types.NativeForEmulated`, `sqlalchemy.types._AbstractInterval`)

  method `sqlalchemy.dialects.postgresql.INTERVAL.` `__init__`(precision=None, fields=None)

    Construct an INTERVAL.

    Parameters

      - precision – optional integer precision value

      - fields –

        string fields specifier. allows storage of fields to be limited, such as `"YEAR"`, `"MONTH"`, `"DAY TO HOUR"`, etc.

        New in version 1.2.

class `sqlalchemy.dialects.postgresql.` `JSON`(none_as_null=False, astext_type=None)

  Represent the PostgreSQL JSON type.

  This type is a specialization of the Core-level `JSON` type. Be sure to read the documentation for `JSON` for important tips regarding treatment of NULL values and ORM use.

  Changed in version 1.1: `JSON` is now a PostgreSQL- specific specialization of the new `JSON` type.

  The operators provided by the PostgreSQL version of `JSON` include:

  - Index operations (the `->` operator):

        data_table.c.data['some key']

        data_table.c.data[5]

  - Index operations returning text (the `->>` operator):

        data_table.c.data['some key'].astext == 'some value'

    Note that equivalent functionality is available via the `Comparator.as_string` accessor.

  - Index operations with CAST (equivalent to `CAST(col ->> ['some key'] AS <type>)`):

        data_table.c.data['some key'].astext.cast(Integer) == 5

    Note that equivalent functionality is available via the `Comparator.as_integer` and similar accessors.

  - Path index operations (the `#>` operator):

        data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')]

  - Path index operations returning text (the `#>>` operator):

        data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')].astext == 'some value'

  Changed in version 1.1: The `ColumnElement.cast()` operator on JSON objects now requires that the `Comparator.astext` modifier be called explicitly, if the cast works only from a textual string.

  Index operations return an expression object whose type defaults to `JSON` by default, so that further JSON-oriented instructions may be called upon the result type.

  Custom serializers and deserializers are specified at the dialect level, that is using `create_engine()`. The reason for this is that when using psycopg2, the DBAPI only allows serializers at the per-cursor or per-connection level. E.g.:

      engine = create_engine("postgresql://scott:tiger@localhost/test",
                              json_serializer=my_serialize_fn,
                              json_deserializer=my_deserialize_fn
                      )

  When using the psycopg2 dialect, the json_deserializer is registered against the database using `psycopg2.extras.register_default_json`.

  See also

  `JSON` - Core level JSON type

  `JSONB`

  Class signature

  class `sqlalchemy.dialects.postgresql.JSON` (`sqlalchemy.types.JSON`)

  class `Comparator`(expr)

    Define comparison operations for `JSON`.

    Class signature

    class `sqlalchemy.dialects.postgresql.JSON.Comparator` (`sqlalchemy.types.Comparator`)

    attribute `sqlalchemy.dialects.postgresql.JSON.Comparator.` `astext`

      On an indexed expression, use the “astext” (e.g. “->>”) conversion when rendered in SQL.

      E.g.:

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

      See also

      `ColumnElement.cast()`

  method `sqlalchemy.dialects.postgresql.JSON.` `__init__`(none_as_null=False, astext_type=None)

    Construct a `JSON` type.

    Parameters

      - none_as_null –

        if True, persist the value `None` as a SQL NULL value, not the JSON encoding of `null`. Note that when this flag is False, the `null()` construct can still be used to persist a NULL value:

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

        Changed in version 0.9.8: - Added `none_as_null`, and `null()` is now supported in order to persist a NULL value.

        See also

        `JSON.NULL`

      - astext_type –

        the type to use for the `Comparator.astext` accessor on indexed attributes. Defaults to `Text`.

        New in version 1.1.

  attribute `sqlalchemy.dialects.postgresql.JSON.` `comparator_factory`

    alias of `JSON.Comparator`

class `sqlalchemy.dialects.postgresql.` `JSONB`(none_as_null=False, astext_type=None)

  Represent the PostgreSQL JSONB type.

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

  The `JSONB` type includes all operations provided by `JSON`, including the same behaviors for indexing operations. It also adds additional operators specific to JSONB, including `Comparator.has_key()`, `Comparator.has_all()`, `Comparator.has_any()`, `Comparator.contains()`, and `Comparator.contained_by()`.

  Like the `JSON` type, the `JSONB` type does not detect in-place changes when used with the ORM, unless the `sqlalchemy.ext.mutable` extension is used.

  Custom serializers and deserializers are shared with the `JSON` class, using the `json_serializer` and `json_deserializer` keyword arguments. These must be specified at the dialect level using `create_engine()`. When using psycopg2, the serializers are associated with the jsonb type using `psycopg2.extras.register_default_jsonb` on a per-connection basis, in the same way that `psycopg2.extras.register_default_json` is used to register these handlers with the json type.

  New in version 0.9.7.

  See also

  `JSON`

  Class signature

  class `sqlalchemy.dialects.postgresql.JSONB` (`sqlalchemy.dialects.postgresql.json.JSON`)

  class `Comparator`(expr)

    Define comparison operations for `JSON`.

    Class signature

    class `sqlalchemy.dialects.postgresql.JSONB.Comparator` (`sqlalchemy.dialects.postgresql.json.Comparator`)

    method `sqlalchemy.dialects.postgresql.JSONB.Comparator.` `contained_by`(other)

      Boolean expression. Test if keys are a proper subset of the keys of the argument jsonb expression.

    method `sqlalchemy.dialects.postgresql.JSONB.Comparator.` `contains`(other, **kwargs)

      Boolean expression. Test if keys (or array) are a superset of/contained the keys of the argument jsonb expression.

    method `sqlalchemy.dialects.postgresql.JSONB.Comparator.` `has_all`(other)

      Boolean expression. Test for presence of all keys in jsonb

    method `sqlalchemy.dialects.postgresql.JSONB.Comparator.` `has_any`(other)

      Boolean expression. Test for presence of any key in jsonb

    method `sqlalchemy.dialects.postgresql.JSONB.Comparator.` `has_key`(other)

      Boolean expression. Test for presence of a key. Note that the key may be a SQLA expression.

  attribute `sqlalchemy.dialects.postgresql.JSONB.` `comparator_factory`

    alias of `JSONB.Comparator`

class `sqlalchemy.dialects.postgresql.` `MACADDR`

  Class signature

  class `sqlalchemy.dialects.postgresql.MACADDR` (`sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `MONEY`

  Provide the PostgreSQL MONEY type.

  New in version 1.2.

  Class signature

  class `sqlalchemy.dialects.postgresql.MONEY` (`sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `OID`

  Provide the PostgreSQL OID type.

  New in version 0.9.5.

  Class signature

  class `sqlalchemy.dialects.postgresql.OID` (`sqlalchemy.types.TypeEngine`)

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

  The SQL REAL type.

  Class signature

  class `sqlalchemy.dialects.postgresql.REAL` (`sqlalchemy.types.Float`)

  method `sqlalchemy.dialects.postgresql.REAL.` `__init__`(precision=None, asdecimal=False, decimal_return_scale=None)

    inherited from the `sqlalchemy.types.Float.__init__` method of `Float`

    Construct a Float.

    Parameters

      - precision – the numeric precision for use in DDL `CREATE TABLE`.

      - asdecimal – the same flag as that of `Numeric`, but defaults to `False`. Note that setting this flag to `True` results in floating point conversion.

      - decimal_return_scale –

        Default scale to use when converting from floats to Python decimals. Floating point values will typically be much longer due to decimal inaccuracy, and most floating point database types don’t have a notion of “scale”, so by default the float type looks for the first ten decimal places when converting. Specifying this value will override that length. Note that the MySQL float types, which do include “scale”, will use “scale” as the default for decimal_return_scale, if not otherwise specified.

        New in version 0.9.0.

class `sqlalchemy.dialects.postgresql.` `REGCLASS`

  Provide the PostgreSQL REGCLASS type.

  New in version 1.2.7.

  Class signature

  class `sqlalchemy.dialects.postgresql.REGCLASS` (`sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `TSVECTOR`

  The `TSVECTOR` type implements the PostgreSQL text search type TSVECTOR.

  It can be used to do full text queries on natural language documents.

  New in version 0.9.0.

  See also

  Full Text Search

  Class signature

  class `sqlalchemy.dialects.postgresql.TSVECTOR` (`sqlalchemy.types.TypeEngine`)

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

  PostgreSQL UUID type.

  Represents the UUID column type, interpreting data either as natively returned by the DBAPI or as Python uuid objects.

  The UUID type may not be supported on all DBAPIs. It is known to work on psycopg2 and not pg8000.

  Class signature

  class `sqlalchemy.dialects.postgresql.UUID` (`sqlalchemy.types.TypeEngine`)

  method `sqlalchemy.dialects.postgresql.UUID.` `__init__`(as_uuid=False)

    Construct a UUID type.

    Parameters

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

### Range Types

The new range column types found in PostgreSQL 9.2 onwards are catered for by the following types:

Object Name | Description
--- | ---
`DATERANGE` | Represent the PostgreSQL DATERANGE type.
`INT4RANGE` | Represent the PostgreSQL INT4RANGE type.
`INT8RANGE` | Represent the PostgreSQL INT8RANGE type.
`NUMRANGE` | Represent the PostgreSQL NUMRANGE type.
`RangeOperators` | This mixin provides functionality for the Range Operators listed in Table 9-44 of the postgres documentation for Range Functions and Operators. It is used by all the range types provided in the `postgres` dialect and can likely be used for any range types you create yourself.
`TSRANGE` | Represent the PostgreSQL TSRANGE type.
`TSTZRANGE` | Represent the PostgreSQL TSTZRANGE type.

class `sqlalchemy.dialects.postgresql.` `INT4RANGE`

  Represent the PostgreSQL INT4RANGE type.

  Class signature

  class `sqlalchemy.dialects.postgresql.INT4RANGE` (`sqlalchemy.dialects.postgresql.ranges.RangeOperators`, `sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `INT8RANGE`

  Represent the PostgreSQL INT8RANGE type.

  Class signature

  class `sqlalchemy.dialects.postgresql.INT8RANGE` (`sqlalchemy.dialects.postgresql.ranges.RangeOperators`, `sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `NUMRANGE`

  Represent the PostgreSQL NUMRANGE type.

  Class signature

  class `sqlalchemy.dialects.postgresql.NUMRANGE` (`sqlalchemy.dialects.postgresql.ranges.RangeOperators`, `sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `DATERANGE`

  Represent the PostgreSQL DATERANGE type.

  Class signature

  class `sqlalchemy.dialects.postgresql.DATERANGE` (`sqlalchemy.dialects.postgresql.ranges.RangeOperators`, `sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `TSRANGE`

  Represent the PostgreSQL TSRANGE type.

  Class signature

  class `sqlalchemy.dialects.postgresql.TSRANGE` (`sqlalchemy.dialects.postgresql.ranges.RangeOperators`, `sqlalchemy.types.TypeEngine`)

class `sqlalchemy.dialects.postgresql.` `TSTZRANGE`

  Represent the PostgreSQL TSTZRANGE type.

  Class signature

  class `sqlalchemy.dialects.postgresql.TSTZRANGE` (`sqlalchemy.dialects.postgresql.ranges.RangeOperators`, `sqlalchemy.types.TypeEngine`)

The types above get most of their functionality from the following mixin:

class `sqlalchemy.dialects.postgresql.ranges.` `RangeOperators`

  This mixin provides functionality for the Range Operators listed in Table 9-44 of the postgres documentation for Range Functions and Operators. It is used by all the range types provided in the `postgres` dialect and can likely be used for any range types you create yourself.

  No extra support is provided for the Range Functions listed in Table 9-45 of the postgres documentation. For these, the normal `func()` object should be used.

  class `comparator_factory`(expr)

    Define comparison operations for range types.

    Class signature

    class `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory` (`sqlalchemy.types.Comparator`)

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `__ne__`(other)

      Boolean expression. Returns true if two ranges are not equal

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `adjacent_to`(other)

      Boolean expression. Returns true if the range in the column is adjacent to the range in the operand.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `contained_by`(other)

      Boolean expression. Returns true if the column is contained within the right hand operand.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `contains`(other, **kw)

      Boolean expression. Returns true if the right hand operand, which can be an element or a range, is contained within the column.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `not_extend_left_of`(other)

      Boolean expression. Returns true if the range in the column does not extend left of the range in the operand.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `not_extend_right_of`(other)

      Boolean expression. Returns true if the range in the column does not extend right of the range in the operand.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `overlaps`(other)

      Boolean expression. Returns true if the column overlaps (has points in common with) the right hand operand.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `strictly_left_of`(other)

      Boolean expression. Returns true if the column is strictly left of the right hand operand.

    method `sqlalchemy.dialects.postgresql.ranges.RangeOperators.comparator_factory.` `strictly_right_of`(other)

      Boolean expression. Returns true if the column is strictly right of the right hand operand.

Warning

The range type DDL support should work with any PostgreSQL DBAPI driver, however the data types returned may vary. If you are using `psycopg2`, it’s recommended to upgrade to version 2.5 or later before using these column types.

When instantiating models that use these column types, you should pass whatever data type is expected by the DBAPI driver you’re using for the column type. For `psycopg2` these are `psycopg2.extras.NumericRange`, `psycopg2.extras.DateRange`, `psycopg2.extras.DateTimeRange` and `psycopg2.extras.DateTimeTZRange` or the class you’ve registered with `psycopg2.extras.register_range`.

For example:

    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 Constraint Types

SQLAlchemy supports PostgreSQL EXCLUDE constraints via the `ExcludeConstraint` class:

Object Name | Description
--- | ---
`ExcludeConstraint` | A table-level EXCLUDE constraint.

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

  A table-level EXCLUDE constraint.

  Defines an EXCLUDE constraint as described in the postgres documentation.

  Class signature

  class `sqlalchemy.dialects.postgresql.ExcludeConstraint` (`sqlalchemy.schema.ColumnCollectionConstraint`)

  method `sqlalchemy.dialects.postgresql.ExcludeConstraint.` `__init__`(*elements, **kw)

    Create an `ExcludeConstraint` object.

    E.g.:

        const = ExcludeConstraint(
            (Column('period'), '&&'),
            (Column('group'), '='),
            where=(Column('group') != 'some group')
        )

    The constraint is normally embedded into the `Table` construct directly, or added later using `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'
            )
        )

    Parameters

      - *elements – A sequence of two tuples of the form `(column, operator)` where “column” is a SQL expression element or a raw SQL string, most typically a `Column` object, and “operator” is a string containing the operator to use. In order to specify a column name when a `Column` object is not available, while ensuring that any necessary quoting rules take effect, an ad-hoc `Column` or `column()` object should be used.

      - name – Optional, the in-database name of this constraint.

      - deferrable – Optional bool. If set, emit DEFERRABLE or NOT DEFERRABLE when issuing DDL for this constraint.

      - initially – Optional string. If set, emit INITIALLY <value> when issuing DDL for this constraint.

      - using – Optional string. If set, emit USING <index_method> when issuing DDL for this constraint. Defaults to ‘gist’.

      - where –

        Optional SQL expression construct or literal SQL string. If set, emit WHERE <predicate> when issuing DDL for this constraint.

        Warning

        The `ExcludeConstraint.where` argument to `ExcludeConstraint` can be passed as a Python string argument, which will be treated as trusted SQL text and rendered as given. DO NOT PASS UNTRUSTED INPUT TO THIS PARAMETER.

For example:

    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 Constructs

Object Name | Description
--- | ---
`insert`(table[, values, inline, bind, ...], **dialect_kw) | Construct an `Insert` object.
`Insert` | PostgreSQL-specific implementation of INSERT.

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

  Construct an `Insert` object.

  Inherited from `insert()`; this constructor creates a `Insert` object

  Similar functionality is available via the `TableClause.insert()` method on `Table`.

  Parameters

    - table – `TableClause` which is the subject of the insert.

    - values – collection of values to be inserted; see `Insert.values()` for a description of allowed formats here. Can be omitted entirely; a `Insert` construct will also dynamically render the VALUES clause at execution time based on the parameters passed to `Connection.execute()`.

    - inline – if True, no attempt will be made to retrieve the SQL-generated default values to be provided within the statement; in particular, this allows SQL expressions to be rendered ‘inline’ within the statement without the need to pre-execute them beforehand; for backends that support “returning”, this turns off the “implicit returning” feature for the statement.

  If both values and compile-time bind parameters are present, the compile-time bind parameters override the information specified within values on a per-key basis.

  The keys within values can be either `Column` objects or their string identifiers. Each key may reference one of:

  - a literal data value (i.e. string, number, etc.);

  - a Column object;

  - a SELECT statement.

  If a `SELECT` statement is specified which references this `INSERT` statement’s table, the statement will be correlated against the `INSERT` statement.

  See also

  Insert Expressions - SQL Expression Tutorial

  Inserts, Updates and Deletes - SQL Expression Tutorial

class `sqlalchemy.dialects.postgresql.` `Insert`(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

  PostgreSQL-specific implementation of INSERT.

  Adds methods for PG-specific syntaxes such as ON CONFLICT.

  The `Insert` object is created using the `insert()` function.

  New in version 1.1.

  Class signature

  class `sqlalchemy.dialects.postgresql.Insert` (`sqlalchemy.sql.expression.Insert`)

  attribute `sqlalchemy.dialects.postgresql.Insert.` `excluded`

    Provide the `excluded` namespace for an ON CONFLICT statement

    PG’s ON CONFLICT clause allows reference to the row that would be inserted, known as `excluded`. This attribute provides all columns in this row to be referenceable.

    See also

    INSERT…ON CONFLICT (Upsert) - example of how to use `Insert.excluded`

  method `sqlalchemy.dialects.postgresql.Insert.` `on_conflict_do_nothing`(constraint=None, index_elements=None, index_where=None)

    Specifies a DO NOTHING action for ON CONFLICT clause.

    The `constraint` and `index_elements` arguments are optional, but only one of these can be specified.

    Parameters

      - constraint – The name of a unique or exclusion constraint on the table, or the constraint object itself if it has a .name attribute.

      - index_elements – A sequence consisting of string column names, `Column` objects, or other column expression objects that will be used to infer a target index.

      - index_where –

        Additional WHERE criterion that can be used to infer a conditional target index.

        New in version 1.1.

    See also

    INSERT…ON CONFLICT (Upsert)

  method `sqlalchemy.dialects.postgresql.Insert.` `on_conflict_do_update`(constraint=None, index_elements=None, index_where=None, set_=None, where=None)

    Specifies a DO UPDATE SET action for ON CONFLICT clause.

    Either the `constraint` or `index_elements` argument is required, but only one of these can be specified.

    Parameters

      - constraint – The name of a unique or exclusion constraint on the table, or the constraint object itself if it has a .name attribute.

      - index_elements – A sequence consisting of string column names, `Column` objects, or other column expression objects that will be used to infer a target index.

      - index_where – Additional WHERE criterion that can be used to infer a conditional target index.

      - set_ –

        Required argument. A dictionary or other mapping object with column names as keys and expressions or literals as values, specifying the `SET` actions to take. If the target `Column` specifies a “. key” attribute distinct from the column name, that key should be used.

        Warning

        This dictionary does not take into account Python-specified default UPDATE values or generation functions, e.g. those specified using `Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the `Insert.on_conflict_do_update.set_` dictionary.

      - where –

        Optional argument. 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`. Rows not meeting the `WHERE` condition will not be updated (effectively a `DO NOTHING` for those rows).

        New in version 1.1.

    See also

    INSERT…ON CONFLICT (Upsert)

## psycopg2

Support for the PostgreSQL database via the psycopg2 driver.

### DBAPI

Documentation and download information (if applicable) for psycopg2 is available at: http://pypi.python.org/pypi/psycopg2/

### Connecting

Connect String:

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

### psycopg2 Connect Arguments

psycopg2-specific keyword arguments which are accepted by `create_engine()` are:

- `server_side_cursors`: Enable the usage of “server side cursors” for SQL statements which support this feature. What this essentially means from a psycopg2 point of view is that the cursor is created using a name, e.g. `connection.cursor('some name')`, which has the effect that result rows are not immediately pre-fetched and buffered after statement execution, but are instead left on the server and only retrieved as needed. SQLAlchemy’s `ResultProxy` uses special row-buffering behavior when this feature is enabled, such that groups of 100 rows at a time are fetched over the wire to reduce conversational overhead. Note that the `Connection.execution_options.stream_results` execution option is a more targeted way of enabling this mode on a per-execution basis.

- `use_native_unicode`: Enable the usage of Psycopg2 “native unicode” mode per connection. True by default.

  See also

  Disabling Native Unicode

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

  See also

  Psycopg2 Transaction Isolation Level

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

  See also

  Unicode with Psycopg2

- `executemany_mode`, `executemany_batch_page_size`, `executemany_values_page_size`: Allows use of psycopg2 extensions for optimizing “executemany”-stye queries. See the referenced section below for details.

  See also

  Psycopg2 Fast Execution Helpers

- `use_batch_mode`: this is the previous setting used to affect “executemany” mode and is now deprecated.

### Unix Domain Connections

psycopg2 supports connecting via Unix domain connections. When the `host` portion of the URL is omitted, SQLAlchemy passes `None` to psycopg2, which specifies Unix-domain communication rather than TCP/IP communication:

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

By default, the socket file used is to connect to a Unix-domain socket in `/tmp`, or whatever socket directory was specified when PostgreSQL was built. This value can be overridden by passing a pathname to psycopg2, using `host` as an additional keyword argument:

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

See also

PQconnectdbParams

### Specfiying multiple fallback hosts

psycopg2 supports multiple connection points in the connection string. When the `host` parameter is used multiple times in the query section of the URL, SQLAlchemy will create a single string of the host and port information provided to make the connections:

    create_engine(
        "postgresql+psycopg2://user:password@/dbname?host=HostA:port1&host=HostB&host=HostC"
    )

A connection to each host is then attempted until either a connection is successful or all connections are unsuccessful in which case an error is raised.

New in version 1.3.20: Support for multiple hosts in PostgreSQL connection string.

See also

PQConnString

### Empty DSN Connections / Environment Variable Connections

The psycopg2 DBAPI can connect to PostgreSQL by passing an empty DSN to the libpq client library, which by default indicates to connect to a localhost PostgreSQL database that is open for “trust” connections. This behavior can be further tailored using a particular set of environment variables which are prefixed with `PG_...`, which are consumed by `libpq` to take the place of any or all elements of the connection string.

For this form, the URL can be passed without any elements other than the initial scheme:

    engine = create_engine('postgresql+psycopg2://')

In the above form, a blank “dsn” string is passed to the `psycopg2.connect()` function which in turn represents an empty DSN passed to libpq.

New in version 1.3.2: support for parameter-less connections with psycopg2.

See also

Environment Variables - PostgreSQL documentation on how to use `PG_...` environment variables for connections.

### Per-Statement/Connection Execution Options

The following DBAPI-specific options are respected when used with `Connection.execution_options()`, `Executable.execution_options()`, `Query.execution_options()`, in addition to those not specific to DBAPIs:

- `isolation_level` - Set the transaction isolation level for the lifespan of a `Connection` (can only be set on a connection, not a statement or query). See Psycopg2 Transaction Isolation Level.

- `stream_results` - Enable or disable usage of psycopg2 server side cursors - this feature makes use of “named” cursors in combination with special result handling methods so that result rows are not fully buffered. If `None` or not set, the `server_side_cursors` option of the `Engine` is used.

- `max_row_buffer` - when using `stream_results`, an integer value that specifies the maximum number of rows to buffer at a time. This is interpreted by the `BufferedRowResultProxy`, and if omitted the buffer will grow to ultimately store 1000 rows at a time.

  New in version 1.0.6.

### Psycopg2 Fast Execution Helpers

Modern versions of psycopg2 include a feature known as Fast Execution Helpers , which have been shown in benchmarking to improve psycopg2’s executemany() performance, primarily with INSERT statements, by multiple orders of magnitude. SQLAlchemy allows this extension to be used for all `executemany()` style calls invoked by an `Engine` when used with multiple parameter sets, which includes the use of this feature both by the Core as well as by the ORM for inserts of objects with non-autogenerated primary key values, by adding the `executemany_mode` flag to `create_engine()`:

    engine = create_engine(
        "postgresql+psycopg2://scott:tiger@host/dbname",
        executemany_mode='batch')

Changed in version 1.3.7: - the `use_batch_mode` flag has been superseded by a new parameter `executemany_mode` which provides support both for psycopg2’s `execute_batch` helper as well as the `execute_values` helper.

Possible options for `executemany_mode` include:

- `None` - By default, psycopg2’s extensions are not used, and the usual `cursor.executemany()` method is used when invoking batches of statements.

- `'batch'` - Uses `psycopg2.extras.execute_batch` so that multiple copies of a SQL query, each one corresponding to a parameter set passed to `executemany()`, are joined into a single SQL string separated by a semicolon. This is the same behavior as was provided by the `use_batch_mode=True` flag.

- `'values'`- For Core `insert()` constructs only (including those emitted by the ORM automatically), the `psycopg2.extras.execute_values` extension is used so that multiple parameter sets are grouped into a single INSERT statement and joined together with multiple VALUES expressions. This method requires that the string text of the VALUES clause inside the INSERT statement is manipulated, so is only supported with a compiled `insert()` construct where the format is predictable. For all other constructs, including plain textual INSERT statements not rendered by the SQLAlchemy expression language compiler, the `psycopg2.extras.execute_batch` method is used. It is therefore important to note that “values” mode implies that “batch” mode is also used for all statements for which “values” mode does not apply.

For both strategies, the `executemany_batch_page_size` and `executemany_values_page_size` arguments control how many parameter sets should be represented in each execution. Because “values” mode implies a fallback down to “batch” mode for non-INSERT statements, there are two independent page size arguments. For each, the default value of `None` means to use psycopg2’s defaults, which at the time of this writing are quite low at 100. For the `execute_values` method, a number as high as 10000 may prove to be performant, whereas for `execute_batch`, as the number represents full statements repeated, a number closer to the default of 100 is likely more appropriate:

    engine = create_engine(
        "postgresql+psycopg2://scott:tiger@host/dbname",
        executemany_mode='values',
        executemany_values_page_size=10000, executemany_batch_page_size=500)

See also

Executing Multiple Statements - General information on using the `Connection` object to execute statements in such a way as to make use of the DBAPI `.executemany()` method.

Changed in version 1.3.7: - Added support for `psycopg2.extras.execute_values`. The `use_batch_mode` flag is superseded by the `executemany_mode` flag.

### Unicode with Psycopg2

By default, the psycopg2 driver uses the `psycopg2.extensions.UNICODE` extension, such that the DBAPI receives and returns all strings as Python Unicode objects directly - SQLAlchemy passes these values through without change. Psycopg2 here will encode/decode string values based on the current “client encoding” setting; by default this is the value in the `postgresql.conf` file, which often defaults to `SQL_ASCII`. Typically, this can be changed to `utf8`, as a more useful default:

    # postgresql.conf file

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

A second way to affect the client encoding is to set it within Psycopg2 locally. SQLAlchemy will call psycopg2’s `psycopg2:connection.set_client_encoding()` method on all new connections based on the value passed to `create_engine()` using the `client_encoding` parameter:

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

This overrides the encoding specified in the PostgreSQL client configuration. 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.

Note that the `client_encoding` setting as passed to `create_engine()` is not the same as the more recently added `client_encoding` parameter now supported by libpq directly. This is enabled when `client_encoding` is passed directly to `psycopg2.connect()`, and from SQLAlchemy is passed using the `create_engine.connect_args` parameter:

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

The above parameter was only added to libpq as of version 9.1 of PostgreSQL, so using the previous method is better for cross-version support.

#### Disabling Native Unicode

SQLAlchemy can also be instructed to skip the usage of the psycopg2 `UNICODE` extension and to instead utilize its own unicode encode/decode services, which are normally reserved only for those DBAPIs that don’t fully support unicode directly. Passing `use_native_unicode=False` to `create_engine()` will disable usage of `psycopg2.extensions. UNICODE`. SQLAlchemy will instead encode data itself into Python bytestrings on the way in and coerce from bytes on the way back, using the value of the `create_engine()` `encoding` parameter, which defaults to `utf-8`. SQLAlchemy’s own unicode encode/decode functionality is steadily becoming obsolete as most DBAPIs now support unicode fully.

### Bound Parameter Styles

The default parameter style for the psycopg2 dialect is “pyformat”, where SQL is rendered using `%(paramname)s` style. This format has the limitation that it does not accommodate the unusual case of parameter names that actually contain percent or parenthesis symbols; as SQLAlchemy in many cases generates bound parameter names based on the name of a column, the presence of these characters in a column name can lead to problems.

There are two solutions to the issue of a `Column` that contains one of these characters in its name. One is to specify the `Column.key` for columns that have such names:

    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.

Changed in version 1.0.0: - SQL expressions will use `Column.key` as the source of naming when anonymous bound parameters are created in SQL expressions; previously, this behavior only applied to `Table.insert()` and `Table.update()` parameter names.

The other solution is to use a positional format; psycopg2 allows use of the “format” paramstyle, which can be passed to `create_engine.paramstyle`:

    engine = create_engine(
        'postgresql://scott:tiger@localhost:5432/test', paramstyle='format')

With the above engine, instead of a statement like:

    INSERT INTO measurement ("Size (meters)") VALUES (%(Size (meters))s)
    {'Size (meters)': 1}

we instead see:

    INSERT INTO measurement ("Size (meters)") VALUES (%s)
    (1, )

Where above, the dictionary style is converted into a tuple with positional style.

### Transactions

The psycopg2 dialect fully supports SAVEPOINT and two-phase commit operations.

### Psycopg2 Transaction Isolation Level

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()`. When using the psycopg2 dialect , these options make use of psycopg2’s `set_isolation_level()` connection method, rather than emitting a PostgreSQL directive; this is because psycopg2’s API-level setting is always emitted at the start of each transaction in any case.

The psycopg2 dialect supports these constants for isolation level:

- `READ COMMITTED`

- `READ UNCOMMITTED`

- `REPEATABLE READ`

- `SERIALIZABLE`

- `AUTOCOMMIT`

See also

Transaction Isolation Level

pg8000 Transaction Isolation Level

### NOTICE logging

The psycopg2 dialect will log PostgreSQL NOTICE messages via the `sqlalchemy.dialects.postgresql` logger. When this logger is set to the `logging.INFO` level, notice messages will be logged:

    import logging

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

Above, it is assumed that logging is configured externally. If this is not the case, configuration such as `logging.basicConfig()` must be utilized:

    import logging

    logging.basicConfig()   # log messages to stdout
    logging.getLogger('sqlalchemy.dialects.postgresql').setLevel(logging.INFO)

See also

Logging HOWTO - on the python.org website

### HSTORE type

The `psycopg2` DBAPI includes an extension to natively handle marshalling of the HSTORE type. The SQLAlchemy psycopg2 dialect will enable this extension by default when psycopg2 version 2.4 or greater is used, and it is detected that the target database has the HSTORE type set up for use. In other words, when the dialect makes the first connection, a sequence like the following is performed:

1. Request the available HSTORE oids using `psycopg2.extras.HstoreAdapter.get_oids()`. If this function returns a list of HSTORE identifiers, we then determine that the `HSTORE` extension is present. 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.

The `register_hstore()` extension has the effect of all Python dictionaries being accepted as parameters regardless of the type of target column in SQL. The dictionaries are converted by this extension into a textual HSTORE expression. If this behavior is not desired, disable the use of the hstore extension by setting `use_native_hstore` to `False` as follows:

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

The `HSTORE` type is still supported when the `psycopg2.extensions.register_hstore()` extension is not used. It merely means that the coercion between Python dictionaries and the HSTORE string format, on both the parameter side and the result side, will take place within SQLAlchemy’s own marshalling logic, and not that of `psycopg2` which may be more performant.

## pg8000

Support for the PostgreSQL database via the pg8000 driver.

### DBAPI

Documentation and download information (if applicable) for pg8000 is available at: https://pythonhosted.org/pg8000/

### Connecting

Connect String:

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

Note

The pg8000 dialect is not tested as part of SQLAlchemy’s continuous integration and may have unresolved issues. The recommended PostgreSQL dialect is psycopg2.

### Unicode

pg8000 will encode / decode string values between it and the server using the PostgreSQL `client_encoding` parameter; by default this is the value in the `postgresql.conf` file, which often defaults to `SQL_ASCII`. Typically, this can be changed to `utf-8`, as a more useful default:

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

The `client_encoding` can be overridden for a session by executing the SQL:

SET CLIENT_ENCODING TO ‘utf8’;

SQLAlchemy will execute this SQL on all new connections based on the value passed to `create_engine()` using the `client_encoding` parameter:

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

### pg8000 Transaction Isolation Level

The pg8000 dialect offers the same isolation level settings as that of the psycopg2 dialect:

- `READ COMMITTED`

- `READ UNCOMMITTED`

- `REPEATABLE READ`

- `SERIALIZABLE`

- `AUTOCOMMIT`

New in version 0.9.5: support for AUTOCOMMIT isolation level when using pg8000.

See also

Transaction Isolation Level

Psycopg2 Transaction Isolation Level

## psycopg2cffi

Support for the PostgreSQL database via the psycopg2cffi driver.

### DBAPI

Documentation and download information (if applicable) for psycopg2cffi is available at: http://pypi.python.org/pypi/psycopg2cffi/

### Connecting

Connect String:

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

`psycopg2cffi` is an adaptation of `psycopg2`, using CFFI for the C layer. This makes it suitable for use in e.g. PyPy. Documentation is as per `psycopg2`.

New in version 1.0.0.

See also

`sqlalchemy.dialects.postgresql.psycopg2`

## py-postgresql

Support for the PostgreSQL database via the py-postgresql driver.

### DBAPI

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

### Connecting

Connect String:

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

Note

The pypostgresql dialect is not tested as part of SQLAlchemy’s continuous integration and may have unresolved issues. The recommended PostgreSQL driver is psycopg2.

## pygresql

Support for the PostgreSQL database via the pygresql driver.

### DBAPI

Documentation and download information (if applicable) for pygresql is available at: http://www.pygresql.org/

### Connecting

Connect String:

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

Note

The pygresql dialect is not tested as part of SQLAlchemy’s continuous integration and may have unresolved issues. The recommended PostgreSQL dialect is psycopg2.

## zxjdbc

Support for the PostgreSQL database via the zxJDBC for Jython driver.

### DBAPI

Drivers for this database are available at: http://jdbc.postgresql.org/

### Connecting

Connect String:

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