Attributs et mots clés de chaîne de connexion et DSN
Cette page liste les mots clés des chaînes de connexion et des noms de source de données pour SQLSetConnectAttr et SQLGetConnectAttr, disponibles dans le pilote ODBC pour SQL Server.
Attributs de connexion et mots clés de chaîne de connexion et de nom de source de données pris en charge
Le tableau suivant liste les mots clés disponibles et les attributs pour chaque plateforme (L : Linux, M : macOS, W : Windows). Pour plus d’informations, sélectionnez le mot clé ou l’attribut.
Voici des mots clés de chaîne de connexion et des attributs de connexion qui ne sont pas documentés dans Utilisation de mots clés de chaîne de connexion avec SQL Server Native Client, SQLSetConnectAttr et Fonction SQLSetConnectAttr.
Description
Utilisé pour décrire la source de données.
SQL_COPT_SS_ANSI_OEM
Contrôle la conversion ANSI vers OEM des données.
| Valeur d'attribut | Description |
|---|---|
| SQL_AO_OFF | (Par défaut) La traduction n’est pas effectuée. |
| SQL_AO_ON | La traduction est effectuée. |
SQL_COPT_SS_AUTOBEGINTXN
Version 17.6+ alors que la validation automatique est désactivée, contrôle la BEGIN TRANSACTION automatique après ROLLBACK ou COMMIT.
| Valeur d'attribut | Description |
|---|---|
| SQL_AUTOBEGINTXN_ON | (Par défaut) BEGIN TRANSACTION automatique après ROLLBACK ou COMMIT. |
| SQL_AUTOBEGINTXN_OFF | Aucun BEGIN TRANSACTION automatique après ROLLBACK ou COMMIT. |
SQL_COPT_SS_FALLBACK_CONNECT
Contrôle l’utilisation de connexions de secours SQL Server. Cet attribut n’est plus pris en charge.
| Valeur d'attribut | Description |
|---|---|
| SQL_FB_OFF | (Valeur par défaut) Les connexions de secours sont désactivées. |
| SQL_FB_ON | Les connexions de secours sont activées. |
Nouveaux attributs de connexion et mots clés de chaîne de connexion
Authentification - SQL_COPT_SS_AUTHENTICATION
Définit le mode d’authentification à utiliser lors de la connexion à SQL Server. Pour plus d’informations, consultez Utilisation de Microsoft Entra ID.
| Valeur de mot clé | Valeur d'attribut | Description |
|---|---|---|
| SQL_AU_NONE | (Valeur par défaut) Non défini. La combinaison des autres attributs détermine le mode d’authentification. | |
| SqlPassword | SQL_AU_PASSWORD | Authentification SQL Server avec nom d’utilisateur et mot de passe. |
| ActiveDirectoryIntegrated | SQL_AU_AD_INTEGRATED | Authentification intégrée Microsoft Entra. |
| ActiveDirectoryPassword | SQL_AU_AD_PASSWORD | Authentification par mot de passe Microsoft Entra. |
| ActiveDirectoryInteractive | SQL_AU_AD_INTERACTIVE | Authentification interactive Microsoft Entra. |
| ActiveDirectoryMsi | SQL_AU_AD_MSI | Authentification à l’aide d’une identité managée Microsoft Entra. Pour l’identité attribuée par l’utilisateur, UID est défini sur l’ID d’objet de l’identité d’utilisateur. |
| ActiveDirectoryServicePrincipal | SQL_AU_AD_SPA | Authentification du principal de service Microsoft Entra. UID est défini sur l’ID client du principal de service. PWD est défini sur le secret client. |
| SQL_AU_RESET | Non défini. Remplace tout nom de source de données ou paramètre de chaîne de connexion. |
Notes
Quand vous utilisez le mot clé ou l’attribut Authentication, vous devez explicitement définir le paramètre Encrypt sur la valeur souhaitée dans la chaîne de connexion / le nom de source de données / l’attribut de connexion. Pour plus d’informations, consultez Utilisation de mots clés de chaîne de connexion avec SQL Server Native Client.
ColumnEncryption - SQL_COPT_SS_COLUMN_ENCRYPTION
Contrôle le chiffrement transparent des colonnes (Always Encrypted). Pour plus d’informations, consultez Utilisation d’Always Encrypted (ODBC).
| Valeur de mot clé | Valeur d'attribut | Description |
|---|---|---|
| activé | SQL_CE_ENABLED | Active Always Encrypted. |
| Désactivé | SQL_CE_DISABLED | (Valeur par défaut) Désactive Always Encrypted. |
| SQL_CE_RESULTSETONLY | Active le déchiffrement uniquement (résultats et valeurs de retour). |
Encrypt (Chiffrer)
Spécifie si les connexions utilisent le chiffrement TLS sur le réseau. Les valeurs possibles sont yes/mandatory(18.0+), no/optional(18.0+) et strict(18.0+). La valeur par défaut est yes dans la version 18.0+ et no dans les versions précédentes.
Quel que soit le paramètre défini pour Encrypt, les informations de connexion du serveur (nom d’utilisateur et mot de passe) sont toujours chiffrées.
Les paramètres Encrypt, TrustServerCertificate et le paramètre Force Encryption côté serveur jouent un rôle dans le chiffrement des connexions sur le réseau. Les tableaux suivants montrent l’effet de ces paramètres.
ODBC Driver 18 et versions ultérieures
| Paramètre de chiffrement | Faire confiance au certificat de serveur | Chiffrement forcé du serveur | Résultat |
|---|---|---|---|
| Non | Non | Non | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur ne sont pas chiffrées. |
| Non | Oui | Non | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur ne sont pas chiffrées. |
| Oui | No | Non | Le certificat de serveur est vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Oui | Oui | Non | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Non | Non | Oui | Le certificat de serveur est vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Non | Oui | Oui | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Oui | No | Oui | Le certificat de serveur est vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Oui | Oui | Oui | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Strict | - | - | TrustServerCertificate est ignoré. Le certificat de serveur est vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
Notes
Strict est uniquement disponible sur les serveurs qui prennent en charge les connexions TDS 8.0.
ODBC Driver 17 et versions antérieures
| Paramètre de chiffrement | Faire confiance au certificat de serveur | Chiffrement forcé du serveur | Résultat |
|---|---|---|---|
| Non | Non | Non | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur ne sont pas chiffrées. |
| Non | Oui | Non | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur ne sont pas chiffrées. |
| Oui | No | Non | Le certificat de serveur est vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Oui | Oui | Non | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Non | Non | Oui | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Non | Oui | Oui | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Oui | No | Oui | Le certificat de serveur est vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
| Oui | Oui | Oui | Le certificat de serveur n’est pas vérifié. Les données envoyées entre le client et le serveur sont chiffrées. |
TransparentNetworkIPResolution - SQL_COPT_SS_TNIR
Contrôle la fonctionnalité Résolution d’adresses IP réseau transparente, qui interagit avec MultiSubnetFailover pour autoriser les tentatives de reconnexion plus rapides. Pour plus d’informations, consultez Utilisation de la résolution d’adresses IP réseau transparente.
| Valeur de mot clé | Valeur d'attribut | Description |
|---|---|---|
| activé | SQL_IS_ON | (Par défaut) Active la résolution transparente d’adresses IP réseau. |
| Désactivé | SQL_IS_OFF | Désactive la résolution d’adresses IP réseau transparente. |
UseFMTONLY
Contrôle l’utilisation de SET FMTONLY pour les métadonnées lors de la connexion à SQL Server versions 2012 et ultérieures.
| Valeur de mot clé | Description |
|---|---|
| Non | (Valeur par défaut) Utiliser sp_describe_first_result_set pour les métadonnées si elles sont disponibles. |
| Oui | Utiliser SET FMTONLY pour les métadonnées. |
Réplication
Spécifie l’utilisation d’une connexion de réplication sur la version 17.8 et les versions ultérieures du pilote ODBC.
| Valeur de mot clé | Description |
|---|---|
| Non | (Par défaut) La connexion de réplication n’est pas utilisée. |
| Oui | Les déclencheurs comportant l’option NOT FOR REPLICATION ne sont pas activés sur la connexion. |
RetryExec
La logique de nouvelle tentative configurable est disponible à compter de la version 18.1. Elle réexécute automatiquement des appels de fonction ODBC spécifiques sur la base de conditions configurables. Cette fonctionnalité peut être activée via la chaîne de connexion à l’aide du mot clé RetryExec, ainsi qu’une liste de règles de nouvelle tentative. Chaque règle de nouvelle tentative comporte trois composants séparés par deux points : une correspondance d’erreur, une stratégie de nouvelle tentative et une correspondance de requête.
La correspondance de requête détermine la règle de nouvelle tentative à utiliser pour une exécution donnée. Elle est comparée avec le texte de commande entrant (SQLExecDirect) ou le texte de commande préparé dans l’objet d’instruction (SQLExecute). Si plusieurs règles correspondent, la première correspondance dans la liste est utilisée. Ce comportement permet aux règles d’être répertoriées dans l’ordre de généralité croissante. Si aucune correspondance n’est établie avec une règle, aucune nouvelle tentative n’est appliquée.
Lorsque l’exécution entraîne une erreur et qu’il existe une règle de nouvelle tentative applicable, sa correspondance d’erreur est utilisée pour déterminer si l’exécution doit être retentée.
La valeur du mot clé RetryExec est une liste de règles de nouvelle tentative séparées par des points-virgules.
RetryExec={rule1;rule2}
Une règle de nouvelle tentative se présente comme suit : <errormatch>:<retrypolicy>:<querymatch>
Correspondance d’erreur : liste de codes d’erreur séparés par des virgules. Par exemple, vous pouvez spécifier 1000,2000 comme codes d’erreur à réessayer.
Stratégie de nouvelle tentative : spécifie le délai jusqu’à la nouvelle tentative suivante. Le premier paramètre correspond au nombre de nouvelles tentatives alors que la seconde correspond au délai. Par exemple, 3,10+7 correspond à 3 tentatives commençant à 10 et chaque nouvelle tentative suivante effectue une incrémentation de 7 secondes. Si +7 n’est pas spécifié, chaque nouvelle tentative suivante est doublée de façon exponentielle.
Correspondance de requête : spécifie la requête avec laquelle établir une correspondance. Si rien n’est spécifié, celle-ci s’applique à toutes les requêtes. La spécification de SELECT s’applique à toutes les requêtes qui commencent par SELECT.
Il est possible de combiner les trois composants ci-dessus dans une chaîne de connexion comme suit :
RetryExec={1000,2000:3,10+7:SELECT}
Cela signifie : « Pour les erreurs 1000 et 2000, sur une requête qui commence par SELECT, réessayer deux fois avec un délai initial de 10 secondes et ajouter 7 secondes pour chaque tentative suivante »
Exemples
40501,40540:4,5
Pour les erreurs 40501 et 40540, réessayez jusqu’à quatre fois, avec un délai initial de 5 secondes et un doublement exponentiel entre chaque nouvelle tentative. Cette règle s’applique à toutes les requêtes.
49919:2,10+:CREATE
Pour l’erreur 49919 sur une requête qui commence par CREATE, réessayez deux fois au maximum, initialement après 10 secondes, puis 20 secondes.
49918,40501,10928:5,10+5:SELECT c1
Pour les erreurs 49918, 40501 et 10928 sur les requêtes commençant par SELECT c1, réessayez jusqu’à cinq fois, en attendant 10 secondes à la première nouvelle tentative et en augmentant l’attente de 5 secondes par la suite.
Les trois règles ci-dessus peuvent être spécifiées ensemble dans la chaîne de connexion comme suit :
RetryExec={49918,40501,10928:5,10+5:SELECT c1;49919:2,10+:CREATE;40501,40540:4,5}
La règle la plus générale (match-all) est placée à la fin, pour permettre aux deux règles les plus spécifiques avant celle-ci d’établir une correspondance avec leurs requêtes respectives.
ClientCertificate
Spécifie le certificat à utiliser pour l’authentification. Les options sont :
| Valeur d’option | Description |
|---|---|
sha1:<hash_value> |
le pilote ODBC utilise le hachage SHA1 pour localiser un certificat dans Windows Certificate Store |
subject:<subject> |
le pilote ODBC utilise l’objet pour localiser un certificat dans Windows Certificate Store |
file:<file_location>[,password:<password>] |
le pilote ODBC utilise un fichier de certificat. |
Si le certificat est au format PFX et que la clé privée dans le certificat PFX est protégée par un mot de passe, le mot de passe est requis. Pour les certificats aux formats PEM et DER, l’attribut ClientKey est requis
ClientKey
Spécifie l’emplacement de fichier de la clé privée pour les certificats PEM ou DER spécifiés par l’attribut ClientCertificate. Format:
| Valeur d’option | Description |
|---|---|
file:<file_location>[,password:<password>] |
Spécifie l’emplacement du fichier de la clé privée. |
Si le fichier de la clé privée est protégé par un mot de passe, le mot de passe est requis. Si le mot de passe contient des caractères ,, un caractère , supplémentaire est ajouté immédiatement après chacun d’eux. Par exemple, si le mot de passe est a,b,c, le mot de passe échappé présent dans la chaîne de connexion est a,,b,,c.
HostnameInCertificate
Spécifie le nom d’hôte attendu dans le certificat de serveur pendant la négociation du chiffrement, s’il diffère de la valeur par défaut dérivée de Addr/Address/Server. L’option HostnameInCertificate est ignorée lorsque l’option ServerCertificate est utilisée.
IpAddressPreference
Disponible à partir de la version 18.1, cette option permet à l’utilisateur de spécifier le type d’adresse IP à laquelle il souhaite donner la priorité pour les connexions. Les options possibles sont « IpAddress= [ IPv4First | IPv6First | UsePlatformDefault] ». UsePlatformDefault se connecte aux adresses dans l’ordre dans lequel elles sont fournies par l’appel système pour résoudre le nom du serveur. La valeur par défaut, IPv4First, correspond au comportement dans les versions précédentes.
ServerCertificate
Disponible à partir de la version 18.1, cette option peut être utilisée avec le mode de chiffrement strict. Le mot clé ServerCertificate est utilisé pour spécifier le chemin d’accès vers un fichier de certificat à comparer avec le certificat TLS/SSL SQL Server. La correspondance est effectuée à la place de la validation de certificat standard (expiration, nom d’hôte, chaîne d’approbation, etc.) Les formats de certificat acceptés sont PEM, DER et CER. S’il est spécifié, le certificat SQL Server est vérifié en contrôlant si le ServerCertificate fourni est une correspondance exacte.
SQL_COPT_SS_ACCESS_TOKEN
Autorise l’utilisation d’un jeton d’accès Microsoft Entra pour l’authentification. Pour plus d’informations, consultez Utilisation de Microsoft Entra ID.
| Valeur d'attribut | Description |
|---|---|
| NULL | (Valeur par défaut) Aucun jeton d’accès n’est fourni. |
| ACCESSTOKEN* | Pointeur vers un jeton d’accès. |
SQL_COPT_SS_CEKEYSTOREDATA
Communique avec une bibliothèque de fournisseur de magasins de clés chargée. Consultez « Contrôle le chiffrement transparent des colonnes (Always Encrypted) ». Cet attribut n’a aucune valeur par défaut. Pour plus d’informations, consultez Fournisseurs de magasins de clés personnalisés.
| Valeur d'attribut | Description |
|---|---|
| CEKEYSTOREDATA * | Structure des données de communication pour la bibliothèque du fournisseur de magasins de clés |
SQL_COPT_SS_CEKEYSTOREPROVIDER
Charge une bibliothèque de fournisseur de magasins de clés pour Always Encrypted, ou récupère les noms des bibliothèques de fournisseur de magasins de clés chargées. Pour plus d’informations, consultez Fournisseurs de magasins de clés personnalisés. Cet attribut n’a aucune valeur par défaut.
| Valeur d'attribut | Description |
|---|---|
| char * | Chemin d’une bibliothèque de fournisseur de magasins de clés |
SQL_COPT_SS_ENLIST_IN_XA
Pour activer les transactions XA avec un processeur de transaction (TP) compatible XA, l’application doit appeler SQLSetConnectAttr avec SQL_COPT_SS_ENLIST_IN_XA et un pointeur vers un objet XACALLPARAM. Cette option est prise en charge sur Windows (17.3+), Linux et macOS.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER); // XACALLPARAM *param
Pour associer une transaction XA à une connexion ODBC uniquement, fournissez TRUE ou FALSE avec SQL_COPT_SS_ENLIST_IN_XA au lieu du pointeur quand vous appelez SQLSetConnectAttr . Ce paramètre est seulement valide sur Windows et ne peut pas être utilisé pour spécifier des opérations XA avec une application cliente.
SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, (SQLPOINTER)TRUE, 0);
| Valeur | Description | Plateformes |
|---|---|---|
| Objet XACALLPARAM* | Pointeur vers un objet XACALLPARAM. |
Windows, Linux et macOS |
| TRUE | Associe la transaction XA à la connexion ODBC. Toutes les activités de base de données connexes sont effectuées sous la protection de la transaction XA. | Windows |
| FALSE | Dissocie la transaction de la connexion ODBC. | Windows |
Pour plus d’informations sur les transactions XA, consultez Utilisation de transactions XA.
SQL_COPT_SS_LONGASMAX
Autorise l’envoi de données de type long aux serveurs en tant que données de type max.
| Valeur d'attribut | Description |
|---|---|
| Non | (Par défaut) Ne convertit pas les types longs en types max lors de l’envoi. |
| Oui | Convertit les données des types longs en types max lors de l’envoi. |
SQL_COPT_SS_SPID
Récupère l’ID du processus serveur de la connexion. Cette propriété équivaut à la variable T-SQL @@SPID, mais n’entraîne aucun aller-retour supplémentaire sur le serveur.
| Valeur d'attribut | Description |
|---|---|
| DWORD | SPID |