"db_pool" -- DBAPI 2 database connection pooling
************************************************

The db_pool module is useful for managing database connections.  It
provides three primary benefits: cooperative yielding during database
operations, concurrency limiting to a database host, and connection
reuse.  db_pool is intended to be database-agnostic, compatible with
any DB-API 2.0 database module.

*It has currently been tested and used with both MySQLdb and
psycopg2.*

A ConnectionPool object represents a pool of connections open to a
particular database.  The arguments to the constructor include the
database-software-specific module, the host name, and the credentials
required for authentication.  After construction, the ConnectionPool
object decides when to create and sever connections with the target
database.

>>> import MySQLdb
>>> cp = ConnectionPool(MySQLdb, host='localhost', user='root', passwd='')

Once you have this pool object, you connect to the database by calling
"get()" on it:

>>> conn = cp.get()

This call may either create a new connection, or reuse an existing
open connection, depending on whether it has one open already or not.
You can then use the connection object as normal.  When done, you must
return the connection to the pool:

>>> conn = cp.get()
>>> try:
...     result = conn.cursor().execute('SELECT NOW()')
... finally:
...     cp.put(conn)

After you've returned a connection object to the pool, it becomes
useless and will raise exceptions if any of its methods are called.


Constructor Arguments
=====================

In addition to the database credentials, there are a bunch of keyword
constructor arguments to the ConnectionPool that are useful.

* min_size, max_size : The normal Pool arguments.  max_size is the
  most important constructor argument -- it determines the number of
  concurrent connections can be open to the destination database.
  min_size is not very useful.

* max_idle : Connections are only allowed to remain unused in the pool
  for a limited amount of time.  An asynchronous timer periodically
  wakes up and closes any connections in the pool that have been idle
  for longer than they are supposed to be.  Without this parameter,
  the pool would tend to have a 'high-water mark', where the number of
  connections open at a given time corresponds to the peak historical
  demand.  This number only has effect on the connections in the pool
  itself -- if you take a connection out of the pool, you can hold on
  to it for as long as you want.  If this is set to 0, every
  connection is closed upon its return to the pool.

* max_age : The lifespan of a connection.  This works much like
  max_idle, but the timer is measured from the connection's creation
  time, and is tracked throughout the connection's life.  This means
  that if you take a connection out of the pool and hold on to it for
  some lengthy operation that exceeds max_age, upon putting the
  connection back in to the pool, it will be closed.  Like max_idle,
  max_age will not close connections that are taken out of the pool,
  and, if set to 0, will cause every connection to be closed when put
  back in the pool.

* connect_timeout : How long to wait before raising an exception on
  connect().  If the database module's connect() method takes too
  long, it raises a ConnectTimeout exception from the get() method on
  the pool.


DatabaseConnector
=================

If you want to connect to multiple databases easily (and who doesn't),
the DatabaseConnector is for you.  It's a pool of pools, containing a
ConnectionPool for every host you connect to.

The constructor arguments are:

* module : database module, e.g. MySQLdb.  This is simply passed
  through to the ConnectionPool.

* credentials : A dictionary, or dictionary-alike, mapping hostname to
  connection-argument-dictionary.  This is used for the constructors
  of the ConnectionPool objects.  Example:

>>> dc = DatabaseConnector(MySQLdb,
...      {'db.internal.example.com': {'user': 'internal', 'passwd': 's33kr1t'},
...       'localhost': {'user': 'root', 'passwd': ''}})

If the credentials contain a host named 'default', then the value for
'default' is used whenever trying to connect to a host that has no
explicit entry in the database.  This is useful if there is some pool
of hosts that share arguments.

* conn_pool : The connection pool class to use.  Defaults to
  db_pool.ConnectionPool.

The rest of the arguments to the DatabaseConnector constructor are
passed on to the ConnectionPool.

*Caveat: The DatabaseConnector is a bit unfinished, it only suits a
subset of use cases.*

class eventlet.db_pool.BaseConnectionPool(db_module, min_size=0, max_size=4, max_idle=10, max_age=30, connect_timeout=5, cleanup=<function cleanup_rollback>, *args, **kwargs)

   clear()

      Close all connections that this pool still holds a reference to,
      and removes all references to them.

   get()

      Return an item from the pool, when one is available.  This may
      cause the calling greenthread to block.

   item(cleanup=<object object>)

      Get an object out of the pool, for use with with statement.

      >>> from eventlet import pools
      >>> pool = pools.TokenPool(max_size=4)
      >>> with pool.item() as obj:
      ...     print("got token")
      ...
      got token
      >>> pool.free()
      4

   put(conn, cleanup=<object object>)

      Put an item back into the pool, when done.  This may cause the
      putting greenthread to block.

exception eventlet.db_pool.ConnectTimeout

eventlet.db_pool.ConnectionPool

   alias of "TpooledConnectionPool"

class eventlet.db_pool.DatabaseConnector(module, credentials, conn_pool=None, *args, **kwargs)

   This is an object which will maintain a collection of database
   connection pools on a per-host basis.

   credentials_for(host)

   get(host, dbname)

      Returns a ConnectionPool to the target host and schema.

class eventlet.db_pool.GenericConnectionWrapper(baseconn)

   affected_rows(*args, **kwargs)

   autocommit(*args, **kwargs)

   begin(*args, **kwargs)

   change_user(*args, **kwargs)

   character_set_name(*args, **kwargs)

   close(*args, **kwargs)

   commit(*args, **kwargs)

   cursor(*args, **kwargs)

   dump_debug_info(*args, **kwargs)

   errno(*args, **kwargs)

   error(*args, **kwargs)

   errorhandler(*args, **kwargs)

   get_server_info(*args, **kwargs)

   insert_id(*args, **kwargs)

   literal(*args, **kwargs)

   ping(*args, **kwargs)

   query(*args, **kwargs)

   rollback(*args, **kwargs)

   select_db(*args, **kwargs)

   server_capabilities(*args, **kwargs)

   set_character_set(*args, **kwargs)

   set_isolation_level(*args, **kwargs)

   set_server_option(*args, **kwargs)

   set_sql_mode(*args, **kwargs)

   show_warnings(*args, **kwargs)

   shutdown(*args, **kwargs)

   sqlstate(*args, **kwargs)

   stat(*args, **kwargs)

   store_result(*args, **kwargs)

   string_literal(*args, **kwargs)

   thread_id(*args, **kwargs)

   use_result(*args, **kwargs)

   warning_count(*args, **kwargs)

class eventlet.db_pool.PooledConnectionWrapper(baseconn, pool)

   A connection wrapper where: - the close method returns the
   connection to the pool instead of closing it directly -
   "bool(conn)" returns a reasonable value - returns itself to the
   pool if it gets garbage collected

   close()

      Return the connection to the pool, and remove the reference to
      it so that you can't use it again through this wrapper object.

class eventlet.db_pool.RawConnectionPool(db_module, min_size=0, max_size=4, max_idle=10, max_age=30, connect_timeout=5, cleanup=<function cleanup_rollback>, *args, **kwargs)

   A pool which gives out plain database connections.

   classmethod connect(db_module, connect_timeout, *args, **kw)

   create()

      Generate a new pool item.  In order for the pool to function,
      either this method must be overriden in a subclass or the pool
      must be constructed with the *create* argument. It accepts no
      arguments and returns a single instance of whatever thing the
      pool is supposed to contain.

      In general, "create()" is called whenever the pool exceeds its
      previous high-water mark of concurrently-checked-out-items.  In
      other words, in a new pool with *min_size* of 0, the very first
      call to "get()" will result in a call to "create()".  If the
      first caller calls "put()" before some other caller calls
      "get()", then the first item will be returned, and "create()"
      will not be called a second time.

class eventlet.db_pool.TpooledConnectionPool(db_module, min_size=0, max_size=4, max_idle=10, max_age=30, connect_timeout=5, cleanup=<function cleanup_rollback>, *args, **kwargs)

   A pool which gives out "Proxy"-based database connections.

   classmethod connect(db_module, connect_timeout, *args, **kw)

   create()

      Generate a new pool item.  In order for the pool to function,
      either this method must be overriden in a subclass or the pool
      must be constructed with the *create* argument. It accepts no
      arguments and returns a single instance of whatever thing the
      pool is supposed to contain.

      In general, "create()" is called whenever the pool exceeds its
      previous high-water mark of concurrently-checked-out-items.  In
      other words, in a new pool with *min_size* of 0, the very first
      call to "get()" will result in a call to "create()".  If the
      first caller calls "put()" before some other caller calls
      "get()", then the first item will be returned, and "create()"
      will not be called a second time.

eventlet.db_pool.cleanup_rollback(conn)
