本文介绍如何将 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 执行批量操作。 |