Django MSSQL Documentation

Transcription

1 Django MSSQL Documentation Release dev Django MSSQL authors June 07, 2012

2

3 CONTENTS 1 Welcome to Django-mssql s documentation! Quickstart Settings Management Commands Datatypes Testing Changelog i

4 ii

5 Provides an ADO based Django database backend for Microsoft SQL Server. CONTENTS 1

6 2 CONTENTS

7 CHAPTER ONE WELCOME TO DJANGO-MSSQL S DOCUMENTATION! Contents: 1.1 Quickstart Installation Install django-mssql with 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 Dependencies Django Django 1.2 and newer are supported by the current release. Support for Django 1.1 requires getting code from tag legacy

8 Python This backend requires Python 2.6 or newer. Python 3.x support will be investigated when Django supports it. PyWin32 PyWin32 build 212 or newer is required. 1.2 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 :, OPTIONS : { provider : SQLOLEDB, use_mars : True, }, } } ENGINE This value must be set to sqlserver_ado. HOST Default: 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. 4 Chapter 1. Welcome to Django-mssql s documentation!

9 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 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: False Set to True to enable Multiple Active Recordsets. It is recommended to enable MARS to avoid seeing the Cannot create new connection because in manual or distributed transaction mode error. Note: This will only set the appropriate connection string value for the SQLOLEDB provider. If you are using a different provider, you will need to add the appropriate connection string value to extra_params. 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: SQLOLEDB The SQL provider to use when connecting to the database Settings 5

10 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 Management Commands Adding sql_app to your INSTALLED_APPS adds the following custom management commands 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 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, Django previously only supported dates back to 1900, but recent revisions 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 a datetime2 type, 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. 6 Chapter 1. Welcome to Django-mssql s documentation!

11 1.4.2 bigint Prior to Django 1.3, bigint was not provided. This backend provided model fields to allow using the bigint datatype. class sqlserver_ado.fields.bigautofield This is a django.db.models.autofield for the bigint datatype. class sqlserver_ado.fields.bigintegerfield This was previously an django.db.models.integerfield that specified the bigint datatype. As of Django 1.3, django.db.models.bigintegerfield is provided and should be used instead. class sqlserver_ado.fields.bigforeignkey This is a django.db.models.foreignkey that should be used to reference either a BigAutoField or a BigIntegerField 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 the tests folder DB-API The folder tests/api/ contains a test suite for checking DB-API 2 conformance Django Support Database Introspection Located in folder tests/test_inspectdb. These tests verify the database introspection. To run: set up the SQLINSTANCE python manage.py inspectdb 1.5. Testing 7

12 Main Tests The tests for basic functionality and regressions are located in the tests/test_main/ folder. To run: set up the SQLINSTANCE python manage.py test 1.6 Changelog v1.1 (in development) Updated SQLInsertCompiler to work with Django 1.4 Added support for disable_constraint_checking, which is required for loaddata to work properly. Implemented DatabaseOperations.date_interval_sql to allow using expressions like end lte=f( start )+delta. Fixed date part extraction for week_day. DatabaseWrapper reports vendor as microsoft. AVG function now matches core backend behaviors and will auto-cast to float, instead of maintaining datatype. Set database OPTIONS setting disable_avg_cast to turn off the auto-cast behavior. StdDev and Variance aggregate functions are now supported and will map to the proper MSSQL named functions. Includes work around for Django ticket # Monkey patched django.db.backends.util.cursorwrapper to allow using cursors as ContextManagers in Python 2.7. Django Ticket # Chapter 1. Welcome to Django-mssql s documentation!