Часто задаваемые вопросы о mssql-django

В этой статье приведены ответы на часто задаваемые вопросы о mssql-django бэкенде Django для SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure и базы данных SQL в Microsoft Fabric.

General

Что такое mssql-django?

Пакет mssql-django — это серверная часть базы данных Django, поддерживаемая Microsoft для SQL Server. Он позволяет приложениям Django подключаться к SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure и SQL Database в Microsoft Fabric. Версии 2.0 и более поздние версии подключаются либо через драйвер pyodbc, который используется по умолчанию, либо через драйвер Microsoft mssql-python.

Установите его с помощью pip:

pip install mssql-django

Какие версии Django поддерживают mssql-django?

mssql-django Версия пакета 2.0 поддерживает Django 5.2, 6.0 и 6.1. Проекты на Django 3.2–5.1 остаются на версии 1.8.0. Проверьте жизненный цикл поддержки для полной матрицы совместимости.

Какие версии Python поддерживаются?

mssql-django Версия пакета 2.0 поддерживает Python 3.10–3.14. Конкретная версия Python также должна быть совместима с вашей версией для Django: Django 5.2 тестируется с Python 3.10–3.13, а Django 6.0 и 6.1 тестируются с Python 3.12–3.14. См. раздел "Жизненный цикл поддержки " для полной матрицы совместимости.

Какой драйвер базы данных на Python использует mssql-django?

Версии 2.0 и более поздние поддерживают два драйвера, выбранных для каждого псевдонима базы данных. pyodbcявляется по умолчанию и требует установленного внешнего драйвера Microsoft ODBC для SQL Server. Чтобы использовать драйвер Microsoftmssql-python, который не требует отдельной установки драйвера ODBC, добавьте python_driver в словарь этого псевдонимаOPTIONS:

"OPTIONS": {
    "python_driver": "mssql_python",
},

Псевдонимы, в которых этот параметр не указан, продолжают использовать pyodbc. Для различий в поведении между двумя путями см. Выберите драйвер базы данных для mssql-django.

Поддерживается ли mssql-django Microsoft?

Yes. Пакет mssql-django поддерживается Microsoft и доступен в PyPI и GitHub.

Конфигурация

Какое значение ENGINE следует использовать в settings.py?

Установите значение ENGINE"mssql" в DATABASES конфигурации:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>",
    },
}

Какой драйвер ODBC следует использовать?

На пути по умолчанию pyodbc используйте Microsoft ODBC Driver 18 for SQL Server. Это по умолчанию, и бэкенд автоматически возвращается к ODBC Driver 17, если версия 18 не установлена. Явно указывайте драйвер только в словаре OPTIONS, если вам нужно зафиксировать конкретную версию; при этом также отключается резервный вариант:

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
},

Путь mssql-python игнорирует параметр driver и использует ODBC Driver 18, который pip устанавливает вместе с собой.

Как подключиться к База данных SQL Azure?

Используйте полное имя сервера с портом 1433:

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

Как использовать проверку подлинности Microsoft Entra?

Используйте extra_params в OPTIONS или параметр TOKEN. Параметр TOKEN работает с любыми azure.identity учетными данными, включая DefaultAzureCredential и ManagedIdentityCredential.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

"TOKEN": token,

Сведения обо всех поддерживаемых методах см. в проверке подлинности Microsoft Entra.

Features

Поддерживает ли mssql-django JSONField?

Да, JSONField поддерживается в SQL Server 2016 и более поздних версий. Данные JSON хранятся как nvarchar(max) и запрашиваются с помощью функций JSON SQL Server. См. поддержку JSONField для получения сведений о поддерживаемых операциях поиска и ограничениях.

Поддерживает ли mssql-django значения даты и времени с учетом часового пояса?

Yes. Когда USE_TZ=True, Django использует в SQL Server тип данных datetimeoffset. При переносе существующей базы данных необходимо изменить существующие столбцы datetime2 . См. сведения о поддержке часового пояса.

Можно ли вызывать хранимые процедуры?

Yes. Используйте connection.cursor() с cursor.execute() для вызова хранимых процедур. См. хранимые процедуры для примеров с несколькими параметрами и наборами результатов.

Возвращает ли bulk_create идентификаторы?

По умолчанию нет. Для параметра return_rows_bulk_insert по умолчанию установлено значение False. Установите в базе данных True значение OPTIONS, чтобы включить возврат идентификаторов после пакетной вставки. Этот параметр должен оставаться False для таблиц с триггерами. См. статью "Массовые операции".

Troubleshooting

Я получаю "Драйвер ODBC не найден". Как это исправить?

Установите драйвер ODBC Microsoft для SQL Server. В Linux сначала добавьте репозиторий APT Microsoft, а затем установите драйвер:

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
ACCEPT_EULA=Y sudo apt-get install -y msodbcsql18

На Windows скачайте установщик с веб-сайта Microsoft. В macOS используйте Homebrew:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

Полные инструкции для конкретной платформы см. в разделе "Установка ".

Почему миграция завершается сбоем с сообщением «Не удается изменить столбец IDENTITY»?

SQL Server не поддерживает изменение типа столбца на IDENTITY (AutoField) или с IDENTITY (AutoField). Создайте модель с нужным типом поля и вручную переносите данные. См. ограничения и неподдерживаемые функции в mssql-django.

Почему bulk_update не работает с полями, допускающими значение NULL?

Серверная часть автоматически обрабатывает обновления, в которых все значения равны NULL. Если нужно контролировать значение заполнителя, используйте параметр default в bulk_update, который не допускает использования NULL в выражениях CASE WHEN ... THEN NULL, вызывающих ошибки вывода типа в SQL Server:

Product.objects.bulk_update(products, ["description"], default="")

Дополнительные сведения см. в статье "Массовые операции ".

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