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.
  • Windows
  • Linux/macOS

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

• Librerie di sistema Linux mancanti
  • Il driver richiede diverse librerie di sistema su Linux. Vedi Dipendenze specifiche della piattaforma per i pacchetti da installare.

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

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

Checkout lento dopo un'interruzione della rete

Se una connect() chiamata si blocca mentre si riutilizza una connessione pooled, aggiorna il driver e imposta un timeout di login positivo:

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

Con il provider predefinito msodbcsql18, il driver usa quel valore come timeout temporaneo nativo per l'operazione di connessione durante la validazione del pool, poi tenta un login sostitutivo se la validazione fallisce. Un valore esplicito in attrs_before ha la precedenza. Se il timeout per il login è zero o non specificato, il timeout temporaneo è di 15 secondi.

La validazione può comportare più operazioni, la pulizia può aggiungere tempo e il login sostitutivo ha un proprio timeout. L'acquisizione del token Microsoft Entra ID non è limitata dal timeout di accesso. timeout=30 Non è una scadenza di 30 secondi per la convalida o l'intera chiamata. Se il server o la rete rimane indisponibile, gestisci l'errore di connessione con la policy di ritentativi della tua applicazione.

Il fornitore opt-in mssql-odbc non garantisce gli stessi limiti di validazione. Per ulteriori informazioni, vedi Controlli di salute della connessione, limitazioni dei provider nativi e logica di retry.

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
)

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:

Quando libltdl o le librerie di Kerberos sono mancanti, import mssql_python ha successo, ma la prima connect() chiamata solleva 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.

Su Alpine Linux, quando libstdc++ manca, import mssql_python fallisce:

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

Soluzione:

Installa i pacchetti di sistema richiesti per la tua distribuzione:

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

• Installa il driver mssql-python
• Stringhe di connessione per mssql-python
• Gestire le connessioni con mssql-python
• Crittografia e convalida di certificati
• Container e sviluppo locale
• Risoluzione dei problemi mssql-python