- cleanup on connection methods + documentation. custom DBAPI

arguments specified in query string, 'connect_args' argument
to 'create_engine', or custom creation function via 'creator'
function to 'create_engine'.
- added "recycle" argument to Pool, is "pool_recycle" on create_engine,
defaults to 3600 seconds; connections after this age will be closed and
replaced with a new one, to handle db's that automatically close
stale connections [ticket:274]

2 files changed, 27 insertions, 2 deletions

diff --git a/doc/build/content/dbengine.txt b/doc/build/content/dbengine.txt
index e35cc0499..d8dec80c0 100644
--- a/doc/build/content/dbengine.txt
+++ b/doc/build/content/dbengine.txt
@@ -61,6 +61,28 @@ Available drivernames are `sqlite`, `mysql`, `postgres`, `oracle`, `mssql`, and
 
 The `Engine` will create its first connection to the database when a SQL statement is executed.  As concurrent statements are executed, the underlying connection pool will grow to a default size of five connections, and will allow a default "overflow" of ten.   Since the `Engine` is essentially "home base" for the connection pool, it follows that you should keep a single `Engine` per database established within an application, rather than creating a new one for each connection.
 
+#### Custom DBAPI keyword arguments
+
+Custom arguments can be passed to the underlying DBAPI in three ways.  String-based arguments can be passed directly from the URL string as query arguments:
+
+    {python}
+    db = create_engine('postgres://scott:tiger@localhost/test?argument1=foo&argument2=bar')
+
+If SQLAlchemy's database connector is aware of a particular query argument, it may convert its type from string to its proper type.
+    
+`create_engine` also takes an argument `connect_args` which is an additional dictionary that will be passed to `connect()`.  This can be used when arguments of a type other than string are required, and SQLAlchemy's database connector has no type conversion logic present for that parameter:
+
+    {python}
+    db = create_engine('postgres://scott:tiger@localhost/test', create_args = {'argument1':17, 'argument2':'bar'})
+
+The most customizable connection method of all is to pass a `creator` argument, which specifies a callable that returns a DBAPI connection:
+
+    {python}
+    def connect():
+        return psycopg.connect(user='scott', host='localhost')
+
+    db = create_engine('postgres://', creator=connect)
+        
 ### Database Engine Options {@name=options}
 
 Keyword options can also be specified to `create_engine()`, following the string URL as follows:
@@ -71,9 +93,10 @@ Keyword options can also be specified to `create_engine()`, following the string
 Options that can be specified include the following:
 
 * strategy='plain' : the Strategy describes the general configuration used to create this Engine.  The two available values are `plain`, which is the default, and `threadlocal`, which applies a "thread-local context" to implicit executions performed by the Engine.  This context is further described in [dbengine_connections_context](rel:dbengine_connections_context).
-* pool=None : an instance of `sqlalchemy.pool.Pool` to be used as the underlying source for connections, overriding the engine's connect arguments (pooling is described in [pooling](rel:pooling)).  If None, a default `Pool` (usually `QueuePool`, or `SingletonThreadPool` in the case of SQLite) will be created using the engine's connect arguments.
+* poolclass=None : a `sqlalchemy.pool.Pool` subclass (or duck-typed equivalent) that will be instantated in place of the default connection pool.
+* pool=None : an actual pool instance.  Note that an already-constructed pool should already know how to create database connections, so this option supercedes any other connect options specified.  Typically, it is an instance of `sqlalchemy.pool.Pool` to be used as the underlying source for connections.  For more on connection pooling, see [pooling](rel:pooling).
 
-Example:
+Example of a manual invocation of `pool.QueuePool` (which is the pool instance used for all databases except sqlite):
 
     {python}
     from sqlalchemy import *
@@ -88,6 +111,7 @@ Example:
 * pool_size=5 : the number of connections to keep open inside the connection pool.  This used with `QueuePool` as well as `SingletonThreadPool` as of 0.2.7.
 * max_overflow=10 : the number of connections to allow in "overflow", that is connections that can be opened above and beyond the initial five.  this is only used with `QueuePool`.
 * pool_timeout=30 : number of seconds to wait before giving up on getting a connection from the pool.  This is only used with `QueuePool`.
+* pool_recycle=3600 : this setting causes the pool to recycle connections after the given number of seconds has passed.  It defaults to 3600 seconds, or one hour.  Note that MySQL in particular will disconnect automatically if no activity is detected on a connection for eight hours.
 * echo=False : if True, the Engine will log all statements as well as a repr() of their parameter lists to the engines logger, which defaults to sys.stdout.  The `echo` attribute of `ComposedSQLEngine` can be modified at any time to turn logging on and off.  If set to the string `"debug"`, result rows will be printed to the standard output as well.
 * logger=None : a file-like object where logging output can be sent, if echo is set to True.  Newlines will not be sent with log messages.  This defaults to an internal logging object which references `sys.stdout`.
 * module=None : used by database implementations which support multiple DBAPI modules, this is a reference to a DBAPI2 module to be used instead of the engine's default module.  For Postgres, the default is psycopg2, or psycopg1 if 2 cannot be found.  For Oracle, its cx_Oracle.
diff --git a/doc/build/content/pooling.txt b/doc/build/content/pooling.txt
index 186b3e596..424a64ab4 100644
--- a/doc/build/content/pooling.txt
+++ b/doc/build/content/pooling.txt
@@ -31,6 +31,7 @@ When proxying a DBAPI module through the `pool` module, options exist for how th
 
 * echo=False : if set to True, connections being pulled and retrieved from/to the pool will be logged to the standard output, as well as pool sizing information.
 * use\_threadlocal=True : if set to True, repeated calls to connect() within the same application thread will be guaranteed to return the **same** connection object, if one has already been retrieved from the pool and has not been returned yet.  This allows code to retrieve a connection from the pool, and then while still holding on to that connection, to call other functions which also ask the pool for a connection of the same arguments;  those functions will act upon the same connection that the calling method is using.  Note that once the connection is returned to the pool, it then may be used by another thread.  To guarantee a single unique connection per thread that **never** changes, use the option `poolclass=SingletonThreadPool`, in which case the use_threadlocal parameter is not used.
+* recycle=3600 : this setting causes the pool to recycle connections after the given number of seconds has passed.  It defaults to 3600 seconds, or one hour.  Note that MySQL in particular will disconnect automatically if no activity is detected on a connection for eight hours.
 * poolclass=QueuePool :  the Pool class used by the pool module to provide pooling.  QueuePool uses the Python `Queue.Queue` class to maintain a list of available connections.  A developer can supply his or her own Pool class to supply a different pooling algorithm.  Also included is the `SingletonThreadPool`, which provides a single distinct connection per thread and is required with SQLite.
 * pool\_size=5 : used by `QueuePool` as well as `SingletonThreadPool` as of 0.2.7 - the size of the pool to be maintained.  This is the largest number of connections that will be kept persistently in the pool.  Note that the pool begins with no connections; once this number of connections is requested, that number of connections will remain.
 * max\_overflow=10 : used by `QueuePool` - the maximum overflow size of the pool.  When the number of checked-out connections reaches the size set in pool_size, additional connections will be returned up to this limit.  When those additional connections are returned to the pool, they are disconnected and discarded.  It follows then that the total number of simultaneous connections the pool will allow is `pool_size` + `max_overflow`, and the total number of "sleeping" connections the pool will allow is `pool_size`.  `max_overflow` can be set to -1 to indicate no overflow limit; no limit will be placed on the total number of concurrent connections.