Selecteer de database driver voor mssql-django

Vanaf versie 2.0 mssql-django maakt verbinding via een van twee Python-databasedrivers:

• Pyodbc met een extern geïnstalleerde Microsoft ODBC-driver voor SQL Server. Deze driver is de standaard.
• mssql-python, Microsoft's Python-driver, die geen apart geïnstalleerde ODBC-driver nodig heeft.

Je kiest de driver voor elke databasealias. Eén alias kan mssql-python gebruiken, terwijl de rest van het project op pyodbc blijft. De ENGINE waarde blijft in beide gevallen bestaan "mssql" .

Meld een alias aan voor mssql-python

Stel de python_driver optie in in het OPTIONS woordenboek van die alias:

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

De backend accepteert "mssql_python", "mssql-python", en "python", en de vergelijking negeert de naamval. Laat python_driver weg, laat het leeg of stel het in op "pyodbc" om het standaardstuurprogramma te behouden. Omdat de instelling per alias is, rol je één database tegelijk terug door de optie te verwijderen.

De mssql-python module wordt alleen geïmporteerd wanneer een alias deze selecteert. Als de geïnstalleerde versie lager is dan 1.15.0, geeft de backend ImproperlyConfigured weer waarin de vereiste versie wordt vermeld.

Installatievereisten

pip install mssql-django Installeert beide drivers. Het mssql-python pad heeft geen aparte ODBC-driverinstallatie. Een --no-deps installatie, of een privé-index die niet spiegelt mssql-python, laat het pakket ontbreken en de alias faalt tijdens import.

Installeer de platformvereisten voor mssql-python, inclusief OpenSSL op macOS en de vereiste bibliotheken op Linux.

Omdat mssql-python een vereiste afhankelijkheid is, mssql-django installeert 2.0 alleen op platforms met een compatibele mssql-python distributie. Voor de platformlijst, zie mssql-django ondersteuning en levenscyclus.

Gedragsverschillen

De twee drivers bouwen verschillende verbindingsstrings en tonen verschillende verbindingszoekwoorden. Bekijk dit gedeelte voordat je een alias verandert.

Verbindingsinstellingen

Time-outs, herpogingen, isolatieniveau, sortering en return_rows_bulk_insert werken op beide paden hetzelfde.

Extra verbindingsparameters

mssql-python 1.15 valideert extra_params tegen een toestemmingslijst en wijst alles buiten die lijst af. Ondersteunde trefwoorden omvatten Authentication, Encrypt, TrustServerCertificate, HostnameInCertificate, ServerCertificate, MultiSubnetFailover, ServerSPN, ConnectRetryCount, ConnectRetryInterval, KeepAlive, KeepAliveInterval, ApplicationIntent, IpAddressPreference en PacketSize.

Het stuurprogramma wijst MARS_Connection, APP, LongAsMax en WSID af, samen met trefwoorden die alleen door pyodbc worden gebruikt, zoals ColumnEncryption, AnsiNPW, UseFMTONLY, Regional, Description, Network Library, QuotedId, Current Language, Connect Timeout, SERVERNAME, DSN en DRIVER. Verwijder die trefwoorden voordat je een alias wisselt, en gebruik de connection_timeout optie in plaats van Connect Timeout.

Wanneer extra_params een trefwoord wordt ingesteld dat ook door de backend wordt gegenereerd, wint de expliciete waarde.

Meerdere actieve resultaatsets

Op het pyodbc pad voegt de backend toe MARS_Connection=yes wanneer de alias een Microsoft ODBC-driver op Windows gebruikt. Een expliciete MARS_Connection waarde in extra_params wordt in plaats daarvan gerespecteerd, en de match negeert de naamval.

Het mssql-python pad schakelt MARS nooit in en weigert het MARS_Connection trefwoord, dus je kunt MARS niet aanzetten voor die alias.

Zonder MARS, leest QuerySet.iterator() het volledige resultaat volledig in het geheugen voordat het rijen teruggeeft, zodat een geneste query de verbinding kan hergebruiken, en chunk_size verandert daar niets aan. Houd rekening met de geheugenkosten bij grote querysets.

Voor endpoints die MARS weigeren, zoals Microsoft Fabric Warehouse, zie MARS uitschakelen.

Coderingsconfiguratie

Beide drivers accepteren setencoding en setdecoding, en elke invoer gaat naar de verbindingsmethode van de geselecteerde driver. Elke setdecoding invoer heeft een sqltype sleutel nodig op beide paden, en dezelfde invoer werkt op beide drivers. Een verschil: mssql-python accepteert -99 voor SQL_WMETADATA, en pyodbc verwerpt het.

Kies uit de stuurprogramma's

Gebruik mssql-pythonvoor nieuwe ontwikkeling . Het verwijdert de ODBC-driverinstallatiestap uit containerimages en app service-deployments.

Gebruik pyodbc wanneer je deployment afhankelijk is van een benoemd DSN, FreeTDS, Always Encrypted via het ColumnEncryption trefwoord, een ODBC-driverversie die je zelf beheert, of MARS. Voor wat MARS vereist op elk pad, zie Multiple Active Result Sets.

Bestaande projecten kunnen blijven staan pyodbc. Het blijft de standaard en wordt volledig ondersteund. Als je wel verhuist, wissel dan één alias tegelijk en laat je testsuite erop draaien voordat je de rest verplaatst.

Verwante onderwerpen

• Verbindingsopties voor mssql-django
• naslaginformatie voor mssql-django-configuratie
• Groepsgewijze verbindingen in mssql-django
• Microsoft Entra-authenticatie met mssql-django
• mssql-python driver voor SQL Server