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

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

Выбор драйверов базы данных Python

mssql-djangoВерсии 2.0 и более поздние подключаются либо через pyodbc, по умолчанию, либо через драйвер Microsoftmssql-python. Выберите mssql-python для псевдонима базы данных с параметром python_driver:

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

Не устанавливайте driver на этом пути. Путь driver игнорирует параметры dsn, host_is_server, unicode_results и extra_params, проверяет mssql-python по списку разрешённых значений и не включает MARS. Полный список различий в поведении см. Выберите драйвер базы данных для mssql-django. Остальная часть этой статьи описывает путь по умолчанию pyodbc , если это не указано.

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

В пути pyodbc серверная часть по умолчанию использует драйвер 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.

При подключении к База данных SQL Azure, Управляемый экземпляр SQL Azure, базе данных SQL в Microsoft Fabric, прослушивателю группы доступности или экземпляру отказоустойчивого кластера добавьте MultiSubnetFailover=Yes в extra_params. Когда имя сервера разрешается на более чем один IP-адрес, драйвер подключается ко всем этим адресам одновременно и использует первый, который отвечает. Без него драйвер перебирает адреса по одному, и адрес, который не отвечает, расходует всё оставшееся время ожидания аутентификации, прежде чем драйвер перейдёт к следующему. Когда DNS разрешается по одному адресу, драйвер делает одну попытку подключения, поэтому параметр можно оставить включённым.

MultiSubnetFailover=Yes имеет следующие ограничения:

  • Вы не можете использовать его поверх протокола, кроме TCP.

  • Подключение к экземпляру SQL Server, настроенному с более чем 64 IP-адресами, завершается сбоем.

  • Вы не можете использовать его с зеркалированием базы данных. Драйвер возвращает ошибку, когда в строке подключения указано Failover_Partner, а также когда сервер сообщает, что база данных является зеркальной. Зеркалирование базы данных устарело во всех поддерживаемых версиях SQL Server. Вместо этого используйте группы доступности AlwaysOn.

Caution

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

Отключить MARS

На пути pyodbc бэкенд по умолчанию включает Multiple Active Result Sets (MARS) при использовании в Windows драйвера ODBC от Microsoft. Некоторые конечные точки отклоняют ключевое слово MARS_Connection, в том числе Microsoft Fabric Warehouse. Чтобы подключиться к одной из этих точек подключения, задайте MARS_Connection=no в extra_params этого псевдонима:

DATABASES = {
    "warehouse": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.datawarehouse.fabric.microsoft.com",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "extra_params": "Authentication=ActiveDirectoryServicePrincipal;MARS_Connection=no",
        },
    },
}

Начиная с версии mssql-django 2.0, явное значение MARS_Connection учитывается, а сопоставление не учитывает регистр, поэтому бэкенд не добавляет конфликтующее значение по умолчанию. В версии 1.8.0 и более ранних версиях значение по умолчанию в Windows перезаписывало явно заданное значение, и подключение завершалось с ошибкой.

При отключённом MARS QuerySet.iterator() считывает весь результат в память, прежде чем возвращать строки, чтобы вложенный запрос мог повторно использовать соединение. Учитывайте затраты памяти для больших наборов результатов запросов.

Для других методов аутентификации сохраняйте соответствующие настройки аутентификации и добавляйте MARS_Connection=no к extra_params. Эта настройка соединения не подразумевает полную поддержку Microsoft Fabric Warehouse для миграций Django или других функций SQL Server.

Путь mssql-python не включает MARS и отклоняет ключевое MARS_Connection слово, поэтому эта настройка применяется только к pyodbc.

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

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

Опция По умолчанию 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,
        },
    },
}

connection_timeout=0 — MSSQL-Django по умолчанию. Поскольку pyodbc вызывает SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, ...) только при указании положительного значения, по умолчанию действует драйвер-зависимый режим (15 секунд для Microsoft ODBC Driver for SQL Server). Установите явное значение, чтобы попытки подключения без ответа предсказуемо завершались неудачей.

Если в качестве целевого ресурса используется бессерверная База данных SQL Azure с включенной автопаузой, используйте как минимум 60. Автоматически приостановленная база данных возобновляется при первой попытке подключения, и эта попытка может провалиться из-за ошибки 40613, пока база данных возобновляется. При более коротком тайм-ауте первая попытка соединения заканчивается до завершения резюме. connection_retries в конечном итоге выполняется успешно, но первый запрос пережидает несколько тайм-аутов, прежде чем соединение будет установлено. Для получения дополнительной информации смотрите разделы «Автопауза и автовозобновление».

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)

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

Связанный контент

  • Последнее обновление: