Support for the Microsoft SQL Server database.
The MSSQL dialect will work with three different available drivers:
Drivers are loaded in the order listed above based on availability.
If you need to load a specific driver pass module_name when creating the engine:
engine = create_engine('mssql+module_name://dsn')
module_name currently accepts: pyodbc, pymssql, and adodbapi.
Currently the pyodbc driver offers the greatest level of compatibility.
Connecting with create_engine() uses the standard URL approach of mssql://user:pass@host/dbname[?key=value&key=value...].
If the database name is present, the tokens are converted to a connection string with the specified values. If the database is not present, then the host token is taken directly as the DSN name.
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'
Additional arguments which may be specified either as query string arguments on the URL, or as keyword argument to create_engine() are:
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.
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
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.
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.
Support for the Microsoft SQL Server database via the zxjdbc JDBC connector.
Requires the jTDS driver, available from: http://jtds.sourceforge.net/
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.