# SQLAlchemy 0.6.0 Documentation

Search:
Version: 0.6.0 Last Updated: 04/18/2010 19:16:18

# Microsoft SQL Server

Support for the Microsoft SQL Server database.

## Connecting

See the individual driver sections below for details on connecting.

## Auto Increment Behavior

`IDENTITY` columns are supported by using SQLAlchemy `schema.Sequence()` objects. In other words:

    Table('test', mss_engine,
           Column('id', Integer,
                  Sequence('blah',100,10), primary_key=True),
           Column('name', String(20))
         ).create()

would yield:

    CREATE TABLE test (
      id INTEGER NOT NULL IDENTITY(100,10) PRIMARY KEY,
      name VARCHAR(20) NULL,
      )

Note that the `start` and `increment` values for sequences are optional and will default to 1,1.

Implicit `autoincrement` behavior works the same in MSSQL as it does in other dialects and results in an `IDENTITY` column.

- Support for `SET IDENTITY_INSERT ON` mode (automagic on / off for `INSERT` s)
- Support for auto-fetching of `@@IDENTITY/@@SCOPE_IDENTITY()` on `INSERT`

## Collation Support

MSSQL specific string types support a collation parameter that creates a column-level specific collation for the column. The collation parameter accepts a Windows Collation Name or a SQL Collation Name. Supported types are MSChar, MSNChar, MSString, MSNVarchar, MSText, and MSNText. For example:

    Column('login', String(32, collation='Latin1_General_CI_AS'))

will yield:

    login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL

## LIMIT/OFFSET Support

MSSQL has no support for the LIMIT or OFFSET keysowrds. LIMIT is supported directly through the `TOP` Transact SQL keyword:

    select.limit

will yield:

    SELECT TOP n

If using SQL Server 2005 or above, LIMIT with OFFSET support is available through the `ROW_NUMBER OVER` construct. For versions below 2005, LIMIT with OFFSET usage will fail.

## Nullability

MSSQL has support for three levels of column nullability. The default nullability allows nulls and is explicit in the CREATE TABLE construct:

    name VARCHAR(20) NULL

If `nullable=None` is specified then no specification is made. In other words the database’s configured default is used. This will render:

    name VARCHAR(20)

If `nullable` is `True` or `False` then the column will be `NULL` or ``NOT NULL` respectively.

## Date / Time Handling

DATE and TIME are supported. Bind parameters are converted to datetime.datetime() objects as required by most MSSQL drivers, and results are processed from strings if needed. The DATE and TIME types are not available for MSSQL 2005 and previous - if a server version below 2008 is detected, DDL for these types will be issued as DATETIME.

## Compatibility Levels

MSSQL supports the notion of setting compatibility levels at the database level. This allows, for instance, to run a database that is compatibile with SQL2000 while running on a SQL2005 database server. `server_version_info` will always retrun the database server version information (in this case SQL2005) and not the compatibiility level information. Because of this, if running under a backwards compatibility mode SQAlchemy may attempt to use T-SQL statements that are unable to be parsed by the database server.

## Known Issues

- No support for more than one `IDENTITY` column per table

## PyODBC

Support for MS-SQL via pyodbc.

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`. The connection string that is created will appear like:

      dsn=mydsn;Trusted_Connection=Yes

- `mssql+pyodbc://user:pass@mydsn` - connects using the DSN named `mydsn` passing in the `UID` and `PWD` information. The connection string that is created will appear like:

      dsn=mydsn;UID=user;PWD=pass

- `mssql+pyodbc://user:pass@mydsn/?LANGUAGE=us_english` - connects using the DSN named `mydsn` passing in the `UID` and `PWD` information, plus the additional connection configuration option `LANGUAGE`. The connection string that is created will appear like:

      dsn=mydsn;UID=user;PWD=pass;LANGUAGE=us_english

- `mssql+pyodbc://user:pass@host/db` - connects using a connection string dynamically created that would appear like:

      DRIVER={SQL Server};Server=host;Database=db;UID=user;PWD=pass

- `mssql+pyodbc://user:pass@host:123/db` - connects using a connection string that is dynamically created, which also includes the port information using the comma syntax. If your connection string requires the port information to be passed as a `port` keyword see the next example. This will create the following connection string:

      DRIVER={SQL Server};Server=host,123;Database=db;UID=user;PWD=pass

- `mssql+pyodbc://user:pass@host/db?port=123` - connects using a connection string that is dynamically created that includes the port information as a separate `port` keyword. This will create the following connection string:

      DRIVER={SQL Server};Server=host;Database=db;UID=user;PWD=pass;port=123

If you require a connection string that is outside the options presented above, use the `odbc_connect` keyword to pass in a urlencoded connection string. What gets passed in will be urldecoded and passed directly.

For example:

    mssql+pyodbc:///?odbc_connect=dsn%3Dmydsn%3BDatabase%3Ddb

would create the following connection string:

    dsn=mydsn;Database=db

Encoding your connection string can be easily accomplished through the python shell. For example:

    >>> import urllib
    >>> urllib.quote_plus('dsn=mydsn;Database=db')
    'dsn%3Dmydsn%3BDatabase%3Ddb'

## mxODBC

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

## pymssql

Support for the pymssql dialect.

This dialect supports pymssql 1.0 and greater.

pymssql is available at:

> http://pymssql.sourceforge.net/

### Connecting

Sample connect string:

    mssql+pymssql://<username>:<password>@<freetds_name>

Adding “?charset=utf8” or similar will cause pymssql to return 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
- poor support for large decimals
- poor support for binary fields
- poor support for VARCHAR/CHAR fields over 255 characters

Please consult the pymssql documentation for further information.

## zxjdbc Notes

Support for the Microsoft SQL Server database via the zxjdbc JDBC connector.

### JDBC Driver

Requires the jTDS driver, available from: http://jtds.sourceforge.net/

### Connecting

URLs are of the standard form of `mssql+zxjdbc://user:pass@host:port/dbname[?key=value&key=value...]`.

Additional arguments which may be specified either as query string arguments on the URL, or as keyword arguments to `create_engine()` will be passed as Connection properties to the underlying JDBC driver.

## AdoDBAPI

The adodbapi dialect is not implemented for 0.6 at this time.