1 files changed, 34 insertions, 2 deletions
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