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

  • Verlängere die Verbindungszeit.

  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.

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:

ImportError: libltdl.so.7: cannot open shared object file: No such file or directory
ImportError: libkrb5.so.3: cannot open shared object file

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