Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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:
Nessuna wheel precompilata 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
-
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
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>otelnet <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.
Regole firewall Azure SQL
- 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:
Mancata corrispondenza 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.
- Per database SQL di Azure, Istanza gestita di SQL di Azure e SQL database in Fabric, preferisci una modalità Microsoft Entra come
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.
- Usa l'autenticazione Microsoft Entra (consigliata):
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 controlla una connessione poolata prima di riutilizzarla, e ogni richiesta in quella verifica utilizza questo valore come timeout. Se si imposta SQL_ATTR_LOGIN_TIMEOUT in attrs_before, il driver utilizza invece quel valore. Se il timeout di accesso è zero o non è impostato, il driver utilizza 15 secondi.
Se il controllo fallisce, il driver effettua il login con una nuova connessione e quel login riceve un proprio timeout completo per il login. Il controllo può inviare più di una richiesta, quindi timeout=30 non limita l'intera chiamata a 30 secondi. L'acquisizione del token Microsoft Entra ID non viene conteggiata ai fini del timeout di accesso. Se il server o la rete restano non disponibili, gestisci l'errore di connessione con la policy di ritentativo della tua applicazione.
Il provider opt-in mssql-odbc applica lo stesso timeout a ogni richiesta quando resetta una connessione pooled. Quando cancella una richiesta, attende separatamente che la cancellazione finisca, quindi l'attesa totale può essere più lunga del timeout. Per ulteriori informazioni, consulta Controlli dello stato della connessione, Funzionalità supportate dal provider nativo e Logica di ritentativo.
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 è un fallback 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:
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:
| 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 libstdc++ |
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"