PostgreSQL — SQLAlchemy 0.7.1 Documentation

# SQLAlchemy 0.7.1 Documentation

Search:
Version: 0.7.1 Last Updated: 06/05/2011 13:13:59

# PostgreSQL

Support for the PostgreSQL database.

For information on connecting using specific drivers, see the documentation section regarding that driver.

## Sequences/SERIAL

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

## Transaction Isolation Level

`create_engine()` accepts an `isolation_level` parameter which results in the command `SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL <level>` being invoked for every new connection. Valid values for this parameter are `READ_COMMITTED`, `READ_UNCOMMITTED`, `REPEATABLE_READ`, and `SERIALIZABLE`. Note that the psycopg2 dialect does not use this technique and uses psycopg2-specific APIs (see that dialect for details).

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

## Indexes

PostgreSQL supports partial indexes. To create them pass a postgresql_where option to the Index constructor:

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

## 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, INET, INTEGER, INTERVAL, \
        MACADDR, NUMERIC, REAL, SMALLINT, TEXT, TIME, TIMESTAMP, \
        UUID, VARCHAR

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

class `sqlalchemy.dialects.postgresql.` `ARRAY`(item_type, mutable=False, as_tuple=False)

  Bases: `sqlalchemy.types.MutableType`, `sqlalchemy.types.Concatenable`, `sqlalchemy.types.TypeEngine`

  Postgresql ARRAY type.

  Represents values as Python lists.

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

  `__init__`(item_type, mutable=False, as_tuple=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. The type mapping figures out on the fly mutable=False – Specify whether lists passed to this class should be considered mutable - this enables “mutable types” mode in the ORM. Be sure to read the notes for `MutableType` regarding ORM performance implications (default changed from `True` in 0.7.0). Note This functionality is now superseded by the `sqlalchemy.ext.mutable` extension described in Mutation Tracking. 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. This flag can only be set to `True` when `mutable` is set to `False`. (new in 0.6.5)

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

  Bases: `sqlalchemy.types.TypeEngine`

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

  Bases: `sqlalchemy.types.LargeBinary`

  `__init__`(length=None)

    Construct a LargeBinary type.

    Parameters: | length – optional, a length for the column for use in DDL statements, for those BLOB types that accept a length (i.e. MySQL). It does not produce a small BINARY/VARBINARY type - use the BINARY/VARBINARY types specifically for those. May be safely omitted if no `CREATE TABLE` will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the `CREATE TABLE` DDL is issued.

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

  Bases: `sqlalchemy.types.TypeEngine`

  `__init__`(*args, **kwargs)

    Support implementations that were passing arguments

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

  Bases: `sqlalchemy.types.Float`

  `__init__`(precision=None, asdecimal=False, **kwargs)

    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.

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

  Bases: `sqlalchemy.types.Enum`

  `__init__`(*enums, **kw)

    Construct an enum.

    Keyword arguments which don’t apply to a specific backend are ignored by that backend.

    Parameters: | *enums – string or unicode enumeration labels. If unicode labels are present, the convert_unicode flag is auto-enabled. convert_unicode – Enable unicode-aware bind parameter and result-set processing for this Enum’s data. This is set automatically based on the presence of unicode label strings. metadata – Associate this type directly with a `MetaData` object. For types that exist on the target database as an independent schema construct (Postgresql), this type will be created and dropped within `create_all()` and `drop_all()` operations. If the type is not associated with any `MetaData` object, it will associate itself with each `Table` in which it is used, and will be created when any of those individual tables are created, after a check is performed for it’s existence. The type is only dropped when `drop_all()` is called for that `Table` object’s metadata, however. name – The name of this type. This is required for Postgresql and any future supported database which requires an explicitly named type, or an explicitly named constraint in order to generate the type and/or a table that uses it. native_enum – Use the database’s native ENUM type when available. Defaults to True. When False, uses VARCHAR + check constraint for all backends. schema – Schemaname of this type. For types that exist on the target database as an independent schema construct (Postgresql), this parameter specifies the named schema in which the type is present. quote – Force quoting to be on or off on the type’s name. If left as the default of None, the usual schema-level “case sensitive”/”reserved name” rules are used to determine if this type’s name should be quoted.

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

  Bases: `sqlalchemy.types.TypeEngine`

  `__init__`(*args, **kwargs)

    Support implementations that were passing arguments

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

  Bases: `sqlalchemy.types.TypeEngine`

  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 `sqlalchemy.dialects.postgresql.` `MACADDR`(*args, **kwargs)

  Bases: `sqlalchemy.types.TypeEngine`

  `__init__`(*args, **kwargs)

    Support implementations that were passing arguments

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

  Bases: `sqlalchemy.types.Float`

  The SQL REAL type.

  `__init__`(precision=None, asdecimal=False, **kwargs)

    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.

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

  Bases: `sqlalchemy.types.TypeEngine`

  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.

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

## psycopg2 Notes

Support for the PostgreSQL database via the psycopg2 driver.

### Driver

The psycopg2 driver is available at http://pypi.python.org/pypi/psycopg2/ . The dialect has several behaviors which are specifically tailored towards compatibility with this module.

Note that psycopg1 is not supported.

### Connecting

URLs are of the form `postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...]`.

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 `stream_results=True` 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.

### 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). This includes the options `SERIALIZABLE`, `READ COMMITTED`, `READ UNCOMMITTED` and `REPEATABLE READ`.
- stream_results - Enable or disable usage of server side cursors. If `None` or not set, the `server_side_cursors` option of the `Engine` is used.

### Unicode

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. Note that this setting requires that the PG client encoding be set to one which can accomodate the kind of character data being passed - typically `utf-8`. If the Postgresql database is configured for `SQL_ASCII` encoding, which is often the default for PG installations, it may be necessary for non-ascii strings to be encoded into a specific encoding before being passed to the DBAPI. If changing the database’s client encoding setting is not an option, specify `use_native_unicode=False` as a keyword argument to `create_engine()`, and take note of the `encoding` setting as well, which also defaults to `utf-8`. Note that disabling “native unicode” mode has a slight performance penalty, as SQLAlchemy now must translate unicode strings to/from an encoding such as utf-8, a task that is handled more efficiently within the Psycopg2 driver natively.

### Transactions

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

### Transaction Isolation Level

The `isolation_level` parameter of `create_engine()` here makes use psycopg2’s `set_isolation_level()` connection method, rather than issuing a `SET SESSION CHARACTERISTICS` command. This because psycopg2 resets the isolation level on each new transaction, and needs to know at the API level what level should be used.

### NOTICE logging

The psycopg2 dialect will log Postgresql NOTICE messages via the `sqlalchemy.dialects.postgresql` logger:

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

## py-postgresql Notes

Support for the PostgreSQL database via py-postgresql.

### Connecting

URLs are of the form `postgresql+pypostgresql://user@password@host:port/dbname[?key=value&key=value...]`.

## pg8000 Notes

Support for the PostgreSQL database via the pg8000 driver.

### Connecting

URLs are of the form `postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...]`.

### Unicode

pg8000 requires that the postgresql client encoding be configured in the postgresql.conf file in order to use encodings other than ascii. Set this value to the same value as the “encoding” parameter on create_engine(), usually “utf-8”.

### Interval

Passing data from/to the Interval type is not supported as of yet.

## zxjdbc Notes

Support for the PostgreSQL database via the zxjdbc JDBC connector.

### JDBC Driver

The official Postgresql JDBC driver is at http://jdbc.postgresql.org/.