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.

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.

Mot clé Alias Default Description
Server addr, address None Nom d’hôte, adresse IP ou instance nommée de SQL Server. Pour les instances nommées, utilisez server\instance. Pour Azure SQL, utilisez server.database.windows.net. Pour spécifier un port, utilisez server,port.
Database None None Nom de la base de données auquel se connecter.

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.

Mot clé Alias Default Description
UID uid None Nom d’utilisateur pour l’authentification SQL.
PWD pwd None Mot de passe pour l’authentification SQL.
Trusted_Connection trusted_connection no Utilisez l’authentification intégrée Windows. Définissez la valeur sur yes pour activer.
Authentication authentication None Mode d’authentification Microsoft Entra. Consultez l’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.

Mot clé Alias Default Description
Encrypt encrypt yes Activez le chiffrement TLS. Valeurs : yes, no, strict. Utilisez strict pour TDS 8.0 avec TLS 1.3 obligatoire.
TrustServerCertificate trust_server_certificate, trustservercertificate no Faites confiance aux certificats serveur auto-signés sans validation. Réglé sur yes pour développement uniquement.
HostnameInCertificate hostnameincertificate None Nom d’hôte attendu dans le certificat TLS du serveur.
ServerCertificate servercertificate None Chemin vers un fichier PEM contenant l’autorité de certification de confiance.
ServerSPN serverspn None Nom principal du service serveur pour l’authentification Kerberos.

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.

Mot clé Alias Default Description
MultiSubnetFailover multisubnetfailover no Activez le basculement multi-sous-réseaux pour les groupes de disponibilité Always On.
ApplicationIntent applicationintent ReadWrite Déclarez le type de charge de travail de l’application. À utiliser ReadOnly pour le routage en lecture seule vers des répliques secondaires.
ConnectRetryCount connectretrycount 1 Nombre de tentatives de reconnexion automatique pour la résilience de la connexion au repos. Il s’agit d’une fonctionnalité au niveau du pilote pour les connexions inactives coupées, et non d’un substitut à la logique de réessayage au niveau de l’application.
ConnectRetryInterval connectretryinterval 10 Quelques secondes entre les tentatives de résilience de la connexion au repos.

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.

Mot clé Alias Default Description
PacketSize packet size, packetsize 4096 Taille du paquet réseau en octets (512–32767).
KeepAlive keepalive None Intervalle TCP de maintien en vie en quelques secondes.
KeepAliveInterval keepaliveinterval None Intervalle de réessai TCP keep-alive en quelques secondes.
IpAddressPreference ipaddresspreference None Préférence de famille d’adresses IP : IPv4First, IPv6First, UsePlatformDefault.

Mots clés réservés

Mot clé Description
Driver Réservé à une utilisation interne. Le conducteur gère cette valeur automatiquement.
APP Réservé. Toujours réglé sur "MSSQL-Python" par le conducteur.

Modes d’authentification Microsoft Entra

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

Valeur Description Quand utiliser
ActiveDirectoryDefault Utilisations DefaultAzureCredential issues du SDK Azure Identity. Essaie plusieurs méthodes d’authentification en séquence. Développement local à travers Azure CLI, Azure PowerShell et Azure Developer CLI. Pour la production, utilisez un mode spécifique (ActiveDirectoryMSI, ActiveDirectoryServicePrincipal) pour éviter la lenteur de la chaîne des accréditations.
ActiveDirectoryInteractive Connexion interactive basée sur navigateur. Sous Windows, il délègue nativement au pilote ODBC. Le développement local et les outils où un utilisateur est présent pour s’authentifier dans un navigateur.
ActiveDirectoryDeviceCode Flux de code de dispositif pour les environnements sans interface interlocuteur. Affiche un code à saisir à https://microsoft.com/devicelogin. Sessions SSH, conteneurs Docker ou autres environnements sans navigateur.
ActiveDirectoryPassword Deprecated. Authentification par nom d’utilisateur et mot de passe avec Microsoft Entra ID. Nécessite UID et PWD. Utilise le flux ROPC, qui est incompatible avec la MFA. Non recommandé. Utilisez plutôt ActiveDirectoryMSI ou ActiveDirectoryServicePrincipal.
ActiveDirectoryMSI Identité de service géré pour les applications hébergées sur Azure. Azure VMs, App Service ou Azure Functions où l’identité gérée est configurée. Aucune information d’identification n’est nécessaire.
ActiveDirectoryServicePrincipal Authentification du principal de service. Nécessite UID (identifiant client) et PWD (client secret). Les pipelines CI/CD et les services en arrière-plan utilisant une identité d’application enregistrée.
ActiveDirectoryIntegrated Authentification intégrée Windows avec Microsoft Entra ID (Kerberos). Machines Windows jointes au domaine dans des environnements d’entreprise avec Kerberos configuré.

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

  • Last updated on