Fehlerbehebung für mssql-django

Diagnostizieren und Beheben häufiger Probleme mit dem mssql-django Back-End für SQL Server, Azure SQL-Datenbank, Azure SQL Managed Instance und SQL-Datenbank in Microsoft Fabric.

mssql-django 2.0 unterstützt den Standard-Pyodbc-Treiberpfad und einen opt-in mssql-python-Treiberpfad. Weitere Informationen finden Sie unter Select the database driver for mssql-django.

Verbindungsprobleme

In diesem Abschnitt werden die am häufigsten auftretenden Verbindungsfehler und deren Behebung behandelt.

ODBC-Treiber auf dem pyodbc-Pfad nicht gefunden

Symptome:

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

Oder:

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

Mögliche Ursachen und Lösungen:

• ODBC-Treiber nicht installiert

  Installiere den Microsoft ODBC-Treiber für SQL Server, wenn du den Standardpfad von pyodbc verwendest. Downloadlinks finden Sie unter "ODBC-Treiber herunterladen" für SQL Server. Der mssql-python-Pfad verwendet keinen extern installierten ODBC-Treiber.

• Mehrere Treiberversionen installiert

  Geben Sie den genauen Treibernamen oder Pfad 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",
          },
      },
  }
  

  Geben Sie unter Linux den vollständigen Pfad an:

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

• Überprüfen der installierten Treiber

  • Führen Sie unter Linux/macOS odbcinst -q -d aus.
  • Überprüfen Sie auf Windows ODBC-Datenquellen in den Verwaltungstools.

mssql-python lehnt eine Verbindungsoption ab

Symptome:

Ein Alias, das "python_driver": "mssql_python" festlegt, schlägt während der Verbindungseinrichtung fehl, nachdem Sie pyodbc-Schlüsselwörter der Verbindungszeichenfolge nach OPTIONS["extra_params"] verschoben haben, und zwar mit einem der folgenden Fehler:

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

Der Schlüsselwortname in der Nachricht ist in Kleinbuchstaben geschrieben, sodass ein von Ihnen geschriebenes Schlüsselwort LongAsMax als longasmaxerscheint. ConnectionStringParseError ist nicht Teil der DB-API Ausnahmehierarchie, daher packt Django sie nicht als django.db.utils Fehler neu.

Mögliche Ursachen und Lösungen:

• Nur für pyodbc verfügbares Schlüsselwort in extra_params

  Der mssql-python-Pfad validiert extra_params gegen eine Erlaubnisliste. DRIVER und APP sind dem Fahrer vorbehalten und liefern das Reserved keyword Formular. DSN, SERVERNAME, MARS_Connection und nur für pyodbc geltende Schlüsselwörter wie LongAsMax, ColumnEncryption, WSID, QuotedId, AnsiNPW, Regional, UseFMTONLY, Current Language, Description, Network Library und Connect Timeout sind nicht in der Zulassungsliste enthalten und erzeugen die Form Unknown keyword. Entferne das Schlüsselwort oder verwende den Standardpfad pyodbc für ein Alias, das diese ODBC-Option benötigt.

• Treiberoption soll mssql-python steuern

  Der mssql-python-Pfad ignoriert driver, dsn, host_is_server, und unicode_results. HOST und PORT werden zu SERVER=<server>,<port>, und ein leeres HOST wird zu localhost.

MSSQL-Python-Abhängigkeit ist zu alt

Symptome:

Ein Alias, der "python_driver": "mssql_python" setzt, schlägt beim Einrichten der Verbindung mit einem dieser Fehler fehl:

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

Die zweite Form bedeutet, dass das Modul mssql_python überhaupt nicht importierbar ist.

Lösung: Installieren mssql-python>=1.15.0. mssql-django 2.0 deklariert mssql-python>=1.15.0, sodass ein normales pip install mssql-django auf unterstützten Plattformen eine kompatible Version ermittelt.

Treiber-17-Fallback gilt nicht für mssql-python

Symptome:

Ein Alias, der "python_driver": "mssql_python" festlegt, schlägt dennoch fehl, obwohl Microsoft ODBC Driver 17 für SQL Server installiert ist.

In diesem Fall gibt es keinen besonderen Fehler. Der mssql-python-Pfad ignoriert die Option driver stillschweigend, sodass die Verbindung mit dem jeweils zugrunde liegenden Fehler fehlschlägt. Wenn du stattdessen den Treibernamen einträgst extra_params , bekommst du eine Fehlermeldung Reserved keyword 'driver' . Siehe mssql-python lehnt eine Verbindungsoption ab.

Lösung: Verwenden Sie den Standardpfad von pyodbc, wenn der Alias einen extern installierten ODBC-Treiber 17 verwenden muss. Der mssql-python-Pfad greift nicht auf Treiber 17 zurück und ignoriert die driver Option. Dieser Pfad benötigt keinen separat installierten ODBC-Treiber.

Verbindung verweigert

Symptome:

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

Mögliche Ursachen und Lösungen:

• TCP/IP ist für SQL Server nicht aktiviert

  • Öffnen Sie den SQL Server-Konfigurations-Manager.
  • Aktivieren Sie unter SQL Server NetzwerkkonfigurationTCP/IP.
  • Aktivieren Sie in den TCP/IP-Eigenschaften die für die Verbindung verwendete IP-Adresse.
  • Starten Sie den SQL Server-Dienst neu.

• Firewall blockiert Port 1433

  • Überprüfen Sie, ob Firewallregeln eingehende Verbindungen an Port 1433 zulassen.
  • Fügen Sie für Azure SQL Ihre Client-IP in den Azure Portalfirewalleinstellungen hinzu.

• Falscher Servername oder -port

  Überprüfen Sie die Werte HOST und PORT in Ihrer Konfiguration.

Fehler bei der Anmeldung

Symptome:

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)")

Auf dem mssql-python-Pfad:

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

Mögliche Ursachen und Lösungen:

• Falsche Anmeldeinformationen

  Überprüfen Sie den Benutzernamen und das Kennwort.

• Die Datenbank in NAME existiert nicht

  Auf SQL Server wird der mssql-python-Pfad mit derselben OperationalError Nachricht wie bei einem schlechten Passwort angezeigt, sodass die Nachricht allein nicht anzeigt, welches Passwort du getroffen hast. Bestätigen Sie, dass die Datenbank existiert, bevor Sie die Zugangsdaten ändern. Richten Sie NAME auf master, um die Anmeldung isoliert zu testen: Wenn die Verbindung hergestellt werden kann, sind die Zugangsdaten korrekt und das Problem liegt bei der Datenbank. Der Pyodbc-Pfad meldet diesen Fall separat als Cannot open database "<database>" requested by the login. The login failed. (4060).

  Azure SQL-Datenbank berichtet diesen Fall anders. Der mssql-python-Pfad löst Driver Error: General error; DDBC Error: [Microsoft][SQL Server]Cannot open server "<server>" requested by the login. The login failed. aus. Die Meldung nennt den Server, aber der Servername ist in Ordnung. Prüfen Sie stattdessen NAME.

• Der Benutzer ist nicht vorhanden.

  Vergewissern Sie sich, dass die Anmeldung einem Benutzer in der Zieldatenbank zugeordnet ist.

• SQL Server Authentifizierung deaktiviert

  Aktivieren Sie die Authentifizierung im gemischten Modus, oder verwenden Sie Windows oder Microsoft Entra Authentifizierung.

Verbindungstimeout

Symptome:

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

Mögliche Ursachen und Lösungen:

• Netzwerklatenz

  Erhöhen Sie connection_timeout in OPTIONEN.

• Azure SQL-Datenbank serverlos mit aktivierter automatischer Pause

  Eine automatisch pausierte Datenbank wird beim ersten Verbindungsversuch fortgesetzt, und dieser Versuch kann mit dem Fehler 40613 scheitern, während die Datenbank fortgesetzt wird. Stelle connection_timeout auf mindestens 60 und versuche die erste Verbindung erneut. Weitere Informationen finden Sie unter Azure SQL-Datenbank serverlos und Automatisches Anhalten und automatisches Fortsetzen.

• Serverüberladung

  Erhöhen Sie connection_retries und connection_retry_backoff_time.

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

Migrationsprobleme

Diese Fehler treten bei Django-Migrationsvorgängen gegen SQL Server auf.

Rohe SQL- und GROUP BY-Probleme

Diese Fehler treten auf, wenn rohe oder annotierte Abfragen mit einer Klausel GROUP BY den Platzhalter-Umschreibungsschritt des Backends durchlaufen.

IndexError bei „GROUP BY“ mit maskierten %%-Parametern

Symptome:

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

Die Abfrage funktioniert ohne die GROUP BY Klausel und ohne das entkommene %% Literal, scheitert jedoch, wenn beide zusammen mit einem realen %s Parameter vorhanden sind.

Lösung: Upgrade auf eine aktuelle mssql-django Version. Das Backend schränkt das Platzhalter-Umschreib-Regex auf %% und %s nur ein, sodass entkommene %% Literals wortwörtlich erhalten bleiben und keine Phantom-Platzhalter eingefügt werden.

NotImplementedError für IntegerChoices rohe GROUP BY-Abfragen

Symptome:

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

Derselbe Enum-Wert funktioniert in ORM-Abfragen und in Rohabfragen ohne GROUP BY, scheitert jedoch, wenn er als Parameter an eine Rohfrage, die eine Klausel GROUP BY enthält, übergeben wird.

Lösung: Upgrade auf eine aktuelle mssql-django Version. Das Backend verwendet isinstance für Parametertypprüfungen im Pfad GROUP BY, sodass IntegerChoices (eine int-Unterklasse) ordnungsgemäß gebunden wird. bool bindet weiterhin bit, und einfaches int bleibt unverändert.

Probleme mit der Regex-Suche

__regex oder __iregex gibt keine Zeilen zurück

Symptome: Die Abfrage läuft fehlerfrei und liefert eine leere Ergebnismenge, obwohl die Zeilen dem Muster entsprechen.

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

Ursache: dbo.REGEXP_LIKE Ignoriert den buchstäblichen Weißraum im Muster. Das Muster wird so abgeglichen, als wäre es ^Widget\d+$, was von keinem Wert erfüllt werden kann, der ein Leerzeichen enthält. Nichts wird angezeigt, sodass das leere Ergebnis wie ein Datenproblem aussieht.

Lösung: Schreibe Whitespace als Escape oder als Charakterklasse:

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

Cannot find ... dbo.REGEXP_LIKE

Symptome:

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)')

Auf dem mssql-python Pfad:

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.

Ursache: Die CLR-Assembler ist nicht in der Datenbank installiert, die du absprichst. Es wird pro Datenbank installiert, nicht pro Server.

Lösung: Führen Sie python manage.py install_regex_clr <database> für diese Datenbank aus. Führe es erneut aus, nachdem du eine Datenbank gelöscht und neu erstellt hast. Siehe Regex-Lookups einrichten.

Probleme mit Datum und Uhrzeit

Now() Werte werden verschoben, wenn USE_TZ=True

Symptome:

Zeitstempel, die mit Django Now(), auto_now oder auto_now_add geschrieben werden, sind verschoben, wenn die Zeitzone des SQL-Server-Hosts nicht UTC ist.

Lösung: Upgrade auf eine aktuelle mssql-django Version. Das Backend erzeugt zeitzonenfähiges Now() SQL, behält datetimeoffset-Offsets bei und liest Zeitzonendaten über zoneinfo und tzdata.

AttributeError beim Anrufen .explain()

Symptome:

AttributeError: ... explain_format ...

Lösung: Upgrade auf eine aktuelle mssql-django Version. Die Backend-Handles erklären Metadaten für jede unterstützte Django-Version.

AutoField kann nicht geändert werden

Symptome:

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

Lösung: SQL Server unterstützt keine Änderung eines Felds von oder zu .AutoField Erstellen Sie ein neues Modell mit dem gewünschten Feldtyp, migrieren Sie die Daten manuell, und legen Sie dann die alte Tabelle ab. Problemumgehungen finden Sie unter Datenbankmigrationen mit mssql-django.

Umbenennen schlägt aufgrund einer Fremdschlüsselbeschränkung fehl

Symptome:

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

Lösung: SQL Server erfordert das Ablegen von Fremdschlüsseleinschränkungen vor dem Umbenennen von Spalten. Verwenden Sie SeparateDatabaseAndState in Ihrer Migration. Ein Beispiel finden Sie unter Datenbankmigrationen mit mssql-django.

Codierungsprobleme

Kodierungsfehler treten typischerweise auf dem pyodbc-Pfad auf, wenn pyodbc Zeichendaten aus dem SQL Server falsch interpretiert werden.

Unicode-Codierungsfehler

Symptome:

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

Lösung: Konfigurieren Sie die pyodbc-Kodierung im OPTIONS-Wörterbuch. Der mssql-python-Pfad ignoriert unicode_results.

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

FreeTDS-Probleme

FreeTDS erfordert eine pyodbc-spezifische Konfiguration, die sich vom Microsoft ODBC-Treiber unterscheidet.

host_is_server Fehler

Symptome:

Verbindung schlägt fehl, wenn FreeTDS ohne Angabe host_is_serververwendet wird.

Lösung: Legen Sie host_is_server auf True fest, wenn Sie FreeTDS verwenden:

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

Weitere Informationen zur FreeTDS-Konfiguration finden Sie unter "Verbindungsoptionen für mssql-django".

Testen von Datenbankproblemen

Die Erstellung und Zerstörung der Testdatenbank kann je nach Authentifizierungsmethode fehlschlagen.

Die Testdatenbank mit verwalteter Identität kann nicht erstellt werden.

Symptome:

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

Oder:

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

Der Testläufer kann die Testdatenbank nicht erstellen oder löschen, wenn Sie die ActiveDirectoryMsi-Authentifizierung mit verwalteter Identität verwenden. Diese Einschränkung besteht aus folgenden Gründen:

• Anmeldeinformationen für verwaltete Identitäten werden aus der Hostumgebung abgerufen (z. B. Azure VM und App Service).

• Der Testläufer versucht, sich beim Teardown mit den Datenbank-Anmeldeinformationen von test zu verbinden.

• Einer verwalteten Identität können Rollen auf Datenbankebene zugewiesen werden, aber zum Erstellen und Löschen von Testdatenbanken sind in der Regel Berechtigungen auf Serverebene erforderlich, über die Test-Runner häufig nicht verfügen.

Betroffene Authentifizierungsmethoden:

• ActiveDirectoryMsi (von Azure verwaltete Identität)
• ActiveDirectoryServicePrincipal (nur bei Konfiguration auf Serverebene)

Unterstützte Authentifizierungsmethoden (Testdatenbankerstellung funktioniert):

• ActiveDirectoryPassword
• ActiveDirectoryIntegrated
• SQL-Authentifizierung (Benutzername/Kennwort)

Kompromisse bei der Authentifizierung für Testumgebungen

Lösungen:

• Für die Entwicklung: Verwenden Sie das Flag --keepdb, um die Bereinigung der Testdatenbank zu überspringen:

  python manage.py test --keepdb
  

• Für CI/CD-Pipelines: Erstellen Sie eine dedizierte Testdatenbank vorab und gewähren Sie die verwaltete Identität CREATE TABLE und ALTER Berechtigungen:

  -- 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];
  

• Alternative: Verwenden Sie die SQL-Authentifizierung für Testumgebungen, oder wechseln Sie für CI/CD-Testläufer zu ActiveDirectoryPassword.

Rollback-Prozeduren

Wenn eine Migration während des Vorgangs fehlschlägt, verwenden Sie diese Rollback-Sequenz, um zu einem bekanntermaßen funktionsfähigen Zustand zurückzukehren:

1. Beenden Sie Anwendungsschreibvorgänge, um zusätzliche Schemaabweichungen zu vermeiden.

2. Überprüfen des Migrationsstatus:

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

3. Führen Sie einen Rollback auf die letzte bekannte gute Migration durch:

   python manage.py migrate <app_label> <previous_migration>
   

4. Wenn das Schema und die Migrationshistorie voneinander abweichen, korrigieren Sie den Zustand sorgfältig mit --fake, aber erst, nachdem Sie das tatsächliche Datenbankschema überprüft haben.

5. Führen Sie Migrationen zuerst in einer Staging-Umgebung erneut aus und versuchen Sie es dann in der Produktionsumgebung erneut.

Probleme mit Docker und Containern

Container-Images erfordern eine explizite ODBC-Treiberinstallation und Build-Abhängigkeiten, wenn man den Standardpfad von pyodbc verwendet. Der mssql-python-Pfad hat keine separate ODBC-Treiberinstallation, benötigt aber trotzdem die unixODBC-Laufzeit, weil das Backend pyodbc importiert, wenn Django es lädt.

ODBC-Treiber im Container nicht gefunden

Symptome:

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

Mögliche Ursachen und Lösungen:

• ODBC-Treiber nicht im Containerimage installiert

  Schlanke oder Alpine-Basis-Images enthalten den ODBC-Treiber nicht. Füge das Microsoft-APT-Repository hinzu und installiere msodbcsql18 in deinem Dockerfile, wenn du pyodbc verwendest. Ein vollständiges Dockerfile-Beispiel finden Sie unter Deploy to App Service.

• Fehlendes unixodbc-dev Paket

  Das pyodbc-Wheel verbindet sich mit libodbc.so. Installieren Sie unixodbc-dev (Debian/Ubuntu) oder unixODBC-devel (RHEL/Fedora), bevor Sie Python Pakete installieren.

• apt-get autoremove entfernt libgssapi-krb5-2 nach der Treiberinstallation

  msodbcsql18 lädt libgssapi-krb5-2 zur Laufzeit, ohne es als Abhängigkeit zu deklarieren. Die Bibliothek wird in der Regel als Abhängigkeit von curl installiert. Daher wird sie entfernt, wenn curl mit --auto-remove vollständig entfernt oder anschließend apt-get autoremove ausgeführt wird. Das Bild baut sich sauber auf und jede Verbindung schlägt dann fehl. Installieren Sie libgssapi-krb5-2 explizit, und entfernen Sie es nach der Treiberinstallation nicht automatisch.

Treiber 17 wurde als fehlend gemeldet, als du Version 18 installiert hast

Symptome:

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

In der Fehlermeldung wird Version 17 genannt, aber odbcinst -q -d zeigt Version 18 als registriert an und dpkg -l msodbcsql18 zeigt sie als installiert an.

Ursache: Version 18 ist registriert, lädt aber nicht, sodass mssql-django auf Version 17 zurückfällt, die nicht installiert ist. Der Fallback meldet den Treiber, den er als Zweites versucht hat, nicht den, der fehlgeschlagen ist.

Lösung: Installieren libgssapi-krb5-2 und neu aufbauen. Siehe die vorangehende Anmerkung zu „Autoremove“, wie es dazu kommt, dass die Bibliothek verschwindet.

Fehler beim Laden des pyodbc-Moduls in einem Container

Symptome:

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

Ursache: Das Image hat keine unixODBC-Laufzeit. mssql-django importiert pyodbc, wenn Django das Backend lädt, sodass dieser Fehler auch auf dem mssql-python-Pfad auftritt, bevor eine Verbindung versucht wird.

Lösung: Installieren unixodbc (oder unixodbc-dev).

mssql-python-treiber kann nicht geladen werden

Symptome:

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

Ursache: Der mit mssql-python gelieferte Treiber benötigt die Kerberos-Laufzeitbibliotheken, die in schlanken Basis-Images nicht enthalten sind.

Lösung: Installieren libkrb5-3 und libgssapi-krb5-2.

Pyodbc baut nicht auf schlanken Images auf

Symptome:

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

Oder:

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

Lösung: Installieren Sie die Build-Abhängigkeiten vor pip install:

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

Alternativ können Sie einen mehrstufigen Build verwenden, um das endgültige Image klein zu halten:

# 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 kann keine Verbindung mit SQL Server herstellen

Symptome:

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

Mögliche Ursachen und Lösungen:

• Docker Compose-Dienstname nicht als Host verwendet

  Wenn Sie Docker Compose verwenden, legen Sie DB_HOST den Dienstnamen fest (z. B db. ), nicht localhost oder 127.0.0.1.

• SQL Server Container nicht bereit

  Der SQL Server-Container benötigt mehrere Sekunden zum Starten. Zustandsprüfung oder Startverzögerung hinzufügen:

  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
  

• Portzuordnungskonflikte

  Wenn eine andere Instanz von SQL Server auf dem Host ausgeführt wird, ändern Sie den verfügbar gemachten Port (z. B1434:1433. ) und aktualisieren Sie die Django-Konfiguration entsprechend.

Azure SQL vorübergehende Fehlerwiederherstellung

Das mssql-django Back-End erkennt automatisch Azure SQL-Datenbank und Azure SQL Managed Instance Verbindungen durch AbfragenSERVERPROPERTY('EngineEdition'). Beim Betrieb mit Azure SQL versucht das Back-End bei vorübergehenden Fehlern (z. B. vorübergehenden Ressourcenbeschränkungen oder kurzzeitigen Netzwerkunterbrechungen) erneut, eine Verbindung herzustellen.

Sie können dieses Verhalten mit den OPTIONEN connection_retries und connection_retry_backoff_time anpassen:

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

Diese Einstellungen gelten nur für die anfängliche Verbindungseinrichtung. Das Backend versucht fehlgeschlagene Abfragen nicht erneut. Wenn eine Abfrage nach dem Herstellen der Verbindung mit einem vorübergehenden Fehler fehlschlägt, wird die Ausnahme an den Anwendungscode weitergegeben. Verwenden Sie die Wiederholungslogik auf Anwendungsebene (z. B. django-retry-db oder eine benutzerdefinierte Middleware) für die Resilienz auf Abfrageebene.

Langsame Abfragen und Planen von Regressionen

Diese Probleme erfordern in der Regel eine serverseitige Analyse sowie eine Überprüfung der Abfragen auf Django-Ebene.

Die Abfrage wird langsamer oder es kommt zu Zeitüberschreitungen.

Symptome:

Dieselbe Abfrage wird im Laufe der Zeit langsamer oder verursacht nach einer Bereitstellung, einer Indexänderung oder einer Aktualisierung von Statistiken Zeitüberschreitungen.

Mögliche Ursachen und Lösungen:

• Beginnen Mit integrierten Leistungsberichten

  Öffnen Sie für SQL Server und Azure SQL Managed Instance das Performance Dashboard in SQL Server Management Studio. Öffnen Sie für Azure SQL-Datenbank Abfrageleistungsanalyse für Azure SQL-Datenbank. Diese Werkzeuge sind in der Regel ein besserer erster Schritt als Ad-hoc-DMV-Abfragen, da sie teure Abfragen, Wartezeiten und Ressourcenengpässe schnell sichtbar machen.

• Planen der Regression

  Verwenden Sie Abfragespeicher, um die langsame Abfrage zu finden und zu überprüfen, ob sie über mehrere Pläne verfügt. Beginnen Sie mit den Ansichten "Regressed Queries" und "Top Resource Consuming Queries", die in bewährten Methoden für die Überwachung von Workloads mit Abfragespeicher beschrieben werden.

• Ineffizienter Ausführungsplan

  Öffnen Sie einen tatsächlichen Ausführungsplan für die Anweisung, und suchen Sie nach Tabellen- oder Indexüberprüfungen, großen Schlüsselsuchen, Hash-Überläufen oder ungenauen Zeilenschätzungen. Hintergrundinformationen finden Sie unter Übersicht über den Ausführungsplan.

• Falscher Engpass identifiziert

  Wenn die Abfrage nicht CPU-gebunden ist, verwenden Sie Abfragespeicher Wartestatistik, und identifizieren Sie Engpässe, um CPU, Arbeitsspeicher, Datenträger-E/A, Blockierung und Verbindungsdruck zu unterscheiden.

• Korrektur auf der falschen Ebene angewendet

  Wenden Sie den kleinsten effektiven Fix an: Indizes hinzufügen oder anpassen, Statistiken aktualisieren, ausgewählte Spalten und Zeilen reduzieren oder große Schreibvorgänge stapeln. Wenn Sie eine Sofortmaßnahme benötigen, kann ein DBA vorübergehend einen bekanntermaßen guten Plan im Abfragespeicher erzwingen, während Sie die Grundursache beheben.

Verwenden von dbshell für interaktive Abfragen

Der Verwaltungsbefehl von dbshell Django öffnet eine interaktive SQL-Shell, die mit Ihrer Datenbank verbunden ist:

python manage.py dbshell

Das Backend verwendet sqlcmd, wenn Sie den Microsoft ODBC-Treiber konfigurieren, oder isql, wenn Sie FreeTDS verwenden. Überprüfen Sie, ob das Tool in Ihrem PATH ist:

• Windows: sqlcmd ist in SQL Server Tools enthalten, oder Sie können sie separat herunterladen.
• Linux und macOS: Installieren mssql-tools18 sie aus dem Microsoft Repository.

Verwandte Inhalte

• mssql-django-Konfigurationsreferenz
• Verbindungsoptionen für mssql-django
• Wiederholungslogik und Verbindungsresilienz mit mssql-django
• Einschränkungen und nicht unterstützte Features in mssql-django
• Leistungsdashboard
• Abfrageleistungserblick für Azure SQL-Datenbank
• Überwachen Sie die Leistung mithilfe des Abfragespeichers
• Analysieren eines tatsächlichen Ausführungsplans
• Problembehandlung für Wiki
• Häufig gestellte Fragen