Usa il driver mssql-odbc (Anteprima)

mssql-python carica uno dei due fornitori ODBC nativi:

Provider Description Stato
msodbcsql18 Microsoft ODBC Driver 18+ per SQL Server Impostazione predefinita
mssql-odbc Driver ODBC basato su Rust Anteprima, opt-in

Il mssql-python-rs pacchetto 0.4.0 include il mssql-odbc provider.

Note

Da usare msodbcsql18 per carichi di lavoro in produzione. Prima di aderire al provider in anteprima mssql-odbc, controlla i problemi noti.

Availability

Il driver viene fornito all'interno del pacchetto mssql-python-rs come wheel precompilate per CPython 3.10 e versioni successive:

Platform Architectures
Windows x64; ARM64 su CPython 3.11 e versioni successive
macOS universal2 (x86_64 e arm64), macOS 15 e versioni successive
Linux (glibc) x86_64 e aarch64 (manylinux_2_28 e manylinux_2_34)
Linux (musl) x86_64 e aarch64 (musllinux_1_2)

Abilitare il driver

Installando mssql-python si installa mssql-python-rsanche , che contiene il mssql-odbc driver:

python -m pip install mssql-python

Se installi con --no-deps o da un indice privato, installa mssql-python-rs anche esplicitamente.

Seleziona il provider prima di aprire la prima connessione. Utilizzare uno dei metodi seguenti.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Imposta la MSSQL_CONNECTION_STRING variabile ambiente sulla stringa di connessione della tua applicazione. Mantieni attivata la validazione dei certificati (Encrypt=yes;TrustServerCertificate=no). Per ulteriori informazioni, vedi Stringhe di connessione e Crittografia e certificati.

Esegui questo esempio con il fornitore che hai scelto:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

L'esempio stampa 1.

La selezione del fornitore segue queste regole:

  • MSSQL_PYTHON_NATIVE_PROVIDER ha la precedenza rispetto a native_provider. Impostando l'attributo a un fornitore in conflitto si ottiene RuntimeWarning.
  • Prima che il driver si carichi, imposta native_provider su None per cancellare l'impostazione di Python. Questo non elimina la variabile ambientale.
  • Un nome di fornitore non riconosciuto genera ValueError. Assegnare un nome non valido a native_provider genera immediatamente un errore; una variabile di ambiente non valida genera un errore quando ti connetti. Il driver non ripiega sul provider predefinito.
  • Il provider viene impostato quando il driver inizia un tentativo di connessione nativa, anche se quel tentativo fallisce. Riavvia Python per cambiare provider. Passare da native_provider a un altro provider genera RuntimeWarning e non ha effetto.

Errori di validazione delle stringhe di connessione e pacchetti provider mancanti si verificano prima di questo punto. Puoi correggere questi errori e scegliere un altro fornitore senza dover riavviare il processo.

Chiama mssql_python.get_native_provider_info() per verificare il nome del fornitore, come è stato selezionato e se la selezione è fissa.

Per tornare a msodbcsql18, rimuovi MSSQL_PYTHON_NATIVE_PROVIDER e qualsiasi assegnazione di native_provider dalla tua applicazione, allora riavvia Python.

Impostazioni predefinite del failover multi-subnet

Il provider Rust abilita MultiSubnetFailover di default per le connessioni applicabili al Transmission Control Protocol (TCP). Imposta MultiSubnetFailover=no esplicitamente per richiedere tentativi di connessione sequenziali. Per modificare il default a livello di distribuzione, impostare MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT su true o false prima che il driver nativo venga utilizzato per la prima volta. La parola chiave connection-string sovrascrive questo valore predefinito.

L'attributo numerico SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) sovrascrive anche la parola chiave quando impostato prima di connettersi.

Il driver non abilita questo predefinito per i trasporti non TCP, il mirroring del database, le istanze nominate che richiedono la scoperta da parte di SQL Server Browser, o le connessioni locali di Windows che omettono un protocollo e un indirizzo espliciti. L'abilitazione esplicita di MultiSubnetFailover per un trasporto non TCP, il mirroring del database o il rilevamento di SQL Server Browser genera un errore di connessione. Per maggiori informazioni, vedi Alta disponibilità e failover.

Caratteristiche supportate

Le seguenti funzionalità sono supportate, soggette ai problemi noti.

Area Note
Ciclo di vita della connessione Connessione, close()blocchi with, timeout di accesso, diagnostica e modifica del database corrente. Le impostazioni della stringa di connessione includono ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, e ConnectRetryCount / ConnectRetryInterval (resilienza della connessione inattiva). Il driver nativo negozia anche la cache DNS assistita dal server e il routing migliorato quando il server li supporta.
Authentication Autenticazione SQL (UID / PWD); autenticazione di Windows (Trusted_Connection=Yes, utilizzando Security Support Provider Interface (SSPI) su Windows o Kerberos su Linux e macOS); e Microsoft Entra ID interattiva, integrata, codice del dispositivo, entità servizio, identità gestita, credenziale predefinita e token di accesso. L'autenticazione tramite password Microsoft Entra ID non è supportata. Per altre informazioni, vedere Problemi noti.
Sicurezza del Livello di Trasporto (TLS) Encrypt, TrustServerCertificate, HostnameInCertificate e ServerCertificate.
Esecuzione della query Esecuzione diretta e preparata, riutilizzo del piano preparato, qmark parametri e la conversione pyformatmssql-python esegue.
Sintassi di escape ODBC Funzione, data/ora, outer-join, identificatore globalmente unico (GUID), LIKE ... {escape ...}, intervallo e {encrypt ...} forme di escape.
Procedure memorizzate Richiamali con Transact-SQL (T-SQL) o sintassi posizionale {call ...} tramite execute(), leggi i set di risultati e passa a quello successivo con nextset().
Parametri di input Parametri scalari, SQL NULL, setinputsizes(), e parametri misti regolari/streaming.
Parametri grandi Grandi testi, binari, Extensible Markup Language (XML) e parametri di tipo definito dall'utente (UDT) supportano lo streaming dei dati in fase di esecuzione.
executemany() In batch con array di parametri ODBC. Le righe contenenti valori streamati tornano all'esecuzione riga per riga.
Recupero delle righe fetchone(), fetchmany(), fetchall(), iterazione, fetchval(), conversione digitata e streaming di testo/binario di grandi dimensioni.
Recupero della freccia arrow_batch(), arrow()e arrow_reader(). Richiede pyarrow.
Più set di risultati nextset(), compresi i risultati prodotti dagli array di parametri.
Transactions Autocommit, commit, rollback e i livelli di isolamento read-uncommitted, read-committed, repeatable-read, serializable e isolamento snapshot. Con l'autocommit disattivato, il gestore del contesto della connessione effettua il commit quando termina correttamente ed esegue il rollback in caso di eccezione.
Timeout query Imposta Connection.timeout in secondi prima di creare un cursore. Quando un'istruzione supera tale timeout, il driver genera OperationalError. 0 Significa niente timeout. Imposta il timeout di accesso separatamente con connect(timeout=...).
Pool di connessioni Il pool integrato include il reset della connessione prima del riutilizzo, compreso mssql-python. Per l'isolamento del pool per l'autenticazione, vedi Isolamento identità.
API dei metadati tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures() e getTypeInfo().
Codifica caratteri e convertitori Codifica predefinita a caratteri larghi, convertitori di output e parametri non Unicode sensibili alle regole di confronto, inclusi UTF-8 e le regole di confronto legacy SQL sort-ID. La decodifica personalizzata di caratteri narrow deve corrispondere alla code page del client. Per altre informazioni, vedere Problemi noti.

L'autenticazione integrata di Microsoft Entra ID utilizza l'account Windows con cui è stato effettuato l'accesso su Windows. Su Linux e macOS, utilizza un ticket Kerberos per autenticarsi all'endpoint Active Directory Federation Services (AD FS) del tenant. Per i prerequisiti, vedi l'autenticazione integrata di Windows.

La chiusura di un arrow_reader() invia SQLCancel per interrompere un recupero in corso. La chiamata di chiusura aspetta che la pulizia dopo l'annullamento finisca. Per maggiori informazioni, vedi integrazione con Apache Arrow.

Tipi di dati

Il driver restituisce valori xml, json e vector come oggetti Pythonstr, con vector rappresentato come un array JavaScript Object Notation (JSON). Restituisce i tipi di runtime del linguaggio comune (CLR) come geometry, geography e hierarchyid come oggetti Pythonbytes. Per maggiori informazioni, vedi Data Type Mapping e Problemi noti.

Problemi noti

Controlla queste differenze prima di cambiare un carico di lavoro da msodbcsql18.

Problema Details Workaround
Autenticazione tramite password Microsoft Entra ID Authentication=ActiveDirectoryPassword non è supportata. Questo metodo non supporta l'autenticazione a più fattori (MFA). L'autenticazione SQL (UID / PWD) non è influenzata. Usa un altro metodo Microsoft Entra ID, come un service principal, un'identità gestita o un token di accesso.
attrs_before impostazioni La modalità di autenticazione di Microsoft Entra ID e l'intento dell'applicazione non possono essere impostati come attributi numerici di connessione. Usa le Authentication parole chiave della stringa di connessione e ApplicationIntent.
Timeout dell'operazione di connessione SQL_ATTR_CONNECTION_TIMEOUT controlla la pulizia dell'annullamento. Non impone un timeout sul reset della connessione in pool. Una richiesta di connessione può rimanere bloccata se il server smette di rispondere durante il reset. Non è disponibile alcun timeout per il reset aggregato. Imposta connect(timeout=...) per il login e Connection.timeout per gli estratti conto.
Host con più indirizzi msodbcsql18 abilita la Transparent Network IP Resolution (TNIR) di default; mssql-odbc non la supporta. mssql-python rifiuta la TransparentNetworkIPResolution parola chiave connection-string con uno dei due fornitori. Utilizzare MultiSubnetFailover=yes per ascoltatori di gruppi di disponibilità e altri host multi-indirizzo. Per le impostazioni predefinite, vedere impostazioni predefinite del failover multi-subnet.
Classificazione dei dati I metadati di classificazione della sensibilità non sono disponibili, e SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) non sono supportati. Query sys.sensitivity_classifications.
fork() Dopo il collegamento Su Linux, un processo forkato dopo la connessione del genitore può bloccarsi quando usa il driver, anche con una nuova connessione. Con il pooling attivato, anche il genitore può bloccarsi. (#566) Usa il metodo spawn start e connettiti all'interno di ogni worker.
Tracciamento nativo su Linux Con il tracciamento nativo abilitato, Python può abortire durante la pulizia del driver all'uscita del processo. Lascia MSSQL_TDS_TRACE non impostato su Linux.
Risultati non letti Chiudere un cursore o eseguire un'altra istruzione legge e scarta i risultati rimanenti invece di annullarli, il che può essere lento. La pulizia dell'istruzione preparata utilizza il timeout della query dell'istruzione, ma un timeout zero lascia quella pulizia illimitata. Recupera solo le righe di cui hai bisogno, ad esempio con TOP, e imposta Connection.timeout prima di creare il cursore.
Decodifica personalizzata dei caratteri narrow Il driver nativo utilizza la pagina codici ANSI di Windows su Windows e la tabella codici delle impostazioni locali del processo su Linux e macOS per il testo a larghezza ridotta. Una decodifica Python esplicita che non corrisponde a quella pagina di codici può produrre testo errato o bytes. Usa la decodifica predefinita a caratteri wide: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Alcuni valori di capacità e limiti basati sulla dimensione del pacchetto differiscono da msodbcsql18. SQL_USER_NAME riporta l'entità di sicurezza del database invece della stringa di connessione UID. Interroga i metadati specifici del server quando una capacità o un limite segnalato è importante per la tua applicazione.
Errori di memoria insufficiente Alcuni errori di allocazione dei driver terminano il processo Python invece di sollevare MemoryError. (#484) Limita la dimensione dei valori che invii e recuperi.
Prestazioni di lettura di valori di grandi dimensioni Le letture a blocchi dei dati varchar(max) e nvarchar(max) possono essere più lente rispetto a quelle con msodbcsql18. (#473) Confronta le prestazioni del tuo carico di lavoro.

Segnala problemi

Se incontri un bug, riproducilo con msodbcsql18 e registra se si verifica con entrambi i fornitori. Per le istruzioni per l'attivazione, vedi Abilita il driver.

Includa l'output di mssql_python.get_native_provider_info(), il sistema operativo, le versioni di Python e del driver, e il batch T-SQL che genera l'errore e il messaggio di errore nella segnalazione:

Su Windows, imposta queste variabili in PowerShell prima di avviare Python per raccogliere la diagnostica dei driver nativi. Riproduci il problema con mssql-odbc selezionato:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE abilita il tracciamento, MSSQL_TDS_TRACE_LEVEL seleziona il livello di log e MSSQL_TDS_TRACE_DIR seleziona la directory per i file di traccia per processo dal driver ODBC nativo invece dell'output di errore standard. Il pacchetto companion di Rust crea anche file di log sotto mssql_python_logs nella directory corrente.

Le tracce possono contenere testo T-SQL e valori di parametri. Oscura i dati sensibili prima di condividere estratti. Dopo la diagnosi, rimuovi queste variabili e riavvia Python per disabilitare il tracciamento.

Contenuti correlati

  • Ultimo aggiornamento: