Usa il driver mssql-odbc (Anteprima)

mssql-python carica uno dei due provider 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

Questo articolo tratta il provider mssql-odbc fornito in mssql-python-rs 0.5.0 e quali sono le differenze rispetto a msodbcsql18.

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 su 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 usa MultiSubnetFailover=yes per impostazione predefinita per le connessioni TCP ammissibili. Imposta MultiSubnetFailover=no per tentativi sequenziali. Per modificare il valore predefinito di distribuzione, imposta MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT su true o false (senza distinzione tra maiuscole e minuscole) prima del primo utilizzo del driver. Altri valori causano un errore a meno che non vengano sovrascritti per la connessione.

La parola chiave connection-string sovrascrive il valore predefinito dell'ambiente. L'attributo pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) sovrascrive entrambi.

Il valore predefinito esclude i trasporti non TCP, il mirroring del database e le istanze denominate che richiedono il rilevamento di SQL Server Browser. Anche questi rifiutano esplicitamente MultiSubnetFailover=yes.

Su Windows, il valore predefinito è disabilitato anche per i target locali nudi come localhost. Un prefisso o porta TCP esplicito, come tcp:localhost o localhost,1433, evita questa esclusione locale-target. Anche l'esplicito MultiSubnetFailover=yes lo sovrascrive. 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).
Resilienza di rete Le connessioni TCP idonee utilizzano di default tentativi paralleli di indirizzi. La modalità parallela non dà priorità agli indirizzi in base a IpAddressPreference e respinge più di 64 indirizzi risolti. Per tentativi sequenziali e ordinazione delle famiglie di indirizzi, vedi Defaults di failover multi-subnet. L'algoritmo separato Transparent Network IP Resolution (TNIR) non è implementato. La cache assistita dal server del Domain Name System (DNS) abilita il fallback per indirizzi memorizzati nella cache in caso di errore DNS dopo un login riuscito in cui il server consente la memorizzazione nella cache. Il routing avanzato viene utilizzato quando è negoziato con il server.
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. Su macOS, Encrypt=Strict le connessioni TCP possono negoziare TLS 1.3 con un server compatibile.
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 parametri di testo e binari fluiscono al server seguendo il normale percorso di associazione. I binding espliciti SQL_SS_UDT e SQL_SS_XML e i binding tramite setinputsizes() vengono anch'essi trasmessi in streaming quando Python seleziona data-at-execution: la dimensione dichiarata deve superare 4000 per str o 8000 per bytes oppure bytearray. Il binding di tipo definito dall'utente (UDT) richiede al server di descrivere il tipo del parametro. Alcuni binding personalizzati e misti continuano a eseguire il buffering. Per altre informazioni, vedere Problemi noti.
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 tipizzata e grande flusso di testo/binario.
Recupero della freccia arrow_batch(), arrow()e arrow_reader(). Richiede pyarrow.
Più set di risultati nextset(), compresi quelli 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 nessun timeout. Imposta il timeout di accesso separatamente con connect(timeout=...).
Timeout delle operazioni di connessione conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) Si applica alle richieste di rete associate alla connessione, incluse commit, rollback e modifiche al catalogo e all'isolamento. Il reset pooled rinvia il reset del server alla seguente richiesta di impostazione di isolamento; sia quella richiesta che qualsiasi rollback precedente utilizzano questo timeout. 0 lascia queste richieste senza limiti di tempo. Questo timeout è separato dai timeout di login e delle query e non rappresenta una scadenza totale per il pool-checkout. La pulizia in seguito all'annullamento può aumentare il tempo di chiamata trascorso.
Pulizia del cursore Chiudere un cursore annulla il lavoro in sospeso sul server quando necessario invece di leggere ogni risultato rimasto. La pulizia dell'istruzione preparata rispetta il timeout della query. La pulizia delle cancellazioni ha un budget di attesa aggiuntivo pari al timeout della connessione, oppure 120 secondi quando tale timeout è 0.
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à.
Multithreading (esecuzione simultanea di più thread) Connessioni e query concorrenti con una connessione e un cursore separati per ogni worker. Non condividere i cursori tra i thread.
API dei metadati tables(), rowIdColumns(), rowVerColumns(), procedures(), getTypeInfo(), getinfo(), statistics(), foreignKeys(), primaryKeys() e columns(). SQL_USER_NAME riporta l'utente del database anziché il UID della stringa di connessione. I valori delle capacità e i limiti basati sulla dimensione dei pacchetti possono differire da msodbcsql18: "N" segnala SQL_NEED_LONG_DATA_LEN perché un input lungo non richiede una lunghezza totale dichiarata. Utilizza le funzionalità e i limiti restituiti.
Codifica caratteri e convertitori La codifica a caratteri larghi predefinita, i convertitori di output, i parametri non Unicode sensibili alla collation e i risultati a caratteri stretti nella codifica client della piattaforma. La decodifica personalizzata a caratteri stretti deve corrispondere a quella codifica; una discrepanza può produrre testo errato o bytes. Usa conn.setdecoding(mssql_python.SQL_CHAR) per ripristinare la decodifica predefinita a caratteri estesi. Per la sostituzione dei parametri non Unicode, vedi 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.

Se un fetch è in esecuzione quando chiudi un arrow_reader(), close() annulla il fetch e ritorna dopo che si è fermato. Chiudere un lettore da una query precedente non influisce su una query successiva sullo stesso cursore. 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 limitazioni prima di spostare un carico di lavoro da msodbcsql18. La tabella seguente indica le esclusioni intenzionali.

Problema Details Workaround
Autenticazione con password Microsoft Entra ID (esclusione intenzionale) Authentication=ActiveDirectoryPassword non è supportato, e il supporto non è previsto perché questo metodo non può soddisfare l'autenticazione multifattore (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 Il selettore di autenticazione numerica (SQL_COPT_SS_AUTHENTICATION) e l'attributo application intent restano non supportati. Vengono implementati failover multi-subnet e attributi di sicurezza integrata. Anche l'abbinamento dell'identificatore dei metadati (SQL_ATTR_METADATA_ID) non è supportato. Usa le parole chiave della stringa di connessione Authentication e ApplicationIntent, ove applicabile.
fork() dopo la connessione 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.
Utilizzo della memoria con binding personalizzati a parametri grandi I valori data-at-execution vincolati come tipi di larghezza fissa SQL_CHAR, SQL_WCHAR oppure SQL_BINARY vengono bufferizzati per la conversione. Mescolare parametri bufferizzati e streamed può anche bufferizzare valori grandi precedenti mentre si aspetta un valore bufferizzato successivo. Preferisci i binding di lunghezza variabile predefiniti. Evita grandi override a larghezza fissa tramite setinputsizes() quando il consumo di memoria è importante.
Sostituzione dei caratteri non Unicode Per i caratteri esterni alla pagina di codice di destinazione di un parametro non Unicode, il driver può sostituire ?, dove msodbcsql18 indica l'uso di un carattere più adatto. Preferisci i tipi SQL Unicode e le associazioni di stringhe predefinite in Python quando il testo deve essere preservato.
Cambiamenti di isolamento dopo SQL grezzo Dopo il raw SET TRANSACTION ISOLATION LEVEL, l'impostazione dell'attributo di connessione al livello memorizzato nella cache del driver può avere esito positivo senza ripristinare quel livello sul server. (#798) Evita di mescolare modifiche di isolamento SQL grezzo e basate su attributi. Usa un SET TRANSACTION ISOLATION LEVEL esplicito quando si ripristina il livello.
Errori di esaurimento della memoria 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. I risultati dipendono dalla piattaforma e dal carico di lavoro. (#473) Confronta le prestazioni del tuo carico di lavoro.

Questo elenco non è esaustivo.

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. Su Linux, lasciare MSSQL_TDS_TRACE non impostato a causa dell'errore all'uscita del processo descritto in Problemi noti.

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"
$env:MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB = "100"

MSSQL_TDS_TRACE abilita il tracciamento, MSSQL_TDS_TRACE_LEVEL seleziona il filtro di log e MSSQL_TDS_TRACE_DIR seleziona la directory per i file di tracciamento per processo dal driver ODBC nativo invece dell'output standard di errore. MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB imposta la soglia di rollover per file (100 MiB di default; accetta da 1 a 1024). Non si tratta di un limite totale di spazio su disco: i singoli file possono superare la soglia e i file vecchi non vengono eliminati. Il pacchetto companion di Rust crea anche file di log sotto mssql_python_logs nella directory corrente. Riavvia Python dopo aver cambiato queste impostazioni.

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.