Параметры подключения для mssql-django

В этой статье описываются OPTIONS параметры словаря в конфигурации Django DATABASES . Эти параметры управляют mssql-django подключением к SQL Server через драйвер ODBC.

Выбор драйвера ODBC

mssql-django По состоянию на 1.7 серверная часть по умолчанию использует драйвер ODBC 18 для SQL Server. Если драйвер ODBC 18 не установлен, серверная часть автоматически возвращается к ODBC Driver 17.

Note

Драйвер ODBC 18 включает Encrypt=yes по умолчанию и проверяет сертификат сервера. Подключения, которые работали с драйвером 17, могут завершиться ошибкой доверия SSL/TLS. Чтобы устранить сбой, выполните следующие действия.

Для локального SQL Server установите сертификат сервера из центра сертификации, которому клиенты уже доверяют, или импортируйте существующий сертификат сервера в каждое хранилище доверия клиента. Инструкции см. в разделе "Настройка SQL Server Database Engine для шифрования подключений".
Если вы подключаетесь по IP-адресу или по псевдониму, который не соответствует полю Subject сертификата или полю Subject Alternative Name (SAN), добавьте HostNameInCertificate=<name-from-certificate> к extra_params.

Сведения о локальной разработке для самозаверяющего сертификата см. в разделе TrustServerCertificate"Дополнительные параметры ODBC".

Драйвер можно указать явным образом:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 17 for SQL Server",
        },
    },
}

В Linux можно также указать полный путь к библиотеке драйверов:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.0.so.1.1",
        },
    },
}

DSN и HOST

Можно подключиться с помощью HOST имени или именованного имени DSN (имя источника данных).

Подключиться к HOST

Большинство конфигураций используют параметр HOST напрямую:

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

Подключение с помощью DSN

Используйте именованный DSN, настроенный в источниках данных ODBC:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "OPTIONS": {
            "dsn": "MyDataSourceName",
        },
    },
}

Поддержка FreeTDS

Чтобы использовать FreeTDS в качестве драйвера ODBC, установите значение host_is_serverTrue. Это указывает серверной части использовать HOST и PORT напрямую вместо поиска имени сервера данных в freetds.conf:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "FreeTDS",
            "host_is_server": True,
        },
    },
}

Дополнительные сведения о подключениях без dsN с помощью FreeTDS см. в руководстве пользователя FreeTDS.

Дополнительные параметры ODBC

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

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": "TrustServerCertificate=yes;ApplicationIntent=ReadOnly",
        },
    },
}

Этот параметр также используется для ключевых слов проверки подлинности Microsoft Entra.

Caution

Используйте TrustServerCertificate=yes только для локальной разработки с самоподписанными сертификатами. Не используйте его в рабочей среде. Это отключает проверку цепочки сертификатов и повышает риск атаки «злоумышленник посередине». Установите доверенный сертификат на сервер и подключитесь с помощью TrustServerCertificate=no.

Время ожидания подключения и повторные попытки

Настройте устойчивость подключения с параметрами времени ожидания и повторных попыток:

Опция	По умолчанию	Description
`connection_timeout`	`0` (отключено)	Максимальное количество секунд для ожидания подключения.
`connection_retries`	`5`	Количество повторных попыток при сбое подключения.
`connection_retry_backoff_time`	`5`	Секунды ожидания между повторными попытками.
`query_timeout`	`0` (отключено)	Максимальное количество секунд ожидания завершения запроса.

Пример:

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",
            "connection_timeout": 30,
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "query_timeout": 120,
        },
    },
}

Collation

Настройте пользовательские правила сортировки для поиска в текстовом поле:

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",
            "collation": "Chinese_PRC_CI_AS",
        },
    },
}

Несколько подключений к базе данных

Django поддерживает подключение к нескольким базам данных одновременно. Это полезно для реплик чтения, запросов между базами данных или разделения рабочих нагрузок по уровню изоляции.

Настройка нескольких баз данных

Определите каждое соединение в параметре DATABASES :

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-primary-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
    "readonly": {
        "ENGINE": "mssql",
        "NAME": "app_db",
        "HOST": "<your-readonly-replica>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Encrypt=yes;ApplicationIntent=ReadOnly",
        },
    },
    "analytics": {
        "ENGINE": "mssql",
        "NAME": "analytics_db",
        "HOST": "<your-analytics-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "isolation_level": "READ UNCOMMITTED",
        },
    },
}

Caution

READ UNCOMMITTED допускает грязное чтение. Используйте этот уровень изоляции только для запросов отчетов или аналитики, где абсолютная точность не требуется. Дополнительные сведения см. в разделе "Управление транзакциями".

Маршрутизация запросов с помощью маршрутизатора базы данных

Создайте маршрутизатор базы данных для направления операций чтения и записи к соответствующему подключению:

class ReadReplicaRouter:
    """Route read queries to the readonly replica, writes to the primary."""

    def db_for_read(self, model, **hints):
        return "readonly"

    def db_for_write(self, model, **hints):
        return "default"

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == "default"

Регистрация маршрутизатора в settings.py:

DATABASE_ROUTERS = ["myproject.routers.ReadReplicaRouter"]

Сохраните класс маршрутизатора в файле, myproject/routers.pyнапример.

Запрос конкретной базы данных напрямую

using() Используйте метод для запроса определенного псевдонима базы данных:

# Explicit read from analytics database
reports = AnalyticsReport.objects.using("analytics").filter(date__gte="2025-01-01")

# Write to default
Product.objects.create(name="Widget", price=9.99)

Дополнительные сведения об уровнях изоляции для баз данных для каждого подключения см. в разделе "Чтение данных без блокировки".

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

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

Last updated on 2026-07-21