Fehlerbehebung von Installations- und Verbindungsproblemen mit mssql-python

Nutzen Sie diesen Artikel, um Probleme mit Installation, Verbindung, Container und kontinuierlicher Integration (CI) mit dem mssql-python Treiber zu diagnostizieren.

Installationsprobleme

pip install schlägt fehl oder erstellt aus dem Quellcode

Symptome:

error: Microsoft Visual C++ 14.0 or greater is required
ERROR: Failed building wheel for mssql-python

Mögliche Ursachen und Lösungen:

• Kein vorgefertigtes Lenkrad für deine Plattform

  • Prüfe, ob du eine unterstützte Python-Version (3.10 und spätere Versionen) und eine Plattform benutzt. Siehe Support-Lebenszyklus für die Kompatibilitätsmatrix.
  • Aktualisieren Sie pip vor der Installation mit pip install --upgrade pip.
  • Für reproduzierbare Teamumgebungen verwenden Sie den fixierten Workflow in Wiederholbare Deployments oder die Containermuster in Containern und lokaler Entwicklung, um Abweichungen zwischen lokalen Rechnern zu reduzieren.

• Virtuelle Umgebung nicht aktiviert

  • Aktiviere zuerst deine virtuelle Umgebung. Die Installation von Python im System kann zu Berechtigungsfehlern oder -konflikten führen.
  • Windows
  • Linux/macOS

  python -m venv .venv
  .venv\Scripts\activate
  pip install mssql-python
  

• Fehlende Linux-Systembibliotheken
  • Der Treiber benötigt mehrere Systembibliotheken unter Linux. Siehe Plattformspezifische Abhängigkeiten für die zu installierenden Pakete.

Widersprüchliche Treiberinstallationen

Symptome:

Nach der Installation von mssql-python und pyodbc in derselben Umgebung treten Importfehler oder unerwartetes Verhalten auf.

Solution:

mssql-python und pyodbc koexistieren können. Wenn Sie auf Konflikte stoßen, schaffen Sie eine saubere virtuelle Umgebung.

python -m venv .venv --clear
.venv\Scripts\activate
pip install mssql-python

python -m venv .venv --clear
source .venv/bin/activate
pip install mssql-python

Verbindungsprobleme

Keine Verbindung zum Server möglich

Symptome:

OperationalError: [08001] (0) Client unable to establish connection

Mögliche Ursachen und Lösungen:

• Server nicht erreichbar

  • Überprüfen Sie, ob Servername und Port korrekt sind.
  • Überprüfe die Netzwerkverbindung mit ping <server> oder telnet <server> 1433.
  • Stellen Sie sicher, dass die Firewall ausgehende Verbindungen am Port 1433 zulässt.

• SQL Server läuft nicht

  • Überprüfen Sie, ob der SQL Server-Dienst gestartet ist.
  • Für benannte Instanzen überprüfen Sie, ob der SQL Server Browser-Dienst läuft.

• Azure SQL firewall rules

  • Füge deine Client-IP-Adresse den Azure SQL-Firewall-Regeln im Azure-Portal hinzu.
  • Für die Azure SQL Managed Instance stellen Sie sicher, dass Sie sich über ein erlaubtes Netzwerk verbinden.

Testen Sie die grundlegende TCP-Konnektivität:

import socket

try:
    sock = socket.create_connection(("<server>.database.windows.net", 1433), timeout=5)
    print("TCP connection successful")
    sock.close()
except Exception as e:
    print(f"Cannot reach server: {e}")

Fehler bei der Anmeldung

Symptome:

OperationalError: [28000] (18456) Login failed for user '<user_id>'.

Mögliche Ursachen und Lösungen:

• Authentifizierungsmodus-Fehlanpassung

  • Für Azure SQL-Datenbank, Azure SQL Managed Instance und SQL Database in Fabric bevorzugen Sie einen Microsoft Entra-Modus wie Authentication=ActiveDirectoryDefault.
  • Wenn du absichtlich SQL-Authentifizierung verwendest, prüfe, ob der Server sie erlaubt und dass du das korrekte Anmeldeformat für diesen Endpunkt verwendest.

• Falsche SQL-Authentifizierungsdaten

  • Überprüfen Sie Benutzer-ID und Passwort.
  • Für Azure SQL geben Sie die vollständige Benutzer-ID an: <user_id>@<server>.

• User existiert nicht in der Datenbank

  • Überprüfen Sie, dass der Benutzer Zugriff auf die angegebene Datenbank hat.
  • Prüfen Sie, ob die Anmeldung einem Datenbankbenutzer zugeordnet ist.

• Authentifizierung nicht konfiguriert

  • Verwenden Sie Microsoft Entra-Authentifizierung (empfohlen): Authentication=ActiveDirectoryDefault.
  • Wenn du Fehler bei einer lokalen SQL Server-Instanz behebst, die SQL-Authentifizierung akzeptieren sollte, vergewissere dich, dass SQL Server den gemischten Authentifizierungsmodus verwendet.

Verbindungstimeout

Symptome:

OperationalError: [HYT00] (0) Timeout expired
OperationalError: [HYT01] (0) Connection timeout expired

Mögliche Ursachen und Lösungen:

• Der Server reagiert langsam

  • Erhöhen Sie das Verbindungstimeout.

  conn = mssql_python.connect(connection_string, timeout=60)
  

• Netzwerklatenz

  • Überprüfe den Netzwerkpfad zum Server.
  • Betrachten Sie einen kürzeren Netzwerkpfad oder ein virtuelles privates Netzwerk (VPN).

• Server unter hoher Last

  • Versuche, dich außerhalb der Hauptverkehrszeiten zu verbinden.
  • Kontaktieren Sie Ihren Datenbankadministrator.

Langsamer Checkout nach einer Netzwerkunterbrechung

Wenn ein connect()-Aufruf beim Wiederverwenden einer Pool-Verbindung stockt, aktualisieren Sie den Treiber und setzen Sie eine positive Login-Zeitpause:

conn = mssql_python.connect(connection_string, timeout=30)

Mit dem Standardprovider msodbcsql18 verwendet der Treiber diesen Wert als temporären nativen Timeout für Verbindungsvorgänge während der Pool-Validierung und versucht dann, bei fehlschlagender Validierung eine erneute Anmeldung durchzuführen. Ein explizites SQL_ATTR_LOGIN_TIMEOUT In attrs_before hat Vorrang. Wenn der Login-Timeout null oder nicht angegeben ist, beträgt der temporäre Timeout 15 Sekunden.

Die Validierung kann mehrere Operationen umfassen, die Bereinigung kann mehr Zeit in Anspruch nehmen, und der alternative Login hat sein eigenes Timeout. Die Erwerbung des Microsoft Entra ID-Tokens ist nicht durch den Login-Timeout begrenzt. timeout=30 ist keine 30-Sekunden-Frist für die Validierung oder den gesamten Anruf. Wenn der Server oder das Netzwerk weiterhin nicht verfügbar ist, behandle den Verbindungsfehler mit der Retry-Policy deiner Anwendung.

Der Opt-in-Anbieter mssql-odbc garantiert nicht dieselben Validierungsgrenzwerte. Weitere Informationen finden Sie unter Verbindungsintegritätsprüfungen, Einschränkungen des nativen Providers und Logik für Wiederholungen.

SSL-Zertifikatfehler

Symptome:

OperationalError: [08001] SSL Provider: The certificate chain was issued by an authority that is not trusted

Lösungen :

Verwenden Sie vorzugsweise ein vertrauenswürdiges Zertifikat oder die lokalen Entwicklungsmethoden in Container und lokale Entwicklung. Verwenden Sie TrustServerCertificate=yes es nur für lokale Entwicklung gegen einen Server, den Sie steuern.

Für Entwicklung und Tests mit einem selbstsignierten Zertifikat:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "TrustServerCertificate=yes;"  # Don't use in production
)

Für die Produktion installieren Sie die entsprechenden Zertifikate und verwenden:

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
    "HostnameInCertificate=<server>.domain.com;"
)

Container- und CI-Probleme

Fehlende Systembibliotheken unter Linux

Symptome:

Wenn libltdl oder die Kerberos-Bibliotheken fehlen, gelingt import mssql_python, aber der erste connect()-Aufruf löst OperationalError aus:

OperationalError: Driver Error: Connection operation failed; DDBC Error: Failed to load the driver. Please read the documentation (https://github.com/microsoft/mssql-python#installation) to install the required dependencies.

Wenn libstdc++ fehlt, schlägt import mssql_python auf Alpine Linux fehl:

ImportError: Error loading shared library libstdc++.so.6: No such file or directory

Solution:

Installieren Sie die erforderlichen Systempakete für Ihre Distribution:

Für Dockerfile-Beispiele siehe Container und lokale Entwicklung.

macOS SSL-Fehler nach der Installation

Symptome:

Man stößt auf SSL-bezogene Fehler, wenn man sich von macOS verbindet, besonders auf Apple Silicon.

Solution:

Installiere OpenSSL mit Homebrew und setze die Linker-Flags:

brew install openssl
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Verwandte Inhalte

• Installiere den mssql-python-Treiber
• Verbindungsstrings für mssql-python
• Verwalte Verbindungen mit mssql-python
• Verschlüsselung und Zertifikatüberprüfung
• Container und lokale Entwicklung
• Fehlerbehebung mssql-python