Rozwiązywanie problemów z instalacją i połączeniem z mssql-python

Użyj tego artykułu, aby zdiagnozować problemy z instalacją, połączeniem, kontenerem i ciągłą integracją (CI) sterownika mssql-python .

Problemy z instalacją

Instalacja pip kończy się niepowodzeniem lub pakiet jest kompilowany ze źródeł

Objawy:

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

Możliwe przyczyny i rozwiązania:

  • Brak gotowego koła na twoją platformę

    • Sprawdź, czy masz obsługiwaną wersję Python (wersje 3.10 i nowsze) i platformę. Zobacz cykl życia pomocy technicznej, aby sprawdzić macierz zgodności.
    • Ulepsz pip przed instalacją za pomocą .pip install --upgrade pip
    • W przypadku powtarzalnych środowisk zespołowych używaj zablokowanego przepływu pracy w Powtarzalnych wdrożeniach lub wzorców kontenerowych w Kontenerach i rozwoju lokalnym, aby ograniczyć rozbieżności konfiguracji między lokalnymi maszynami.

  • Środowisko wirtualne nieaktywowane

    • Najpierw aktywuj swoje środowisko wirtualne. Instalacja w systemowym Pythonie może powodować błędy uprawnień lub konflikty.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

Konfliktowe instalacje sterowników

Objawy:

Po zainstalowaniu mssql-python i pyodbc w tym samym środowisku występują błędy importu lub nieoczekiwane działanie.

Rozwiązanie:

mssql-python i pyodbc mogą współistnieć. Jeśli napotkasz konflikty, stwórz czyste środowisko wirtualne.

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

Problemy z połączeniem

Nie można połączyć się z serwerem

Objawy:

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

Możliwe przyczyny i rozwiązania:

  • Serwer niedostępny

    • Sprawdź, czy nazwa serwera i port są poprawne.
    • Sprawdź łączność sieciową za pomocą ping <server> lub telnet <server> 1433.
    • Upewnij się, że zapora sieciowa pozwala na połączenia wychodzące na porcie 1433.

  • SQL Server nie działa

    • Sprawdź, czy usługa SQL Server została uruchomiona.
    • Dla nazwanych instancji sprawdź, czy usługa SQL Server Browser jest uruchomiona.

  • Azure SQL firewall rules

    • Dodaj adres IP klienta do reguł zapory Azure SQL w portalu Azure.
    • W przypadku Azure SQL Managed Instance upewnij się, że łączysz się z dozwolonej sieci.

Testuj podstawową łączność TCP:

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

Logowanie nie powiodło się

Objawy:

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

Możliwe przyczyny i rozwiązania:

  • Niedopasowanie trybów uwierzytelniania

    • Dla Azure SQL Database, Azure SQL Managed Instance oraz SQL Database in Fabric preferują tryb Microsoft Entra, taki jak Authentication=ActiveDirectoryDefault.
    • Jeśli celowo używasz uwierzytelniania SQL, sprawdź, czy serwer na to pozwala i czy używasz właściwego formatu logowania dla tego punktu końcowego.

  • Nieprawidłowe dane uwierzytelniające SQL

    • Sprawdź identyfikator użytkownika i hasło.
    • Dla Azure SQL dołącz pełne ID użytkownika: <user_id>@<server>.

  • Użytkownik nie istnieje w bazie danych

    • Sprawdź, czy użytkownik ma dostęp do określonej bazy danych.
    • Sprawdź, czy logowanie jest przypisane do użytkownika bazy danych.

  • Uwierzytelnianie nie skonfigurowane

    • Używaj uwierzytelniania Microsoft Entra (zalecane): Authentication=ActiveDirectoryDefault.
    • Jeśli rozwiązujesz problem z lokalną instancją SQL Server, która powinna akceptować uwierzytelnianie SQL, sprawdź, czy SQL Server korzysta z uwierzytelniania w trybie mieszanym.

Przekroczenie limitu czasu połączenia

Objawy:

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

Możliwe przyczyny i rozwiązania:

  • Serwer reaguje wolno

    • Zwiększ czas oczekiwania połączenia.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Opóźnienie sieci

    • Sprawdź ścieżkę sieciową do serwera.
    • Rozważ krótszą ścieżkę sieciową lub wirtualną sieć prywatną (VPN).

  • Serwer pod dużym obciążeniem

    • Staraj się łączyć w godzinach poza szczytem.
    • Skontaktuj się z administratorem swojej bazy danych.

Błędy certyfikatu SSL

Objawy:

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

Rozwiązania:

Preferuj zaufany certyfikat lub wzorce programowania lokalnego opisane w sekcji Kontenery i programowanie lokalne. Używaj TrustServerCertificate=yes tylko do lokalnego rozwoju na serwerze, który kontrolujesz.

Do programowania i testowania z certyfikatem z podpisem własnym:

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 to wyłącznie lokalne rozwiązanie zapasowe. Nie przenoś go do wspólnych kontenerów deweloperskich, pipeline'ów CI ani wdrożeń produkcyjnych. Więcej informacji można znaleźć w artykule Szyfrowanie i certyfikaty.

Do produkcji zainstaluj odpowiednie certyfikaty i użyj:

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

Problemy z kontenerami i CI

Brakujące biblioteki systemowe na Linuksie

Objawy:

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

Rozwiązanie:

Zainstaluj wymagane pakiety systemowe dla swojej dystrybucji:

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

Przykłady Dockerfile można znaleźć w artykule Kontener i rozwój lokalny.

Błędy SSL w systemie macOS po instalacji

Objawy:

Podczas łączenia z systemu macOS, zwłaszcza na komputerach Mac z układami Apple silicon, występują błędy związane z SSL.

Rozwiązanie:

Zainstaluj OpenSSL z Homebrew i ustaw flagi linkera:

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

Treści powiązane

  • Last updated on