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.

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.

SQL_COPT_SS_FALLBACK_CONNECT

Contrôle l’utilisation de connexions de secours SQL Server. Cet attribut n’est plus pris en charge.

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.

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).

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

ODBC Driver 17 et versions antérieures

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.

UseFMTONLY

Contrôle l’utilisation de SET FMTONLY pour les métadonnées lors de la connexion à SQL Server versions 2012 et ultérieures.

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.

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 :

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:

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.

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.

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.

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);

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.

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.