Novità in mssql-python

Ogni release del driver mssql-python introduce nuove funzionalità, miglioramenti delle prestazioni e correzioni di bug. Le sezioni seguenti dettagliano ogni versione.

mssql-python 1.12.0

Data di uscita: luglio 2026

Enhancements

Pacchetto complementare mssql-python-odbc autonomo

I binari driver ODBC di mssql-python cui ha bisogno in tempo reale sono ora pubblicati anche come pacchetto compagno separato, solo per dati: mssql-python-odbc (nome mssql_python_odbcdi importazione, attualmente fissato alla versione 18.6.2). Il mssql-python pacchetto dichiara mssql-python-odbc==18.6.2 in install_requires, quindi pip install mssql-python installa trasparentemente il pacchetto compagno insieme ad esso. Non sono necessarie modifiche al codice.

Il loader nativo preferisce il pacchetto esterno mssql_python_odbc quando è presente, e in sua assenza ripiega sui binari ODBC ancora inclusi nel wheel mssql-python. Il fallback è sicuro con il Python Global Interpreter Lock (GIL) e funziona su distribuzioni Linux basate su musl come Alpine.

Questa divisione permette di fissare o aggiornare i binari dei driver indipendentemente dal codice Python, dà ai redistributori una ruota più piccola mssql-python nel tempo ed evita problemi di duplicazione da file ODBC impacchettati.

Correzioni dei bug

cursor.bulkcopy() ora utilizza il timeout di connessione della connessione padre

L'operazione di copia in massa apre una connessione separata tramite l'estensione mssql_py_core nativa. In precedenza, questa operazione utilizzava sempre un timeout di connessione hardcoded di 15 secondi senza possibilità di sovrascriverlo da Python. Se imposti un timeout di connessione sulla connessione padre (connect(..., timeout=<seconds>)), bulkcopy() ora inoltra tale valore alla connessione interna. L'impostazione timeout=0 preserva il comportamento no override e lascia il valore predefinito interno di 15 secondi. Il timeout del cursore al momento della bulkcopy() chiamata viene utilizzato per l'operazione, quindi le modifiche successive alla connessione genitore non influenzano una copia in blocco in volo.

Il seguente esempio utilizza la Production.Culture tabella di ricerca dal database di esempio AdventureWorks . Regola la stringa di connessione e il nome del database per il tuo ambiente:

import mssql_python
from datetime import datetime

# The 60-second timeout applies to both the initial connection and
# the internal connection that bulkcopy() opens.
conn = mssql_python.connect(
    "Server=<server>;"
    "Database=AdventureWorks2022;"
    "Encrypt=yes",
    timeout=60,
)
conn.autocommit = True
cursor = conn.cursor()

# Bulk-copy two rows into Production.Culture (CultureID, Name, ModifiedDate).
now = datetime.now()
rows = [
    ("xx", "Demo culture 1", now),
    ("yy", "Demo culture 2", now),
]
result = cursor.bulkcopy("Production.Culture", rows)
print(f"Copied {result['rows_copied']} rows")

# Remove the demo rows so the sample is re-runnable.
cursor.execute("DELETE FROM Production.Culture WHERE CultureID IN ('xx','yy')")

cursor.bulkcopy() supporta colonne di tipo definite dall'utente CLR

In precedenza, cursor.bulkcopy() non riusciva con Protocol Error: Unsupported TDS type for bulk copy: 0xF0 per qualsiasi colonna di destinazione che utilizzava un tipo definito dall'utente Common Language Runtime (CLR), inclusi i tipi predefiniti geography, geometry e hierarchyid e qualsiasi UDT CLR personalizzato registrato in un assembly. Il percorso del filo nativo mssql_py_core non aveva un handler per il token di tipo UDT (0xF0) e commetteva errori durante la scrittura dei metadati delle colonne, prima che venissero inviate righe. Le colonne CLR UDT sono ora mappate a varbinary(max) a livello di trasmissione e i byte forniti vengono trasmessi in streaming come payload IBinarySerialize dell'UDT, in modo coerente con il modo in cui pyodbc e python-tds caricano le colonne UDT. SQL Server materializza l'UDT all'inserimento. Consegnato tramite l'mssql_py_coreaggiornamento dalla versione 0.1.6 alla 0.1.7.

Il seguente esempio archivia la colonna org-chart da HumanResources.Employee (una colonna hierarchyid, uno degli UDT CLR integrati di SQL Server) in una nuova tabella. In un flusso di lavoro reale, i byte UDT potrebbero provenire da un'altra istanza di SQL Server, da un file serializzato o dall'output del IBinarySerialize.Write() tuo tipo CLR; questo esempio li legge da una colonna esistente tramite CAST(... AS varbinary(max)) così che il campione sia autocontenuto. La copia in blocco include la riga il cui OrganizationNode è NULL:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=AdventureWorks2022;"
    "Encrypt=yes",
)
conn.autocommit = True  # bulkcopy uses a separate connection; the destination must be visible
cursor = conn.cursor()

cursor.execute(
    "IF OBJECT_ID('dbo.EmployeeOrgArchive','U') IS NOT NULL "
    "DROP TABLE dbo.EmployeeOrgArchive;"
    "CREATE TABLE dbo.EmployeeOrgArchive (BusinessEntityID int, OrganizationNode hierarchyid);"
)

# Casting a hierarchyid column to varbinary(max) yields the UDT's
# serialized IBinarySerialize payload.
cursor.execute(
    "SELECT BusinessEntityID, CAST(OrganizationNode AS varbinary(max)) "
    "FROM HumanResources.Employee;"
)
rows = cursor.fetchall()

# Stream the (id, bytes) tuples into the destination's hierarchyid column.
result = cursor.bulkcopy("dbo.EmployeeOrgArchive", rows)
print(f"Copied {result['rows_copied']} rows")

cursor.execute("DROP TABLE dbo.EmployeeOrgArchive")

Per un UDT CLR personalizzato registrato nell'assembly, utilizzare il tipo nella tabella di destinazione e fornire i byte prodotti dal metodo IBinarySerialize.Write() del tipo.

MSSQL-python 1.11.0

Data di uscita: luglio 2026

Enhancements

Semantica migliorata del gestore di contesto

with connection: ora esegue correttamente il commit delle transazioni in caso di uscita corretta e il rollback in caso di eccezione, rendendolo più in linea con Python e prevedibile.

import mssql_python

# On clean exit, transaction commits
with mssql_python.connect(connection_string) as conn:
    cursor = conn.cursor()
    cursor.execute("INSERT INTO MyTable (Name) VALUES ('Alice')")
    # Automatically committed on exit

# On exception, transaction rolls back
try:
    with mssql_python.connect(connection_string) as conn:
        cursor = conn.cursor()
        cursor.execute("INSERT INTO MyTable (Name) VALUES ('Bob')")
        raise ValueError("Oops!")
except ValueError:
    pass
# Changes rolled back on exit

Correzioni dei bug

• Corretto un deadlock del GIL nella fase di teardown di ODBC (conn.close() e cursor.close()) e in SQLDescribeParam per i parametri con valore None nelle configurazioni con tunnel SSH e forwarder in-process.
• Parametri fissi BINARY e VARBINARY NULL nelle tabelle temporanee e nelle variabili della tabella. Quando la risoluzione automatica dei tipi fallisce, il driver emette un avviso Python con indicazioni esplicitecursor.setinputsizes().
• Risolto il problema di import mssql_python su Apple Silicon dopo un'installazione pulita (regressione introdotta nella versione 1.8.0). Le dipendenze incluse delle librerie dinamiche ODBC sono ora riscritte sia per l'architettura arm64 sia per l'architettura x86_64.
• Corretto un deadlock GIL nel core Rust che bloccava le operazioni di copia in blocco durante l'autenticazione con Authentication=ActiveDirectoryServicePrincipal.

mssql-python 1.10.0

Data di rilascio: giugno 2026

Enhancements

Supporto ActiveDirectoryServicePrincipal per la copia in blocco

cursor.bulkcopy() ora supporta Authentication=ActiveDirectoryServicePrincipal, consentendo inserimenti in blocco tramite credenziali del service principal.

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<application-client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##SpDemo (ID INT, Value FLOAT)")
conn.commit()

result = cursor.bulkcopy("##SpDemo", [(1, 1.5), (2, 2.5)])
print(f"Copied {result['rows_copied']} rows")

Correzioni dei bug

• Corretti i dati non ASCII VARCHAR e CHAR nel percorso di fetch di Arrow.
• Risolti i timeout di connessione durante le operazioni di caricamento massivo.

MSSQL-Python 1.9.0

Data di rilascio: giugno 2026

Enhancements

Oggetti riga in copia in blocco

cursor.bulkcopy() ora accetta direttamente gli oggetti Row recuperati invece di richiedere la conversione manuale in tupla.

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

# Fetch rows from source table
cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product")
rows = cursor.fetchall()

# Pass fetched Row objects directly to bulkcopy
cursor.execute("CREATE TABLE ##RowBulkDemo (ProductID INT, Name NVARCHAR(50), ListPrice MONEY)")
conn.commit()
result = cursor.bulkcopy("##RowBulkDemo", rows)
print(f"Copied {result['rows_copied']} rows")

Correzioni dei bug

• Packaging a ruote fisse, quindi simdutf è sempre collegato staticamente.
• Sono stati sistemati inserti grandi DECIMAL in executemany().
• Corretto il fallback del tipo errato per i parametri NULL.
• Corretta un'eccezione nei round-trip di pickle e unpickle.
• Corretto nextset() affinché mantenga PRINT i messaggi nei vari set di risultati.
• Corretta la gestione di Row nel percorso di fallback executemany() data-at-execution.
• Controllo del tipo di metodo fetch fisso per strumenti di analisi statica.

MSSQL-Python 1.8.0

Data di rilascio: maggio 2026

Enhancements

Supporto ActiveDirectoryMSI per la copia di massa

cursor.bulkcopy() ora supporta Authentication=ActiveDirectoryMSI per le identità gestite assegnate dal sistema e dall'utente.

import mssql_python

# System-assigned managed identity
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##MsiDemo (ID INT, Name NVARCHAR(50))")
conn.commit()

result = cursor.bulkcopy("##MsiDemo", [(1, "Alice"), (2, "Bob")])
print(f"Copied {result['rows_copied']} rows")

Indicizzazione delle righe con chiave stringa

Ora puoi accedere ai valori delle righe per nome di colonna, ad esempio row["col"], oltre all'indicizzazione posizionale e all'accesso agli attributi.

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product WHERE ProductID = 1")
row = cursor.fetchone()

# Access by column name (new in 1.8.0)
print(row["ProductID"]) # Access by key
print(row["Name"])

# Still supports positional indexing
print(row[0])           # Positional access

# And attribute access
print(row.Name)         # Attribute access

Aggiornamento del driver ODBC incluso

Il driver Microsoft ODBC per SQL Server è stato aggiornato alla versione 18.6.2.1.

Correzioni dei bug

• Corretti i problemi relativi al ciclo di vita differito degli attributi di connessione nell'autenticazione basata su token.
• Corretto il parsing ripetuto di stringa di connessione nel percorso di autenticazione.
• Annotazioni di tipo fisso executemany() per gli ingressi di sequenza.

mssql-python 1.7.1

Data di rilascio: maggio 2026

Enhancements

Copertura delle ruote ampliata e miglioramenti delle prestazioni

Questa versione aggiunge wheel compatibili con RHEL 8, ripristina i wheel di macOS per Python 3.10 universal2, migliora la gestione di UTF-16 tramite simdutf e ottimizza il percorso critico di execute().

Impatto sulle prestazioni: la velocità di esecuzione batch migliora di ~15% rispetto ai carichi di lavoro tipici grazie alle ottimizzazioni del percorso caldo nel execute() metodo.

Correzioni dei bug

• Corretti gli errori di accesso in modo che generino eccezioni DB-API mssql_python invece di RuntimeError.
• Rilascio esteso GIL bloccando l'esecuzione, il fetch, la transazione e le chiamate agli attributi di connessione ODBC.
• Corretti i problemi executemany() in caso di cambio di segno dei valori decimali.
• Corretta la decodifica incoerente di CP1252 VARCHAR su diverse piattaforme.
• Corretti i problemi cursor.bulkcopy() relativi alle stringhe vuote nelle colonne NVARCHAR(MAX) e VARCHAR(MAX).

MSSQL-Python 1.6.0

Data di rilascio: aprile 2026

Enhancements

Sanitizzazione delle stringa di connessione basata su parser

Questo miglioramento garantisce la corretta interpretazione dei caratteri speciali nei campi della password e nei valori racchiusi tra parentesi graffe.

import mssql_python

# Complex passwords with special characters now parse correctly
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "UID=user@contoso;"
    "PWD={p@ssw0rd;with{braces}};"  # Braced values now handled correctly
    "Encrypt=yes"
)

La sanitizzazione delle Connection string passò dalla logica basata su regex all'elaborazione basata su parser per la corretta gestione della sintassi delle stringa di connessione ODBC.

Correzioni dei bug

• Rilascio GIL corretto durante il blocco delle operazioni di connessione e disconnessione ODBC.
• Risolti i crash con setinputsizes() che si verificavano con i suggerimenti SQL_DECIMAL e SQL_NUMERIC.
• Corretto il comportamento errato di fetchone() nei metodi del catalogo ODBC.
• Corretti gli errori di stato non valido del cursore quando reset_cursor=False viene usato.
• Suggerimenti di tipo fisso executemany() per sequenze di parametri basate sulla mappatura.
• Aggiunta una guardia per l'attraversamento del percorso per setup_logging(log_file_path=...).

MSSQL-Python 1.5.0

Data di rilascio: aprile 2026

Nuove funzionalità

Supporto per il fetch di Apache Arrow

Tre nuovi metodi di cursore offrono il recupero di dati columnari ad alte prestazioni tramite l'Interfaccia Dati Arrow C:

• cursor.arrow() restituisce un pyarrow.Table completo.
• cursor.arrow_batch() restituisce un singolo pyarrow.RecordBatch.
• cursor.arrow_reader() restituisce un pyarrow.RecordBatchReader per lo streaming.

L'implementazione evita la creazione di oggetti Python nel percorso critico per migliorare le prestazioni. Per la documentazione completa, vedi integrazione con Apache Arrow.

supporto per il tipo sql_variant

Il driver ora rileva sql_variant le colonne al momento del recupero, ne risolve il tipo base sottostante e restituisce valori Python correttamente tipizzati invece dei byte grezzi.

Supporto UUID nativo

Una nuova native_uuid impostazione determina se UNIQUEIDENTIFIER le colonne vengono restituite come uuid.UUID oggetti (predefinito) o come stringhe maiuscole compatibili con pyodbc. Configuralo a livello di modulo o per connessione:

# Module-level default
settings = mssql_python.get_settings()
settings.native_uuid = True  # default

# Per-connection override
conn = mssql_python.connect(connection_string, native_uuid=False)

Per ulteriori informazioni, vedi Configurazione dei moduli.

Esportazione pubblica della classe a file

La Row classe viene ora esportata al livello superiore per le annotazioni di tipo:

from mssql_python import Row

Correzioni dei bug

• Corretto il rilevamento dei falsi positivi ? all'interno di identificatori tra parentesi, letterali stringa e commenti.
• Corretto il binding dei parametri NULL per le colonne VARBINARY (non genera più errori di conversione implicita).
• Valori fissi datetime.time che perdono microsecondi nei viaggi di andata e ritorno per TIME(1) colonne di passaggio TIME(7) .
• Ho corretto il percorso di recupero delle frecce per includere correttamente le frazioni di secondo per TIME le colonne.
• Corretta la copia in blocco relativa ai metodi di autenticazione di Microsoft Entra ID (i campi delle credenziali obsoleti non causano più errori di convalida).
• Istanze di credenziali Azure Identity memorizzate nella cache a livello di modulo per migliorare le prestazioni di autenticazione.

MSSQL-Python 1.4.0

Data di uscita: marzo 2025

Nuove funzionalità

Supporto per la copia di massa

Il caricamento massivo di dati ad alte prestazioni è ora disponibile tramite cursor.bulkcopy():

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

cursor.execute("CREATE TABLE ##BulkDemo (ID INT, Name NVARCHAR(50), Price DECIMAL(10,2))")
conn.commit()

data = [
    (1, "Item 1", 10.50),
    (2, "Item 2", 20.75),
    # ... potentially millions of rows
]

result = cursor.bulkcopy("##BulkDemo", data)
print(f"Copied {result['rows_copied']} rows")

Il metodo accetta opzioni per batch_size, timeout, column_mappings, keep_identity, check_constraintstable_lock, keep_nulls, , fire_triggers, e use_internal_transaction.

Vedi Copia in blocco per la documentazione completa.

Improvements

• Ottimizzazioni delle prestazioni per grandi set di risultati.
• Riduzione dell'uso di memoria durante le operazioni batch.
• Messaggi di errore migliorati per fallimenti di copia in massa.

MSSQL-Python 1.3.0

Data di uscita: gennaio 2025

Nuove funzionalità

Classe di ambientazione

Configura il comportamento a livello di modulo tramite la nuova Settings classe:

import mssql_python

settings = mssql_python.get_settings()
settings.lowercase = True       # Lowercase column names in cursor.description

Vedi configurazione del modulo per i dettagli.

Improvements

• Gestione migliore del timeout della connessione durante il failover Azure SQL.
• Compatibilità migliorata con Python 3.13.

MSSQL-Python 1.2.0

Data di uscita: novembre 2024

Nuove funzionalità

Metodi di scoperta dello schema

Nuovi metodi di cursore per l'esplorazione dei metadati del database:

cursor = conn.cursor()

# List all tables
cursor.tables(schema="dbo")

# Get column information
cursor.columns(table="Product", schema="Production")

# Get primary keys
cursor.primaryKeys(table="Product", schema="Production")

# Get foreign key relationships
cursor.foreignKeys(table="SalesOrderDetail", schema="Sales")

# Get stored procedures
cursor.procedures(schema="dbo")

# Get index statistics
cursor.statistics(table="Product", schema="Production")

# Get type information
cursor.getTypeInfo()

Vedi Scoperta dello schema per la documentazione completa.

Improvements

• Cache dei metadati migliorata per le query ripetute dello schema.
• Migliore gestione delle colonne calcolate nei columns() risultati.

MSSQL-python 1.1.0

Data di uscita: settembre 2024

Nuove funzionalità

Convertitori di uscita personalizzati

Registrare funzioni personalizzate per trasformare i valori delle colonne durante il fetch:

import mssql_python
from decimal import Decimal

conn = mssql_python.connect(connection_string)

# Convert decimals to float (converter receives Decimal)
def decimal_to_float(value):
    if value is None:
        return None
    return float(value)  # value is already a Decimal object

conn.add_output_converter(mssql_python.SQL_DECIMAL, decimal_to_float)

# Custom money formatting
def format_money(value):
    if value is None:
        return "$0.00"
    return f"${float(value):,.2f}"  # value is already a Decimal object

conn.add_output_converter(mssql_python.SQL_DECIMAL, format_money)

Metodi di gestione:

• add_output_converter(sql_type, converter_func)
• get_output_converter(sql_type)
• remove_output_converter(sql_type)
• clear_output_converters()

Per la documentazione completa, vedi Convertitori di tipo personalizzato.

Improvements

• Messaggi di errore migliori in caso di errore nella conversione del tipo.
• Supporto per funzioni convertitrici che restituiscono None.

MSSQL-Python 1.0.0

Data di uscita: luglio 2024

Versione iniziale GA

La prima versione di disponibilità generale di mssql-python, il driver Python nativo di Microsoft per SQL Server.

Funzionalità di base

• Architettura DDBC: Connettività diretta al database senza richiedere l'installazione di driver ODBC.
• Conformità a DB-API 2.0: interfaccia standard per database di Python.
• Pool di connessioni: gestione integrata del pool di connessioni.
• Autenticazione Microsoft Entra: Supporto completo per l'autenticazione basata sull'identità di Azure.
• Crittografia TLS: Connessioni sicure con validazione dei certificati.

Caratteristiche di connessione

• 21 parole chiave della stringa di connessione.
• 9 modalità di autenticazione (SQL, Windows e 7 metodi Microsoft Entra ID).
• Controllo dell'autocommit.
• Metodi di esecuzione: execute(), executemany(), e batch_execute().
• Attributi di connessione attraverso set_attr() e getinfo().
• Supporto per il gestore di contesto.

Caratteristiche del cursore

• Metodi standard di riporto: fetchone(), fetchmany(), fetchall().
• Metodi estesi: fetchval(), skip().
• Metodi di esecuzione: execute() e executemany().
• Oggetti di riga con accesso tramite attributi e indici.
• Navigazione tra set di risultati multipli con nextset().

Supporto dei tipi di dati

• Tutti tipi nativi di SQL Server.
• Mappature dei tipi Python↔SQL.
• Costanti di tipo SQL per tipizzazione esplicita (ad esempio, mssql_python.SQL_DECIMAL).
• Gestione di NULL in PythonNone.

Supporto delle transazioni

• Commit e rollback manuali.
• Modalità auto-commit.
• Controllo del livello di isolamento.
• Rilevamento e gestione dei deadlock.

Modalità di autenticazione

Upgrade

Da pyodbc

Per linee guida dettagliate sulla migrazione, vedi Migrate from pyodbc.

Differenze principali:

• Sono supportati entrambi gli stili di parametri: ? (qmark) e %(name)s (pyformat). Le tue query esistenti ? funzionano senza cambiamenti.
• Nessun metodo callproc(). Usa invece le istruzioni EXECUTE.
• Pooling di connessione integrato.
• Nessuna dipendenza da driver ODBC esterni.

Da pymssql

Per indicazioni dettagliate sulla migrazione, vedi Migrate from pymssql.

Differenze principali:

• Sostituire i marcatori di parametro %s e %d con ? o %(name)s.
• Usa una stringa di connessione invece degli argomenti posizionali.
• Nessuna dipendenza da FreeTDS.
• Più cursori concorrenti per connessione.
• Gli oggetti riga con accesso agli attributi sostituiscono as_dict=True.

Tra le versioni di mssql-python

Aggiorna il driver per ottenere nuove funzionalità e correzioni.

pip install --upgrade mssql-python

Controlla le note di rilascio per eventuali cambiamenti improvvisi prima di aggiornare i sistemi di produzione.

Roadmap

Per le prossime funzionalità e la roadmap di sviluppo, consulta il repository GitHub.

Contenuti correlati

• Driver mssql-python
• Ciclo di vita del supporto
• Installazione
• Rilasci su GitHub