Connections

class dbapix.connection.Connection(engine, con)

A normalized connection to a database.

See the DB-API 2.0 specs for the minimal methods provided there.

Cursors and Convenience

Connection.cursor()

Get a Cursor for this connection.

cur = con.cursor()
cur.execute('SELECT 1')
assert next(cur)[0] == 1

Connection.execute(query, params=None)

Create a cursor, and execute a query on it in one step.

Returns

The created Cursor.

See also

Cursor.execute() for parameters and examples.

Connection.select(*args, **kwargs)

Pythonic wrapper for selecting.

See also

Cursor.select() for parameters and examples.

Connection.insert(*args, **kwargs)

Pythonic wrapper for inserting.

See also

Cursor.insert() for parameters and examples.

Connection.update(*args, **kwargs)

Pythonic wrapper for updating.

See also

Cursor.update() for parameters and examples.

Transactions

Transaction management is one of the larger normalization efforts of dbapix.

Connections start in “autocommit” mode (and can be inspected by Connection.autocommit). When in autocommit, the connection behaves as if it automatically commits after every query; your changes are immediately reflected in the database and availible to other connections.

When not in autocommit, the connection ensures it is in a transaction before executing a query, and the user must call Connection.commit() for changes to be reflected in the database (or may call Connection.rollback() to rollback).

Regardless of the state of autocommit, you can enter a transaction by using the connection as a context manager, or calling Connection.begin(). Autocommit is restored after the transaction if it was set before.

You can use a connection as a context manager to implicitly begin()/commit()/rollback():

with con:
    # Do stuff.
    pass

or you can call the methods explicitly:

con.begin()
try:
    # Do stuff.
    pass
except:
    con.rollback()
else:
    con.commit()

Connection.autocommit

Is every query executed in an implicit transaction that is auto committed?

Defaults to True on new connections.

Connection.begin()

Assert that we are or will be in a transaction.

Returns

A context manager that will automatically rollback or commit the current transaction.

If it can be avoided, this does not actually start a transaction, but instead asserts that the connection is not in autocommit mode. If autocommit cannot be disabled, then an explicit BEGIN will be executed.

commit() and rollback() restore autocommit to it’s value when begin() was called.

Connection.commit()

Commit changes made since the transaction started.

Connection.rollback()

Rollback changes made since the transaction started.

Session

Connection.closed

Has this connection been closed?

Connection.close()

Close the connection immediately.

This prevents the engine from reusing connections, and so is discouraged unless you are sure the connection should not be reused.

Connection.reset_session(autocommit=False)

Reset the connection to an initial clean state.

This is automatically called when connections are retreived from an engine, and is designed so that every connection feels like a new one, even though they are reused.

Connection.fileno()

Wrapped

Connection.wrapped

This is the underlying DB-API2 connection object, in case you need to access it.

Connection.__getattr__(key)

Attributes that are not provided by dbapix are passed through to the wrapped connection.