Configurer les paramètres du module mssql-python

Le pilote mssql-python fournit une Settings classe qui contrôle le comportement à l’échelle du module. Ces réglages affectent toutes les connexions et les opérations du curseur. Configurez-les une fois au démarrage de l’application, avant de créer des connexions.

Paramètres d’accès

Récupérer l’objet actuel Settings et inspecter ou modifier ses propriétés :

import mssql_python

# Get settings object
settings = mssql_python.get_settings()

# Check current values
print(settings.lowercase)
print(settings.decimal_separator)

Paramètres disponibles

Les paramètres suivants contrôlent la manière dont le pilote retourne les données et forme les résultats.

Minuscules

Le paramètre lowercase contrôle si les noms de colonnes dans cursor.description apparaissent en minuscules. Activez ce paramètre lorsque votre application accède aux colonnes par nom et que vous souhaitez éviter les incompatibilités de casse. Les frameworks web tels que Flask et FastAPI convertissent souvent les lignes en dictionnaires, ce qui rend la cohérence de la casse essentielle :

settings = mssql_python.get_settings()

# Enable lowercase column names (default: False)
settings.lowercase = True

# Column names in cursor.description are now lowercased:
# ('productid', ...) instead of ('ProductID', ...)

Valeur	Description
`False`	Default. Les noms des colonnes conservent la casse d’origine.
`True`	Les noms de colonnes dans `cursor.description` sont convertis en minuscules.

Séparateur décimal

Le pilote fournit des fonctions au niveau du module pour contrôler le séparateur décimal lors des conversions numériques. Changez ce paramètre uniquement si votre instance SQL Server utilise un lieu avec une virgule comme séparateur décimal, comme les localités françaises ou allemandes. La plupart des applications n’ont pas besoin de modifier ce paramètre :

import mssql_python

# Get current separator
sep = mssql_python.getDecimalSeparator()
print(f"Current separator: {sep}")  # Usually "."

# Set custom separator (for locales using comma)
mssql_python.setDecimalSeparator(",")

Pour plus d’informations sur la gestion des nombres décimaux, voir Correspondance des types de données.

native_uuid

Le native_uuid paramètre contrôle si UNIQUEIDENTIFIER les colonnes sont retournées sous forme d’objets Python uuid.UUID ou sous forme de chaînes majuscules compatibles avec pyodbc. Ce paramètre est utile pour les équipes migrant depuis pyodbc qui dépendent des valeurs UUID de chaîne :

settings = mssql_python.get_settings()

# Return UUIDs as uuid.UUID objects (default: True)
settings.native_uuid = True

# Return UUIDs as uppercase strings (pyodbc-compatible)
settings.native_uuid = False

Valeur	Description
`True`	Default. `UNIQUEIDENTIFIER` colonnes retournent `uuid.UUID` objets.
`False`	`UNIQUEIDENTIFIER` Les colonnes renvoient des chaînes en majuscules (compatibles avec pyodbc).

Vous pouvez aussi définir native_uuid par connexion :

# Override for a specific connection
conn = mssql_python.connect(connection_string, native_uuid=False)

Note

Le native_uuid cadre a été introduit dans mssql-python version 1.5.0.

Sélectionnez le fournisseur ODBC natif

Le pilote charge un fournisseur ODBC natif par processus. Deux prestataires sont disponibles :

Provider	Description	Expédié sous
`msodbcsql18`	Default. Microsoft ODBC Driver 18 pour SQL Server.	`mssql-python-odbc`
`mssql-odbc`	Opt-in. Un fournisseur ODBC basé sur Rust.	`mssql-python-rs`

Les deux packages s’installent avec pip install mssql-python, donc vous n’avez pas besoin d’installer autre chose pour essayer le mssql-odbc fournisseur. Le code de votre application ne change pas.

Sélectionnez le fournisseur avec la variable d’environnement MSSQL_PYTHON_NATIVE_PROVIDER. Sur Linux ou macOS :

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

Sur Windows PowerShell :

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Ou alors définir l’attribut de module native_provider avant d’ouvrir la première connexion :

import mssql_python

mssql_python.native_provider = "mssql-odbc"

conn = mssql_python.connect(connection_string)
print(mssql_python.get_native_provider_info())

La get_native_provider_info() fonction retourne le fournisseur sélectionné et l’origine de la sélection :

{'id': 'mssql-odbc', 'package': 'mssql_py_core', 'version': None, 'driver_path': '...', 'source': 'property', 'frozen': True}

Le pilote applique ces règles lorsqu’il résout le fournisseur de services :

La variable d’environnement a la priorité sur l’attribut native_provider. Si vous définissez l’attribut à un fournisseur différent de la variable d’environnement, le pilote émet RuntimeWarning et utilise la variable d’environnement.
La sélection est fixée lorsque le pilote charge le fournisseur, ce qui se produit après que la chaîne de connexion a été analysée et avant que le pilote ne contacte le serveur. La sélection reste fixe même si la connexion échoue ensuite, par exemple parce que le serveur est inaccessible. Une erreur générée avant le chargement du fournisseur, comme une erreur d'analyse de chaîne de connexion ou un package de fournisseur manquant, ne résout pas le problème de sélection. Une fois la sélection fixée, une modification de native_provider émet RuntimeWarning et n’a aucun effet sur le reste du processus.
Un nom de prestataire non reconnu génère ValueError. Définir l’attribut sur un nom inconnu provoque immédiatement une erreur. Un nom inconnu dans la variable environnement provoque une erreur lorsque vous ouvrez la première connexion. Le pilote ne se rabat pas sur le fournisseur par défaut.
Réglez native_provider sur None pour effacer une sélection avant la première connexion.

Constantes au niveau du module

Le pilote expose des constantes de conformité en lecture seule DB-API 2.0 qui décrivent ses capacités. Utilisez ces constantes pour écrire un code qui s’adapte à différents pilotes DB-API :

import mssql_python

# DB-API 2.0 compliance level
print(mssql_python.apilevel)      # '2.0'

# Thread safety level
print(mssql_python.threadsafety)  # 1

# Parameter style
print(mssql_python.paramstyle)    # 'pyformat'

niveau d'API

La constante apilevel indique le niveau de conformité à la DB-API :

Valeur	Meaning
`'2.0'`	Conformité DB-API 2.0 complète.

Sécurité du filetage

Le threadsafety constant rapporte le niveau de sécurité du fil :

Valeur	Meaning
`0`	Les fils de discussion ne peuvent pas partager le module.
`1`	Les threads peuvent partager le module mais pas les connexions.
`2`	Les threads peuvent partager le module et les connexions.
`3`	Les threads peuvent partager le module, les connexions et les curseurs.

Le pilote mssql-python utilise threadsafety = 1, ce qui signifie :

Vous pouvez importer et utiliser le module entre threads.
Chaque connexion doit appartenir à un seul thread à la fois.
Créez une connexion séparée par thread, ou utilisez un pool de connexions (activé par défaut). Pour plus d’informations, voir Mise en pool de connexions.

paramstyle

La paramstyle constante rapporte le format de placement provisoire des paramètres :

Style	Format	Exemple :
`'qmark'`	Points d’interrogation	`WHERE id = ?`
`'numeric'`	Position numérale	`WHERE id = :1`
`'named'`	Nommé	`WHERE id = :id`
`'format'`	ANSI C printf	`WHERE id = %s`
`'pyformat'`	Format Python	`WHERE id = %(id)s`

Le pilote mssql-python utilise paramstyle = 'pyformat'. Utilisez toujours des paramètres nommés pour éviter l’injection SQL. Ne construisez jamais de requêtes à partir d’entrées utilisateur en utilisant le formatage de chaînes ou des f-strings :

# Use named parameters with %(name)s syntax
cursor.execute(
    "SELECT * FROM Production.Product WHERE ProductSubcategoryID = %(cat)s AND ListPrice > %(price)s",
    {"cat": 5, "price": 10.00}
)

Détails de version

Vérifiez quelle version du pilote est installée :

import mssql_python

# Driver version
print(mssql_python.__version__)  # For example, '1.16.0'

Configurez les paramètres au démarrage

Définissez la configuration du module une fois au démarrage de l’application, avant de créer des connexions. Définir les valeurs tôt évite les comportements incohérents entre les connexions :

import mssql_python

def configure_driver():
    """Configure mssql-python settings for this application."""
    settings = mssql_python.get_settings()
    
    # Use lowercase column names in cursor.description
    settings.lowercase = True

# Call at application startup
configure_driver()

# All subsequent connections use these settings
conn = mssql_python.connect(connection_string)

Considérations de sécurité du filetage

Les paramètres du module sont globaux et affectent toutes les connexions entre tous les threads. Si vous changez un réglage après que les connexions sont déjà disponibles, les connexions existantes ne reflètent peut-être pas le changement de manière cohérente. Définissez toutes les valeurs de configuration avant de créer votre première connexion :

import mssql_python
import threading

# Settings changes affect all threads
settings = mssql_python.get_settings()
settings.lowercase = True  # Affects all connections in all threads

def worker():
    # This connection uses the global settings
    conn = mssql_python.connect(connection_string)
    cursor = conn.cursor()
    cursor.execute("SELECT Name FROM Production.Product")
    row = cursor.fetchone()
    print(cursor.description[0][0])  # 'name' due to global setting

threads = [threading.Thread(target=worker) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Important

Configurez les paramètres avant de créer des connexions. Changer les paramètres après la création des connexions peut entraîner des comportements incohérents.

Configuration spécifique à la connexion

Vous pouvez contourner certains paramètres par connexion sans changer la règle globale par défaut. Utilisez des overrides par connexion lorsque différentes parties de votre application nécessitent un comportement différent. Par exemple, un module de génération de rapports peut nécessiter des UUID sous forme de chaîne, alors que le reste de l’application utilise des objets uuid.UUID :

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

# Use the autocommit property
conn.autocommit = True

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-10-19