Commits

Mike Bayer committed 682f9b9

documentation updates

Comments (0)

Files changed (15)

doc/build/reference/dialects/index.rst

     oracle
     postgresql
     sqlite
+    sybase
 
 Unsupported Databases
 ---------------------
     access
     informix
     maxdb
-    sybase
 

doc/build/reference/dialects/mssql.rst

 ------
 .. automodule:: sqlalchemy.dialects.mssql.pyodbc
 
+mxODBC
+------
+.. automodule:: sqlalchemy.dialects.mssql.mxodbc
+
 pymssql
 -------
 .. automodule:: sqlalchemy.dialects.mssql.pymssql

doc/build/reference/dialects/mysql.rst

 MySQL Column Types
 ------------------
 
+.. automodule:: sqlalchemy.dialects.mysql
+    
 .. autoclass:: NUMERIC
    :members: __init__
    :show-inheritance:

doc/build/static/docs.css

 
 body, td {
 	font-family: verdana, sans-serif;
-	font-size:.95em;
+	font-size:.9em;
 }
 
 body {
 	background-color: #FDFBFC;
-	margin:20px 20px 20px 20px;
+	margin:38px;
+	color:#333333;
 }
 
 form {
 }
 
 
-a {font-weight:normal; text-decoration:underline;}
+a {
+        font-weight:normal; 
+        text-decoration:none;
+}
 a:link {color:#0000FF;}
 a:visited {color:#0000FF;}
 a:active {color:#0000FF;}
 
 .topnav .prevnext {
     padding: 5px 0px 0px 0px;
-    font-size: 0.8em
+    /*font-size: 0.8em*/
 }
 
 h1, h2, h3, h4, h5 {

lib/sqlalchemy/connectors/mxodbc.py

 possible for this to be used on other database platforms.
 
 For more info on mxODBC, see http://www.egenix.com/
+
 """
 
 import sys

lib/sqlalchemy/dialects/mssql/mxodbc.py

 """
-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

lib/sqlalchemy/dialects/mssql/pymssql.py

 
     http://pymssql.sourceforge.net/
     
-Connect string::
+Connecting
+^^^^^^^^^^
+    
+Sample connect string::
 
     mssql+pymssql://<username>:<password>@<freetds_name>
 
 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

lib/sqlalchemy/dialects/mssql/pyodbc.py

 
     http://pypi.python.org/pypi/pyodbc/
 
+Connecting
+^^^^^^^^^^
+
 Examples of pyodbc connection string URLs:
 
 * ``mssql+pyodbc://mydsn`` - connects using the specified DSN named ``mydsn``.

lib/sqlalchemy/dialects/mysql/__init__.py

 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'
 )

lib/sqlalchemy/dialects/mysql/base.py

 # -*- 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
 -------------------------------
 
 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
 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
 ---------------
 
 Some limited direct support for MySQL extensions to SQL is currently
 available.
 
-  * SELECT pragma::
-
-      select(..., prefixes=['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
-
-  * UPDATE with LIMIT::
-
-      update(..., mysql_limit=10)
-
-Boolean Types
--------------
-
-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.
+* SELECT pragma::
+
+    select(..., prefixes=['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
+
+* UPDATE with LIMIT::
+
+    update(..., mysql_limit=10)
 
 Troubleshooting
 ---------------

lib/sqlalchemy/dialects/mysql/mysqlconnector.py

 """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>
 
 """
 

lib/sqlalchemy/dialects/mysql/mysqldb.py

 """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
 --------------
 
 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

lib/sqlalchemy/dialects/mysql/oursql.py

 """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
 --------------
 

lib/sqlalchemy/dialects/mysql/pyodbc.py

 """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

lib/sqlalchemy/dialects/mysql/zxjdbc.py

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