MSSQL-Django 配置参考

本文是Djangosettings.py数据库后端的完整mssql-django配置参考。 通过编辑DATABASES你 Django 项目settings.py文件中的字典来配置 SQL Server 连接。

最小配置

以下示例展示了默认 pyodbc 路径的最低要求配置：

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",
        },
    },
}

要运行别名 mssql-python ，可以设置 python_driver 并省略 driver。 路径 mssql-python 忽略 driver：

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>",
        "PORT": "1433",
        "OPTIONS": {
            "python_driver": "mssql_python",
        },
    },
}

ENGINE 两条路都保持 "mssql" 。 同一项目中的别名可以使用不同的驱动程序。 有关行为差异的完整列表，请参见 MSSQL-django 的“选择数据库驱动程序”。

除非特别说明，本文其他示例展示了默认 pyodbc 路径。

数据库连接设置

这些设置会配置你的 DATABASES 连接。 大多数是标准的Django设置;例外情况如下：

设置	类型	Description
ENGINE	String	必须是 "mssql"。
NAME	String	数据库名称。 必填。
HOST	String	服务器主机名或IP地址。 命名实例使用 "server\\instance" 格式。
PORT	String	服务器实例端口。 空字符串表示默认端口。
USER	String	数据库用户名。 如果没有提供，则使用 Windows 集成安全。
PASSWORD	String	数据库用户密码。
AUTOCOMMIT	布尔	设置为 False 禁用Django的交易管理。 默认值为 True。
Trusted_Connection	String	设置为"yes"（默认）使用未提供Windows集成安全USER。 当 USER 和 PASSWORD 都设置好时，这些凭证优先，会 Trusted_Connection 被忽略。 设置为 以"no"明确禁用 Windows Authentication。 这是一个 mssql-django 扩展，不是标准的Django设置。
TOKEN	String	Microsoft Entra 认证的访问令牌（例如通过 azure.identity）。 这是一个 mssql-django 扩展，不是标准的Django设置。

测试设置

这些设置控制 Django 测试运行工具所使用的测试数据库：

设置	类型	Description
NAME	String	测试数据库名称。 默认值："test_" + NAME。
COLLATION	String	测试数据库的整合。 默认：实例默认。
DEPENDENCIES	列表	数据库的创建顺序依赖关系。
MIRROR	String	测试时用数据库的别名镜像。

示例：

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",
        },
        "TEST": {
            "NAME": "test_mydb",
            "COLLATION": "SQL_Latin1_General_CP1_CI_AS",
        },
    },
}

选项

该 OPTIONS 词典提供后端特定的配置。 将以下设置放入字典中 DATABASES["default"]["OPTIONS"] ：

选项	类型	默认	Description
python_driver	String	未设置	设置为 "mssql_python" 通过驱动连接这个别名 mssql-python 。 没有设置或 "pyodbc" 保留默认 pyodbc 驱动。 参见 MSSQL-django 的选择数据库驱动程序。
driver	String	"ODBC Driver 18 for SQL Server"	使用ODBC驱动。 如果没有安装驱动18，会自动退回到驱动17。 在路上被 mssql-python 忽视。
isolation_level	String	None	事务隔离级别：READ UNCOMMITTED、、READ COMMITTEDREPEATABLE READ、SNAPSHOT或SERIALIZABLE。
dsn	String	None	命名为DSN。 可以用来代替 HOST。 在路上被 mssql-python 忽视。
host_is_server	布尔	False	设置为True直接与FreeTDS一起使用HOST/PORT，而不是用freetds.conf数据服务器名称。 在路上被 mssql-python 忽视。
unicode_results	布尔	False	启动 pyodbc unicode_results 的功能。 在路上被 mssql-python 忽视。
extra_params	String	None	格式中的"param=value;param=value"额外连接字符串参数。 用于 Microsoft Entra 认证。 路径会 mssql-python 根据允许列表验证这些内容。
collation	String	None	用于文本字段查找的校对（例如， "Chinese_PRC_CI_AS"。
connection_timeout	Integer	0	连接超时（0 =禁用）。 启用自动暂停的Azure SQL 数据库无服务器至少使用60。 自动暂停的数据库在首次连接尝试时恢复，而该尝试可能在数据库恢复时出现错误40613而失败，因此应用程序必须重试。 更多信息请参见 自动暂停和自动恢复。
connection_retries	Integer	5	连接重试次数。
connection_retry_backoff_time	Integer	5	重投之间要有几秒钟的后退时间。
query_timeout	Integer	0	查询超时时间为秒0 （=禁用）。
setencoding / setdecoding	列表	None	编码和解码配置传递给所选驱动的连接方法。 每个 setdecoding 条目都需要在两条路径上都有 sqltype 密钥，同一条条目在任一驱动上都能使用。 mssql-python 接受 -99 ， SQL_WMETADATA拒绝 pyodbc 。 参见 pyodbc 编码 和 解码 参考资料。
return_rows_bulk_insert	布尔	False	允许从散装插入物中返回行。 一定是 False 表格有触发器。
datefirst	Integer	7	每周的第一天。SET DATEFIRST 7是周日（SQL Server默认1），是周一。
driver_needs_utf8	仅在场选项	未设置	为ODBC驱动启用UTF-8编码。 当密钥存在于 OPTIONS;时该选项被忽略。 通常在FreeTDS或默认为Latin-1的老版UnixODBC配置中需要。
driver_charset	String	None	ODBC驱动的显式字符集（例如， "UTF-8"）。 当驱动程序不自动检测编码时使用 driver_needs_utf8 。
connection_recovery_interval_msec	Float	0.0	在后端连接恢复环路中，网络错误后，重试尝试之间等待几毫秒。 对于不稳定的网络链路，提高这个值。

常见选项示例：

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes",
            "isolation_level": "READ COMMITTED",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 5,
            "query_timeout": 60,
        },
    },
}

后端特定设置

该设置位于词典之外settings.py的模块层DATABASES面：

设置	类型	默认	Description
DATABASE_CONNECTION_POOLING	布尔	True	设置为 False 禁用驱动级连接池。 适用于和pyodbcmssql-python。

示例：

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",
        },
    },
}

# Set this to False to disable driver-level connection pooling
DATABASE_CONNECTION_POOLING = False

相关内容

• mssql-django 的连接选项
• 选择 mssql-django 的数据库驱动程序
• mssql-django 中的 Microsoft Entra 身份验证
• mssql-django 中的连接池
• Django 数据库设置