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-tête. Les frameworks web tels que Flask et FastAPI convertissent souvent les lignes en dictionnaires, ce qui rend la cohérence des casiers 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', ...)

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

Vous pouvez aussi définir native_uuid par connexion :

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

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 :

Sécurité du filetage

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

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 :

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__)  # e.g., '1.5.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()

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

Contenu connexe

• Chaînes de connexion
• Gestion des connexions
• Mappages de types de données