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:

from sqlalchemy import Table, Integer, Sequence, Column

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

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:

from sqlalchemy.dialects.mssql import VARCHAR
Column('login', VARCHAR(32, collation='Latin1_General_CI_AS'))

When such a column is associated with a Table, the CREATE TABLE statement for this column 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 return 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.

Triggers¶

SQLAlchemy by default uses OUTPUT INSERTED to get at newly generated primary key values via IDENTITY columns or other server side defaults. MS-SQL does not allow the usage of OUTPUT INSERTED on tables that have triggers. To disable the usage of OUTPUT INSERTED on a per-table basis, specify implicit_returning=False for each Table which has triggers:

Table('mytable', metadata, 
    Column('id', Integer, primary_key=True), 
    # ...,
    implicit_returning=False
)

Declarative form:

class MyClass(Base):
    # ...
    __table_args__ = {'implicit_returning':False}

This option can also be specified engine-wide using the implicit_returning=False argument on create_engine().

Enabling Snapshot Isolation¶

Not necessarily specific to SQLAlchemy, SQL Server has a default transaction isolation mode that locks entire tables, and causes even mildly concurrent applications to have long held locks and frequent deadlocks. Enabling snapshot isolation for the database as a whole is recommended for modern levels of concurrency support. This is accomplished via the following ALTER DATABASE commands executed at the SQL prompt:

ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON

ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON

Background on SQL Server snapshot isolation is available at http://msdn.microsoft.com/en-us/library/ms175095.aspx.

Known Issues¶

No support for more than one IDENTITY column per table
reflection of indexes does not work with versions older than SQL Server 2005

SQL Server Data Types¶

As with all SQLAlchemy dialects, all UPPERCASE types that are known to be valid with SQL server are importable from the top level dialect, whether they originate from sqlalchemy.types or from the local dialect:

from sqlalchemy.dialects.mssql import \
    BIGINT, BINARY, BIT, CHAR, DATE, DATETIME, DATETIME2, \
    DATETIMEOFFSET, DECIMAL, FLOAT, IMAGE, INTEGER, MONEY, \
    NCHAR, NTEXT, NUMERIC, NVARCHAR, REAL, SMALLDATETIME, \
    SMALLINT, SMALLMONEY, SQL_VARIANT, TEXT, TIME, \
    TIMESTAMP, TINYINT, UNIQUEIDENTIFIER, VARBINARY, VARCHAR

Types which are specific to SQL Server, or have SQL Server-specific construction arguments, are as follows:

class sqlalchemy.dialects.mssql.BIT(*args, **kwargs)¶: Bases: sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.CHAR(*args, **kw)¶

Bases: sqlalchemy.dialects.mssql.base._StringType, sqlalchemy.types.CHAR

MSSQL CHAR type, for fixed-length non-Unicode data with a maximum of 8,000 characters.

__init__(*args, **kw)¶

Construct a CHAR.

Parameters:

Parameters:	length – Optinal, maximum data length, in characters. convert_unicode – defaults to False. If True, convert `unicode` data sent to the database to a `str` bytestring, and convert bytestrings coming back from the database into `unicode`. Bytestrings are encoded using the dialect’s `encoding`, which defaults to utf-8. If False, may be overridden by `sqlalchemy.engine.base.Dialect.convert_unicode`. collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

length – Optinal, maximum data length, in characters.
convert_unicode –
defaults to False. If True, convert unicode data sent to the database to a str bytestring, and convert bytestrings coming back from the database into unicode.

Bytestrings are encoded using the dialect’s encoding, which defaults to utf-8.

If False, may be overridden by sqlalchemy.engine.base.Dialect.convert_unicode.
collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

class sqlalchemy.dialects.mssql.DATETIME2(precision=None, **kwargs)¶: Bases: sqlalchemy.dialects.mssql.base._DateTimeBase, sqlalchemy.types.DateTime

class sqlalchemy.dialects.mssql.DATETIMEOFFSET(precision=None, **kwargs)¶: Bases: sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.IMAGE(length=None)¶

Bases: sqlalchemy.types.LargeBinary

__init__(length=None)¶

Construct a LargeBinary type.

Parameters: length – optional, a length for the column for use in DDL statements, for those BLOB types that accept a length (i.e. MySQL). It does not produce a small BINARY/VARBINARY type - use the BINARY/VARBINARY types specifically for those. May be safely omitted if no CREATE TABLE will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the CREATE TABLE DDL is issued.

Parameters:	length – optional, a length for the column for use in DDL statements, for those BLOB types that accept a length (i.e. MySQL). It does not produce a small BINARY/VARBINARY type - use the BINARY/VARBINARY types specifically for those. May be safely omitted if no `CREATE TABLE` will be issued. Certain databases may require a length for use in DDL, and will raise an exception when the `CREATE TABLE` DDL is issued.

class sqlalchemy.dialects.mssql.MONEY(*args, **kwargs)¶: Bases: sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.NCHAR(*args, **kw)¶

Bases: sqlalchemy.dialects.mssql.base._StringType, sqlalchemy.types.NCHAR

MSSQL NCHAR type.

For fixed-length unicode character data up to 4,000 characters.

__init__(*args, **kw)¶

Construct an NCHAR.

Parameters:	length – Optional, Maximum data length, in characters. collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

class sqlalchemy.dialects.mssql.NTEXT(*args, **kwargs)¶

Bases: sqlalchemy.dialects.mssql.base._StringType, sqlalchemy.types.UnicodeText

MSSQL NTEXT type, for variable-length unicode text up to 2^30 characters.

__init__(*args, **kwargs)¶

Construct a NTEXT.

Parameters:	collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

class sqlalchemy.dialects.mssql.NVARCHAR(*args, **kw)¶

Bases: sqlalchemy.dialects.mssql.base._StringType, sqlalchemy.types.NVARCHAR

MSSQL NVARCHAR type.

For variable-length unicode character data up to 4,000 characters.

__init__(*args, **kw)¶

Construct a NVARCHAR.

Parameters:	length – Optional, Maximum data length, in characters. collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

class sqlalchemy.dialects.mssql.REAL¶

Bases: sqlalchemy.types.Float

A type for real numbers.

class sqlalchemy.dialects.mssql.SMALLDATETIME(timezone=False)¶: Bases: sqlalchemy.dialects.mssql.base._DateTimeBase, sqlalchemy.types.DateTime

class sqlalchemy.dialects.mssql.SMALLMONEY(*args, **kwargs)¶: Bases: sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.SQL_VARIANT(*args, **kwargs)¶: Bases: sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.TEXT(*args, **kw)¶

Bases: sqlalchemy.dialects.mssql.base._StringType, sqlalchemy.types.TEXT

MSSQL TEXT type, for variable-length text up to 2^31 characters.

__init__(*args, **kw)¶

Construct a TEXT.

Parameters:	collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

class sqlalchemy.dialects.mssql.TIME(precision=None, **kwargs)¶: Bases: sqlalchemy.types.TIME

class sqlalchemy.dialects.mssql.TINYINT(*args, **kwargs)¶: Bases: sqlalchemy.types.Integer

class sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER(*args, **kwargs)¶: Bases: sqlalchemy.types.TypeEngine

class sqlalchemy.dialects.mssql.VARCHAR(*args, **kw)¶

Bases: sqlalchemy.dialects.mssql.base._StringType, sqlalchemy.types.VARCHAR

MSSQL VARCHAR type, for variable-length non-Unicode data with a maximum of 8,000 characters.

__init__(*args, **kw)¶

Construct a VARCHAR.

Parameters:

Parameters:	length – Optinal, maximum data length, in characters. convert_unicode – defaults to False. If True, convert `unicode` data sent to the database to a `str` bytestring, and convert bytestrings coming back from the database into `unicode`. Bytestrings are encoded using the dialect’s `encoding`, which defaults to utf-8. If False, may be overridden by `sqlalchemy.engine.base.Dialect.convert_unicode`. collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

length – Optinal, maximum data length, in characters.
convert_unicode –
defaults to False. If True, convert unicode data sent to the database to a str bytestring, and convert bytestrings coming back from the database into unicode.

Bytestrings are encoded using the dialect’s encoding, which defaults to utf-8.

If False, may be overridden by sqlalchemy.engine.base.Dialect.convert_unicode.
collation – Optional, a column-level collation for this string value. Accepts a Windows Collation Name or a SQL Collation Name.

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 a particular API call specific to the SQL Server Native Client ODBC driver known SQLDescribeParam, while the latter does not.

mxODBC apparently only makes repeated use of a single prepared statement when SQLDescribeParam is used. The advantage to prepared statement reuse is one of performance. The disadvantage is that SQLDescribeParam has a limited set of scenarios in which bind parameters are understood, 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 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.

SQLAlchemy 0.6 Documentation