Settings

DATABASES

Please see the Django documentation on DATABASES settings for a complete list of available settings. Django-mssql builds upon these settings.

This is an example of a typical configuration:

DATABASES = {
    'default': {
        'NAME': 'my_database',
        'ENGINE': 'sqlserver_ado',
        'HOST': 'dbserver\\ss2008',
        'USER': '',
        'PASSWORD': '',
    }
}

ENGINE

This value must be set to sqlserver_ado.

HOST

Default: '127.0.0.1'

This defines the Microsoft SQL Server to establish a connection. This value can be a hostname or IP address.

PORT

Default: '' (Empty string)

This defines the network port to use when connecting to the server. If not defined, the standard Microsoft SQL Server port will be used.

NAME

This is the name of the SQL server database.

USER

Default: '' (Empty string)

This defines the name of the user to use when authenticating to the server. When empty, a trusted connection (SSPI) will be used.

PASSWORD

Default: '' (Empty string)

When a USER is defined, this field should be the plain text password to use when authenticating.

Note

Any user or service that can read the configuration file can will be able to see the plain-text password. Trusted connections are recommended.

TEST_CREATE

Default: True

This setting is specific to the django-mssql backend and controls whether or not the test database will be created and destroyed during the test creation. This is useful when integrating to a legacy database with a complex schema that is created by another application or cannot be easily created by Django’s syncdb.

DATABASES = {
    'default': {
        'NAME': 'test_legacy_database',
        'HOST': r'servername\ss2008',
        'TEST_NAME': 'test_legacy_database',
        'TEST_CREATE': False,
    }
}

Note

This is not intended to allow you to run tests against a QA, staging, or production database.

OPTIONS

Django-mssql provides a few extra OPTIONS that are specific to this backend. Please note that while the main database settings are UPPERCASE keys, the OPTIONS dictionary keys are expected to be lowercase (due to legacy reasons).

use_mars

Default: True

Set to False to disable Multiple Active Recordsets. It is not recommended to disable MARS. Without MARS enabled, you will probably end up seeing the error “Cannot create new connection because in manual or distributed transaction mode”.

Note

This doesn’t really work properly with the “SQLOLEDB” provider.

extra_params

Default: '' (Empty string)

This value will be appended to the generated connection string. Use this to provide any specific connection settings that are not controllable with the other settings.

provider

Default: 'SQLCLI10'

The SQL provider to use when connecting to the database. If this doesn’t work, try ‘SQLCLI11’ or ‘SQLOLEDB’.

Note

use_mars = True doesn’t always work properly with ‘SQLOLEDB’ and can result in the error “Cannot create new connection because in manual or distributed transaction mode.” if you try to filter a queryset with another queryset.

disable_avg_cast

Default: False

This backend will automatically CAST fields used by the AVG function as FLOAT to match the behavior of the core database backends. Set this to True if you need SQL server to retain the datatype of fields used with AVG.

New in version 1.1.

Note

SQL server maintains the datatype of the values used in AVG. The average of an int column will be an int. With this option set to True, AVG([1,2]) == 1, not 1.5.

use_legacy_date_fields

Default: True

This setting alters which data types are used for the DateField, DateTimeField, and TimeField fields. When True, the fields will all use the datetime data type. When False, they will use date, datetime, and time data types.

New in version 1.4.