Utilisation du pilote mssql-odbc (Aperçu)

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

Provider Qu’est-ce que c’est ? Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server, le pilote C++ de référence Par défaut, inchangé
mssql-odbc Un nouveau pilote ODBC écrit en Rust Aperçu, activation

Cet article couvre mssql-odbcla version 0.3.0, la version actuellement utilisée par mssql-python, et ce qui diffère de msodbcsql18.

Note

mssql-odbc est en cours de développement et de validation actifs. Ce n'est pas encore un remplaçant complet du pilote ODBC 18 de Microsoft. Conservez msodbcsql18 comme votre valeur par défaut de production pour l’instant. L’équipe de développement prévoit de combler les lacunes de prévisualisation dans les prochaines versions, sauf pour les exclusions intentionnelles explicitement identifiées dans cet article.

Availability

Le pilote est livré dans le mssql-python-rs package sous forme de wheels précompilées pour CPython 3.10 et versions ultérieures :

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

Activation du pilote

Le mssql-python paquet dépend de mssql-python-rs, donc une installation normale apporte avec elle le pilote Rust :

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 la première connexion, soit avec une variable d’environnement :

PowerShell :

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash ou Zsh :

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

ou à partir de Python :

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Connectez-vous en utilisant la chaîne de connexion existante de votre application. Gardez la validation des certificats activée (Encrypt=yes;TrustServerCertificate=no). Pour l’authentification et la configuration des certificats, voir Chaînes de connexion et Chiffrement et certificats.

connection = mssql_python.connect(connection_string)

Le pilote applique ces règles lors du choix du fournisseur :

  • La MSSQL_PYTHON_NATIVE_PROVIDER variable d’environnement a la priorité sur native_provider. Une affectation d’attribut conflictuelle génère RuntimeWarning.
  • La sélection devient fixe après validation de la chaîne de connexion et immédiatement avant la construction de la connexion native. Une défaillance de connexion ultérieure n’efface pas la sélection. Une erreur d’analyse de chaîne de connexion antérieure ou un package de fournisseur manquant ne permet pas de corriger la sélection. Une fois la sélection verrouillée, remplacer native_provider par un autre fournisseur émet RuntimeWarning et est sans effet. Redémarrez le processus pour changer de fournisseur.
  • Un nom de fournisseur non reconnu provoque ValueError; le pilote ne revient pas au fournisseur par défaut. Un nom inconnu attribué à native_provider déclenche immédiatement une erreur. Un nom inconnu dans la variable environnement provoque une erreur lorsque vous tentez de vous connecter.
  • Réglez native_provider sur None pour effacer la sélection d’attributs avant qu’elle ne soit verrouillée. La variable d’environnement a toujours priorité.

Appelez mssql_python.get_native_provider_info() pour inspecter le fournisseur sélectionné, la source de sélection et si la sélection est fixe. Avant de se connecter, cela indique la sélection, pas la preuve que le pilote natif a été chargé avec succès.

Pour revenir en arrière, mettez la variable sur msodbcsql18, ou déconfigurez-la et supprimez toute native_provider assignation de votre code (ou définissez-la à "msodbcsql18"). Ensuite, relancez le processus.

Ce qui fonctionne aujourd’hui

Le mssql-odbc pilote implémente toutes les fonctions ODBC que mssql-python appelle, donc la plupart des applications peuvent changer de fournisseur sans modification de code. Vérifiez les problèmes connus pour les différences restantes.

Area Notes
Cycle de vie de la connexion Connect, close(), with blocs, délai d’attente de connexion, diagnostics, et modification de la base de données actuelle. Les réglages de la chaîne de connexion incluent ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, et ConnectRetryCount / ConnectRetryInterval (résilience de connexion inactive).
Authentication authentification SQL (UID / PWD) ; authentification Windows (Trusted_Connection=Yes, utilisant SSPI sur Windows ou Kerberos sur Linux et macOS) ; et authentification interactive Microsoft Entra, code d’appareil, principal de service, identité gérée, informations d’identification par défaut et jeton d’accès. L’intégration Entra et l’authentification par mot de passe ne sont pas pris en charge ; voir Problèmes connus.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate et ServerCertificate.
Exécution de la requête Exécution directe et préparée, réutilisation du plan préparé, paramètres qmark, et la conversion pyformatmssql-python qu’effectue.
Syntaxe d’échappement ODBC Fonction, date/heure, jointure extérieure, GUID, LIKE ... {escape ...}, intervalle et {encrypt ...} formes d’échappement.
Procédures stockées Appelez-les avec 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 grands paramètres de texte et de binaires sont transmis au serveur par le chemin de liaison standard ; les limitations des paramètres XML et UDT sont listées ci-dessous.
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 flux texte/binaire volumineux.
Récupération de flèche 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, le commit automatique (ou rollback, si une erreur a échappé) qui se produit à la fin d’un bloc with connect(...), ainsi que les niveaux lecture non validée, lecture validée, lecture répétable, sérialisable et snapshot.
Délai d’expiration de la requête Définissez Connection.timeout (en secondes) pour limiter la durée d'exécution des instructions exécutées par les curseurs de cette connexion ; l'expiration déclenche OperationalError. 0 signifie aucun délai d’expiration. Ce paramètre est distinct du délai de connexion transmis sous la forme de connect(timeout=...).
Regroupement de connexions Le pool intégrémssql-python, incluant la réinitialisation de la connexion lors de l’extraction d’une connexion et les pools séparés par identité Microsoft Entra.
API de métadonnées tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), et getTypeInfo().
Encodage et convertisseurs Encodage par défaut à caractères larges et convertisseurs de sortie. Le décodage personnalisé à caractères étroits et la conversion de paramètres non-Unicode présentent des limitations dans Problèmes connus.

Types de données

Vous pouvez lire tous les types de données SQL Server, et le pilote prend en charge tous les types de paramètres que mssql-python lie. Le pilote retourne les valeurs xml, vector et str comme vector (geometry en tant que tableau JSON), et les types CLR tels que geography, hierarchyid et bytes comme json. Pour d’autres correspondances Python, voir Mappages de types de données. Pour les limitations spécifiques à chaque type, voir Problèmes connus.

Problèmes connus

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

Problème Details Solution de contournement
Authentification intégrée Microsoft Entra Authentication=ActiveDirectoryIntegrated n’est pas pris en charge. Authentification Windows (Trusted_Connection=Yes) n’est pas affectée. Utilisez une autre méthode Microsoft Entra, ou conservez msodbcsql18.
Authentification par mot de passe Microsoft Entra Authentication=ActiveDirectoryPassword n’est pas pris en charge, et sa prise en charge n’est pas prévue car cette méthode ne peut pas satisfaire la MFA. L’authentification SQL (UID / PWD) n’est pas affectée. Utilisez une autre méthode Microsoft Entra, comme un principal de service, une identité gérée ou un jeton d’accès.
attrs_before paramètres L’authentification, l’intention d’application et le basculement multi-sous-réseaux ne peuvent pas être définis comme attributs numériques. Les attributs d’instruction autres que le délai d’attente de la requête sont rejetés. Utilisez les mots-clés de chaîne de connexion équivalents.
Délai d’attente de l’opération de connexion set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) accepte et stocke la valeur, mais elle n’impose pas de délai d’expiration en 0.3.0. Utilisez connect(timeout=...) pour la connexion et Connection.timeout pour les relevés ; aucun des deux n’est un délai général pour les opérations de connexion.
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. Sans MultiSubnetFailover=Yes, les adresses sont testées une à une, donc une adresse inaccessible peut retarder la connexion. La mise en cache DNS assistée par serveur et le routage amélioré ne sont pas négociés. Configurez MultiSubnetFailover=Yes pour les écouteurs de groupes de disponibilité et autres hôtes multi-adresses.
Défaillances DNS transitoires Si une recherche DNS échoue, le pilote ne revient pas à la dernière adresse ayant abouti. (#457) Réessayez la connexion.
Classification des données Les métadonnées de classification de sensibilité ne sont pas disponibles, et SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) ne sont pas pris en charge. Query sys.sensitivity_classifications.
Multithreading L’utilisation multithread n’a pas été validée. Gardez msodbcsql18 pour les charges de travail multithreadées.
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.
Annulation d’une instruction en cours Une requête ou une récupération en cours ne peut pas être interrompue. Par exemple, fermer un arrow_reader() n’arrête pas une lecture en cours sur un autre fil. Utilisez Connection.timeout pour limiter les instructions à longue exécution.
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. Fermer un curseur qui utilisait une instruction préparée ignore Connection.timeout et peut se bloquer si le serveur cesse de répondre. (#546) Récupérez uniquement les lignes dont vous avez besoin, par exemple avec TOP.
Paramètres grands xml et UDT Les valeurs liées sous la forme SQL_SS_XML ou SQL_SS_UDT via setinputsizes() sont mises en mémoire au lieu d’être diffusées en streaming. Liez xml les valeurs comme des chaînes ordinaires.
Valeurs vides image Une valeur SQL Server image vide, non NULL, est retournée comme None au lieu de b"". Lisez CAST(image_column AS varbinary(max)), ou utilisez msodbcsql18 lorsque la distinction vide/NULL compte.
Paramètres de chaînes non-Unicode Les chaînes liées comme char / varchar à setinputsizes() peuvent être incorrectement encodées pour les pages de codes 437, 850 et les collations UTF-8. Utilisez la liaison de chaîne par défaut.
Décodage de pages de code héritées sous Windows Avec setdecoding(SQL_CHAR, encoding="cp1252") ou une autre page de code héritée, le texte peut être décodé incorrectement ou retourné comme bytes, car le pilote renvoie les données char / varchar en UTF-8. Utilisez la valeur par défaut : conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME retourne la chaîne UIDde connexion, pas l’utilisateur de la base de données. Il est vide quand aucun UID n’atteint le pilote. Certaines valeurs de capacité et des limites basées sur la taille des paquets diffèrent de msodbcsql18. Utilisez SELECT USER_NAME() pour l’utilisateur de la base de données.
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 de grande taille Dans un benchmark, les lectures en chunks des varchar(max) / nvarchar(max) données étaient légèrement plus lentes qu’avec msodbcsql18. (#473) Évaluez votre charge de travail.

Cette liste n’est pas exhaustive.

Signalement des problèmes

Si vous rencontrez un bug, sélectionnez msodbcsql18, redémarrez le processus, et vérifiez si le comportement persiste. Supprimez également toute attribution conflictuelle de fournisseur côté Python. La comparaison aide à isoler le problème ; elle ne prouve pas à elle seule quelle en est la cause. Incluez la sortie de mssql_python.get_native_provider_info(), votre plateforme, ainsi que le SQL défaillant ou le message d’erreur :

Pour le diagnostic du pilote Rust, définissez ces variables avant de lancer Python et reproduisez le problème après avoir sélectionné mssql-odbc. Par exemple, dans PowerShell :

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

MSSQL_TDS_TRACE active le traçage, MSSQL_TDS_TRACE_LEVEL sélectionne le filtre de journal et MSSQL_TDS_TRACE_DIR écrit des fichiers par processus au lieu de stderr. Redémarrez Python après avoir modifié ces paramètres. Les traces peuvent contenir du texte SQL et des valeurs de paramètres. Examinez et caviardez les données sensibles avant de partager les extraits pertinents, et désactivez le traçage après le diagnostic.

Contenu connexe

  • Dernière mise à jour :