Risoluzione problemi di installazione e connessione con mssql-python

Usa questo articolo per diagnosticare problemi di installazione, connessione, container e integrazione continua (CI) con il mssql-python driver.

Problemi di installazione

Fallimento dell'installazione di PIP o compilazione dal sorgente

Sintomi:

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

Possibili cause e soluzioni:

  • Nessun volante preassemblato per la tua piattaforma

    • Controlla di avere una versione Python supportata (versioni 3.10 e successive) e una piattaforma. Vedi ciclo di vita del supporto per la matrice di compatibilità.
    • Aggiorna il pip prima dell'installazione con pip install --upgrade pip.
    • Per ambienti di team ripetibili, usa il flusso di lavoro bloccato nelle implementazioni ripetibili o i pattern container nel container e nello sviluppo locale per ridurre il drift locale della macchina.

  • Ambiente virtuale non attivato

    • Attiva prima il tuo ambiente virtuale. L'installazione di Python nel sistema può causare errori o conflitti di autorizzazione.
    python -m venv .venv
.venv\Scripts\activate
pip install mssql-python

Installazioni di driver in conflitto

Sintomi:

Dopo l'installazione mssql-python e pyodbc nello stesso ambiente incontri errori di importazione o comportamenti inaspettati.

Soluzione:

mssql-python e pyodbc possono coesistere. Se incontri conflitti, crea un ambiente virtuale pulito.

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

Problemi di connessione

Impossibile connettersi al server

Sintomi:

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

Possibili cause e soluzioni:

  • Server non raggiungibile

    • Verifica che il nome del server e la porta siano corretti.
    • Controlla la connettività di rete con ping <server> o telnet <server> 1433.
    • Assicurati che il firewall consenta connessioni in uscita sulla porta 1433.

  • SQL Server non in esecuzione

    • Verifica che il servizio SQL Server sia stato avviato.
    • Per le istanze nominate, verifica che il servizio SQL Server Browser sia in esecuzione.

  • Azure SQL firewall rules

    • Aggiungi il tuo indirizzo IP client alle regole del firewall Azure SQL nel portale Azure.
    • Per Istanza gestita di SQL di Azure, assicurati di connetterti da una rete consentita.

Testare la connettività TCP di base:

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

Accesso non riuscito

Sintomi:

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

Possibili cause e soluzioni:

  • Disallineamento della modalità di autenticazione

    • Per database SQL di Azure, Istanza gestita di SQL di Azure e SQL database in Fabric, preferisci una modalità Microsoft Entra come Authentication=ActiveDirectoryDefault.
    • Se usi l'autenticazione SQL intenzionalmente, verifica che il server lo consenta e che tu utilizzi il formato di login corretto per quell'endpoint.

  • Credenziali di autenticazione SQL errate

    • Verifica l'ID utente e la password.
    • Per Azure SQL, includere l'ID utente completo: <user_id>@<server>.

  • L'utente non esiste nel database

    • Verifica che l'utente abbia accesso al database specificato.
    • Controlla se l'accesso è mappato a un utente del database.

  • Autenticazione non configurata

    • Usa l'autenticazione Microsoft Entra (consigliata): Authentication=ActiveDirectoryDefault.
    • Se stai risolvendo i problemi di un'istanza locale di SQL Server che dovrebbe accettare l'autenticazione SQL, verifica che SQL Server utilizzi l'autenticazione in modalità mista.

Timeout della connessione

Sintomi:

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

Possibili cause e soluzioni:

  • Il server risponde lentamente

    • Aumenta il timeout della connessione.
    conn = mssql_python.connect(connection_string, timeout=60)

  • Latenza di rete

    • Controlla il percorso di rete verso il server.
    • Considera un percorso di rete più breve o una rete privata virtuale (VPN).

  • Server sotto carico elevato

    • Cerca di connetterti durante le ore di punta basse.
    • Contatta l'amministratore del tuo database.

Errori del certificato SSL

Sintomi:

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

Soluzioni:

Preferire un certificato attendibile o gli schemi di sviluppo locale in Container e sviluppo locale. Usalo TrustServerCertificate=yes solo per lo sviluppo locale su un server che controlli.

Per sviluppo e test con certificato autofirmato:

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 è una soluzione di riserva solo locale. Non portarla in container di sviluppo condivisi, pipeline CI o implementazioni in produzione. Per maggiori informazioni, vedi Crittografia e certificati.

Per la produzione, installare i certificati appropriati e utilizzare:

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

Problemi di container e CI

Librerie di sistema mancanti su Linux

Sintomi:

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

Soluzione:

Installa i pacchetti di sistema richiesti per la tua distribuzione:

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

Per esempi di Dockerfile, vedi Container e sviluppo locale.

Errori SSL di macOS dopo l'installazione

Sintomi:

Incontri errori legati alla SSL quando ti connetti da macOS, specialmente su Apple silicon.

Soluzione:

Installa OpenSSL con Homebrew e imposta i flag del linker:

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

Contenuti correlati

  • Last updated on