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

  • Kontrollera att du kör en stödd Python-version (3.10 och senare versioner) och plattform. Se Supportlivscykel för kompatibilitetsmatrisen .
  • Uppgradera pip före installation med pip install --upgrade pip.
  • För repeterbara teammiljöer, använd det låsta arbetsflödet i Repeatable deployments eller container-mönstren i Container- och lokal utveckling för att minska lokal maskindrift.

• Virtuell miljö aktiverad ej

  • Aktivera din virtuella miljö först. Installation i systemets Python kan orsaka behörighetsfel eller konflikter.
  • Windows
  • Linux/macOS

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

• Saknade Linux-systembibliotek
  • Drivrutinen kräver flera systembibliotek på Linux. Se Plattformsspecifika beroenden för vilka paket som ska installeras.

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

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

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
)

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:

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

Solution:

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

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

• Installera mssql-python-drivrutinen
• Anslutningssträngar för mssql-python
• Hantera anslutningar med mssql-python
• Kryptering och certifikatvalidering
• Containrar och lokal utveckling
• Felsökning mssql-python