=============
django-pyodbc
=============
A Django_ MS SQL Server external DB backend that uses ODBC by employing
the pyodbc_ library. It supports SQL Server 2000 and 2005.
.. _Django: http://djangoproject.com/
.. _pyodbc: http://pyodbc.sourceforge.net
Features
========
* Supports LIMIT+OFFSET and offset w/o LIMIT emulation under SS2005.
* Supports LIMIT+OFFSET under SS2000.
* Transparently supports Django's TextField both under SS2000 and SS2005.
* Passes most of the tests of the Django test suite.
* Compatible with SQL Server and SQL Server Native Client from Microsoft
(Windows) and FreeTDS ODBC drivers (Linux).
Dependencies
============
* Django from SVN, revision 8328 or newer (1.0 is r8961.)
* pyodbc 2.0.58 or newer
Installation
============
1. Install pyodbc.
2. Add the directory where you have copied the project files to your Python
path. So, for example, if you have the following directory structure::
/home/user/src/django-pyodbc
|
+- sql_server
|
+- pyodbc
you should add ``/home/user/src/django-pyodbc`` to you Python module search
path. One way to do this is setting the ``PYTHONPATH`` environment
variable::
$ export PYTHONPATH=/home/user/src/django-pyodbc
3. Now you can point the ``DATABASE_ENGINE`` setting in the settings file used
by your Django application or project to the ``'sql_server.pyodbc'``
module path::
DATABASE_ENGINE='sql_server.pyodbc'
Configuration
=============
The following settings control the behavior of the backend:
Standard Django settings
------------------------
``DATABASE_NAME``
String. Database name. Required.
``DATABASE_HOST``
String. SQL Server instance in ``"server\instance"`` format.
``DATABASE_PORT``
String. Server instance port.
``DATABASE_USER``
String. Database user name. If not given then MS Integrated Security will
be used.
``DATABASE_PASSWORD``
String. Database user password.
``DATABASE_OPTIONS``
Dictionary. Current available keys are:
``autocommit``
Boolean. Indicates if pyodbc should direct the the ODBC driver to
activate the autocommit feature. Default value is ``False``.
``MARS_Connection``
Boolean. Only relevant when running on Windows and with SQL Server 2005
or later through MS *SQL Server Native client* driver (i.e. setting
``DATABASE_ODBC_DRIVER`` to ``"SQL Native Client"``). See
http://msdn.microsoft.com/en-us/library/ms131686.aspx.
Default value is ``False``.
``host_is_server``
Boolean. Only relevant if using the FreeTDS ODBC driver under
Unix/Linux.
By default, when using the FreeTDS ODBC driver the value specified in
the ``DATABASE_HOST`` setting is used in a ``SERVERNAME`` ODBC
connection string component instead of being used in a ``SERVER``
component; this means that this value should be the name of a
*dataserver* definition present in the ``freetds.conf`` FreeTDS
configuration file instead of a hostname or an IP address.
But if this option is present and it's value is True, this special
behavior is turned off.
See http://freetds.org/userguide/dsnless.htm for more information.
``django-pyodbc``-specific settings
-----------------------------------
``DATABASE_ODBC_DSN``
String. A named DSN can be used instead of ``DATABASE_HOST``.
``DATABASE_ODBC_DRIVER``
String. ODBC Driver to use. Default is ``"SQL Server"`` on Windows and
``"FreeTDS"`` on other platforms.
``DATABASE_EXTRA_PARAMS``
String. Additional parameters for the ODBC connection. The format is
``"param=value;param=value"``.
``DATABASE_COLLATION``
String. Name of the collation to use when performing text field lookups
against the database. Default value is ``"Latin1_General_CI_AS"``.
For Chinese language you can set it to ``"Chinese_PRC_CI_AS"``.
License
=======
New BSD LICENSE
Credits
=======
* Ramiro Morales `<http://djangopeople.net/ramiro/>`_
* Filip Wasilewski (http://code.djangoproject.com/ticket/5246)
* Wei guangjing `<http://djangopeople.net/vcc/>`_
* mamcx (http://code.djangoproject.com/ticket/5062)
* Alex Vidal `<http://github.com/avidal/>`_