从 django-mssql-backend 迁移到 mssql-django

本文介绍如何将 Django 项目从 django-mssql-backend 包(使用 sql_server.pyodbc 引擎)迁移到 mssql-django 包。

Overview

包 mssql-django 是后续包 django-mssql-backend。 它为 SQL Server 提供了 Django 数据库后端,包名、引擎标识符更新,并支持较新的 Django 版本。 pyodbc 驱动路径在 2.0 中 mssql-django 仍为默认,每个数据库别名都可以选择加入 mssql-python 驱动。 欲了解更多信息,请参见 为 mssql-django 选择数据库驱动程序。

功能 / 特点 django-mssql-backend mssql-django
包名称 django-mssql-backend mssql-django
发动机 sql_server.pyodbc mssql
Django 支持 2.2, 3.0, 3.1 5.2, 6.0, 6.1
由...维护 Microsoft Microsoft
PyPI pip install django-mssql-backend pip install mssql-django

步骤 1:更新Python包

卸载旧包并安装新包:

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

如果使用 requirements.txt 文件,请替换包引用:

# Before
django-mssql-backend>=2.8.1

# After
mssql-django>=2.0

步骤 2:更新 DATABASE 引擎

在你的 settings.py 中,将 ENGINE 的值从 sql_server.pyodbc 更改为 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

默认的 pyodbc 路径使用 Microsoft ODBC 驱动 18 for SQL Server。 你可以在 pyodbc 路径上通过在 driver 选项中显式指定 Driver 17,继续使用它。 mssql-python路径忽略了这个 driver 选项。

步骤 3:更新INSTALLED_APPS

如果您的INSTALLED_APPS引用了sql_server,请更新:

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

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

步骤 4:验证配置

运行快速验证以确保新后端成功连接:

python manage.py check
python manage.py showmigrations

步骤 5:运行测试套件

运行项目的测试套件,验证所有内容都适用于新后端:

python manage.py test

需要留意的破坏性更改

Area 更改
默认数据库驱动 mssql-django 2.0 版本保留了 pyodbc 作为默认数据库驱动。 要使用 mssql-python 路径,请在别名的 "python_driver": "mssql_python" 字典中设置 OPTIONS。
pyodbc路径上的默认ODBC驱动 pyodbc 路径使用 ODBC Driver 18 for SQL Server,默认会设置 Encrypt=yes。 与使用自签名证书或不受信任证书的服务器的连接将失败,除非将 TrustServerCertificate=yes 添加到 extra_params 中。 或者,在 pyodbc 路径上指定驱动程序 17,或在服务器上安装受信任证书。
return_rows_bulk_insert 默认值为 False. 将其设为 True,以启用在 bulk_create 之后返回 ID。 对于具有触发器的表,必须保持为 False。 请参阅 使用 mssql-django 执行批量操作。