Support for the Microsoft SQL Server database.
The following dialect/DBAPI options are available. Please refer to individual DBAPI sections for connect information.
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.
SET IDENTITY_INSERT ON
mode (automagic on / off for
INSERT
s)@@IDENTITY/@@SCOPE_IDENTITY()
on
INSERT
Character collations are supported by the base string types, specified by the string argument “collation”:
from sqlalchemy 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
New in version 0.8: Character collations are now part of the base string types.
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.
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 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.
The MSSQL dialect supports special options for Index
.
The mssql_clustered
option adds the CLUSTERED keyword to the index:
Index("my_index", table.c.x, mssql_clustered=True)
would render the index as CREATE CLUSTERED INDEX my_index ON table (x)
New in version 0.8.
The mssql_include
option renders INCLUDE(colname) for the given string names:
Index("my_index", table.c.x, mssql_include=['y'])
would render the index as CREATE INDEX my_index ON table (x) INCLUDE (y)
New in version 0.8.
Index ordering is available via functional expressions, such as:
Index("my_index", table.c.x.desc())
would render the index as CREATE INDEX my_index ON table (x DESC)
New in version 0.8.
See also
MSSQL supports the notion of setting compatibility levels at the
database level. This allows, for instance, to run a database that
is compatible 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
compatibility 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.
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()
.
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.
IDENTITY
column per tableAs 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:
sqlalchemy.dialects.mssql.
BIT
(*args, **kwargs)¶Bases: sqlalchemy.types.TypeEngine
__init__
(*args, **kwargs)¶Support implementations that were passing arguments
sqlalchemy.dialects.mssql.
CHAR
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)¶Bases: sqlalchemy.types.String
The SQL CHAR type.
__init__
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)¶Create a string-holding type.
Parameters: |
|
---|
sqlalchemy.dialects.mssql.
DATETIME2
(precision=None, **kw)¶Bases: sqlalchemy.dialects.mssql.base._DateTimeBase
, sqlalchemy.types.DateTime
sqlalchemy.dialects.mssql.
DATETIMEOFFSET
(precision=None, **kwargs)¶Bases: sqlalchemy.types.TypeEngine
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. |
---|
sqlalchemy.dialects.mssql.
MONEY
(*args, **kwargs)¶Bases: sqlalchemy.types.TypeEngine
__init__
(*args, **kwargs)¶Support implementations that were passing arguments
sqlalchemy.dialects.mssql.
NCHAR
(length=None, **kwargs)¶Bases: sqlalchemy.types.Unicode
The SQL NCHAR type.
sqlalchemy.dialects.mssql.
NTEXT
(length=None, **kwargs)¶Bases: sqlalchemy.types.UnicodeText
MSSQL NTEXT type, for variable-length unicode text up to 2^30 characters.
sqlalchemy.dialects.mssql.
NVARCHAR
(length=None, **kwargs)¶Bases: sqlalchemy.types.Unicode
The SQL NVARCHAR type.
sqlalchemy.dialects.mssql.
REAL
(**kw)¶Bases: sqlalchemy.types.REAL
sqlalchemy.dialects.mssql.
SMALLDATETIME
(timezone=False)¶Bases: sqlalchemy.dialects.mssql.base._DateTimeBase
, sqlalchemy.types.DateTime
sqlalchemy.dialects.mssql.
SMALLMONEY
(*args, **kwargs)¶Bases: sqlalchemy.types.TypeEngine
__init__
(*args, **kwargs)¶Support implementations that were passing arguments
sqlalchemy.dialects.mssql.
SQL_VARIANT
(*args, **kwargs)¶Bases: sqlalchemy.types.TypeEngine
__init__
(*args, **kwargs)¶Support implementations that were passing arguments
sqlalchemy.dialects.mssql.
TEXT
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)¶Bases: sqlalchemy.types.Text
The SQL TEXT type.
__init__
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)¶Create a string-holding type.
Parameters: |
|
---|
sqlalchemy.dialects.mssql.
TIME
(precision=None, **kwargs)¶Bases: sqlalchemy.types.TIME
sqlalchemy.dialects.mssql.
TINYINT
(*args, **kwargs)¶Bases: sqlalchemy.types.Integer
__init__
(*args, **kwargs)¶Support implementations that were passing arguments
sqlalchemy.dialects.mssql.
UNIQUEIDENTIFIER
(*args, **kwargs)¶Bases: sqlalchemy.types.TypeEngine
__init__
(*args, **kwargs)¶Support implementations that were passing arguments
sqlalchemy.dialects.mssql.
VARCHAR
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)¶Bases: sqlalchemy.types.String
The SQL VARCHAR type.
__init__
(length=None, collation=None, convert_unicode=False, unicode_error=None, _warn_on_bytestring=False)¶Create a string-holding type.
Parameters: |
|
---|
Support for the Microsoft SQL Server database via the PyODBC driver.
Documentation and download information (if applicable) for PyODBC is available at: http://pypi.python.org/pypi/pyodbc/
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
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 which includes the port
information using the comma syntax. 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 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
mssql+pyodbc://user:pass@host/db?driver=MyDriver
- connects using a connection
string that includes a custom
ODBC driver name. This will create the following connection string:
DRIVER={MyDriver};Server=host;Database=db;UID=user;PWD=pass
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'
The current state of PyODBC on a unix backend with FreeTDS and/or EasySoft is poor regarding unicode; different OS platforms and versions of UnixODBC versus IODBC versus FreeTDS/EasySoft versus PyODBC itself dramatically alter how strings are received. The PyODBC dialect attempts to use all the information it knows to determine whether or not a Python unicode literal can be passed directly to the PyODBC driver or not; while SQLAlchemy can encode these to bytestrings first, some users have reported that PyODBC mis-handles bytestrings for certain encodings and requires a Python unicode object, while the author has observed widespread cases where a Python unicode is completely misinterpreted by PyODBC, particularly when dealing with the information schema tables used in table reflection, and the value must first be encoded to a bytestring.
It is for this reason that whether or not unicode literals for bound
parameters be sent to PyODBC can be controlled using the
supports_unicode_binds
parameter to create_engine()
. When
left at its default of None
, the PyODBC dialect will use its
best guess as to whether or not the driver deals with unicode literals
well. When False
, unicode literals will be encoded first, and when
True
unicode literals will be passed straight through. This is an interim
flag that hopefully should not be needed when the unicode situation stabilizes
for unix + PyODBC.
New in version 0.7.7: supports_unicode_binds
parameter to create_engine()
.
Support for the Microsoft SQL Server database via the mxODBC driver.
Documentation and download information (if applicable) for mxODBC is available at: http://www.egenix.com/
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 unconditionally use string-escaped parameters.
Support for the Microsoft SQL Server database via the pymssql driver.
Documentation and download information (if applicable) for pymssql is available at: http://pymssql.sourceforge.net/
pymssql inherits a lot of limitations from FreeTDS, including:
Please consult the pymssql documentation for further information.
Support for the Microsoft SQL Server database via the zxJDBC for Jython driver.
Drivers for this database are available at: http://jtds.sourceforge.net/
Support for the Microsoft SQL Server database via the adodbapi driver.
Documentation and download information (if applicable) for adodbapi is available at: http://adodbapi.sourceforge.net/
Note
The adodbapi dialect is not implemented SQLAlchemy versions 0.6 and above at this time.