MSSQL-Django 配置参考

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

最小配置

以下示例展示了最小要求的配置：

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

数据库连接设置

这些设置会配置你的 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
driver String "ODBC Driver 18 for SQL Server" 使用ODBC驱动。 如果没有安装驱动18，会自动退回到驱动17。
isolation_level String None 事务隔离级别：READ UNCOMMITTED、、READ COMMITTEDREPEATABLE READ、SNAPSHOT或SERIALIZABLE。
dsn String None 命名为DSN。 可以用来代替 HOST。
host_is_server 布尔 False 设置为True直接与FreeTDS一起使用PORTHOST/，而不是用freetds.conf数据服务器名称。
unicode_results 布尔 False 启动 pyodbc unicode_results 的功能。
extra_params String None 格式中的 "param=value;param=value" 额外ODBC参数。 用于 Microsoft Entra 认证。
collation String None 用于文本字段查找的校对（例如， "Chinese_PRC_CI_AS"。
connection_timeout Integer 0 连接超时（0 =禁用）。
connection_retries Integer 5 连接重试次数。
connection_retry_backoff_time Integer 5 重投之间要有几秒钟的后退时间。
query_timeout Integer 0 查询超时时间为秒0 （=禁用）。
setencoding / setdecoding 列表 None 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,
        },
    },
}

后端特定设置

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

设置 类型 默认 Description
DATABASE_CONNECTION_POOLING 布尔 True 设置为 False 以禁用 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",
        },
    },
}

# Set this to False to disable pyodbc's connection pooling
DATABASE_CONNECTION_POOLING = False

相关内容

  • Last updated on