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.

Verbindingsproblemen

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

ODBC-stuurprogramma niet gevonden

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 het ODBC-stuurprogramma voor Microsoft voor SQL Server. Zie ODBC-stuurprogramma voor SQL Server downloaden voor downloadlinks.

• Meerdere stuurprogrammaversies geïnstalleerd

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

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

  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.

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 '<username>'.")

Mogelijke oorzaken en oplossingen:

• Onjuiste referenties

  Controleer de gebruikersnaam en het wachtwoord.

• 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.

• 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 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: voer een upgrade uit naar mssql-django 1.7.2 of hoger. Versie 1.7.2 verhelpt problemen met tijdzonebewuste Now()SQL-generatie en de offsetverwerking van datetimeoffset.

AttributeError bij bellen .explain()

Symptomen:

AttributeError: ... explain_format ...

Oplossing: voer een upgrade uit naar mssql-django 1.7.2 of hoger. Versie 1.7.2 corrigeert compilercompatibiliteit voor Django 4.0 en later uitleg van metagegevens.

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

Coderingsfouten treden meestal op wanneer pyodbc tekengegevens van SQL Server verkeerd worden geïnterpreteerd.

Unicode-coderingsfouten

Symptomen:

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

Oplossing: Codering configureren pyodbc in de OPTIONS woordenlijst:

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

Problemen met FreeTDS

FreeTDS vereist specifieke configuratie die verschilt van het Microsoft ODBC-stuurprogramma.

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 een expliciete installatie van ODBC-stuurprogramma's en build-afhankelijkheden.

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-opslagplaats toe en installeer msodbcsql18 deze in uw Dockerfile. 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.

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 \
    && apt-get purge -y --auto-remove 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