11 files changed, 158 insertions, 49 deletions
diff --git a/lib/sqlalchemy/connectors/mxodbc.py b/lib/sqlalchemy/connectors/mxodbc.py
index f50bff7da..816474d43 100644
--- a/lib/sqlalchemy/connectors/mxodbc.py
+++ b/lib/sqlalchemy/connectors/mxodbc.py
@@ -9,6 +9,7 @@ and 2008, using the SQL Server Native driver. However, it is
 possible for this to be used on other database platforms.
 
 For more info on mxODBC, see http://www.egenix.com/
+
 """
 
 import sys
diff --git a/lib/sqlalchemy/dialects/mssql/mxodbc.py b/lib/sqlalchemy/dialects/mssql/mxodbc.py
index 7148a3628..efe763659 100644
--- a/lib/sqlalchemy/dialects/mssql/mxodbc.py
+++ b/lib/sqlalchemy/dialects/mssql/mxodbc.py
@@ -1,9 +1,41 @@
 """
-MSSQL dialect tweaked to work with mxODBC, mainly by making use
-of the MSSQLStrictCompiler.
+Support for MS-SQL via mxODBC.
+
+mxODBC is available at:
+
+    http://www.egenix.com/
 
 This was tested with mxODBC 3.1.2 and the SQL Server Native
 Client connected to MSSQL 2005 and 2008 Express Editions.
+
+Connecting
+~~~~~~~~~~
+
+Connection is via DSN::
+
+    mssql+mxodbc://<username>:<password>@<dsnname>
+    
+Execution Modes
+~~~~~~~~~~~~~~~
+
+mxODBC features two styles of statement execution, using the ``cursor.execute()``
+and ``cursor.executedirect()`` methods (the second being an extension to the 
+DBAPI specification).   The former makes use of the native
+parameter binding services of the ODBC driver, while the latter uses string escaping.
+The primary advantage to native parameter binding is that the same statement, when
+executed many times, is only prepared once.   Whereas the primary advantage to the
+latter is that the rules for bind parameter placement are relaxed.   MS-SQL has very 
+strict rules for native binds, including that they cannot be placed within the argument
+lists of function calls, anywhere outside the FROM, or even within subqueries within the
+FROM clause - making the usage of bind parameters within SELECT statements impossible for 
+all but the most simplistic statements.  For this reason, the mxODBC dialect uses the 
+"native" mode by default only for INSERT, UPDATE, and DELETE statements, and uses the
+escaped string mode for all other statements.   This behavior can be controlled completely
+via :meth:`~sqlalchemy.sql.expression.Executable.execution_options`
+using the ``native_odbc_execute`` flag with a value of ``True`` or ``False``, where a value of 
+``True`` will unconditionally use native bind parameters and a value of ``False`` will 
+uncondtionally use string-escaped parameters.
+
 """
 
 import re
diff --git a/lib/sqlalchemy/dialects/mssql/pymssql.py b/lib/sqlalchemy/dialects/mssql/pymssql.py
index 36cb5f370..ca1c4a142 100644
--- a/lib/sqlalchemy/dialects/mssql/pymssql.py
+++ b/lib/sqlalchemy/dialects/mssql/pymssql.py
@@ -7,7 +7,10 @@ pymssql is available at:
 
     http://pymssql.sourceforge.net/
     
-Connect string::
+Connecting
+^^^^^^^^^^
+    
+Sample connect string::
 
     mssql+pymssql://<username>:<password>@<freetds_name>
 
@@ -16,6 +19,9 @@ strings as Python unicode objects.   This can potentially improve
 performance in some scenarios as decoding of strings is 
 handled natively.
 
+Limitations
+^^^^^^^^^^^
+
 pymssql inherits a lot of limitations from FreeTDS, including:
 
 * no support for multibyte schema identifiers
diff --git a/lib/sqlalchemy/dialects/mssql/pyodbc.py b/lib/sqlalchemy/dialects/mssql/pyodbc.py
index eb4bf5cff..c74be0e53 100644
--- a/lib/sqlalchemy/dialects/mssql/pyodbc.py
+++ b/lib/sqlalchemy/dialects/mssql/pyodbc.py
@@ -5,6 +5,9 @@ pyodbc is available at:
 
     http://pypi.python.org/pypi/pyodbc/
 
+Connecting
+^^^^^^^^^^
+
 Examples of pyodbc connection string URLs:
 
 * ``mssql+pyodbc://mydsn`` - connects using the specified DSN named ``mydsn``.
diff --git a/lib/sqlalchemy/dialects/mysql/__init__.py b/lib/sqlalchemy/dialects/mysql/__init__.py
index e4ecccdfc..f37a0c766 100644
--- a/lib/sqlalchemy/dialects/mysql/__init__.py
+++ b/lib/sqlalchemy/dialects/mysql/__init__.py
@@ -6,12 +6,12 @@ base.dialect = mysqldb.dialect
 from sqlalchemy.dialects.mysql.base import \
     BIGINT, BINARY, BIT, BLOB, BOOLEAN, CHAR, DATE, DATETIME, DECIMAL, DOUBLE, ENUM, DECIMAL,\
     FLOAT, INTEGER, INTEGER, LONGBLOB, LONGTEXT, MEDIUMBLOB, MEDIUMINT, MEDIUMTEXT, NCHAR, \
-    NVARCHAR, NUMERIC, SET, SMALLINT, TEXT, TIME, TIMESTAMP, TINYBLOB, TINYINT, TINYTEXT,\
+    NVARCHAR, NUMERIC, SET, SMALLINT, REAL, TEXT, TIME, TIMESTAMP, TINYBLOB, TINYINT, TINYTEXT,\
     VARBINARY, VARCHAR, YEAR, dialect
     
 __all__ = (
 'BIGINT', 'BINARY', 'BIT', 'BLOB', 'BOOLEAN', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'DOUBLE',
 'ENUM', 'DECIMAL', 'FLOAT', 'INTEGER', 'INTEGER', 'LONGBLOB', 'LONGTEXT', 'MEDIUMBLOB', 'MEDIUMINT',
-'MEDIUMTEXT', 'NCHAR', 'NVARCHAR', 'NUMERIC', 'SET', 'SMALLINT', 'TEXT', 'TIME', 'TIMESTAMP',
+'MEDIUMTEXT', 'NCHAR', 'NVARCHAR', 'NUMERIC', 'SET', 'SMALLINT', 'REAL', 'TEXT', 'TIME', 'TIMESTAMP',
 'TINYBLOB', 'TINYINT', 'TINYTEXT', 'VARBINARY', 'VARCHAR', 'YEAR', 'dialect'
 )
diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index 6650b8388..6a0761476 100644
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -1,37 +1,13 @@
 # -*- fill-column: 78 -*-
-# mysql.py
+# mysql/base.py
 # Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Michael Bayer mike_mp@zzzcomputing.com
+# and Jason Kirtland.
 #
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
 """Support for the MySQL database.
 
-Overview
---------
-
-For normal SQLAlchemy usage, importing this module is unnecessary.  It will be
-loaded on-demand when a MySQL connection is needed.  The generic column types
-like :class:`~sqlalchemy.String` and :class:`~sqlalchemy.Integer` will
-automatically be adapted to the optimal matching MySQL column type.
-
-But if you would like to use one of the MySQL-specific or enhanced column
-types when creating tables with your :class:`~sqlalchemy.Table` definitions,
-then you will need to import them from this module::
-
-  from sqlalchemy.dialect.mysql import base as mysql
-
-  Table('mytable', metadata,
-        Column('id', Integer, primary_key=True),
-        Column('ittybittyblob', mysql.TINYBLOB),
-        Column('biggy', mysql.BIGINT(unsigned=True)))
-
-All standard MySQL column types are supported.  The OpenGIS types are
-available for use via table reflection but have no special support or mapping
-to Python classes.  If you're using these types and have opinions about how
-OpenGIS can be smartly integrated into SQLAlchemy please join the mailing
-list!
-
 Supported Versions and Features
 -------------------------------
 
@@ -44,10 +20,7 @@ in the suite 100%.  No heroic measures are taken to work around major missing
 SQL features- if your server version does not support sub-selects, for
 example, they won't work in SQLAlchemy either.
 
-Currently, the only DB-API driver supported is `MySQL-Python` (also referred to
-as `MySQLdb`).  Either 1.2.1 or 1.2.2 are recommended.  The alpha, beta and
-gamma releases of 1.2.1 and 1.2.2 should be avoided.  Support for Jython and
-IronPython is planned.
+Most available DBAPI drivers are supported; see below.
 
 =====================================  ===============
 Feature                                Minimum Version
@@ -64,6 +37,37 @@ Nested Transactions                    5.0.3
 See the official MySQL documentation for detailed information about features
 supported in any given server release.
 
+Connecting
+----------
+
+See the API documentation on individual drivers for details on connecting.
+    
+Data Types
+----------
+
+All of MySQL's standard types are supported.   These can also be specified within 
+table metadata, for the purpose of issuing CREATE TABLE statements
+which include MySQL-specific extensions.   The types are available
+from the module, as in::
+
+    from sqlalchemy.dialects import mysql
+
+    Table('mytable', metadata,
+          Column('id', Integer, primary_key=True),
+          Column('ittybittyblob', mysql.TINYBLOB),
+          Column('biggy', mysql.BIGINT(unsigned=True)))
+
+See the API documentation on specific column types for further details.
+
+Connection Timeouts
+-------------------
+
+MySQL features an automatic connection close behavior, for connections that have
+been idle for eight hours or more.   To circumvent having this issue, use the 
+``pool_recycle`` option which controls the maximum age of any connection::
+
+    engine = create_engine('mysql+mysqldb://...', pool_recycle=3600)
+
 Storage Engines
 ---------------
 
@@ -159,20 +163,13 @@ And of course any valid MySQL statement can be executed as a string as well.
 Some limited direct support for MySQL extensions to SQL is currently
 available.
 
-  * SELECT pragma::
-
-      select(..., prefixes=['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
-
-  * UPDATE with LIMIT::
+* SELECT pragma::
 
-      update(..., mysql_limit=10)
+    select(..., prefixes=['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
 
-Boolean Types
--------------
+* UPDATE with LIMIT::
 
-MySQL's BOOL type is a synonym for SMALLINT, so is actually a numeric value,
-and additionally MySQL doesn't support CHECK constraints. Therefore SQLA's
-Boolean type cannot fully constrain values to just "True" and "False" the way it does for most other backends.
+    update(..., mysql_limit=10)
 
 Troubleshooting
 ---------------
diff --git a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py
index 981e1e204..2da18e50f 100644
--- a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py
+++ b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py
@@ -1,6 +1,15 @@
 """Support for the MySQL database via the MySQL Connector/Python adapter.
 
-# TODO: add docs/notes here regarding MySQL Connector/Python
+MySQL Connector/Python is available at:
+
+    https://launchpad.net/myconnpy
+
+Connecting
+-----------
+
+Connect string format::
+
+    mysql+mysqlconnector://<user>:<password>@<host>[:<port>]/<dbname>
 
 """
 
diff --git a/lib/sqlalchemy/dialects/mysql/mysqldb.py b/lib/sqlalchemy/dialects/mysql/mysqldb.py
index 9d34939a1..6e6bb0ecc 100644
--- a/lib/sqlalchemy/dialects/mysql/mysqldb.py
+++ b/lib/sqlalchemy/dialects/mysql/mysqldb.py
@@ -1,5 +1,18 @@
 """Support for the MySQL database via the MySQL-python adapter.
 
+MySQL-Python is available at:
+
+    http://sourceforge.net/projects/mysql-python
+    
+At least version 1.2.1 or 1.2.2 should be used.
+
+Connecting
+-----------
+
+Connect string format::
+
+    mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>
+    
 Character Sets
 --------------
 
@@ -14,10 +27,21 @@ enabling ``use_unicode`` in the driver by default.  For regular encoded
 strings, also pass ``use_unicode=0`` in the connection arguments::
 
   # set client encoding to utf8; all strings come back as unicode
-  create_engine('mysql:///mydb?charset=utf8')
+  create_engine('mysql+mysqldb:///mydb?charset=utf8')
 
   # set client encoding to utf8; all strings come back as utf8 str
-  create_engine('mysql:///mydb?charset=utf8&use_unicode=0')
+  create_engine('mysql+mysqldb:///mydb?charset=utf8&use_unicode=0')
+
+Known Issues
+-------------
+
+MySQL-python at least as of version 1.2.2 has a serious memory leak related
+to unicode conversion, a feature which is disabled via ``use_unicode=0``.   
+The recommended connection form with SQLAlchemy is::
+
+    engine = create_engine('mysql://scott:tiger@localhost/test?charset=utf8&use_unicode=0', pool_recycle=3600)
+
+
 """
 
 import re
diff --git a/lib/sqlalchemy/dialects/mysql/oursql.py b/lib/sqlalchemy/dialects/mysql/oursql.py
index 9e38993f2..ebc726482 100644
--- a/lib/sqlalchemy/dialects/mysql/oursql.py
+++ b/lib/sqlalchemy/dialects/mysql/oursql.py
@@ -1,5 +1,16 @@
 """Support for the MySQL database via the oursql adapter.
 
+OurSQL is available at:
+
+    http://packages.python.org/oursql/
+    
+Connecting
+-----------
+
+Connect string format::
+
+    mysql+oursql://<user>:<password>@<host>[:<port>]/<dbname>
+
 Character Sets
 --------------
 
diff --git a/lib/sqlalchemy/dialects/mysql/pyodbc.py b/lib/sqlalchemy/dialects/mysql/pyodbc.py
index 5add45b21..1f73c6ef1 100644
--- a/lib/sqlalchemy/dialects/mysql/pyodbc.py
+++ b/lib/sqlalchemy/dialects/mysql/pyodbc.py
@@ -1,5 +1,24 @@
 """Support for the MySQL database via the pyodbc adapter.
 
+pyodbc is available at:
+
+    http://pypi.python.org/pypi/pyodbc/
+
+Connecting
+----------
+
+Connect string::
+
+    mysql+pyodbc://<username>:<password>@<dsnname>
+
+Limitations
+-----------
+
+The mysql-pyodbc dialect is subject to unresolved character encoding issues 
+which exist within the current ODBC drivers available.
+(see http://code.google.com/p/pyodbc/issues/detail?id=25).   Consider usage
+of OurSQL, MySQLdb, or MySQL-connector/Python.
+
 """
 
 from sqlalchemy.dialects.mysql.base import MySQLDialect, MySQLExecutionContext
diff --git a/lib/sqlalchemy/dialects/mysql/zxjdbc.py b/lib/sqlalchemy/dialects/mysql/zxjdbc.py
index f4cf0013c..06d3e6616 100644
--- a/lib/sqlalchemy/dialects/mysql/zxjdbc.py
+++ b/lib/sqlalchemy/dialects/mysql/zxjdbc.py
@@ -6,6 +6,13 @@ JDBC Driver
 The official MySQL JDBC driver is at
 http://dev.mysql.com/downloads/connector/j/.
 
+Connecting
+----------
+
+Connect string format:
+
+    mysql+zxjdbc://<user>:<password>@<hostname>[:<port>]/<database>
+
 Character Sets
 --------------