Telepítési és kapcsolati problémák keresése mssql-python használatával

Használja ezt a cikket a telepítési, csatlakozási, konténeri és folyamatos integrációs (CI) problémáinak diagnosztizálására az mssql-python illesztőprogramban.

Telepítési problémák

A pip telepítése meghibásodik vagy forrásból épít

Tünetek:

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

Lehetséges okok és megoldások:

  • Nincs előre összeszerelt kerék a platformodhoz

    • Ellenőrizd, hogy támogatott Python verziót (3.10 és újabb verziók) és platformot futtatsz. A kompatibilitási mátrixot lásd a támogatási életciklusnál.
    • Frissítsd a pipet a telepítés előtt a(z) pip install --upgrade pip paranccsal.
    • Az ismételhető csapatkörnyezetekhez használd a zárolt munkafolyamatot a Repeatable deployments részben, vagy a konténermintákat a Container and local development részben a helyi gépek közötti eltérések csökkentése érdekében.

  • Virtuális környezet nem aktiválva

    • Először aktiváld a virtuális környezetedet. A Python rendszerbe való telepítés jogosultsági hibákat vagy ütközéseket okozhat.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python
  • Hiányzó Linux rendszerkönyvtárak

Ellentmondó illesztőprogram-telepítések

Tünetek:

Importálási hibákat vagy váratlan működést tapasztalsz, miután ugyanabban a környezetben telepíted a pyodbc és mssql-python elemeket.

Solution:

mssql-python és pyodbc együtt létezhetnek. Ha konfliktusokkal találkozol, hozz létre egy tiszta, virtuális környezetet.

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

Kapcsolódási problémák

Nem tudok csatlakozni a szerverhez

Tünetek:

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

Lehetséges okok és megoldások:

  • A szerver nem elérhető

    • Ellenőrizd, hogy a szerver neve és a port helyes-e.
    • Ellenőrizd a hálózati kapcsolatot a(z) ping <server> vagy telnet <server> 1433 segítségével.
    • Győződj meg róla, hogy a tűzfal engedélyezi a kimenő kapcsolatokat a 1433-as porton.

  • SQL Server nem fut

    • Ellenőrizd, hogy az SQL Server szolgáltatás elindult-e.
    • Az elnevezett példányok esetén ellenőrizze, hogy fut-e az SQL Server Browser szolgáltatás.

  • Azure SQL firewall rules

    • Adja hozzá az ügyfél IP-címét az Azure SQL tűzfal szabályaihoz az Azure portálban.
    • Azure SQL Managed Instance esetén győződj meg róla, hogy engedélyezett hálózatról csatlakozzon.

Teszteld az alapvető TCP csatlakozást:

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

A bejelentkezés sikertelen

Tünetek:

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

Lehetséges okok és megoldások:

  • Hitelesítési mód eltérése

    • Azure SQL Database, Azure SQL Managed Instance és SQL database in Fabric esetén előnyben részesítsünk egy Microsoft Entra módot, például Authentication=ActiveDirectoryDefault.
    • Ha szándékosan használod az SQL hitelesítést, ellenőrizd, hogy a szerver engedélyezi-e, és hogy a megfelelő bejelentkezési formátumot használod az adott végponthoz.

  • Hibás SQL hitelesítési adatok

    • Ellenőrizd a felhasználói azonosítót és jelszót.
    • Azure SQL esetén add fel a teljes felhasználói azonosítót: <user_id>@<server>.

  • A felhasználó nem létezik az adatbázisban

    • Ellenőrizd, hogy a felhasználó hozzáfér a megadott adatbázishoz.
    • Ellenőrizze, hogy a bejelentkezés egy adatbázis-felhasználóhoz van leképezve.

  • Hitelesítés nem konfigurált

    • Használd a Microsoft Entra hitelesítést (ajánlott): Authentication=ActiveDirectoryDefault.
    • Ha egy helyi SQL Server példányt vizsgálsz, amely elfogadja az SQL hitelesítést, ellenőrizd, hogy az SQL Server vegyes módú hitelesítést használ-e.

Kapcsolati időkorlát

Tünetek:

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

Lehetséges okok és megoldások:

  • A szerver lassan válaszol

    • Növeld a kapcsolat időkorlátját.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Hálózati késés

    • Ellenőrizd a szerver hálózati útvonalát.
    • Gondoljunk egy rövidebb hálózati útvonalra vagy virtuális privát hálózatra (VPN).

  • Szerver nagy terhelés alatt

    • Próbálj meg nem csúcsidőben csatlakozni.
    • Vegye fel a kapcsolatot az adatbázis-adminisztrátorával.

SSL-tanúsítványhibák

Tünetek:

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

Megoldások:

Inkább megbízható tanúsítványt vagy a Container és helyi fejlesztési mintákat részesítse előnyben. TrustServerCertificate=yes Csak helyi fejlesztésre használd egy olyan szerver ellen, amit te irányítasz.

Önként aláírt tanúsítványsal történő fejlesztés és tesztelés:

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 csak helyi tartalékmegoldás. Ne vigye be megosztott fejlesztési konténerekbe, CI pipeline-okba vagy termelési telepítésekbe. További információért lásd: Titkosítás és tanúsítványok.

Gyártáshoz telepítse a megfelelő tanúsítványokat és használja a következőket:

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

Konténer- és CI problémák

Hiányzó rendszerkönyvtárak Linuxon

Tünetek:

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

Solution:

Telepítse a szükséges rendszercsomagokat a disztribúciójához:

Disztribúció Parancs telepítése
Ubuntu vagy Debian sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
Red Hat vagy Fedora sudo dnf install libtool-ltdl krb5-libs
Alpine apk add libltdl krb5-libs

Dockerfile példákért lásd: Container és helyi fejlesztés.

macOS SSL hibák telepítés után

Tünetek:

SSL hibákat tapasztalsz, amikor macOS-ről csatlakozol, különösen Apple szilícon esetén.

Solution:

Telepítsd az OpenSSL-t Homebrew-szel, és állítsd be a linker zászlókat:

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

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: