1.1.5.8. gnr.sql.SteadyDB

Last page update: September 28, 2011

Classes:

• SteadyDBConnection
• SteadyDBCursor
• connect

Exceptions classes:

• InvalidCursor
• SteadyDBError

Complete reference:

• gnr.sql.SteadyDB - The complete reference list

1.1.5.8.1. SteadyDBConnection

• close()
• commit()
• cursor()
• dbapi()
• rollback()
• threadsafety()

1.1.5.8.2. SteadyDBCursor

• close()
• setinputsizes()
• setoutputsize()

1.1.5.8.3. connect

there is no public method.

1.1.5.8.4. InvalidCursor

there is no public method.

1.1.5.8.5. SteadyDBError

there is no public method.

1.1.5.8.6. gnr.sql.SteadyDB - The complete reference list

SteadyDB - hardened DB-API 2 connections.

Implements steady connections to a database based on an arbitrary DB-API 2 compliant database interface module.

The connections are transparently reopened when they are closed or the database connection has been lost or when they are used more often than an optional usage limit. Database cursors are transparently reopened as well when the execution of a database operation cannot be performed due to a lost connection. Only if the connection is lost after the execution, when rows are already fetched from the database, this will give an error and the cursor will not be reopened automatically, because there is no reliable way to recover the state of the cursor in such a situation.

A typical situation where database connections are lost is when the database server or an intervening firewall is shutdown and restarted for maintenance reasons. In such a case, all database connections would become unusable, even though the database service may be already available again.

The “hardened” connections provided by this module will make the database connections immediately available again.

This approach results in a steady database connection that can be used by PooledDB or PersistentDB to create pooled or persistent connections to a database in a threaded environment such as the application server of “Webware for Python.” Note, however, that the connections themselves may not be thread-safe (depending on the used DB-API module).

• For the Python DB-API 2 specification, see: http://www.python.org/peps/pep-0249.html
• For information on Webware for Python, see: http://www.webwareforpython.org

Usage:

You can use the connection constructor connect() in the same way as you would use the connection constructor of a DB-API 2 module if you specify the DB-API 2 module to be used as the first parameter, or alternatively you can specify an arbitrary constructor function returning new DB-API 2 compliant connection objects as the first parameter. Passing just a function allows implementing failover mechanisms and load balancing strategies.

You may also specify a usage limit as the second parameter (set it to None if you prefer unlimited usage), an optional list of commands that may serve to prepare the session as a third parameter, the exception classes for which the failover mechanism shall be applied, and you can specify whether is is allowed to close the connection (by default this is true). When the connection to the database is lost or has been used too often, it will be transparently reset in most situations, without further notice:

import pgdb # import used DB-API 2 module
from DBUtils.SteadyDB import connect
db = connect(pgdb, 10000, ["set datestyle to german"],
        host=..., database=..., user=..., ...)
...
cursor = db.cursor()
...
cursor.execute('select ...')
result = cursor.fetchall()
...
cursor.close()
...
db.close()

Ideas for improvement:

• Alternatively to the maximum number of uses, implement a maximum time to live for connections.
• Optionally log usage and loss of connection.

Copyright, credits and license:

• Contributed as supplement for Webware for Python and PyGreSQL by Christoph Zwerschke in September 2005
• Allowing creator functions as first parameter as in SQLAlchemy suggested by Ezio Vernacotola in December 2006

Licensed under the Open Software License version 2.1.

exception gnr.sql.SteadyDB.InvalidCursor

Database cursor is invalid.

class gnr.sql.SteadyDB.SteadyDBConnection(creator, maxusage=None, setsession=None, failures=None, closeable=True, *args, **kwargs)

A “tough” version of DB-API 2 connections.

close()

Close the tough connection.

You are allowed to close a tough connection by default and it will not complain if you close it more than once.

You can disallow closing connections by setting the closeable parameter to something false. In this case, closing tough connections will be silently ignored.

commit()

Commit any pending transaction.

cursor(*args, **kwargs)

Return a new Cursor Object using the connection.

dbapi()

Return the underlying DB-API 2 module of the connection.

rollback()

Rollback pending transaction.

threadsafety()

Return the thread safety level of the connection.

class gnr.sql.SteadyDB.SteadyDBCursor(con, *args, **kwargs)

A “tough” version of DB-API 2 cursors.

close()

Close the tough cursor.

It will not complain if you close it more than once.

setinputsizes(sizes)

Store input sizes in case cursor needs to be reopened.

setoutputsize(size, column=None)

Store output sizes in case cursor needs to be reopened.

exception gnr.sql.SteadyDB.SteadyDBError

General SteadyDB error.

gnr.sql.SteadyDB.connect(creator, maxusage=None, setsession=None, failures=None, closeable=True, *args, **kwargs)

A tough version of the connection constructor of a DB-API 2 module.

• creator: either an arbitrary function returning new DB-API 2 compliant

  connection objects or a DB-API 2 compliant database module

• maxusage: maximum usage limit for the underlying DB-API 2 connection

  (number of database operations, 0 or None means unlimited usage) callproc(), execute() and executemany() count as one operation. When the limit is reached, the connection is automatically reset.

• setsession: an optional list of SQL commands that may serve to prepare

  the session, e.g. [“set datestyle to german”, “set time zone mez”]

• failures: an optional exception class or a tuple of exception classes

  for which the failover mechanism shall be applied, if the default (OperationalError, InternalError) is not adequate

• closeable: if this is set to false, then closing the connection will

  be silently ignored, but by default the connection can be closed

• args, kwargs: the parameters that shall be passed to the creator

  function or the connection constructor of the DB-API 2 module