Utilizzo del driver mssql-odbc (Anteprima)

mssql-python carica uno dei due fornitori ODBC nativi:

Provider Che cos'è Stato
msodbcsql18 Microsoft ODBC Driver 18 per SQL Server, il driver C++ consolidato Predefinito, invariato
mssql-odbc Un nuovo driver ODBC scritto in Rust Anteprima, opt-in

Questo articolo copre mssql-odbcla 0.3.0, la versione attualmente utilizzata da mssql-python, e in cosa si differenzia da msodbcsql18.

Note

mssql-odbc è in fase di sviluppo e validazione attive. Non è ancora un sostituto completo del driver ODBC 18 di Microsoft. Mantieni msodbcsql18 come predefinito in produzione per ora. Il team di sviluppo prevede di colmare le lacune dell’anteprima nelle prossime versioni, ad eccezione delle esclusioni intenzionali esplicitamente indicate in questo articolo.

Availability

Il driver è distribuito 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+
macOS universal2 (x86_64 + arm64), macOS 15 o successivo
Linux (glibc) x86_64, aarch64 — manylinux_2_28 e manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Attivazione del driver

Il mssql-python pacchetto dipende da mssql-python-rs, quindi un'installazione normale porta con sé il driver Rust:

pip install mssql-python

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

Seleziona il provider prima della prima connessione, con una variabile di ambiente:

Powershell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash o Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

o in Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Connettiti usando la stringa di connessione già esistente della tua applicazione. Mantieni attivata la validazione dei certificati (Encrypt=yes;TrustServerCertificate=no). Per l'autenticazione e la configurazione dei certificati, vedi Stringhe di connessione e Crittografia e certificati.

connection = mssql_python.connect(connection_string)

Il driver applica queste regole quando seleziona il fornitore:

  • La variabile di ambiente MSSQL_PYTHON_NATIVE_PROVIDER ha la precedenza su native_provider. Un'assegnazione di attributo in conflitto emette RuntimeWarning.
  • La selezione diventa fissa dopo la validazione della stringa di connessione e immediatamente prima della costruzione della connessione nativa. Un successivo guasto alla connessione non cancella la selezione. Un errore precedente di parsing della stringa di connessione o un pacchetto provider mancante non correggono la selezione. Una volta fissata la selezione, cambiare native_provider con un provider diverso emette RuntimeWarning e non ha effetto. Riavvia il processo per cambiare provider.
  • Un nome del fornitore non riconosciuto genera ValueError; il driver non torna al fornitore predefinito. Un nome sconosciuto assegnato a native_provider genera immediatamente un errore. Un nome sconosciuto nella variabile ambiente genera un errore quando tenti di connetterti.
  • Imposta native_provider su None per azzerare la selezione dell'attributo prima che venga bloccata. La variabile ambiente ha ancora la precedenza.

Richiama mssql_python.get_native_provider_info() per ispezionare il fornitore selezionato, la fonte di selezione e se la selezione è fissa. Prima di connettersi, questo riporta la selezione, non la prova che il driver nativo sia stato caricato con successo.

Per tornare indietro, imposta la variabile su msodbcsql18, oppure disimpostala e rimuovi qualsiasi assegnazione native_provider dal tuo codice (o impostala su "msodbcsql18"). Poi riavvia il processo.

Cosa funziona oggi

Il mssql-odbc driver implementa ogni funzione ODBC che mssql-python chiama, quindi la maggior parte delle applicazioni può cambiare provider senza modifiche al codice. Controlla i problemi noti per le differenze rimanenti.

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).
Authentication Autenticazione SQL (UID / PWD); autenticazione di Windows (Trusted_Connection=Yes, usando SSPI su Windows o Kerberos su Linux e macOS); e Microsoft Entra interattiva, codice dispositivo, entità servizio, identità gestita, credenziale predefinita e token di accesso. L'autenticazione integrata di Entra e l'autenticazione tramite password non sono supportate; vedi Problemi noti.
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, GUID, LIKE ... {escape ...}, intervallo e forme di escape {encrypt ...}.
Procedure memorizzate Richiamali con T-SQL o sintassi posizionale {call ...} tramite execute(), leggi i set di risultati, e avanza 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 tramite il percorso di binding ordinario; Le limitazioni dei parametri XML e UDT sono elencate di seguito.
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, il commit automatico (o rollback, se è sfuggito un errore) che avviene quando termina un blocco with connect(...), e i livelli di read-uncommitted, read-committed, repeatable-read, serializable e snapshot isolation.
Timeout query Imposta Connection.timeout (in secondi) per limitare le istruzioni eseguite dai cursori di quella connessione; la scadenza genera OperationalError. 0 Significa niente timeout. Questa impostazione è separata dal timeout di accesso passato come connect(timeout=...).
Pool di connessioni Il pool integrato mssql-python, incluso il reset della connessione al momento dell'assegnazione della connessione e pool separati per identità Microsoft Entra.
API dei metadati tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures() e getTypeInfo().
Codifica caratteri e convertitori Codifica a caratteri estesi e convertitori di uscita predefiniti. La decodifica personalizzata a caratteri stretti e la conversione dei parametri non Unicode presentano limitazioni elencate in Problemi noti.

Tipi di dati

Puoi leggere tutti i tipi di dati di SQL Server e il driver supporta ogni tipo di parametro che mssql-python associa. Il driver restituisce valori xml, json e vector come str (vector come array JSON), e tipi CLR come geometry, geography e hierarchyid come bytes. Per altre mappature Python, vedi Mappature dei tipi di dati. Per limitazioni specifiche per tipo, vedi Problemi noti.

Problemi noti

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

Problema Details Workaround
Autenticazione integrata di Microsoft Entra Authentication=ActiveDirectoryIntegrated non è supportata. autenticazione di Windows (Trusted_Connection=Yes) non è influenzata. Usa un altro metodo Microsoft Entra, oppure mantieni msodbcsql18.
Autenticazione tramite password di Microsoft Entra Authentication=ActiveDirectoryPassword non è supportato, e il supporto non è previsto perché questo metodo non può soddisfare l'MFA. L'autenticazione SQL (UID / PWD) non è influenzata. Usa un altro metodo Microsoft Entra, come un service principal, un'identità gestita o un token di accesso.
attrs_before impostazioni Autenticazione, intento dell'applicazione e failover multi-subnet non possono essere impostati come attributi numerici. Gli attributi dello statement SQL diversi dal timeout della query vengono rifiutati. Usa le parole chiave equivalenti per la stringa di connessione.
Timeout dell'operazione di connessione set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) accetta e memorizza il valore, ma non impone un timeout nella versione 0.3.0. Usa connect(timeout=...) per il login e Connection.timeout per gli estratti conto; nessuna delle due è una scadenza generale per le operazioni di connessione.
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. Senza MultiSubnetFailover=Yes, gli indirizzi vengono provati uno alla volta, quindi un indirizzo irraggiungibile può ritardare la connessione. La cache DNS assistita dal server e il routing potenziato non vengono negoziati. Imposta MultiSubnetFailover=Yes per i listener del gruppo di disponibilità e altri host con più indirizzi.
Fallimenti DNS transitori Se una ricerca DNS fallisce, il driver non torna all'ultimo indirizzo risolto con successo. (#457) Ripetere la connessione.
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.
Multithreading L'uso multithread non è stato convalidato. Mantieni msodbcsql18 per carichi di lavoro multithread.
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.
Annullamento di una query in esecuzione Una query o un fetch in esecuzione non può essere interrotta. Ad esempio, chiudere an arrow_reader() non ferma una lettura in corso su un altro thread. Usalo Connection.timeout per limitare le istruzioni di lunga durata.
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. Chiudere un cursore che ha usato un'istruzione preparata ignora Connection.timeout e può bloccarsi se il server smette di rispondere. (#546) Recupera solo le righe di cui hai bisogno, ad esempio con TOP.
Parametri grandi xml e UDT I valori legati come SQL_SS_XML o da SQL_SS_UDT fino a setinputsizes() vengono bufferizzati in memoria invece che in streaming. Associare i valori xml come stringhe ordinarie.
Valori vuoti image Un valore vuoto e non NULL di SQL Server image viene restituito come None invece di b"". Leggi CAST(image_column AS varbinary(max)), o usa msodbcsql18 quando la distinzione vuoto/NULL conta.
Parametri di stringa non Unicode Le stringhe legate come char / varchar fino a setinputsizes() possono essere codificate erroneamente per le code page 437, code page 850 e le collation UTF-8. Usa il binding di stringa predefinito.
Decodifica legacy delle code page su Windows Con setdecoding(SQL_CHAR, encoding="cp1252") o un'altra pagina di codice legacy, il testo può essere decodificato in modo errato o restituito come bytes, perché il driver restituisce i dati char / varchar come UTF-8. Usa il valore predefinito: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME restituisce la stringa UIDdi connessione , non l'utente del database. È vuoto quando nessun UID raggiunge il driver. Alcuni valori di capacità e limiti basati sulla dimensione del pacchetto differiscono da msodbcsql18. Usa SELECT USER_NAME() per l'utente del database.
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 In una prova comparativa, le letture varchar(max) / nvarchar(max) dei dati in blocchi erano leggermente più lente rispetto a quelle con msodbcsql18. (#473) Confronta le prestazioni del tuo carico di lavoro.

Questo elenco non è esaustivo.

Segnalazione di problemi

Se incontri un bug, seleziona msodbcsql18, riavvia il processo e verifica se il comportamento si presenta ancora. Rimuovi anche eventuali assegnazioni conflittuali di provider lato Python. Il confronto aiuta a isolare il problema; da solo non ne dimostra la causa. Includi l'output di mssql_python.get_native_provider_info(), la tua piattaforma e l'SQL che causa l'errore o il messaggio di errore:

Per la diagnostica dei driver Rust, imposta queste variabili prima di avviare Python e riproduci il problema con mssql-odbc selezionato. Ad esempio, in PowerShell:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "warn,mssqlodbc=debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"

MSSQL_TDS_TRACE Abilita il tracciamento, MSSQL_TDS_TRACE_LEVEL seleziona il filtro log e MSSQL_TDS_TRACE_DIR scrive file per processo invece di stderr. Riavvia Python dopo aver cambiato queste impostazioni. Le tracce possono contenere testo SQL e valori di parametri. Rivedere e oscurare i dati sensibili prima di condividere estratti rilevanti e disabilitare il tracciamento dopo la diagnosi.

Contenuti correlati

  • Ultimo aggiornamento: