Problemen met mssql-django oplossen

Veelvoorkomende problemen met de mssql-django back-end voor SQL Server, Azure SQL Database, Azure SQL Managed Instance en SQL-database in Microsoft Fabric vaststellen en oplossen.

mssql-django 2.0 ondersteunt het standaard pyodbc-driverpad en een opt-in mssql-python driverpad. Voor meer informatie, zie Selecteer de databasedriver voor mssql-django.

Verbindingsproblemen

In deze sectie worden de meest voorkomende verbindingsfouten beschreven en hoe u deze kunt oplossen.

ODBC-bestuurder niet gevonden op het pyodbc-pad

Symptomen:

django.core.exceptions.ImproperlyConfigured: 'ODBC Driver 18 for SQL Server' is not a recognized ODBC driver

Or:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

Mogelijke oorzaken en oplossingen:

• ODBC-stuurprogramma niet geïnstalleerd

  Installeer de Microsoft ODBC-driver voor SQL Server wanneer je het standaard pyodbc-pad gebruikt. Zie ODBC-stuurprogramma voor SQL Server downloaden voor downloadlinks. Het mssql-python-pad gebruikt geen extern geïnstalleerde ODBC-driver.

• Meerdere stuurprogrammaversies geïnstalleerd

  Geef de exacte naam van het stuurprogramma of het exacte pad op in settings.py:

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

  Geef in Linux het volledige pad op:

  "OPTIONS": {
      "driver": "/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1",
  },
  

• Geïnstalleerde stuurprogramma's controleren

  • Voer in Linux/macOS de opdracht uit odbcinst -q -d.
  • Controleer in Windows ODBC-gegevensbronnen in Systeembeheer.

mssql-python verwerpt een verbindingsoptie

Symptomen:

Een alias die "python_driver": "mssql_python" instelt, mislukt tijdens het tot stand brengen van de verbinding nadat je trefwoorden in de pyodbc-verbindingsreeks naar OPTIONS["extra_params"] hebt verplaatst, met een van de volgende fouten:

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Unknown keyword 'longasmax' is not recognized

mssql_python.exceptions.ConnectionStringParseError: Connection string parsing failed:
  Reserved keyword 'driver' is controlled by the driver and cannot be specified by the user

De naam van het trefwoord in het bericht wordt in kleine letters weergegeven, dus een trefwoord dat je als LongAsMax hebt geschreven verschijnt als longasmax. ConnectionStringParseError maakt geen deel uit van de DB-API uitzonderingshiërarchie, dus Django verpakt het niet opnieuw als een django.db.utils fout.

Mogelijke oorzaken en oplossingen:

• trefwoord alleen voor pyodbc in extra_params

  Het mssql-python-pad valideert extra_params tegen een toestemmingslijst. DRIVER en APP zijn gereserveerd voor de bestuurder en leveren het Reserved keyword formulier op. DSN, SERVERNAME, MARS_Connection en trefwoorden die alleen door pyodbc worden gebruikt, zoals LongAsMax, ColumnEncryption, WSID, AnsiNPW, QuotedId, UseFMTONLY, Network Library, Current Language, Description, Regional en Connect Timeout, staan niet in de toegestane lijst en resulteren in het formulier Unknown keyword. Verwijder het trefwoord, of gebruik het standaard pyodbc-pad voor een alias die die ODBC-optie nodig heeft.

• Stuurprogramma-optie bedoeld om mssql-python te beheren

  Het mssql-python-pad negeert driver, dsn, host_is_server, en unicode_results. HOST en PORT wordt SERVER=<server>,<port>, en een leeg HOST wordt localhost.

MSSQL-Python afhankelijkheid is te oud

Symptomen:

Een alias waarmee "python_driver": "mssql_python" wordt ingesteld, mislukt tijdens het opzetten van de verbinding met een van de volgende fouten:

django.core.exceptions.ImproperlyConfigured: mssql-python 1.15.0 or newer is required; you have 1.14.0

django.core.exceptions.ImproperlyConfigured: The 'python_driver' connection option requests mssql-python, but the module could not be imported: No module named 'mssql_python'. Install it with 'pip install "mssql-python>=1.15.0"'.

De tweede vorm betekent dat de mssql_python module helemaal niet importeerbaar is.

Oplossing: Installeren mssql-python>=1.15.0. mssql-django 2.0 specificeert mssql-python>=1.15.0, dus een normale pip install mssql-django vindt een compatibele versie voor ondersteunde platforms.

Driver 17 fallback is niet van toepassing op mssql-python

Symptomen:

Een alias die instelt "python_driver": "mssql_python" faalt nog steeds, ook al is Microsoft ODBC Driver 17 voor SQL Server geïnstalleerd.

Er is geen duidelijke fout in dit geval. Het mssql-python-traject negeert de optie driver geruisloos, waardoor de verbinding mislukt met de onderliggende fout die van toepassing is. Als je de stuurprogrammanaam in plaats daarvan naar extra_params verplaatst, krijg je de foutmelding Reserved keyword 'driver'. Zie mssql-python wijst een verbindingsoptie af.

Oplossing: Gebruik het standaard pyodbc-pad als de alias een extern geïnstalleerde ODBC-driver 17 moet gebruiken. Het mssql-python-pad valt niet terug op Driver 17 en negeert de driver optie. Dat pad heeft geen apart geïnstalleerde ODBC-driver nodig.

Verbinding geweigerd

Symptomen:

django.db.utils.OperationalError: ('08001', '[08001] ... TCP Provider: Error code 0x2749 ...')

Mogelijke oorzaken en oplossingen:

• TCP/IP is niet ingeschakeld op SQL Server

  • Open SQL Server Configuration Manager.
  • Schakel onder SQL Server NetwerkconfiguratieTCP/IP in.
  • Activeer in TCP/IP-eigenschappen het IP-adres dat voor de verbinding wordt gebruikt.
  • Start de SQL Server-service opnieuw.

• Firewall blokkeert poort 1433

  • Controleer of firewallregels binnenkomende verbindingen toestaan op poort 1433.
  • Voeg voor Azure SQL uw client-IP toe in de firewallinstellingen van de Azure portal.

• Verkeerde servernaam of poort

  Controleer de HOST en PORT waarden in uw configuratie.

Aanmelden is mislukt

Symptomen:

django.db.utils.OperationalError: ('28000', "[28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456) (SQLDriverConnect); [28000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Login failed for user '<user_id>'. (18456)")

Op het mssql-python-pad:

django.db.utils.OperationalError: Driver Error: Invalid authorization specification; DDBC Error: [Microsoft][SQL Server]Login failed for user '<user_id>'.

Mogelijke oorzaken en oplossingen:

• Onjuiste referenties

  Controleer de gebruikersnaam en het wachtwoord.

• De database in NAME bestaat niet

  Op SQL Server geeft het mssql-python-pad hetzelfde OperationalError signaal op met hetzelfde bericht als een slecht wachtwoord, dus het bericht alleen vertelt je niet welke je geraadpleegd hebt. Controleer of de database bestaat voordat je je inloggegevens verandert. Laat NAME naar master verwijzen om de aanmelding op zichzelf te testen: als dat verbinding maakt, zijn de inloggegevens juist en is de database het probleem. Het pyodbc-pad rapporteert dit geval afzonderlijk als Cannot open database "<database>" requested by the login. The login failed. (4060).

  Azure SQL Database rapporteert dit geval anders. Het mssql-python-pad genereert Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. Het bericht noemt de server, maar de servernaam is prima. Kijk in plaats daarvan naar NAME.

• Gebruiker bestaat niet

  Controleer of de aanmelding is toegewezen aan een gebruiker in de doeldatabase.

• SQL Server verificatie uitgeschakeld

  Schakel verificatie met gemengde modus in of gebruik Windows-verificatie of Microsoft Entra-verificatie.

Verbindingstijdoverschrijding

Symptomen:

django.db.utils.OperationalError: ('HYT00', '[HYT00] [Microsoft][ODBC Driver 18 for SQL Server]Login timeout expired')

Mogelijke oorzaken en oplossingen:

• Netwerklatentie

  Verhoog connection_timeout in OPTIES.

• Azure SQL Database serverloos met automatisch onderbreken ingeschakeld

  Een automatisch gepauzeerde database wordt hervat bij de eerste verbindingspoging, en die poging kan mislukken met foutmelding 40613 terwijl de database wordt hervat. Stel connection_timeout het in op minstens 60 en probeer de eerste verbinding opnieuw. Voor meer informatie, zie Azure SQL Database serverless en Auto-pause en auto-resume.

• Server overbelast

  Verhoog connection_retries en connection_retry_backoff_time.

  "OPTIONS": {
      "driver": "ODBC Driver 18 for SQL Server",
      "connection_timeout": 30,
      "connection_retries": 5,
      "connection_retry_backoff_time": 10,
  },
  

Migratieproblemen

Deze fouten treden op tijdens django-migratiebewerkingen tegen SQL Server.

Problemen met ruwe SQL en GROUP BY

Deze fouten ontstaan wanneer ruwe of geannoteerde queries met een GROUP BY clausule door de tijdelijke herschrijvingsstap van de backend gaan.

IndexError bij GROUP BY met geëscapete %% en echte parameters

Symptomen:

IndexError: Replacement index N out of range for positional args tuple

De query werkt zonder de clausule GROUP BY en zonder het geëscapete %%-literaal, maar mislukt wanneer beide aanwezig zijn naast een echte parameter %s.

Oplossing: Upgrade naar een huidige mssql-django versie. De backend beperkt de regex voor het herschrijven van placeholders tot alleen %% en %s, zodat geëscapete %%-literals ongewijzigd behouden blijven en er geen spookplaatshouders worden ingevoegd.

NotImplementedError voor IntegerChoices in onbewerkte GROUP BY-query's

Symptomen:

NotImplementedError: Not supported type <enum '...'> (StatusChoices.IN_PROGRESS)

Dezelfde enumwaarde werkt in ORM-queries en in ruwe queries zonder GROUP BY, maar faalt wanneer deze als parameter wordt doorgegeven aan een ruwe query die een GROUP BY clausule bevat.

Oplossing: Upgrade naar een huidige mssql-django versie. De backend gebruikt isinstance voor controles van parametertypen in het GROUP BY pad, dus IntegerChoices (een subklasse van int) wordt correct gebonden. bool Bindt nog steeds bit, en plain int is ongewijzigd.

Regex-zoekproblemen

__regex of __iregex geeft geen rijen terug

Symptomen: De query draait foutloos en geeft een lege resultaatset terug, ook al komen de rijen overeen met het patroon.

Product.objects.filter(name__regex=r"^Widget \d+$")  # no rows, though "Widget 42" exists

Oorzaak: dbo.REGEXP_LIKE negeert letterlijke witruimte in het patroon. Het patroon wordt vergeleken alsof het ^Widget\d+$ zou zijn, waaraan geen enkele waarde die een spatie bevat kan voldoen. Niets wordt verhoogd, dus het lege resultaat lijkt op een dataprobleem.

Oplossing: Schrijf witruimte als een escape- of karakterklasse:

Product.objects.filter(name__regex=r"^Widget\s\d+$")
Product.objects.filter(name__regex=r"^Widget[ ]\d+$")

Cannot find ... dbo.REGEXP_LIKE

Symptomen:

django.db.utils.ProgrammingError: ('42000', '[42000] [Microsoft][ODBC Driver 18 for SQL Server][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous. (4121) (SQLExecDirectW)')

Op het mssql-python pad:

django.db.utils.ProgrammingError: Driver Error: Syntax error or access violation; DDBC Error: [Microsoft][SQL Server]Cannot find either column "dbo" or the user-defined function or aggregate "dbo.REGEXP_LIKE", or the name is ambiguous.

Oorzaak: De CLR-assembly is niet geïnstalleerd in de database die je zoekt. Het wordt per database geïnstalleerd, niet per server.

Oplossing: Voer python manage.py install_regex_clr <database> het op tegen die database. Voer het opnieuw uit nadat je een database hebt verwijderd en opnieuw hebt aangemaakt. Zie regex-zoekopdrachten instellen.

Problemen met datum en tijd

Now() waarden worden verschoven wanneer USE_TZ=True

Symptomen:

Tijdstempels die zijn geschreven met Django Now()of auto_nowauto_now_add worden verschoven wanneer de SQL Server hosttijdzone niet UTC is.

Oplossing: Upgrade naar een huidige mssql-django versie. De backend genereert tijdzonebewuste Now() SQL, bewaart datetimeoffset-offsets en leest tijdzonegegevens via zoneinfo en tzdata.

AttributeError bij bellen .explain()

Symptomen:

AttributeError: ... explain_format ...

Oplossing: Upgrade naar een huidige mssql-django versie. De backend-handlagen leggen metadata uit voor elke ondersteunde Django-versie.

AutoField kan niet worden gewijzigd

Symptomen:

django.db.utils.ProgrammingError: Cannot alter column to or from an IDENTITY column

Oplossing: SQL Server biedt geen ondersteuning voor het wijzigen van een veld van of naar AutoField. Maak een nieuw model met het gewenste veldtype, migreer de gegevens handmatig en zet de oude tabel neer. Zie Databasemigraties met mssql-django voor tijdelijke oplossingen.

Naam wijzigen mislukt vanwege een foreign key-constraint

Symptomen:

django.db.utils.ProgrammingError: ... could not drop constraint ...

Oplossing: SQL Server vereist het verwijderen van beperkingen voor refererende sleutels voordat u de naam van kolommen wijzigt. Gebruik SeparateDatabaseAndState in uw migratie. Zie databasemigraties met mssql-django voor een voorbeeld.

Problemen met codering

Encoderingsfouten treden meestal voor op het pyodbc-pad wanneer pyodbc tekengegevens van SQL Server verkeerd worden geïnterpreteerd.

Unicode-coderingsfouten

Symptomen:

UnicodeDecodeError: 'utf-8' codec can't decode byte ...

Oplossing: Configureer pyodbc codering in het OPTIONS woordenboek. Het mssql-python-pad negeert unicode_results.

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

Problemen met FreeTDS

FreeTDS vereist een pyodbc-specifieke configuratie die verschilt van de Microsoft ODBC-driver.

fout bij host_is_server

Symptomen:

De verbinding mislukt wanneer u FreeTDS gebruikt zonder host_is_server op te geven.

Oplossing: Ingesteld host_is_server op True wanneer u FreeTDS gebruikt:

"OPTIONS": {
    "driver": "FreeTDS",
    "host_is_server": True,
},

Zie Verbindingsopties voor mssql-django voor meer informatie over de FreeTDS-configuratie.

Databaseproblemen testen

Het maken en vernietigen van de testdatabase kan mislukken, afhankelijk van uw authenticatiemethode.

Kan geen testdatabase maken met beheerde identiteit

Symptomen:

django.db.utils.DatabaseError: ('42000', '[42000] ... EXECUTE permission denied on object ...')

Or:

django.db.utils.OperationalError: ('28000', ... login failed ...)

De testrunner kan de testdatabase niet maken of verwijderen wanneer u ActiveDirectoryMsi-authenticatie (beheerde identiteit) gebruikt. Deze beperking bestaat omdat:

• Referenties voor beheerde identiteiten worden verkregen uit de hostomgeving (zoals Azure VM en App Service).

• De testrunner probeert tijdens de teardownfase verbinding te maken met de inloggegevens van de test-database.

• Aan beheerde identiteit kunnen rollen op databaseniveau worden verleend, maar voor het maken en verwijderen van databases zijn meestal machtigingen op serverniveau vereist die testlopers vaak niet hebben.

Beïnvloede verificatiemethoden:

• ActiveDirectoryMsi (door Azure beheerde identiteit)
• ActiveDirectoryServicePrincipal (alleen wanneer geconfigureerd op serverniveau)

Ondersteunde verificatiemethoden (het maken van een testdatabase werkt):

• ActiveDirectoryPassword
• ActiveDirectoryIntegrated
• SQL-verificatie (gebruikersnaam/wachtwoord)

Verificatie-afwegingen voor testomgevingen

Oplossingen:

• Voor ontwikkeling: Gebruik --keepdb de vlag om testdatabase te verwijderen:

  python manage.py test --keepdb
  

• Voor CI/CD-pijplijnen: maak vooraf een toegewezen testdatabase en verdeel de beheerde identiteit CREATE TABLE en ALTER machtigingen:

  -- Connect as a server admin, then:
  USE [test_database_name];
  
  -- Grant permissions for managed identity (replace with your identity name)
  CREATE USER [your-app-identity] FROM EXTERNAL PROVIDER;
  GRANT CREATE TABLE TO [your-app-identity];
  GRANT ALTER ON SCHEMA::dbo TO [your-app-identity];
  

• Alternatief: GEBRUIK SQL-verificatie voor testomgevingen of schakel over naar ActiveDirectoryPassword voor CI/CD-testlopers.

Terugdraaiprocedures

Wanneer een migratie halverwege mislukt, gebruikt u deze terugdraaivolgorde om terug te keren naar een bekende goede status:

1. Stop schrijfbewerkingen van toepassingen om extra schemadrift te voorkomen.

2. Migratiestatus controleren:

   python manage.py showmigrations
   python manage.py sqlmigrate <app_label> <migration_number>
   

3. Ga terug naar de laatst bekende goede migratie:

   python manage.py migrate <app_label> <previous_migration>
   

4. Als het schema en de migratiegeschiedenis van elkaar afwijken, repareer de status dan zorgvuldig met --fake en doe dit alleen nadat u het daadwerkelijke databaseschema hebt gecontroleerd.

5. Voer eerst migraties opnieuw uit in een faseringsomgeving en probeer vervolgens de productie opnieuw uit te voeren.

Problemen met Docker en containers

Containerimages vereisen expliciete ODBC-driverinstallatie en build-afhankelijkheden wanneer je het standaard pyodbc-pad gebruikt. Het mssql-python-pad heeft geen aparte ODBC-driverinstallatie, maar heeft nog steeds de unixODBC-runtime nodig, omdat de backend pyodbc importeert wanneer Django het laadt.

ODBC-stuurprogramma is niet gevonden in container

Symptomen:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 18 for SQL Server'")

Mogelijke oorzaken en oplossingen:

• ODBC-stuurprogramma niet geïnstalleerd in de containerinstallatiekopieën

  Slim- of Alpine-basisinstallatiekopieën bevatten niet het ODBC-stuurprogramma. Voeg de Microsoft APT-repository toe en installeer msodbcsql18 deze in je Dockerfile wanneer je pyodbc gebruikt. Zie Implementeren in App Service voor een volledig Dockerfile-voorbeeld.

• Ontbrekend unixodbc-dev pakket

  Het pyodbc wiel sluit tegen libodbc.so. Installeer unixodbc-dev (Debian/Ubuntu) of unixODBC-devel (RHEL/Fedora) voordat u Python pakketten installeert.

• apt-get autoremove libgssapi-krb5-2 verwijderd na de installatie van de driver

  msodbcsql18 laadt libgssapi-krb5-2 tijdens runtime zonder het als afhankelijkheid op te geven. De bibliotheek wordt meestal geïnstalleerd als afhankelijkheid van curl, dus als je curl met --auto-remove verwijdert of daarna apt-get autoremove uitvoert, wordt deze ook verwijderd. De image wordt zonder fouten gebouwd en daarna mislukt elke verbinding. Installeer libgssapi-krb5-2 expliciet en voer geen automatische verwijdering uit na de installatie van het stuurprogramma.

Driver 17 als ontbrekend gemeld toen je versie 18 installeerde

Symptomen:

Error: ('01000', "[01000] [unixODBC][Driver Manager]Can't open lib 'ODBC Driver 17 for SQL Server' : file not found (0) (SQLDriverConnect)")

De foutmelding noemt versie 17, maar odbcinst -q -d toont versie 18 geregistreerd en dpkg -l msodbcsql18 toont dat het geïnstalleerd is.

Oorzaak: Versie 18 is geregistreerd maar laadt niet, dus mssql-django valt terug op versie 17, die niet geïnstalleerd is. De terugvaloptie meldt het stuurprogramma dat als tweede is geprobeerd, niet het stuurprogramma dat is mislukt.

Oplossing: Installeren libgssapi-krb5-2 en opnieuw opbouwen. Zie de voorgaande opmerking over automatisch verwijderen voor informatie over hoe de bibliotheek kwijtraakt.

Foutlaad pyodbc-module in een container

Symptomen:

django.core.exceptions.ImproperlyConfigured: Error loading pyodbc module: libodbc.so.2: cannot open shared object file: No such file or directory

Oorzaak: De afbeelding heeft geen unixODBC-runtime. mssql-django importeert pyodbc wanneer Django de backend laadt, dus deze fout doet zich ook voor op het mssql-python-pad, voordat er een verbinding wordt geprobeerd.

Oplossing: Installeren unixodbc (of unixodbc-dev).

MSSQL-Python driver kan niet laden

Symptomen:

django.db.utils.OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver.

Oorzaak: De driver die bij mssql-python wordt geleverd, heeft de Kerberos-runtimebibliotheken nodig, die niet in slanke basisimages zijn opgenomen.

Oplossing: Installeren libkrb5-3 en libgssapi-krb5-2.

pyodbc kan niet worden gebouwd op slim-images

Symptomen:

error: command 'gcc' failed: No such file or directory

Or:

fatal error: sql.h: No such file or directory

Oplossing: Installeer afhankelijkheden voor de build vóór pip install:

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    g++ \
    unixodbc-dev

U kunt ook een build in meerdere fasen gebruiken om de uiteindelijke image compact te houden:

# Build stage
FROM python:3.12-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ unixodbc-dev
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Runtime stage
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl gnupg2 unixodbc \
    && curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
    && curl -fsSL https://packages.microsoft.com/config/debian/12/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 libgssapi-krb5-2 \
    && apt-get purge -y curl gnupg2 \
    && rm -rf /var/lib/apt/lists/*
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/*

Container kan geen verbinding maken met SQL Server

Symptomen:

django.db.utils.OperationalError: ('08001', '... TCP Provider: Error code 0x2749 ...')

Mogelijke oorzaken en oplossingen:

• Docker Compose-servicenaam wordt niet als host gebruikt

  Wanneer u Docker Compose gebruikt, stelt u DB_HOST in op de servicenaam (bijvoorbeeld db), niet localhost of 127.0.0.1.

• SQL Server container niet gereed

  Het starten van de SQL Server-container duurt enkele seconden. Voeg een statuscontrole of opstartvertraging toe:

  services:
    db:
      image: mcr.microsoft.com/mssql/server:2022-latest
      healthcheck:
        test: /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -No -Q "SELECT 1" || exit 1
        # $$ escapes the $ sign in Docker Compose YAML
        interval: 10s
        retries: 10
        start_period: 10s
    web:
      depends_on:
        db:
          condition: service_healthy
  

• Poorttoewijzingsconflicten

  Als een ander exemplaar van SQL Server wordt uitgevoerd op de host, wijzigt u de weergegeven poort (bijvoorbeeld 1434:1433) en werkt u de Django-configuratie dienovereenkomstig bij.

Azure SQL tijdelijke foutherstel

De mssql-django back-end detecteert automatisch Azure SQL Database en Azure SQL Managed Instance verbindingen door een query uit te voerenSERVERPROPERTY('EngineEdition'). Wanneer de back-end wordt uitgevoerd op Azure SQL, worden verbindingen opnieuw geprobeerd op tijdelijke fouten (zoals tijdelijke resourcelimieten of korte netwerkonderbrekingen).

U kunt dit gedrag afstemmen met de connection_retries opties en connection_retry_backoff_time opties:

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

Deze instellingen zijn alleen van toepassing op de eerste verbindingsinstelling. De back-end probeert mislukte query's niet opnieuw uit te voeren. Als een query mislukt met een tijdelijke fout nadat de verbinding tot stand is gebracht, wordt de uitzondering doorgegeven aan uw toepassingscode. Gebruik logica voor opnieuw proberen op toepassingsniveau (bijvoorbeeld django-retry-db of een aangepaste middleware) voor tolerantie op queryniveau.

Trage query’s en regressies in uitvoeringsplannen

Deze problemen hebben meestal analyse aan de serverzijde nodig, samen met querybeoordeling op Django-niveau.

Een query wordt trager of krijgt een time-out

Symptomen:

Dezelfde queryset wordt na verloop van tijd langzamer of begint met een time-out na een implementatie, indexwijziging of statistiekenupdate.

Mogelijke oorzaken en oplossingen:

• Beginnen met ingebouwde prestatierapporten

  Open prestatiedashboard in SQL Server Management Studio voor SQL Server en Azure SQL Managed Instance. Open Query Performance Insight voor Azure SQL Database. Deze hulpmiddelen zijn meestal een betere eerste stap dan ad-hoc-DMV-query's, omdat ze kostbare query's, wachttijden en druk op resources snel zichtbaar maken.

• Regressie plannen

  Gebruik Query Store om de langzame query te vinden en te controleren of deze meerdere abonnementen heeft. Begin met de teruggedraaide query's en weergaven voor query's die de meeste resources verbruiken, zoals beschreven in best practices voor het bewaken van workloads met Query Store.

• Inefficiënt uitvoeringsplan

  Open een daadwerkelijk uitvoeringsplan voor de instructie en controleer op tabel- of indexscans, grote sleutelzoekacties, hash-overloop of onjuiste schattingen van rijen. Zie Overzicht van uitvoeringsplan voor achtergrond.

• Onjuist knelpunt geïdentificeerd

  Als de query niet afhankelijk is van de CPU, gebruikt u Query Store wachtstatistieken en identificeert u knelpunten om CPU, geheugen, schijf-I/O, blokkering en verbindingsdruk te onderscheiden.

• Fix toegepast in de verkeerde laag

  Pas de kleinste effectieve oplossing toe: indexen toevoegen of aanpassen, statistieken bijwerken, geselecteerde kolommen en rijen verminderen of grote schrijfbewerkingen in batches uitvoeren. Als u een noodmaatregel nodig hebt, kan een DBA tijdelijk een plan waarvan bekend is dat het goed werkt afdwingen in Query Store terwijl u de hoofdoorzaak corrigeert.

Dbshell gebruiken voor interactieve query's

Met de beheeropdracht van dbshell Django wordt een interactieve SQL-shell geopend die is verbonden met uw database:

python manage.py dbshell

De back-end gebruikt sqlcmd wanneer u het Microsoft ODBC-stuurprogramma configureert of isql wanneer u FreeTDS gebruikt. Controleer of het hulpprogramma zich op uw PATH bevindt:

• Windows: sqlcmd is opgenomen in SQL Server hulpprogramma's of u kunt deze afzonderlijk downloaden.
• Linux en macOS: Installeren mssql-tools18 vanuit de Microsoft opslagplaats.

Verwante inhoud

• naslaginformatie voor mssql-django-configuratie
• Verbindingsopties voor mssql-django
• Logica en verbindingstolerantie opnieuw proberen met mssql-django
• Beperkingen en niet-ondersteunde functies in mssql-django
• Prestatiedashboard
• Inzicht in queryprestaties voor Azure SQL Database
• Prestaties bewaken met behulp van de Query Store
• Een werkelijk uitvoeringsplan analyseren
• Wiki voor probleemoplossing
• FAQ