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.
  • Windows
  • Linux/macOS

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

• Ontbrekende Linux-systeembibliotheken
  • De driver vereist verschillende systeembibliotheken op Linux. Zie Platform-specifieke afhankelijkheden voor de pakketten die geïnstalleerd moeten worden.

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

python -m venv .venv --clear
source .venv/bin/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.

Trage checkout na een netwerkonderbreking

Als een connect() oproep vastloopt tijdens het hergebruiken van een gepoolde verbinding, upgrade dan de driver en stel een positieve logintimeout in:

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

Bij de standaardprovider msodbcsql18 gebruikt de driver die waarde als tijdelijke native verbindingsoperatie-timeout tijdens pooled validation, en probeert vervolgens een vervangende login als validatie mislukt. Een expliciet SQL_ATTR_LOGIN_TIMEOUT in attrs_before heeft voorrang. Als de inlogtijd nul of niet gespecificeerd is, is de tijdelijke timeout 15 seconden.

Validatie kan meerdere bewerkingen omvatten, opruimen kan tijd toevoegen en de vervangende login heeft zijn eigen time-out. Het verkrijgen van Microsoft Entra ID-tokens wordt niet beperkt door de inlogtime-out. timeout=30 is geen limiet van 30 seconden voor validatie of het hele gesprek. Als de server of het netwerk niet beschikbaar blijft, verwerk de verbindingsfout dan volgens het retrybeleid van je applicatie.

De opt-in mssql-odbc provider garandeert niet dezelfde validatiegrenzen. Voor meer informatie, zie statuscontroles van verbindingen, beperkingen van de native provider en Retry-logica.

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
)

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:

Wanneer libltdl of de Kerberos-bibliotheken ontbreken, import mssql_python slaagt erin, maar de eerste connect() oproep roept OperationalError:

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.

Op Alpine Linux, wanneer libstdc++ ontbreekt, faalt import mssql_python:

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

Solution:

Installeer de benodigde systeempakketten voor je distributie:

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

• Installeer de mssql-python driver
• Verbindingsstrings voor mssql-python
• Beheer verbindingen met mssql-python
• Versleuteling en certificaatvalidatie
• Container en lokale ontwikkeling
• Problemen oplossen met mssql-python