mssql-django configuration reference

Эта статья представляет собой полный settings.py справочник по конфигурации для бэкенда базы mssql-django данных Django. Настройте подключение SQL Server, отредактировав DATABASES словарь в файле settings.py вашего проекта Django.

Минимальная конфигурация

Следующий пример показывает минимально требуемую конфигурацию для пути по умолчанию 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; Отмечаются исключения:

Setting	Type	Description
`ENGINE`	String	Этот параметр должен содержать значение `"mssql"`.
`NAME`	String	Имя базы данных. Обязательное.
`HOST`	String	Имя хоста или IP-адрес сервера. Используйте `"server\\instance"` формат для именованных экземпляров.
`PORT`	String	Порт экземпляра сервера. Пустая строка означает порт по умолчанию.
`USER`	String	Имя пользователя базы данных. Если это не указано, используется интегрированная безопасность Windows.
`PASSWORD`	String	Пароль пользователя базы данных.
`AUTOCOMMIT`	Boolean	Настройте на `False` отключение управления транзакциями Django. По умолчанию — `True`.
`Trusted_Connection`	String	Установите на `"yes"` (по умолчанию) для использования интегрированной безопасности Windows, если `USER` она не предоставляется. Когда `USER` обе установлены и `PASSWORD` установлены, эти удостоверения имеют приоритет и `Trusted_Connection` игнорируются. Установите `"no"` на явное отключение проверка подлинности Windows. Это расширение `mssql-django` , а не стандартный сеттинг Django.
`TOKEN`	String	Токен доступа для аутентификации Microsoft Entra (например, через `azure.identity`). Это расширение `mssql-django` , а не стандартный сеттинг Django.

Настройки ТЕСТОВ

Эти настройки управляют базой данных тестов, используемой тестовым раннером Django:

Setting	Type	Description
`NAME`	String	Имя тестовой базы данных. По умолчанию: `"test_" + NAME`.
`COLLATION`	String	Сравнение для тестовой базы данных. По умолчанию: экземпляр по умолчанию.
`DEPENDENCIES`	List	Зависимости порядка создания базы данных.
`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"] словарь:

Опция	Type	По умолчанию	Description
`python_driver`	String	Не установлено	Настроил на `"mssql_python"` подключение этого псевдонима через `mssql-python` драйвер. Не настроен и `"pyodbc"` не сохраняет стандартный `pyodbc` драйвер. См. Выберите драйвер базы данных для mssql-django.
`driver`	String	`"ODBC Driver 18 for SQL Server"`	Драйвер ODBC для использования. Автоматически возвращается к драйверу 17, если 18 не установлен. Игнорируют на `mssql-python` пути.
`isolation_level`	String	`None`	Уровень изоляции транзакций: `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READSNAPSHOT`или `SERIALIZABLE`.
`dsn`	String	`None`	Назван DSN. Может использоваться вместо `HOST`. Игнорируют на `mssql-python` пути.
`host_is_server`	Boolean	`False`	Установлен на `True` использование`HOST`/`PORT`напрямую с FreeTDS вместо `freetds.conf` имени сервера данных. Игнорируют на `mssql-python` пути.
`unicode_results`	Boolean	`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` = отключено). Используйте как минимум 60 для База данных SQL Azure serverless с включенной автопаузой. Автоматически приостановленная база данных возобновляется при первой попытке подключения, и эта попытка может провалиться из-за ошибки 40613, пока база данных возобновляется, поэтому приложение должно попробовать снова. Для получения дополнительной информации смотрите разделы «Автопауза и автовозобновление».
`connection_retries`	Integer	`5`	Количество попыток повторного подключения.
`connection_retry_backoff_time`	Integer	`5`	Время отступления в секунды между повторами.
`query_timeout`	Integer	`0`	Тайм-аут запроса за секунды (`0` = отключено).
`setencoding` / `setdecoding`	List	`None`	Конфигурация кодирования и декодирования передавалась к методам соединения выбранного драйвера. Для каждого `setdecoding` входа нужен `sqltype` ключ на обоих путях, и одна и та же запись работает на обоих драйверах. `mssql-python` принимает `-99` для `SQL_WMETADATA`, но `pyodbc` отвергает. См. ссылку на кодирование и декодирование pyodbc.
`return_rows_bulk_insert`	Boolean	`False`	Разрешите возвращающиеся ряды из оптовой вставки. Должно быть, `False` если в таблицах есть триггеры.
`datefirst`	Integer	`7`	Первый день недели для `SET DATEFIRST`. `7`— воскресенье (по умолчанию SQL Server), `1` — понедельник.
`driver_needs_utf8`	Опция только присутствия	Не установлено	Включите кодирование UTF-8 для драйвера ODBC. Эта опция включается, когда ключ присутствует в `OPTIONS`; само значение игнорируется. Обычно требуется для FreeTDS или более старых конфигураций unixODBC, которые по умолчанию используют Latin-1.
`driver_charset`	String	`None`	Явный набор символов для драйвера ODBC (например, `"UTF-8"`). Используйте с `driver_needs_utf8` моментом, когда драйвер не автоматически определяет кодирование.
`connection_recovery_interval_msec`	Плавать	`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 :

Setting	Type	По умолчанию	Description
`DATABASE_CONNECTION_POOLING`	Boolean	`True`	Настройте на `False` отключение пула соединений на уровне драйвера. Применимо к обоим `pyodbc` и `mssql-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

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-09-29