Session API

The Session class allows for a unified (and simplified) view of interfacing with a PostgreSQL database server.

Connection details are passed in as a PostgreSQL URI and connections are pooled by default, allowing for reuse of connections across modules in the Python runtime without having to pass around the object handle.

While you can still access the raw psycopg2 connection and cursor objects to provide ultimate flexibility in how you use the queries.Session object, there are convenience methods designed to simplify the interaction with PostgreSQL.

For psycopg2 functionality outside of what is exposed in Session, simply use the queries.Session.connection or queries.Session.cursor properties to gain access to either object just as you would in a program using psycopg2 directly.

Example Usage

The following example connects to the postgres database on localhost as the postgres user and then queries a table, iterating over the results:

import queries

with queries.Session('postgresql://postgres@localhost/postgres') as session:
    for row in session.query('SELECT * FROM table'):
        print row

Class Documentation

class queries.Session(uri='postgresql://localhost:5432', cursor_factory=<class 'psycopg2.extras.RealDictCursor'>, pool_idle_ttl=60, pool_max_size=1)[source]

The Session class allows for a unified (and simplified) view of interfacing with a PostgreSQL database server. The Session object can act as a context manager, providing automated cleanup and simple, pythoic way of interacting with the object.

Parameters:
  • uri (str) – PostgreSQL connection URI
  • psycopg2.extensions.cursor – The cursor type to use
  • pool_idle_ttl (int) – How long idle pools keep connections open
  • pool_max_size (int) – The maximum size of the pool to use
backend_pid

Return the backend process ID of the PostgreSQL server that this session is connected to.

Return type:int
callproc(name, args=None)[source]

Call a stored procedure on the server, returning the results in a queries.Results instance.

Parameters:
  • name (str) – The procedure name
  • args (list) – The list of arguments to pass in
Return type:

queries.Results

Raises:

queries.DataError

Raises:

queries.DatabaseError

Raises:

queries.IntegrityError

Raises:

queries.InternalError

Raises:

queries.InterfaceError

Raises:

queries.NotSupportedError

Raises:

queries.OperationalError

Raises:

queries.ProgrammingError

close()[source]

Explicitly close the connection and remove it from the connection pool if pooling is enabled. If the connection is already closed

Raises:psycopg2.InterfaceError
connection

The current open connection to PostgreSQL.

Return type:psycopg2.extensions.connection
cursor

The current, active cursor for the open connection.

Return type:psycopg2.extensions.cursor
encoding

The current client encoding value.

Return type:str
notices

A list of up to the last 50 server notices sent to the client.

Return type:list
pid

Return the pool ID used for connection pooling

Return type:str
query(sql, parameters=None)[source]

A generator to issue a query on the server, mogrifying the parameters against the sql statement. Results are returned as a queries.Results object which can act as an iterator and has multiple ways to access the result data.

Parameters:
  • sql (str) – The SQL statement
  • parameters (dict) – A dictionary of query parameters
Return type:

queries.Results

Raises:

queries.DataError

Raises:

queries.DatabaseError

Raises:

queries.IntegrityError

Raises:

queries.InternalError

Raises:

queries.InterfaceError

Raises:

queries.NotSupportedError

Raises:

queries.OperationalError

Raises:

queries.ProgrammingError

set_encoding(value='UTF8')[source]

Set the client encoding for the session if the value specified is different than the current client encoding.

Parameters:value (str) – The encoding value to use