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.
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_PROVIDERha la precedenza sunative_provider. Impostando l'attributo a un fornitore in conflitto si ottieneRuntimeWarning. - Prima che il driver si carichi, imposta
native_providersuNoneper cancellare l'impostazione di Python. Questo non elimina la variabile ambientale. - Un nome di fornitore non riconosciuto genera
ValueError. Assegnare un nome non valido anative_providergenera 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_providera un altro provider generaRuntimeWarninge 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:
- Problemi del driver: https://github.com/microsoft/mssql-rs/issues
-
mssql-pythonProblematiche: https://github.com/microsoft/mssql-python/issues
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.