Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 |
Cet article traite du fournisseur mssql-odbc fourni dans mssql-python-rs version 0.5.0 et de ce qui diffère de msodbcsql18.
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_PROVIDERa priorité surnative_provider. Définir l’attribut sur un fournisseur en conflit émetRuntimeWarning. - Avant le chargement du pilote, réglez
native_providersurNonepour 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_providerprovoque 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 émetRuntimeWarninget 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 utilise par défaut MultiSubnetFailover=yes pour les connexions TCP éligibles. Définissez MultiSubnetFailover=no pour des tentatives séquentielles. Pour modifier la valeur par défaut du déploiement, réglez MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT sur true ou false (insensible à la majuscule) avant la première utilisation du pilote. D’autres valeurs provoquent une erreur sauf si une valeur de substitution est définie pour la connexion.
Le mot-clé connection-string remplace la valeur par défaut de l’environnement. L’attribut pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) remplace les deux.
La valeur par défaut exclut les transports non TCP, la mise en miroir de base de données et les instances nommées nécessitant la découverte de SQL Server Browser. Ceux-ci rejettent également explicitement MultiSubnetFailover=yes.
Sous Windows, la valeur par défaut est également désactivée pour les cibles locales brutes telles que localhost.
Un préfixe ou port TCP explicite, tel que tcp:localhost ou localhost,1433, évite cette exclusion de la cible locale. Le paramètre explicite MultiSubnetFailover=yes l’emporte également. 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). |
| Résilience du réseau | Les connexions TCP éligibles utilisent par défaut des tentatives parallèles d’adresses. Le mode parallèle ne priorise pas les adresses selon IpAddressPreference et rejette plus de 64 adresses résolues. Pour les tentatives séquentielles et l’ordre par famille d’adresses, voir Paramètres par défaut de basculement multi-sous-réseau. L’algorithme séparé de Transparent Network IP Resolution (TNIR) n’est pas implémenté. La mise en cache DNS assistée par le serveur permet un repli sur l’adresse en cache en cas de défaillance DNS après une connexion réussie lorsque le serveur autorise la mise en cache. Le routage amélioré est utilisé lorsqu’il est négocié avec le serveur. |
| 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. Sur macOS, Encrypt=Strict les connexions TCP peuvent négocier TLS 1.3 avec un serveur compatible. |
| 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 grands paramètres de texte et binaires sont transmis en flux vers le serveur sur le chemin de liaison ordinaire. Les liaisons SQL_SS_XML et SQL_SS_UDT explicites via setinputsizes() sont aussi transmises en continu lorsque Python sélectionne les données à l’exécution : la taille déclarée doit dépasser 4000 pour str ou 8000 pour bytes ou bytearray. La liaison par type défini par l’utilisateur (UDT) exige que le serveur décrive le type du paramètre. Certaines liaisons personnalisées et mixtes restent mises en mémoire tampon. Pour plus d’informations, voir Problèmes connus. |
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 tapée, et flux texte/binaire volumineux. |
| 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 qu’il n’y a pas de délai d’expiration. Définissez séparément le délai de connexion à l’aide de connect(timeout=...). |
| Délai d’attente de l’opération de connexion |
conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) S’applique aux requêtes réseau appartenant à la connexion, y compris commit, rollback, ainsi que les modifications du catalogue et de l’isolation. La réinitialisation du pool repousse la réinitialisation du serveur à la requête de définition du niveau d’isolation suivante ; cette requête et toute annulation précédente utilisent ce délai d’attente.
0 laisse ces demandes sans limites. Ce délai d’attente est distinct des délais de connexion et de requête et ne constitue pas un délai total d’emprunt d’une connexion au pool. Le nettoyage d’annulation peut augmenter le temps d’appel écoulé. |
| Nettoyage du curseur | La fermeture d’un curseur annule le travail serveur en attente lorsque nécessaire au lieu de lire tous les résultats restants. Le nettoyage de l’instruction préparée respecte le délai d’attente de la requête. Le nettoyage d’annulation comporte un budget d’attente supplémentaire égal au délai d’attente de connexion, ou 120 secondes lorsque ce délai d’attente est 0. |
| 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. |
| Multithreads | Connexions et requêtes concurrentes avec une connexion et un curseur séparés par travailleur. Ne partagez pas les curseurs entre les threads. |
| API de métadonnées |
tables(), rowIdColumns(), rowVerColumns(), procedures(), getTypeInfo(), getinfo(), statistics(), foreignKeys(), primaryKeys() et columns().
SQL_USER_NAME indique l’utilisateur de la base de données plutôt que la chaîne UID de connexion. Les valeurs de capacité et les limites basées sur la taille des paquets peuvent différer de msodbcsql18 : "N" indique SQL_NEED_LONG_DATA_LEN car une entrée longue ne nécessite pas de longueur totale déclarée. Utilisez les capacités et limites retournées. |
| Encodage et convertisseurs | L’encodage par défaut à caractères larges, les convertisseurs de sortie, les paramètres non Unicode conscients du classement et les résultats en caractères étroits dans l’encodage client de la plateforme. Le décodage personnalisé en caractères étroits doit correspondre à cet encodage ; une incompatibilité peut produire un texte incorrect ou bytes. Utilisez conn.setdecoding(mssql_python.SQL_CHAR) pour restaurer le décodage par défaut à caractères larges. Pour la substitution de paramètres non-Unicode, 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.
Si un fetch est en cours d’exécution lorsque vous fermez un arrow_reader(), close() annule le fetch et revient après son arrêt. Fermer un lecteur depuis une requête antérieure n’affecte pas une requête ultérieure sur le même curseur. 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 ces limitations avant de migrer une charge de travail depuis msodbcsql18.
Le tableau suivant indique les exclusions intentionnelles.
| Problème | Details | Solution de contournement |
|---|---|---|
| Authentification par mot de passe Microsoft Entra ID (exclusion intentionnelle) |
Authentication=ActiveDirectoryPassword n’est pas prise en charge, et le support n’est pas prévu car cette méthode ne peut pas satisfaire 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 sélecteur d’authentification numérique (SQL_COPT_SS_AUTHENTICATION) et l’attribut d’intention d’application restent non pris en charge. Le basculement multi-sous-réseau et les attributs de sécurité intégrés sont implémentés. La correspondance des identifiants de métadonnées (SQL_ATTR_METADATA_ID) n’est pas non plus prise en charge. |
Utilisez les mots-clés connection-string Authentication et ApplicationIntent lorsque cela est applicable. |
fork() après la connexion |
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 sur 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. |
| Utilisation de la mémoire avec liaisons personnalisées de paramètres volumineux | Les valeurs de données à l’exécution liées en tant que types à largeur fixe SQL_CHAR, SQL_WCHAR ou SQL_BINARY sont mises en mémoire tampon pour conversion. Mélanger des paramètres en mémoire tampon et des paramètres en flux peut également mettre en mémoire tampon des valeurs volumineuses antérieures en attendant une valeur tampon ultérieure. |
Privilégiez les liaisons par défaut à longueur variable. Évitez les grands forçages à largeur fixe par le biais de setinputsizes() lorsque l’utilisation de la mémoire compte. |
| Substitution de caractères non-Unicode | Pour les caractères situés hors de la page de code cible d’un paramètre non Unicode, le pilote peut remplacer ? lorsque msodbcsql18 utilise un caractère d’approximation. |
Privilégiez les types SQL Unicode et les liaisons de chaîne Python par défaut lorsque le texte doit être conservé. |
| Modifications du niveau d’isolation après SQL brut | Après le RAW SET TRANSACTION ISOLATION LEVEL, le fait de définir l’attribut de connexion au niveau mis en cache du pilote peut renvoyer un succès sans restaurer ce niveau sur le serveur. (#798) |
Évitez de mélanger le SQL brut et les changements d’isolation basés sur les attributs. Utilisez un SET TRANSACTION ISOLATION LEVEL explicite lors de la restauration du niveau. |
| 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. Les résultats dépendent de la plateforme et de la charge de travail. (#473) |
Évaluez votre charge de travail. |
Cette liste n’est pas exhaustive.
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 :
- Problèmes de pilote Rust : https://github.com/microsoft/mssql-rs/issues
-
mssql-pythonproblèmes: https://github.com/microsoft/mssql-python/issues
Sous Windows, définissez ces variables dans PowerShell avant de lancer Python pour collecter des diagnostics du pilote natif. Reproduire le problème en sélectionnant mssql-odbc.
Sous Linux, laissez MSSQL_TDS_TRACE non défini en raison de l’échec à la sortie du processus décrit dans Problèmes connus.
$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 active le traçage, MSSQL_TDS_TRACE_LEVEL sélectionne le filtre de journal et MSSQL_TDS_TRACE_DIR sélectionne le répertoire des fichiers de traçage par processus depuis le pilote ODBC natif au lieu de la sortie d’erreur standard.
MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB définit le seuil de roulement par fichier (100 MiB par défaut ; accepte 1-1024). Ce n’est pas une limite totale d’espace disque : les fichiers individuels peuvent dépasser ce seuil, et les anciens fichiers ne sont pas supprimés.
Le paquet compagnon Rust crée également des fichiers journaux sous mssql_python_logs dans le répertoire courant. Redémarrez Python après avoir modifié ces paramètres.
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.