Creating a Managed Connection

>>> from pgmanagedconnection import ManagedConnection
>>>
>>> dsn = 'postgres:///postgres'  # a libpq connection string
>>> manager = ManagedConnection(dsn)
>>> manager
<ManagedConnection: postgres:///postgres (closed)>

Making Queries

>>> with manager() as connection:
...     cursor = connection.cursor()
...     cursor.execute('SELECT 1')
...     cursor.fetchone()
...     connection.commit()
(1,)

Dealing with Uncommitted Transactions

Leaving a transaction open when exiting the context manager will lead to a RuntimeError. This also results in any open transactions implicitly being rolled back.

>>> with manager() as connection:
...    cursor = connection.cursor()
...    cursor.execute('SELECT 1')
Traceback (most recent call last):
    ...
RuntimeError: Did not commit or rollback open transaction before releasing connection.

Dealing with Errors

The currently open transaction will be rolled back if an unhandled exception is encountered.

>>> import psycopg2
>>> with manager() as connection:
...    cursor = connection.cursor()
...    cursor.execute('SELECT 1')
...    assert manager.status is psycopg2.extensions.TRANSACTION_STATUS_INTRANS
...    raise NotImplementedError()
Traceback (most recent call last):
    ...
NotImplementedError
>>> manager.status is psycopg2.extensions.TRANSACTION_STATUS_IDLE
True

Testing

The test suite can be run with make test.

It assumes a running and accessible PostgreSQL server. The connection details are deferred to the underlying libpq implementation, and default values can be specified using libpq environment variables.

tox is also supported as a test runner (if installed.)

$ export PGPORT=5432
$ docker run -dp $PGPORT:5432 postgres
$ PGUSER=postgres make test

$ PGUSER=postgres PGHOST=$(boot2docker ip) make test