Επεξεργασία

Migrate from django-mssql-backend to mssql-django

This article explains how to migrate a Django project from the django-mssql-backend package (which used the sql_server.pyodbc engine) to the mssql-django package.

Overview

The mssql-django package is the successor to django-mssql-backend. It provides a Django database backend for SQL Server with an updated package name, engine identifier, and support for newer Django versions. The pyodbc driver path remains the default in mssql-django 2.0, and each database alias can opt in to the mssql-python driver. For more information, see Select the database driver for mssql-django.

Feature django-mssql-backend mssql-django
Package name django-mssql-backend mssql-django
ENGINE sql_server.pyodbc mssql
Django support 2.2, 3.0, 3.1 5.2, 6.0, 6.1
Maintained by Microsoft Microsoft
PyPI pip install django-mssql-backend pip install mssql-django

Step 1: Update the Python package

Uninstall the old package and install the new one:

pip uninstall django-mssql-backend
pip install mssql-django

If you use a requirements.txt file, replace the package reference:

# Before
django-mssql-backend>=2.8.1

# After
mssql-django>=2.0

Step 2: Update the DATABASE ENGINE

In your settings.py, change the ENGINE value from sql_server.pyodbc to mssql:

# Before
DATABASES = {
    "default": {
        "ENGINE": "sql_server.pyodbc",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

# After
DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Note

The default pyodbc path uses Microsoft ODBC Driver 18 for SQL Server. You can continue to use Driver 17 on the pyodbc path by specifying it explicitly in the driver option. The mssql-python path ignores the driver option.

Step 3: Update INSTALLED_APPS

If your INSTALLED_APPS references sql_server, update it:

# Before
INSTALLED_APPS = [
    "sql_server",
    # ...
]

# After - only needed if using inspectdb
INSTALLED_APPS = [
    "mssql",
    # ...
]

Step 4: Verify configuration

Run a quick verification to ensure the new backend connects successfully:

python manage.py check
python manage.py showmigrations

Step 5: Run your test suite

Run your project's test suite to verify everything works with the new backend:

python manage.py test

Breaking changes to watch for

Area Change
Default database driver mssql-django 2.0 keeps pyodbc as the default database driver. To use the mssql-python path, set "python_driver": "mssql_python" in the alias's OPTIONS dictionary.
Default ODBC driver on the pyodbc path The pyodbc path uses ODBC Driver 18 for SQL Server, which sets Encrypt=yes by default. Connections to servers with self-signed or untrusted certificates fail unless you add TrustServerCertificate=yes to extra_params. Alternatively, specify Driver 17 on the pyodbc path or install a trusted certificate on the server.
return_rows_bulk_insert Defaults to False. Set to True to enable returning IDs after bulk_create. Must remain False for tables with triggers. See Bulk operations with mssql-django.

Related content

  • Last updated on