Probleemoplossing voor installatie- en verbindingsproblemen met mssql-python

Gebruik dit artikel om problemen met installatie, verbinding, container en continue integratie (CI) met de mssql-python driver te diagnosticeren.

Installatieproblemen

pip-installatie mislukt of compileert vanaf broncode

Symptomen:

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

Mogelijke oorzaken en oplossingen:

  • Geen kant-en-klaar wiel voor je platform

    • Controleer of je een ondersteunde Python-versie (3.10 en latere versies) en platform draait. Zie Support-levenscyclus voor de compatibiliteitsmatrix.
    • Werk pip vóór de installatie bij met pip install --upgrade pip.
    • Voor herhaalbare teamomgevingen gebruik je de vergrendelde workflow in herhaalbare implementaties of de containerpatronen in container- en lokale ontwikkeling om lokale machinedrift te verminderen.

  • Virtuele omgeving niet geactiveerd

    • Activeer eerst je virtuele omgeving. Installatie in het systeem Python kan permissiefouten of conflicten veroorzaken.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • Ontbrekende Linux-systeembibliotheken

Conflicterende stuurprogramma-installaties

Symptomen:

Je komt importfouten of onverwacht gedrag tegen na de installatie mssql-python en pyodbc in dezelfde omgeving.

Solution:

mssql-python en pyodbc kunnen naast elkaar bestaan. Als je conflicten tegenkomt, creëer dan een schone virtuele omgeving.

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

Verbindingsproblemen

Kan geen verbinding maken met de server

Symptomen:

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

Mogelijke oorzaken en oplossingen:

  • Server niet bereikbaar

    • Controleer of de servernaam en poort correct zijn.
    • Controleer de netwerkconnectiviteit met ping <server> of telnet <server> 1433.
    • Zorg ervoor dat de firewall uitgaande verbindingen op poort 1433 toestaat.

  • SQL Server draait niet

    • Controleer of de SQL Server-service is gestart.
    • Controleer voor benoemde instanties of de SQL Server Browser-service draait.

  • Azure SQL firewall rules

    • Voeg je client IP-adres toe aan de Azure SQL firewallregels in het Azure portal.
    • Voor Azure SQL Managed Instance moet je ervoor zorgen dat je verbinding maakt vanaf een toegestan netwerk.

Test de eenvoudige TCP-connectiviteit:

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

Aanmelden is mislukt

Symptomen:

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

Mogelijke oorzaken en oplossingen:

  • Niet-overeenkomende verificatiemodus

    • Gebruik voor Azure SQL Database, Azure SQL Managed Instance en SQL database in Fabric bij voorkeur een Microsoft Entra-modus zoals Authentication=ActiveDirectoryDefault.
    • Als je opzettelijk SQL-authenticatie gebruikt, controleer dan of de server het toestaat en dat je het juiste inlogformaat voor dat endpoint gebruikt.

  • Onjuiste SQL-authenticatiegegevens

    • Controleer het gebruikers-ID en wachtwoord.
    • Voor Azure SQL, voeg de volledige gebruikers-ID toe: <user_id>@<server>.

  • Gebruiker bestaat niet in de database

    • Controleer of de gebruiker toegang heeft tot de opgegeven database.
    • Controleer of het aanmelden is gekoppeld aan een databasegebruiker.

  • Authenticatie niet geconfigureerd

    • Gebruik Microsoft Entra-authenticatie (aanbevolen): Authentication=ActiveDirectoryDefault.
    • Als je een lokale SQL Server-instantie oplost die SQL-authenticatie zou moeten accepteren, controleer dan of SQL Server gemixte modus authenticatie gebruikt.

Verbindingstijdoverschrijding

Symptomen:

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

Mogelijke oorzaken en oplossingen:

  • De server reageert traag

    • Verhoog de verbindingstimeout.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Netwerklatentie

    • Controleer het netwerkpad naar de server.
    • Overweeg een korter netwerkpad of een virtueel privénetwerk (VPN).

  • Server onder zware belasting

    • Probeer contact te maken tijdens de laagste uren.
    • Neem contact op met je databasebeheerder.

SSL-certificaatfouten

Symptomen:

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

Oplossingen:

Geef de voorkeur aan een vertrouwd certificaat of de lokale ontwikkelingspatronen in Container en lokale ontwikkeling. Gebruik TrustServerCertificate=yes alleen voor lokale ontwikkeling tegen een server die jij beheert.

Voor ontwikkeling en testen met een zelfondertekend certificaat:

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

Caution

TrustServerCertificate=yes is uitsluitend een lokale terugvaloptie. Neem het niet op in gedeelde ontwikkelcontainers, CI-pijplijnen of productie-implementaties. Voor meer informatie, zie Versleuteling en certificaten.

Voor productie installeer je de juiste certificaten en gebruik:

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

Container- en CI-problemen

Ontbrekende systeembibliotheken op Linux

Symptomen:

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

Solution:

Installeer de benodigde systeempakketten voor je distributie:

Distribution Opdracht Installeren
Ubuntu of Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat of Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Voor voorbeelden van Dockerfile, zie Container en lokale ontwikkeling.

macOS SSL-fouten na installatie

Symptomen:

Je komt SSL-gerelateerde fouten tegen wanneer je verbinding maakt vanaf macOS, vooral op Apple Silicon.

Solution:

Installeer OpenSSL met Homebrew en stel de linkervlaggen in:

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

Verwante onderwerpen

  • Last updated on