Felsök installations- och anslutningsproblem med mssql-python

Använd denna artikel för att diagnostisera problem med installation, anslutning, container och kontinuerlig integration (CI) med drivrutinen mssql-python .

Installationsproblem

Pip-installationen misslyckas eller byggs från källkoden

Symtom:

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

Möjliga orsaker och lösningar:

  • Ingen förbyggd wheel för din plattform

  • Virtuell miljö aktiverad ej

    • Aktivera din virtuella miljö först. Installation i systemets Python kan orsaka behörighetsfel eller konflikter.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • Saknade Linux-systembibliotek

Motstridiga installationer av drivrutiner

Symtom:

Du stöter på importfel eller oväntat beteende efter installationen mssql-python och pyodbc i samma miljö.

Solution:

mssql-python och pyodbc kan samexistera. Om du stöter på konflikter, skapa en ren virtuell miljö.

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

Anslutningsproblem

Kan inte ansluta till servern

Symtom:

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

Möjliga orsaker och lösningar:

  • Server är inte tillgänglig

    • Kontrollera att servernamnet och porten är korrekta.
    • Kontrollera nätverksanslutningen med ping <server> eller telnet <server> 1433.
    • Se till att brandväggen tillåter utgående anslutningar på port 1433.

  • SQL Server körs inte

    • Verifiera att SQL Server-tjänsten är startad.
    • För namngivna instanser, kontrollera att SQL Server Browser-tjänsten körs.

  • Azure SQL firewall rules

    • Lägg till din klients IP-adress i Azure SQL-brandväggsreglerna i Azure-portalen.
    • För Azure SQL Managed Instance, se till att du ansluter från ett tillåtet nätverk.

Testa grundläggande TCP-anslutning:

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

Inloggningen misslyckades

Symtom:

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

Möjliga orsaker och lösningar:

  • Missanpassning i autentiseringsläge

    • För Azure SQL Database, Azure SQL Managed Instance och SQL database in Fabric, föredra ett Microsoft Entra-läge såsom Authentication=ActiveDirectoryDefault.
    • Om du använder SQL-autentisering medvetet, kontrollera att servern tillåter det och att du använder rätt inloggningsformat för den endpointen.

  • Felaktiga SQL-autentiseringsuppgifter

    • Verifiera användar-ID och lösenord.
    • För Azure SQL, inkludera hela användar-ID:t: <user_id>@<server>.

  • Användaren finns inte i databasen

    • Verifiera att användaren har tillgång till den angivna databasen.
    • Kontrollera om inloggningen är mappad till en databasanvändare.

  • Autentisering ej konfigurerad

    • Använd Microsoft Entra-autentisering (rekommenderas): Authentication=ActiveDirectoryDefault.
    • Om du felsöker en lokal SQL Server-instans som borde acceptera SQL-autentisering, kontrollera att SQL Server använder mixed mode-autentisering.

Tidsgräns för anslutning

Symtom:

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

Möjliga orsaker och lösningar:

  • Servern är långsam att svara

    • Öka timeoutvärdet för anslutningen.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Nätverksfördröjning

    • Kolla nätverksvägen till servern.
    • Överväg en kortare nätverksväg eller ett virtuellt privat nätverk (VPN).

  • Server under hög belastning

    • Försök att ansluta utanför rusningstid.
    • Kontakta din databasadministratör.

Långsam utcheckning efter ett nätverksavbrott

Om ett connect() anrop stannar när du återanvänder en poolad anslutning, uppgradera drivrutinen och sätt en positiv inloggningstimeout:

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

Med standardprovidern msodbcsql18 använder drivrutinen det värdet som en tillfällig timeout för nativ anslutningsoperation under poolvalidering, och försöker sedan en ersättningsinloggning om valideringen misslyckas. En explicit SQL_ATTR_LOGIN_TIMEOUT in attrs_before går före. Om timeout för inloggning är noll eller ospecificerad är den tillfälliga timeouten 15 sekunder.

Validering kan involvera flera operationer, rensning kan lägga till tid, och ersättningsinloggningen har sin egen tidsgräns. Microsoft Entra ID-hämtning av token är inte begränsad av tidsgränsen för inloggning. timeout=30 Det är inte en 30-sekunders deadline för validering eller hela samtalet. Om servern eller nätverket fortfarande är otillgängligt, hantera anslutningsfelet med din applikations återförsökspolicy.

Leverantören för opt-in mssql-odbc garanterar inte samma valideringsgränser. För mer information, se Anslutningshälsokontroller, Native-leverantörsbegränsningar och Återförsökslogik.

SSL-certifikatfel

Symtom:

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

Lösningar:

Föredra ett betrodd certifikat eller lokala utvecklingsmönster i Container och lokal utveckling. Använd TrustServerCertificate=yes endast för lokal utveckling mot en server som du kontrollerar.

För utveckling och testning med ett självsignerat certifikat:

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 är en endast lokal reservlösning. Ta inte med det in i delade utvecklingscontainrar, CI-pipelines eller produktionsdistributioner. För mer information, se Kryptering och certifikat.

För produktion, installera lämpliga certifikat och använd:

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

Container- och CI-problem

Saknade systembibliotek på Linux

Symtom:

När libltdl eller Kerberos-biblioteken saknas lyckas import mssql_python, men det första connect()-anropet väcker 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.

På Alpine Linux, när libstdc++ saknas, import mssql_python misslyckas:

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

Solution:

Installera de nödvändiga systempaketen för din distribution:

Distribution Installationskommando
Ubuntu eller Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat eller Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs libstdc++

För exempel på Dockerfile, se Container och lokal utveckling.

macOS SSL-fel efter installation

Symtom:

Du stöter på SSL-relaterade fel när du ansluter från macOS, särskilt på Apple Silicon.

Solution:

Installera OpenSSL med Homebrew och ställ in länkflaggorna:

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

Relaterat innehåll

  • Uppdaterades senast