Django MSSQL Documentation

(1)

Django MSSQL Documentation

Release dev

Django MSSQL authors

(2)

(3)

WELCOME TO DJANGO-MSSQL’S

DOCUMENTATION!

Contents:

1.1 Quickstart

1.1.1 Installation

• Installdjango-mssqlwith your favorite Python package manager: pip install django-mssql

• Add the DATABASES configuration. DATABASES = { ’default’: { ’NAME’: ’my_database’, ’ENGINE’: ’sqlserver_ado’, ’HOST’: ’dbserver\\ss2008’, ’USER’: ’’, ’PASSWORD’: ’’, ’OPTIONS’ : { ’provider’: ’SQLOLEDB’, ’use_mars’: True, }, } }

Note: Although the project is named django-mssql the python module is named

sqlserver_ado.

1.1.2 Dependencies

Django

Django1.2 and newer are supported by the current release. Support for Django 1.1 requires getting code from tag

legacy-1.1.

(8)

Python

This backend requires Python 2.6 or newer. Python 3.x support will be investigated when Django supports it.

PyWin32

PyWin32build 212 or newer is required.

1.2 Settings

1.2.1 DATABASES

Please see theDjango documentation on DATABASES settingsfor 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’: ’’, ’OPTIONS’ : { ’provider’: ’SQLOLEDB’, ’use_mars’: True, }, } } ENGINE

This value must be set tosqlserver_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.

(9)

NAME

This is the name of the SQL server database.

USER

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

PASSWORD

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

1.2.2 OPTIONS

Django-mssqlprovides a few extraOPTIONSthat are specific to this backend.

use_mars Default:False

Set toTrueto enableMultiple Active Recordsets. It is recommended to enable MARS to avoid seeing the “Cannot create new connection because in manual or distributed transaction mode” error.

extra_params

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:’SQLOLEDB’

The SQL provider to use when connecting to the database.

1.3 Management Commands

Addingsql_appto yourINSTALLED_APPSadds the following custom management commands.

(10)

1.3.1 dbgui

This will launch SQL Management Studio, connected to your project’s default database. python manage.py dbgui

1.4 Datatypes

There are known issues related to Python/DB data types.

1.4.1 Dates and Times

Earliest Year

SQL Server provides two datetime types:datetime and smalldatetime.

This backend always uses datetime, which supports dates back to January 1, 1753.

Django previously only supported dates back to 1900, but recent revisions 7946 + 7950 changed this behavior. If you need to store historical data in datetime fields, then SQL Server 2005 will have a problem. (I’d welcome bugs/repro cases/patches on this issue.)

SQL Server 2008 introduces adatetime2type, with support for fractional seconds and the full range of Python datetime dates. To use this time, edit your local creation.py/introspection.py files to use this datatype instead.

Bare Times

SQL Server 2005 doesn’t have a bare “time” datatype, only a datetime. SQL Server 2008 introduces a time type, but this isn’t used by this backend.

1.4.2 bigint

Prior to Django 1.3,bigintwas not provided. This backend provided model fields to allow using thebigint

datatype.

classsqlserver_ado.fields.BigAutoField

This is adjango.db.models.AutoFieldfor thebigintdatatype. classsqlserver_ado.fields.BigIntegerField

This was previously andjango.db.models.IntegerFieldthat specified thebigintdatatype. As of Django 1.3,django.db.models.BigIntegerFieldis provided and should be used instead.

classsqlserver_ado.fields.BigForeignKey

This is a django.db.models.ForeignKey that should be used to reference either aBigAutoFieldor a

BigIntegerField.

(11)

1.4.3 Unsupported Types

These types may behave oddly in a Django application, as they have limits smaller than what Django expects from similar types: • smalldatetime • smallmoney • tinyint • real

1.5 Testing

All tests are contained in thetestsfolder.

1.5.1 DB-API

The foldertests/api/contains a test suite for checking DB-API 2 conformance.

1.5.2 Django Support

Database Introspection

Located in foldertests/test_inspectdb. These tests verify the database introspection. To run:

• set up the SQLINSTANCE

• python manage.py inspectdb

Main Tests

The tests for basic functionality and regressions are located in thetests/test_main/folder. To run:

• set up the SQLINSTANCE • python manage.py test

Django MSSQL Documentation