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 pakietu wheel dla Twojej platformy

    • 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 nie zostało aktywowane

    • 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.
  • Reguły zapory Azure SQL

    • 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:

  • Niezgodność trybu 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 jest 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 sieciowe

    • 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.

Powolna finalizacja zakupu po przerwie w sieci

Jeśli wywołanie connect() utknie podczas ponownego użycia połączenia w puli, zaktualizuj sterownik i ustaw dodatni limit logowania:

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

Przy domyślnym msodbcsql18 dostawcy sterownik sprawdza połączenie w puli przed jego ponownym użyciem, a każde żądanie w tym sprawdzeniu używa tej wartości jako limitu czasu. Jeśli ustawisz SQL_ATTR_LOGIN_TIMEOUT w attrs_before, sterownik używa tej wartości zamiast tego. Jeśli limit logowania wynosi zero lub nie jest ustawiony, sterownik używa wartości 15 sekund.

Jeśli sprawdzenie się nie powiedzie, sterownik loguje się przy użyciu nowego połączenia, a to logowanie otrzymuje własny pełny limit czasu logowania. Sprawdzenie może wysłać więcej niż jedno żądanie, więc timeout=30 nie ogranicza całego wywołania do 30 sekund. Pozyskiwanie tokena Microsoft Entra ID nie liczy się do limitu czasu logowania. Jeśli serwer lub sieć pozostaje niedostępna, rozwiąż błąd połączenia za pomocą polityki ponawiania prób aplikacji.

Dostawca opt-in mssql-odbc stosuje ten sam limit czasu do każdego żądania podczas resetowania połączenia z puli. Gdy anuluje żądanie, czeka osobno na zakończenie anulowania, więc całkowite oczekiwanie może być dłuższe niż limit czasu. Aby uzyskać więcej informacji, zobacz Kontrole stanu połączenia, funkcje obsługiwane przez natywnego dostawcę oraz logikę ponowienia.

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 lokalna opcja awaryjna. 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:

Gdy brakuje libltdl lub bibliotek Kerberos, import mssql_python odnosi sukces, ale pierwsze connect() wywołanie podnosi 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.

W Alpine Linux, gdy brakuje libstdc++, import mssql_python kończy się niepowodzeniem:

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

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 libstdc++

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"