Utilisez le pilote mssql-odbc (Aperçu)

mssql-python charge l’un des deux fournisseurs ODBC natifs :

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server Default
mssql-odbc Pilote ODBC basé sur Rust Préversion, activation facultative

Le package mssql-python-rs0.4.0 inclut le mssql-odbc fournisseur.

Note

À utiliser msodbcsql18 pour les charges de travail en production. Avant d’adhérer au fournisseur en préversion mssql-odbc, examinez ses problèmes connus.

Availability

Le pilote est livré à l’intérieur du mssql-python-rs package sous forme de wheels précompilés pour CPython 3.10 et versions ultérieures :

Platform Architectures
Windows x64 ; ARM64 sur CPython 3.11 et versions ultérieures
macOS universal2 (x86_64 et arm64), versions de macOS 15 et ultérieures
Linux (glibc) x86_64 et aarch64 (manylinux_2_28 et manylinux_2_34)
Linux (musl) x86_64 et aarch64 (musllinux_1_2)

Activer le pilote

L’installation de mssql-python installe aussi mssql-python-rs, qui contient le pilote mssql-odbc :

python -m pip install mssql-python

Si vous installez avec --no-deps ou depuis un index privé, installez mssql-python-rs aussi explicitement.

Sélectionnez le fournisseur avant d’ouvrir la première connexion. Utilisez l’une des méthodes suivantes.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Définissez la variable d'MSSQL_CONNECTION_STRINGenvironnement sur la chaîne de connexion de votre application. Gardez la validation des certificats activée (Encrypt=yes;TrustServerCertificate=no). Pour plus d’informations, voir Chaînes de connexion et Chiffrement et certificats.

Exécutez cet exemple avec votre fournisseur sélectionné :

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’exemple imprime 1.

La sélection des prestataires suit les règles suivantes :

  • MSSQL_PYTHON_NATIVE_PROVIDER est prioritaire par rapport à native_provider. Définir l’attribut sur un fournisseur en conflit émet RuntimeWarning.
  • Avant le chargement du pilote, réglez native_provider sur None pour effacer le paramètre Python. Cela ne permet pas d’effacer la variable environnement.
  • Un nom de prestataire non reconnu génère ValueError. Attribuer un nom invalide à native_provider provoque immédiatement une erreur ; une variable d’environnement invalide provoque une erreur lors de la connexion. Le pilote ne revient pas sur le fournisseur par défaut.
  • Le fournisseur est fixé lorsque le pilote commence une tentative de connexion native, même si cette tentative échoue. Redémarrez Python pour changer de fournisseurs. Passer de native_provider à un autre fournisseur émet RuntimeWarning et n'a aucun effet.

Les erreurs de validation des chaînes de connexion et les packages fournisseurs manquants surviennent avant ce point. Vous pouvez corriger ces erreurs et choisir un autre fournisseur sans redémarrer.

Appelez mssql_python.get_native_provider_info() pour vérifier le nom du prestataire, la façon dont il a été sélectionné, et si la sélection est fixe.

Pour revenir à msodbcsql18, retirez MSSQL_PYTHON_NATIVE_PROVIDER et toute native_provider assignation de votre application, redémarrez alors Python.

Paramètres par défaut de basculement multi-sous-réseaux

Le fournisseur Rust active MultiSubnetFailover par défaut pour les connexions du protocole de contrôle de transmission (TCP) applicables. Définissez MultiSubnetFailover=no explicitement pour demander des tentatives de connexion séquentielles. Pour modifier la valeur par défaut à l’échelle du déploiement, il faut définir MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT sur true ou false avant la première utilisation du pilote natif. Le mot-clé chaîne de connexion remplace cette valeur par défaut.

L’attribut numérique SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) remplace également le mot-clé lorsqu’il est défini avant la connexion.

Le pilote n'active pas ce paramètre par défaut pour les transports non-TCP, le miroir de base de données, les instances nommées nécessitant la découverte par SQL Server Browser, ni les connexions Windows locales qui omettent un protocole et une adresse explicites. Activer explicitement MultiSubnetFailover pour un transport non-TCP, le miroir de base de données ou la découverte du navigateur SQL Server génère une erreur de connexion. Pour plus d’informations, voir Haute disponibilité et basculement.

Fonctionnalités prises en charge

Les fonctionnalités suivantes sont prises en charge, sous réserve des problèmes connus.

Area Notes
Cycle de vie de la connexion Connexion, blocs close() et with, délai d’expiration de connexion, diagnostics et changement de base de données active. Les réglages de la chaîne de connexion incluent ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, et ConnectRetryCount / ConnectRetryInterval (résilience de connexion inactive). Le pilote natif négocie également la mise en cache DNS assistée par le serveur et le routage amélioré lorsque le serveur les supporte.
Authentication Authentification SQL (UID / PWD) ; authentification Windows (Trusted_Connection=Yes, utilisant Security Support Provider Interface (SSPI) sur Windows ou Kerberos sur Linux et macOS) ; et authentification interactive, intégrée, par code d’appareil, avec principal de service, avec identité gérée, avec informations d’identification par défaut et par jeton d’accès Microsoft Entra ID. L'authentification par mot de passe Microsoft Entra ID n'est pas prise en charge. Pour plus d’informations, voir Problèmes connus.
TLS (Transport Layer Security) Encrypt, TrustServerCertificate, HostnameInCertificate et ServerCertificate.
Exécution de la requête Exécution directe et préparée, réutilisation des plans d’exécution préparés, paramètres qmark et conversion pyformat effectuée par mssql-python.
Syntaxe d’échappement ODBC Fonction, date/heure, jointure externe, identifiant global unique (GUID), LIKE ... {escape ...}, intervalle et les formes d’échappement {encrypt ...}.
Procédures stockées Appelez-les avec Transact-SQL (T-SQL) ou une syntaxe positionnelle {call ...} via execute(), lisez les ensembles de résultats, et avancez avec nextset().
Paramètres d'entrée Paramètres scalaires, SQL NULL, setinputsizes(), et paramètres mixtes réguliers/streamés.
Paramètres volumineux Les paramètres de gros texte, binaire, langage de balisage extensible (XML) et type défini par l’utilisateur (UDT) prennent en charge le flux de données à l’exécution.
executemany() Traitement par lots avec des tableaux de paramètres ODBC. Les lignes contenant les valeurs streamées reviennent à l’exécution ligne par ligne.
Récupération de lignes fetchone(), fetchmany(), fetchall(), itération, fetchval(), conversion typée et lecture en flux de données texte et binaires volumineuses.
Récupération des données au format Arrow arrow_batch(), arrow()et arrow_reader(). Exige pyarrow.
Ensembles de résultats multiples nextset(), y compris les résultats produits par les tableaux de paramètres.
Transactions Autocommit, commit, rollback, ainsi que les niveaux d’isolation read-uncommitted, read-committed, repeatable-read, serializable et snapshot. Avec l’autocommit désactivé, le gestionnaire de contexte de connexion effectue un commit lors de la sortie réussie et effectue un rollback sur une exception.
Délai d’expiration de la requête Réglez Connection.timeout en secondes avant de créer un curseur. Lorsqu’une instruction dépasse ce temps d’attente, le pilote lève OperationalError. 0 signifie aucun délai d’expiration. Définissez séparément le délai de connexion à l’aide de connect(timeout=...).
Regroupement de connexions Le pool mssql-python intégré, y compris la réinitialisation de la connexion avant réutilisation. Pour l’isolation du pool spécifique à l’authentification, voir Isolation des identités.
API de métadonnées tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), et getTypeInfo().
Encodage et convertisseurs Encodage de caractères larges par défaut, convertisseurs de sortie et paramètres non Unicode sensibles au classement, y compris UTF-8 et les classements SQL hérités avec ID de tri. Le décodage personnalisé en caractères mono-octet doit correspondre à la page de codes du client. Pour plus d’informations, voir Problèmes connus.

L’authentification intégrée Microsoft Entra ID utilise le compte Windows connecté sur Windows. Sur Linux et macOS, il utilise un ticket Kerberos pour s'authentifier au point de terminaison Services ADFS (AD FS) du locataire. Pour les prérequis, voir authentification intégrée Windows.

La fermeture de arrow_reader() envoie SQLCancel pour interrompre une récupération en cours. L’appel rapproché attend que le nettoyage après annulation se termine. Pour plus d’informations, voir intégration Apache Arrow.

Types de données

Le pilote retourne les valeurs xml, json et vector sous forme d’objets Pythonstr, avec vector représenté sous forme d’un tableau JavaScript Object Notation (JSON). Il renvoie les types d’exécution du langage commun (CLR) tels que geometry, geography et hierarchyid sous forme d’objets Pythonbytes. Pour plus d’informations, voir Mappage des types de données et Problèmes connus.

Problèmes connus

Vérifiez les différences suivantes avant de migrer une charge de travail depuis msodbcsql18.

Problème Details Solution de contournement
Authentification par mot de passe Microsoft Entra ID Authentication=ActiveDirectoryPassword n’est pas pris en charge. Cette méthode ne prend pas en charge l’authentification multifacteur (MFA). L’authentification SQL (UID / PWD) n’est pas affectée. Utilisez une autre méthode Microsoft Entra ID, comme un principal de service, une identité managée ou un jeton d’accès.
attrs_before paramètres Le mode d'authentification et l'intention de l'application Microsoft Entra ID ne peuvent pas être définis comme des attributs de connexion numériques. Utilisez les mots clé de chaîne de connexion Authentication et ApplicationIntent.
Délai d’attente de l’opération de connexion SQL_ATTR_CONNECTION_TIMEOUT contrôle le nettoyage lors de l’annulation. Il n’impose pas de délai d’attente lors de la réinitialisation d’une connexion du pool. Une requête de connexion peut rester bloquée si le serveur cesse de répondre lors d’une réinitialisation. Aucun délai d’expiration de réinitialisation du pool n’est disponible. Configurez connect(timeout=...) pour la connexion et Connection.timeout pour les relevés.
Hôtes multi-adresses msodbcsql18 active par défaut la résolution IP réseau transparente (TNIR) ; mssql-odbc ne la prend pas en charge. mssql-python rejette le mot-clé TransparentNetworkIPResolution de la chaîne de connexion avec l’un ou l’autre fournisseur. Utilisez MultiSubnetFailover=yes pour les écouteurs de groupe de disponibilité et autres hôtes multi-adresses. Pour les paramètres par défaut, voir paramètres par défaut du basculement multi-sous-réseaux.
Classification des données Les métadonnées de classification de sensibilité ne sont pas disponibles, et SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) n’est pas pris en charge. Interrogez sys.sensitivity_classifications.
fork() après s’être connecté Sous Linux, un processus bifurqué après la connexion du parent peut se bloquer lorsqu’il utilise le pilote, même avec une nouvelle connexion. Avec le pooling activé, le parent peut aussi se bloquer. (#566) Utilisez la méthode de démarrage spawn et connectez-vous dans chaque worker.
Traçage natif sous Linux Avec le traçage natif activé, Python peut s’arrêter brutalement lors du nettoyage du pilote à la sortie du processus. Laissez MSSQL_TDS_TRACE non réglé sur Linux.
Résultats non lus Fermer un curseur ou exécuter une autre instruction lit et rejette les résultats restants au lieu de les annuler, ce qui peut être lent. Le nettoyage de la requête préparée utilise le délai d’attente de la requête, mais un délai d’attente égal à zéro laisse ce nettoyage sans limite. Récupérez uniquement les lignes dont vous avez besoin, par exemple avec TOP, et définissez Connection.timeout avant de créer le curseur.
Décodage personnalisé à caractères étroits Le pilote natif utilise la page de codes ANSI de Windows sous Windows et la page de codes de la locale du processus sous Linux et macOS pour le texte non Unicode. Un décodage Python explicite qui ne correspond pas à cette page de code peut produire un texte incorrect ou bytes. Utilisez le décodage par défaut à caractères larges : conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Certaines valeurs de capacité et des limites basées sur la taille des paquets diffèrent de msodbcsql18. SQL_USER_NAME indique le principal de la base de données plutôt que la chaîne de connexion UID. Interrogez les métadonnées spécifiques du serveur lorsqu’une capacité ou une limitation signalée est importante pour votre application.
Erreurs de mémoire insuffisante Certains échecs d’allocation de drivers mettent fin au processus Python au lieu de déclencher MemoryError. (#484) Limitez la taille des valeurs que vous envoyez et récupérez.
Performances de lecture des valeurs volumineuses Les lectures en tranches des données varchar(max) et nvarchar(max) peuvent être plus lentes qu’avec msodbcsql18. (#473) Évaluez votre charge de travail.

Signaler des problèmes

Si vous rencontrez un bug, reproduisez-le avec msodbcsql18 et notez s’il se produit avec les deux fournisseurs. Pour obtenir des instructions de basculement, consultez Activer le pilote.

Incluez la sortie de mssql_python.get_native_provider_info(), la version de votre système d’exploitation, les versions de Python et des pilotes, ainsi que le lot T-SQL défaillant et le message d’erreur dans votre rapport :

Sous Windows, définissez ces variables dans PowerShell avant de lancer Python pour collecter des diagnostics du pilote natif. Reproduisez le problème avec mssql-odbc sélectionné :

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

MSSQL_TDS_TRACE active le traçage, MSSQL_TDS_TRACE_LEVEL sélectionne le niveau de journal, puis MSSQL_TDS_TRACE_DIR sélectionne le répertoire des fichiers de trace par processus depuis le pilote ODBC natif au lieu de la sortie d’erreur standard. Le paquet compagnon Rust crée également des fichiers journaux sous mssql_python_logs dans le répertoire courant.

Les traces peuvent contenir du texte T-SQL et des valeurs de paramètres. Expurgez les données sensibles avant de partager des extraits. Après le diagnostic, supprimez ces variables et redémarrez Python pour désactiver le traçage.

Contenu connexe

  • Dernière mise à jour :