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, Pythonic 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.Resultsinstance.Parameters: - name (str) – The procedure name
- args (list) – The list of arguments to pass in
Return type: 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¶ Return the current open connection to PostgreSQL.
Return type: psycopg2.extensions.connection
-
cursor¶ Return the current, active cursor for the open connection.
Return type: psycopg2.extensions.cursor
-
encoding¶ Return the current client encoding value.
Return type: str
-
notices¶ Return 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.Resultsobject 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: Raises: queries.DataError
Raises: queries.DatabaseError
Raises: queries.IntegrityError
Raises: queries.InternalError
Raises: queries.InterfaceError
Raises: queries.NotSupportedError
Raises: queries.OperationalError
Raises: queries.ProgrammingError