mssql-django — często zadawane pytania

Pakiet mssql-django to Microsoft obsługiwane zaplecze bazy danych Django dla SQL Server. Pozwala aplikacjom Django łączyć się z SQL Server, Azure SQL Database, Azure SQL Managed Instance oraz bazą danych SQL w Microsoft Fabric. Wersje 2.0 i późniejsze łączą się albo przez sterownik, pyodbc który jest domyślny, albo przez sterownik Microsoftmssql-python.

Zainstaluj go za pomocą narzędzia pip:

pip install mssql-django

Wersja pakietu mssql-django 2.0 obsługuje Django 5.2, 6.0 i 6.1. Projekty oparte na Django od wersji 3.2 do 5.1 pozostają w wersji 1.8.0. Zapoznaj się z cyklem życia wsparcia, aby uzyskać pełną macierz zgodności.

Pakiet mssql-django w wersji 2.0 obsługuje Python od 3.10 do 3.14. Konkretna wersja Python musi być również kompatybilna z wersją Django: Django 5.2 jest testowane w Python 3.10 do 3.13, a Django 6.0 i 6.1 testowane są z Python 3.12 do 3.14. Zobacz Cykl życia wsparcia, aby uzyskać pełną macierz zgodności.

Wersje 2.0 i późniejsze obsługują dwa sterowniki, wybierane dla każdego aliasu bazy danych. pyodbcjest domyślną i wymaga zewnętrznego zainstalowanego sterownika Microsoft ODBC dla SQL Server. Aby zamiast tego użyć sterownika firmy Microsoft mssql-python, który nie wymaga osobnej instalacji sterownika ODBC, dodaj python_driver do słownika OPTIONS tego aliasu:

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

Aliasy, które pomijają tę opcję, nadal używają pyodbc. Różnice w zachowaniu między tymi ścieżkami można znaleźć w artykule Wybierz sterownik bazy danych dla mssql-django.

Yes. Pakiet mssql-django jest utrzymywany przez firmę Microsoft i jest dostępny w serwisach PyPI i GitHub.

Ustaw ENGINE na "mssql" w konfiguracji DATABASES:

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

Na domyślnej pyodbc ścieżce użyj sterownika Microsoft ODBC 18 dla SQL Server. Jest to opcja domyślna, a backend automatycznie przechodzi na ODBC Driver 17, jeśli wersja 18 nie jest zainstalowana. Jawnie określ sterownik w słowniku OPTIONS tylko wtedy, gdy musisz wymusić konkretną wersję, co spowoduje również wyłączenie mechanizmu awaryjnego:

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

Ścieżka mssql-python ignoruje opcję driver i używa sterownika ODBC Driver 18, który jest instalowany przez pip.

Użyj w pełni kwalifikowanej nazwy serwera z portem 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",
        },
    },
}

Użyj extra_params w OPTIONS lub w ustawieniu TOKEN. Ustawienie TOKEN działa z dowolnymi azure.identity poświadczeniami, w tym DefaultAzureCredential i ManagedIdentityCredential.

from azure.identity import DefaultAzureCredential

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

"TOKEN": token,

Informacje o wszystkich obsługiwanych metodach znajdziesz w uwierzytelnianiu Microsoft Entra.

Tak, JSONField jest obsługiwany w SQL Server 2016 i nowszych. Dane JSON są przechowywane jako dane nvarchar(max) i są odpytywane przy użyciu funkcji JSON SQL Server. Zobacz obsługę JSONField, aby uzyskać informacje o obsługiwanych typach wyszukiwania i ograniczeniach.

Yes. W przypadku USE_TZ=True, Django używa typu danych datetimeoffset w SQL Server. Jeśli migrujesz istniejącą bazę danych, musisz zmienić istniejące kolumny datetime2 . Zobacz Obsługa strefy czasowej.

Yes. Użyj polecenia connection.cursor() , cursor.execute() aby wywołać procedury składowane. Zobacz Procedury składowane , aby zapoznać się z przykładami, w tym wieloma parametrami i zestawami wyników.

Domyślnie nie. Opcja return_rows_bulk_insert jest domyślnie ustawiona na False. Ustaw ją na True w bazie danych OPTIONS , aby włączyć zwracanie identyfikatorów po wstawieniu zbiorczym. Ta opcja musi pozostać False w przypadku tabel z wyzwalaczami. Zobacz Operacje zbiorcze.

Zainstaluj sterownik Microsoft ODBC dla SQL Server. W systemie Linux najpierw dodaj repozytorium Microsoft APT, a następnie zainstaluj sterownik:

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

Na Windows pobierz instalator z witryny internetowej Microsoft. W systemie macOS użyj oprogramowania Homebrew:

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

Aby uzyskać pełne instrukcje specyficzne dla platformy, zobacz Instalacja .

SQL Server nie obsługuje zmiany typu kolumny na IDENTITY (AutoField) ani z tego typu na inny. Utwórz nowy model z żądanym typem pola i ręcznie przeprowadź migrację danych. Zobacz Ograniczenia i nieobsługiwane funkcje w pliku mssql-django.

Backend automatycznie obsługuje aktualizacje, w których wszystkie wartości to NULL. Jeśli musisz kontrolować wartość zastępczą, użyj parametru default w bulk_update, który chroni NULL przed wyrażeniami CASE WHEN ... THEN NULL powodującymi błędy wnioskowania typu SQL Server:

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

Aby uzyskać szczegółowe informacje, zobacz Operacje zbiorcze .