Chaînes de connexion pour mssql-python

Le pilote mssql-python prend en compte les mots-clés suivants de chaîne de connexion lors de la connexion à SQL Server, Azure SQL Database, Azure SQL Managed Instance et SQL database dans Microsoft Fabric.

Syntaxe de la chaîne de connexion

Les chaînes de connexion utilisent des paires clé-valeur séparées par point-virgule :

keyword1=value1;keyword2=value2;...

Valeurs d’enveloppe contenant des caractères spéciaux (points-virgules, signes égals ou entrethèses à spirales) entre entrecoupées :

PWD={my;complex=password}

Pour inclure une accolade de fermeture littérale dans une valeur, utilisez deux attelles-fermes (}}) :

PWD={password}}with}}brace}

Exemples de connexion de base

Les exemples suivants montrent comment se connecter en utilisant différentes méthodes d’authentification. Pour les applications de production, utilisez l’authentification Microsoft Entra dès que possible. Cela élimine les mots de passe de votre code et des chaînes de connexion.

SQL Server avec authentification Microsoft Entra (recommandé)

Cet exemple utilise ActiveDirectoryDefault, qui essaie plusieurs sources d’identifiants (Azure CLI, variables d’environnement, identité gérée) dans l’ordre. Aucun mot de passe n’est enregistré dans le code :

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Authentication=ActiveDirectoryDefault;Encrypt=yes;"
)

SQL Server avec authentification SQL

Utilisez l’authentification SQL uniquement pour le développement local sur une instance SQL Server que vous contrôlez. Les identifiants sont intégrés dans la chaîne de connexion, donc gardez-les dans des variables d’environnement ou dans un .env fichier plutôt que dans le code source :

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=<database>;"
    "UID=<login>;"
    "PWD=<password>;"
    "Encrypt=yes;"
)

Azure SQL avec authentification Microsoft Entra

La chaîne de connexion pour Azure SQL Database est la même que pour SQL Server. ActiveDirectoryDefaultfonctionne entre le développement local, les conteneurs et les environnements hébergés sur Azure sans modifications de code :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Utilisez des arguments de mots-clés

Vous pouvez passer des paramètres de connexion comme arguments de mots-clés au lieu ou en plus d’un chaîne de connexion. Les arguments de mots-clés évitent les écueils échappants de l’assemblage de chaîne de connexion. Les mots de passe avec des caractères spéciaux comme @, ;, {, ou } qui n’ont pas besoin d’un enroulement à crochets lorsqu’ils sont passés comme arguments de mots-clés :

conn = mssql_python.connect(
    server="<server>.database.windows.net",
    database="<database>",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Comparez avec l’assemblage de chaîne de connexion, où un mot de passe contenant @ doit être enveloppé :

# Connection string requires escaping
conn = mssql_python.connect("Server=srv;UID=user;PWD={p@ss;word};")

# Keyword arguments - no escaping needed
conn = mssql_python.connect(server="srv", uid="user", pwd="p@ss;word")

Le pilote fusionne les arguments de mots-clés dans la chaîne de connexion après normalisation. Si un argument de mot-clé correspond à un paramètre déjà présent dans la chaîne de connexion, l’argument de mot-clé prend la priorité et supprime la valeur de la chaîne de connexion :

# The keyword argument database="production" overrides Database=dev in the connection string
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;Encrypt=yes;",
    database="production",
    authentication="ActiveDirectoryDefault"
)
# Connects to "production", not "dev"

L’exemple suivant combine une chaîne de connexion avec des arguments de mots-clés :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;Database=<database>;",
    authentication="ActiveDirectoryDefault",
    encrypt="yes"
)

Mots-clés de chaîne de connexion

Serveur et base de données

Spécifiez l’instance SQL Server cible et la base de données pour la connexion.

Authentication

Fournir des identifiants pour l’authentification SQL ou spécifier un mode d’authentification Microsoft Entra. Pour les options sans mot de passe, voir les modes d’authentification Microsoft Entra.

Chiffrement et sécurité

Toutes les connexions sont utilisées Encrypt=yes par défaut. Pour la plupart des applications, le défaut est suffisant. Utilisez-le strict uniquement lorsque votre instance SQL Server prend en charge TDS 8.0 et que vous avez besoin de TLS 1.3. À utiliser TrustServerCertificate=yes uniquement dans des environnements de développement avec des certificats auto-signés.

Haute disponibilité et basculement

Ces mots-clés s’appliquent aux déploiements de groupes de disponibilité Always On. Réglez ApplicationIntent=ReadOnly pour router les charges de travail à forte intensité de lecture (rapports, analyses) vers des répliques secondaires, réduisant ainsi la charge sur le principal. Définissez MultiSubnetFailover=yes quand votre groupe de disponibilité couvre plusieurs sous-réseaux.

Performance et réseau

Les paramètres par défaut fonctionnent pour la plupart des applications. Augmentation PacketSize (jusqu’à 32767) pour les transferts de données en masse. Configurez KeepAlive si les connexions franchissent des pare-feux ou des équilibreurs de charge qui coupent les sessions TCP inactives.

Mots clés réservés

Modes d’authentification Microsoft Entra

Le Authentication mot-clé prend en charge les valeurs suivantes. Choisissez le mode qui correspond à votre déploiement :

Pour la configuration reproductible de Docker, devcontainer et environnement CI, voir Conteneur et développement local. Cet article centralise la sélection à l’exécution Python et montre comment utiliser des images épinglées dans des digestes dans des environnements partagés.

Exemple : DefaultAzureCredential

ActiveDirectoryDefaultcorrespond à la chaîne d’identité DefaultAzureCredential Azure. Il essaie d’abord le token Azure CLI lors du développement local, puis l’identité gérée lors du déploiement sur Azure :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDefault;"
    "Encrypt=yes;"
)

Exemple : Flux de code de périphérique

Utilisez le flux de code de l’appareil lors de l’exécution dans des environnements sans navigateur, comme les sessions SSH ou les conteneurs Docker. Le pilote affiche une URL et un code à saisir sur un appareil séparé :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryDeviceCode;"
    "Encrypt=yes;"
)
# Follow the prompt to authenticate at https://microsoft.com/devicelogin

Exemple : Principal de service

L’authentification du principal de service utilise une identité d’application enregistrée avec un identifiant client et un secret. Utilisez cette approche pour les pipelines CI/CD et les services en arrière-plan qui fonctionnent sans interaction utilisateur :

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes;"
)

Pour enregistrer l’application et lui accorder l’accès à la base de données, voir Microsoft Entra service principals avec Azure SQL. Pour la configuration complète dans mssql-python, voir authentification du principal de service.

Délai d’expiration de la connexion

Réglez le délai de connexion à l’aide du timeout paramètre. Utilisez un délai d’attente pour éviter que votre application ne reste en blocage indéfiniment lorsque le serveur est injoignable :

# 30-second connection timeout
conn = mssql_python.connect(connection_string, timeout=30)

Vous pouvez aussi modifier le délai d’attente d’une connexion existante :

conn.timeout = 60

Mode de validation automatique

Par défaut, autocommit est False, ce qui nécessite des appels explicites commit() . Activez l’autocommit pour les instructions DDL ou les requêtes en lecture seule qui n’ont pas besoin de contrôle de transaction :

# Via parameter
conn = mssql_python.connect(connection_string, autocommit=True)

# Or after connection
conn.setautocommit(True)

Attributs de connexion

Définissez les attributs de connexion ODBC avant l’établissement de la connexion en utilisant attrs_before:

import mssql_python

conn = mssql_python.connect(
    connection_string,
    attrs_before={
        mssql_python.SQL_ATTR_LOGIN_TIMEOUT: 30,
        mssql_python.SQL_ATTR_CONNECTION_TIMEOUT: 60,
    }
)

Construction de chaîne de connexion programmatique

Pour éviter l'injection de chaîne de connexion, n'utilisez pas la concaténation de chaînes ni les f-strings avec l'entrée utilisateur. Utilisez plutôt des arguments de mots-clés ou des variables d’environnement. Pour plus de modèles de construction incluant les fichiers de configuration JSON/YAML, Azure Key Vault et une classe builder, voir Build connection strings programmatiquement.

import os

conn = mssql_python.connect(
    server=os.environ["DB_SERVER"],
    database=os.environ["DB_NAME"],
    authentication=os.environ.get("DB_AUTH", "ActiveDirectoryDefault"),
    encrypt="yes"
)

Validation de la chaîne de connexion

Le pilote valide les chaînes de connexion et augmente ConnectionStringParseError les mots-clés inconnus ou mal orthographiés :

try:
    conn = mssql_python.connect("Servr=localhost;")  # Typo
except mssql_python.ConnectionStringParseError as e:
    print(f"Invalid connection string: {e}")
    # Output: Unknown keyword 'Servr'

Contenu connexe

• Construire les chaînes de connexion de façon programmatique
• Installer mssql-python
• Authentification Microsoft Entra
• Regroupement de connexions
• Gestion des connexions