1.1.5.7. gnr.sql.PersistentDB

Last page update: September 28, 2011

Main class:

• PersistentDB

Exceptions classes:

• PersistentDBError
• NotSupportedError

Complete reference:

• gnr.sql.PersistentDB

1.1.5.7.1. PersistentDB

• connection()
• dedicated_connection()
• steady_connection()

1.1.5.7.2. NotSupportedError

there is no public method.

1.1.5.7.3. PersistentDBError

there is no public method.

1.1.5.7.4. gnr.sql.PersistentDB

PersistentDB - persistent DB-API 2 connections.

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

This should result in a speedup for persistent applications such as the application server of “Webware for Python,” without loss of robustness.

Robustness is provided by using “hardened” SteadyDB connections. Even if the underlying database is restarted and all connections are lost, they will be automatically and transparently reopened.

Measures are taken to make the database connections thread-affine. This means the same thread always uses the same cached connection, and no other thread will use it. So even if the underlying DB-API module is not thread-safe at the connection level this will be no problem here.

For best performance, the application server should keep threads persistent. For this, you have to set MinServerThreads = MaxServerThreads in Webware.

• 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:

First you need to set up a generator for your kind of database connections by creating an instance of PersistentDB, passing the following parameters:

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

  connection objects or a DB-API 2 compliant database module

• maxusage: the maximum number of reuses of a single connection

  (the default of 0 or None means unlimited reuse) Whenever the limit is reached, the connection will be reset.

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

  prepare the session, e.g. [“set datestyle to german”, ...].

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

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

*closeable: if this is set to true, then closing connections will

be allowed, but by default this will be silently ignored

• threadlocal: an optional class for representing thread-local data

  that will be used instead of our Python implementation (threading.local is faster, but cannot be used in all cases)

The creator function or the connect function of the DB-API 2 compliant database module specified as the creator will receive any additional parameters such as the host, database, user, password etc. You may choose some or all of these parameters in your own creator function, allowing for sophisticated failover and load-balancing mechanisms.

For instance, if you are using pgdb as your DB-API 2 database module and want every connection to your local database ‘mydb’ to be reused 1000 times:

import pgdb # import used DB-API 2 module
from DBUtils.PersistentDB import PersistentDB
persist = PersistentDB(pgdb, 1000, database='mydb')

Once you have set up the generator with these parameters, you can request database connections of that kind:

db = persist.connection()

You can use these connections just as if they were ordinary DB-API 2 connections. Actually what you get is the hardened SteadyDB version of the underlying DB-API 2 connection.

Closing a persistent connection with db.close() will be silently ignored since it would be reopened at the next usage anyway and contrary to the intent of having persistent connections. Instead, the connection will be automatically closed when the thread dies. You can change this behavior be setting the closeable parameter.

Note that by setting the threadlocal parameter to threading.local, getting connections may become a bit faster, but this may not work in all environments (for instance, mod_wsgi is known to cause problems since it clears the threading.local data between requests).

Requirements:

Python >= 2.2, < 3.0.

Ideas for improvement:

• Add a thread for monitoring, restarting (or closing) bad or expired connections (similar to DBConnectionPool/ResourcePool by Warren Smith).
• Optionally log usage, bad connections and exceeding of limits.

Copyright, credits and license:

• Contributed as supplement for Webware for Python and PyGreSQL by Christoph Zwerschke in September 2005
• Based on an idea presented on the Webware developer mailing list by Geoffrey Talvola in July 2005

Licensed under the Open Software License version 2.1.

exception gnr.sql.PersistentDB.NotSupportedError

DB-API module not supported by PersistentDB.

class gnr.sql.PersistentDB.PersistentDB(creator, maxusage=None, setsession=None, failures=None, closeable=False, threadlocal=None, *args, **kwargs)

Generator for persistent DB-API 2 connections.

After you have created the connection pool, you can use connection() to get thread-affine, steady DB-API 2 connections.

connection(shareable=False)

Get a steady, persistent DB-API 2 connection.

The shareable parameter exists only for compatibility with the PooledDB connection method. In reality, persistent connections are of course never shared with other threads.

dedicated_connection()

Alias for connection(shareable=False).

steady_connection()

Get a steady, non-persistent DB-API 2 connection.

exception gnr.sql.PersistentDB.PersistentDBError

General PersistentDB error.