Mots-clés et attributs de DSN et de chaîne de connexion

Cet article liste les mots-clés que le pilote ODBC Microsoft pour SQL Server accepte dans les noms de sources de données (DSN) et les chaînes de connexion. Il liste également les attributs de connexion pour SQLSetConnectAttr et SQLGetConnectAttr.

Choisissez une connexion DSN ou sans DSN

Pour des conseils sur le choix des méthodes de connexion, de l’authentification, du chiffrement, du routage, des réessais et des paramètres d’application, consultez Configurer les connexions ODBC vers Microsoft SQL. Utilisez cet article pour rechercher les mots-clés exacts et les attributs de connexion.

DSN pris en charge, mots-clés des chaînes de connexion et attributs de connexion

Le tableau suivant liste les mots-clés et attributs disponibles pour chaque plateforme (L : Linux ; M : macOS ; W : Windows). Pour plus d’informations, sélectionnez le mot clé ou l’attribut.

Mot-clé DSN / chaîne de connexion Attribut de connexion Plateforme
Addr LMW
Adresse LMW
AnsiNPW SQL_COPT_SS_ANSI_NPW LMW
APP LMW
ApplicationIntent SQL_COPT_SS_APPLICATION_INTENT LMW
AttachDBFileName SQL_COPT_SS_ATTACHDBFILENAME LMW
Authentication SQL_COPT_SS_AUTHENTICATION LMW
AutoTranslate SQL_COPT_SS_TRANSLATE LMW
ClientCertificate LMW
ClientKey LMW
ColumnEncryption SQL_COPT_SS_COLUMN_ENCRYPTION LMW
ConcatNullYieldsNull (v18.6 et versions ultérieures) SQL_COPT_SS_CONCAT_NULL LMW
ConnectRetryCount SQL_COPT_SS_CONNECT_RETRY_COUNT LMW
ConnectRetryInterval SQL_COPT_SS_CONNECT_RETRY_INTERVAL LMW
ConnectTimeout (v18.7 et versions ultérieures) SQL_ATTR_LOGIN_TIMEOUT LMW
Base de données SQL_ATTR_CURRENT_CATALOG LMW
Description LMW
Pilote LMW
DSN LMW
Chiffrer SQL_COPT_SS_ENCRYPT LMW
Failover_Partner SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartner (v18.7 et versions ultérieures) SQL_COPT_SS_FAILOVER_PARTNER W
FailoverPartnerSPN SQL_COPT_SS_FAILOVER_PARTNER_SPN W
FileDSN LMW
GetDataExtensions (v18.0 et versions ultérieures) SQL_COPT_SS_GETDATA_EXTENSIONS LMW
HostnameInCertificate (v18.0 et versions ultérieures) LMW
IpAddressPreference (v18.1 et versions ultérieures) LMW
KeepAlive (v17.4 et versions ultérieures ; DSN uniquement avant 17.8) LMW
KeepAliveInterval (v17.4 et versions ultérieures ; DSN uniquement avant 17.8) LMW
KeystoreAuthentication LMW
KeystorePrincipalId LMW
KeystoreSecret LMW
Language LMW
LongAsMax (v18.0 et versions ultérieures) SQL_COPT_SS_LONGASMAX LMW
MARS_Connection SQL_COPT_SS_MARS_ENABLED LMW
MultipleActiveResultSets (v18.7 et versions ultérieures) SQL_COPT_SS_MARS_ENABLED LMW
MultiSubnetFailover SQL_COPT_SS_MULTISUBNET_FAILOVER LMW
Net LMW
Réseau LMW
PacketSize (Pilote 18.7) SQL_ATTR_PACKET_SIZE LMW
PWD LMW
QueryLog_On SQL_COPT_SS_PERF_QUERY W
QueryLogFile SQL_COPT_SS_PERF_QUERY_LOG W
QueryLogTime SQL_COPT_SS_PERF_QUERY_INTERVAL W
QuotedId SQL_COPT_SS_QUOTED_IDENT LMW
Régional LMW
Réplication LMW
RetryExec (versions 18.1 et ultérieures) LMW
SaveFile LMW
Server LMW
ServerCertificate (v18.1 et versions ultérieures) LMW
ServerSPN SQL_COPT_SS_SERVER_SPN LMW
StatsLog_On SQL_COPT_SS_PERF_DATA W
StatsLogFile SQL_COPT_SS_PERF_DATA_LOG W
TransparentNetworkIPResolution SQL_COPT_SS_TNIR LMW
Trusted_Connection SQL_COPT_SS_INTEGRATED_SECURITY LMW
TrustServerCertificate SQL_COPT_SS_TRUST_SERVER_CERTIFICATE LMW
UID LMW
UseFMTONLY LMW
vectorTypeSupport (v18.6.1.1 et versions ultérieures) SQL_COPT_SS_VECTOR_TYPE_SUPPORT LMW
WorkstationID (v18.7 et versions ultérieures) LMW
WSID LMW
SQL_ATTR_ACCESS_MODE
(SQL_ACCESS_MODE)
LMW
SQL_ATTR_ASYNC_DBC_EVENT W
SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE W
SQL_ATTR_ASYNC_DBC_PCALLBACK W
SQL_ATTR_ASYNC_DBC_PCONTEXT W
SQL_ATTR_ASYNC_ENABLE W
SQL_ATTR_AUTO_IPD LMW
SQL_ATTR_AUTOCOMMIT
(SQL_AUTOCOMMIT)
LMW
SQL_ATTR_CONNECTION_DEAD LMW
SQL_ATTR_CONNECTION_TIMEOUT LMW
SQL_ATTR_DBC_INFO_TOKEN W
SQL_ATTR_LOGIN_TIMEOUT
(SQL_LOGIN_TIMEOUT)
LMW
SQL_ATTR_METADATA_ID LMW
SQL_ATTR_ODBC_CURSORS
(SQL_ODBC_CURSORS)
LMW
SQL_ATTR_PACKET_SIZE
(SQL_PACKET_SIZE)
LMW
SQL_ATTR_QUIET_MODE
(SQL_QUIET_MODE)
LMW
SQL_ATTR_RESET_CONNECTION
(SQL_COPT_SS_RESET_CONNECTION)
LMW
SQL_ATTR_TRACE
(SQL_OPT_TRACE)
LMW
SQL_ATTR_TRACEFILE
(SQL_OPT_TRACEFILE)
LMW
SQL_ATTR_TRANSLATE_LIB
(SQL_TRANSLATE_DLL)
LMW
SQL_ATTR_TRANSLATE_OPTION
(SQL_TRANSLATE_OPTION)
LMW
SQL_ATTR_TXN_ISOLATION
(SQL_TXN_ISOLATION)
LMW
SQL_COPT_SS_ACCESS_TOKEN LMW
SQL_COPT_SS_ANSI_OEM W
SQL_COPT_SS_AUTOBEGINTXN LMW
SQL_COPT_SS_BCP LMW
SQL_COPT_SS_BROWSE_CACHE_DATA LMW
SQL_COPT_SS_BROWSE_CONNECT LMW
SQL_COPT_SS_BROWSE_SERVER LMW
SQL_COPT_SS_CEKEYSTOREDATA LMW
SQL_COPT_SS_CEKEYSTOREPROVIDER LMW
SQL_COPT_SS_CLIENT_CONNECTION_ID LMW
SQL_COPT_SS_CONNECTION_DEAD LMW
SQL_COPT_SS_DATACLASSIFICATION_VERSION (v17.4.2 et versions ultérieures) LMW
SQL_COPT_SS_ENLIST_IN_DTC W
SQL_COPT_SS_ENLIST_IN_XA LMW
SQL_COPT_SS_FALLBACK_CONNECT LMW
SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD LMW
SQL_COPT_SS_MUTUALLY_AUTHENTICATED LMW
SQL_COPT_SS_OLDPWD LMW
SQL_COPT_SS_PERF_DATA_LOG_NOW W
SQL_COPT_SS_PRESERVE_CURSORS LMW
SQL_COPT_SS_SPID (v17.5 et versions ultérieures) LMW
SQL_COPT_SS_TXN_ISOLATION LMW
SQL_COPT_SS_USER_DATA LMW
SQL_COPT_SS_WARN_ON_CP_ERROR LMW

SQL_ATTR_DBC_INFO_TOKENest réservé au pooling de connexions en fonction du pilote Windows Driver Manager. Les applications ne définissent pas cet attribut.

Voici quelques mots-clés et attributs de chaîne de connexion qui ne sont pas documentés dans Using Connection String Keywords with SQL Server Native Client, SQLSetConnectAttr et SQLSetConnectAttr Function.

Description

Décrit la source des données.

SQL_COPT_SS_ANSI_OEM

Contrôle la conversion entre Windows et les pages de codes du fabricant d’équipement d’origine (OEM).

Valeur de l’attribut Description
SQL_AO_OFF (valeur par défaut) La traduction n’est pas terminée.
SQL_AO_ON La traduction est effectuée.

SQL_COPT_SS_AUTOBEGINTXN

À partir de la version 17.6, lorsque l’autocommit est désactivé, utilisez cette option pour contrôler le BEGIN TRANSACTION automatique après ROLLBACK ou COMMIT.

Valeur de l’attribut Description
SQL_AUTOBEGINTXN_ON (valeur 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 des connexions de secours SQL Server. Cette option n’est plus prise en charge.

Valeur de l’attribut Description
SQL_FB_OFF (valeur par défaut) Désactive les connexions de secours.
SQL_FB_ON Permet de créer des connexions de secours.

Nouveaux mots-clés de chaîne de connexion et attributs de connexion

Les sections suivantes décrivent le comportement des mots-clés, les attributs de connexion et leurs valeurs acceptées. Les restrictions spécifiques au pilote sont indiquées avec l’option correspondante.

Uniformisation des mots-clés de chaîne de connexion

À partir de la version 18.7, le pilote ODBC pour SQL Server prend en charge des mots-clés supplémentaires de chaîne de connexion qui correspondent aux noms de propriétés du Microsoft.Data.SqlClient fournisseur de données. Ce support réduit le renommage de mots-clés lors du passage entre fournisseurs de données Microsoft SQL et pilotes. Chaque fournisseur dispose toujours de ses propres mots-clés et valeurs pris en charge.

Alias de mots-clés

Chaque alias configure la même option que son mot-clé ODBC équivalent :

Alias Mot-clé ODBC équivalent Description
MultipleActiveResultSets MARS_Connection Active ou désactive plusieurs ensembles de résultats actifs (MARS). Accepte Yes ou No.
WorkstationID WSID Définit l’identifiant de la station de travail, généralement le nom réseau de l’ordinateur qui exécute l’application. HOST_NAME() Renvoie cette valeur.
FailoverPartner Failover_Partner Spécifie le serveur partenaire de basculement pour la mise en miroir de la base de données. Pris en charge uniquement sous Windows.

Remarque

Dans la version 18.7, MultipleActiveResultSets accepte Yes ou No, mais pas True ou False.

Le conducteur applique les règles suivantes à ces alias :

  • Insensible à la casse : Le pilote reconnaît les alias sans tenir compte de la casse. Par exemple, multipleactiveresultsets se comporte de la même façon que MultipleActiveResultSets.
  • La première occurrence l’emporte : Un alias et son mot-clé ODBC équivalent configurent la même option. Si une chaîne de connexion contient les deux, le pilote utilise la première valeur et ignore les valeurs suivantes pour cette option.
  • Entrée uniquement : Le pilote accepte des alias comme entrée. Lorsqu’il retourne une chaîne de connexion de sortie ou écrit le paramètre sur un nom de source de données (DSN), il utilise le mot-clé ODBC équivalent.
  • Support de la plateforme : Le pilote supporte MultipleActiveResultSets et WorkstationID sur Windows, Linux et macOS. Le pilote prend en charge FailoverPartner et Failover_Partner uniquement sous Windows.

Mot-clé ConnectTimeout

Le ConnectTimeout mot-clé configure le même délai d’attente de connexion que l’attribut SQL_ATTR_LOGIN_TIMEOUT connexion. Les applications peuvent spécifier le délai d’attente dans la chaîne de connexion au lieu d’appeler SQLSetConnectAttr.

Si une application définit SQL_ATTR_LOGIN_TIMEOUT explicitement avant d’appeler une fonction de connexion, l’attribut de connexion a la priorité sur la ConnectTimeout valeur de la chaîne de connexion.

  • Unités et valeurs par défaut : La valeur spécifie le nombre de secondes à attendre avant que l’ouverture de session se termine. La valeur par défaut est 15 secondes.
  • Pas de délai d’attente : Une valeur de 0 indique au pilote d’attendre indéfiniment.
  • Maximum et limitation : La valeur maximale est 65534. Lorsque vous fournissez une valeur négative, une valeur supérieure à 65534, ou une valeur qui dépasse la plage numérique supportée, le pilote utilise 65534. Si le pilote verrouille la valeur et que la connexion réussit autrement, le pilote revient SQL_SUCCESS_WITH_INFO avec un 01S02 avertissement (valeur de l’option modifiée).
  • Validation : Le pilote rejette les valeurs vides et non numériques.
  • Support DSN : Sous Windows, les applications peuvent stocker et récupérer ConnectTimeout dans un nom de source de données (DSN).
  • Prise en charge de la plateforme : Le pilote prend en charge ConnectTimeout sur Windows, Linux et macOS.

Example

La chaîne de connexion suivante utilise les orthographes unifiées des mots-clés. Remplacez <server>, <database>, <user_id> et <password> par vos valeurs. Pour Azure SQL Database, utilisez <server>.database.windows.net comme nom d’hôte :

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>;Database=<database>;UID=<user_id>;PWD=<password>;Encrypt=yes;TrustServerCertificate=no;MultipleActiveResultSets=Yes;WorkstationID=app-node-01;ConnectTimeout=30;

Les alias dans la chaîne de connexion précédente configurent les mêmes options que les mots-clés ODBC originaux dans la chaîne de connexion suivante :

Driver={ODBC Driver 18 for SQL Server};Server=tcp:<server>;Database=<database>;UID=<user_id>;PWD=<password>;Encrypt=yes;TrustServerCertificate=no;MARS_Connection=Yes;WSID=app-node-01;

Les deux chaînes activent MARS et définissent l’ID du poste de travail à app-node-01. La première chaîne attend également jusqu’à 30 secondes pour que la connexion soit établie. ConnectTimeout n’a pas de mot-clé équivalent dans le pilote 17 ni dans les versions antérieures du pilote 18. Pour définir leur délai d’expiration de connexion, appelez SQLSetConnectAttr avec SQL_ATTR_LOGIN_TIMEOUT.

Authentification - SQL_COPT_SS_AUTHENTICATION

Définit le mode d’authentification de la connexion. Pour plus d’informations, voir Utiliser Microsoft Entra ID avec le pilote ODBC.

Valeur mot-clé Valeur de l’attribut Description
SQL_AU_NONE (valeur par défaut) Sans attribut explicitement défini, d’autres paramètres de connexion déterminent l’authentification. Définir explicitement cet attribut remplace la Authentication sélection du DSN ou de la chaîne de connexion.
SqlPassword SQL_AU_PASSWORD Authentification SQL avec un nom d’utilisateur et un mot de passe.
ActiveDirectoryIntegrated SQL_AU_AD_INTEGRATED Authentification intégrée Microsoft Entra.
ActiveDirectoryInteractive SQL_AU_AD_INTERACTIVE Authentification interactive de Microsoft Entra.
ActiveDirectoryMsi SQL_AU_AD_MSI Authentification d’identité managée Microsoft Entra. Pour une identité attribuée par l’utilisateur, défini UID à son ID client sur Azure App Service ou Azure Container Instances ; utilisez son ID d’objet sur d’autres hôtes pris en charge. Omettre UID pour une identité assignée par le système.
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.
ActiveDirectoryPassword SQL_AU_AD_PASSWORD Authentification Microsoft Entra obsolète du nom d’utilisateur et du mot de passe. Pour plus d’informations, voir ActiveDirectoryPassword déprécié.
SQL_AU_RESET Efface un attribut d'authentification explicitement défini afin que le paramètre Authentication du DSN ou de la chaîne de connexion puisse s'appliquer à nouveau.

Remarque

Lors de l’utilisation du mot-clé ou de l’attribut Authentication, définissez explicitement Encrypt dans la chaîne de connexion, le DSN ou l’attribut de connexion. Pour le comportement et les paramètres par défaut, voir Encrypt.

ChiffrementDeColonne - SQL_COPT_SS_COLUMN_ENCRYPTION

Contrôle le chiffrement transparent des colonnes (Always Encrypted). Pour plus d’informations, consultez Utilisation d’Always Encrypted avec ODBC Driver for SQL Server.

Valeur mot-clé Valeur de l’attribut Description
Enabled SQL_CE_ENABLED Active la fonctionnalité Always Encrypted.
Disabled (valeur par défaut) SQL_CE_DISABLED Désactive Always Encrypted.
SQL_CE_RESULTSETONLY Active le déchiffrement uniquement (résultats et valeurs de retour).

ConcatNullYieldsNull - SQL_COPT_SS_CONCAT_NULL

Contrôle la gestion par l’Organisation internationale de normalisation (ISO) de NULL lors de la concaténation de chaînes. Pour plus d’informations, consultez SET CONCAT_NULL_YIELDS_NULL.

Valeur mot-clé Valeur de l’attribut Description
Yes (valeur par défaut) SQL_CN_ON NULL la concaténation donne NULL.
No SQL_CN_OFF NULL concaténé donne une chaîne.

Chiffrer

Spécifie si les connexions utilisent le chiffrement Transport Layer Security (TLS) sur le réseau. Le Driver 17 accepte yes et no. Le pilote 18 accepte mandatory également comme synonyme de yes, optional comme synonyme de no, et strict, qui sélectionne le chiffrement Tabular Data Stream (TDS) 8.0 et ne possède pas d’équivalent au pilote 17.

Le pilote 18 a pour valeur par défaut yes. Le pilote 17 est normalement assigné par défaut à no, mais par yes défaut lorsqu’un réglage non vide Authentication ou un jeton d’accès est fourni. Définir Encrypt explicitement plutôt que de se fier à ces valeurs par défaut dépendantes de l’authentification.

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 du côté serveur Force Encryption déterminent si les connexions sont chiffrées sur le réseau. Les tableaux suivants montrent l’effet de ces paramètres.

Pilote ODBC 18 et versions ultérieures

Réglage de chiffrement Faire confiance au certificat de serveur Chiffrement forcé du serveur Résultats
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 Non 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 Non 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.

Remarque

La Strict valeur n’est disponible que sur les serveurs supportant les connexions TDS 8.0.

Pilote ODBC 17 et versions antérieures

Réglage de chiffrement Faire confiance au certificat de serveur Chiffrement forcé du serveur Résultats
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 Non 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 Non 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 fonction Transparent Network IP Resolution, une solution de secours multi-IP héritée pour le pilote ODBC. Ce paramètre n’affecte pas la séquence de connexion lorsque MultiSubnetFailover=Yes, ce qui constitue le paramètre recommandé pour Azure SQL Database, Azure SQL Managed Instance, la base de données SQL de Microsoft Fabric, les écouteurs de groupes de disponibilité et les instances de cluster de basculement. Pour plus d’informations, voir Utiliser une résolution IP réseau transparente avec le pilote ODBC ou Haute disponibilité et reprise après sinistre.

Valeur mot-clé Valeur de l’attribut Description
Enabled (valeur par défaut) SQL_IS_ON Permet une résolution IP réseau transparente.
Disabled 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 2012 et versions ultérieures.

Valeur mot-clé Description
No (valeur par défaut) À utiliser sp_describe_first_result_set pour les métadonnées si disponible.
Yes Utiliser SET FMTONLY pour les métadonnées.

Réplication

Spécifie l’utilisation d’un identifiant de réplication sur le pilote ODBC version 17.8 et versions ultérieures.

Valeur mot-clé Description
No (valeur par défaut) La connexion de réplication n’est pas utilisée.
Yes Les déclencheurs comportant l’option NOT FOR REPLICATION ne sont pas activés sur la connexion.

PacketSize

Le pilote 18.7 prend en charge PacketSize pour demander la taille du paquet réseau en octets. La taille négociée peut différer de la valeur demandée. Utilisez SQL_ATTR_PACKET_SIZE pour définir l’attribut de connexion correspondant ou récupérer la taille négociée. Pour les limites et le comportement des attributs, voir SQLSetConnectAttr. Les applications Driver 17 utilisent l’attribut plutôt que le mot-clé PacketSize.

RetryExec

La logique de réessai configurable est disponible dans Driver 18.1 et les versions ultérieures. Le pilote 17 ne prend pas en charge RetryExec. Activez-le avec le RetryExec mot-clé chaîne de connexion et une liste de règles qui contrôlent la réexécution de SQLExecDirect et SQLExecute.

Après une erreur d’exécution, le pilote sélectionne la première règle dont la liste d’erreurs contient ce code d’erreur. Il vérifie ensuite le préfixe de requête de cette règle par rapport au texte de commande entrant pour SQLExecDirect ou au texte préparé pour SQLExecute. Si le préfixe ne correspond pas, le pilote ne réessaie pas la commande ni ne continue vers les règles ultérieures. Une règle de match-all ultérieure n’est pas une solution de rechange pour un code d’erreur déjà listé dans une règle antérieure.

Réessayez uniquement les opérations pouvant être répétées sans risque. Une nouvelle tentative peut exécuter une commande plus d’une fois, et une défaillance de connexion n’établit pas qu’une écriture précédente n’a pas pu être terminée.

La valeur du RetryExec mot-clé est une liste de règles de retentative séparées par point-virgule.
RetryExec={rule1;rule2}

Une règle de nouvelle tentative se présente comme suit : <errormatch>:<retrypolicy>:<querymatch>

  • Correspondance d’erreur : Une liste de codes d’erreur séparés par des virgules, tels que 1000,2000.

  • Politique de réessais : Le nombre de réessais suivi du délai initial en secondes. Par exemple, 3,10+7 permet trois tentatives après l’exécution initiale, avec des délais de 10, 17 et 24 secondes : quatre exécutions au total si chaque tentative échoue. Sans +, le délai double à chaque nouvelle tentative. Un + final sans incrément utilise le délai initial comme incrément.

  • Correspondance de requête : Le préfixe texte de commande. Un préfixe vide s’applique à toutes les commandes. Par exemple, SELECT correspond à des commandes qui commencent par SELECT.

En combinant les trois composants ensemble pour les utiliser dans une chaîne de connexion :

RetryExec={1000,2000:3,10+7:SELECT}

Pour les erreurs 1000 et 2000 pour une commande commençant par SELECT, cette règle autorise trois tentatives, après 10, 17 et 24 secondes.

Examples

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 retentative. Cette règle s’applique à toutes les requêtes.

49919:2,10+:CREATE

Pour une erreur 49919 sur une requête commençant par CREATE, réessayez au maximum deux fois, d’abord après 10 secondes, puis 20 secondes.

49918,40501,10928:5,10+5:SELECT c1

Pour les erreurs 49918, , et 10928 pour les requêtes commençant par SELECT c1, réessayez jusqu’à cinq fois, en attendant 10 secondes à la première tentative et en augmentant l’attente de 5 secondes 40501par la suite.

Spécifiez les trois règles précédentes 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}

Dans cette combinaison, l’erreur 40501 sélectionne la première règle et relance uniquement les commandes commençant par SELECT c1. La règle finale ne fournit pas de solution de recours pour d’autres commandes qui échouent avec 40501. Pour appliquer la stratégie finale à toutes les commandes présentant cette erreur, supprimez 40501 de la liste d’erreurs de la première règle. Privilégiez les listes d’erreurs non chevauchantes lorsque chaque code nécessite une seule politique.

ClientCertificate

Spécifie le certificat d’authentification avec des connexions en boucle. Cette option n’est disponible que sur SQL Server sur Linux. Les options sont :

Valeur d'option Description
sha1:<hash_value> Le pilote ODBC utilise le hash Secure Hash Algorithm 1 (SHA-1) pour localiser un certificat dans le magasin de certificats Windows.
subject:<subject> Le pilote ODBC utilise le sujet pour localiser un certificat dans le magasin de certificats Windows.
file:<file_location>[,password:<password>] le pilote ODBC utilise un fichier de certificat.

Si le certificat est au format Personal Information Exchange (PFX) et que sa clé privée est protégée par mot de passe, incluez le password mot-clé. Pour les certificats aux formats Privacy Enhanced Mail (PEM) et Distinguished Encoding Rules (DER), incluez le ClientKey mot-clé.

ClientKey

Spécifie l’emplacement du fichier de la clé privée pour PEM ou DER des certificats spécifiés par l’attribut ClientCertificate . Format :

Valeur d'option Description
file:<file_location>[,password:<password>] Précise l’emplacement du fichier à clé privée.

Si le fichier de clé privée est protégé par mot de passe, incluez le password mot-clé. Si le mot de passe contient des , caractères, ajoutez un caractère supplémentaire , immédiatement après chacun. Par exemple, si le mot de passe est a,b,c, le mot de passe échappé dans la chaîne de connexion est a,,b,,c.

Nom d’hôte dans le certificat

Spécifie le nom d’hôte à attendre dans le certificat du serveur lorsque le chiffrement est négocié, s’il est différent de la valeur par défaut dérivée de Addr, Address, ou Server. L’option HostnameInCertificate est ignorée quand vous utilisez l’option ServerCertificate.

Préférence d’adresse IP

À partir de la version 18.1, utilisez cette option pour spécifier le type d’adresse IP à prioriser pour les connexions.

Les options possibles sont IPv4First, IPv6First, et 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 est IPv4First, ce qui correspond au comportement des versions précédentes.

certificat de serveur

À partir de la version 18.1, utilisez cette option uniquement en mode de chiffrement strict. Utilisez le ServerCertificate mot-clé pour spécifier le chemin d’accès à un fichier de certificat à correspondre au certificat TLS du serveur. La correspondance de fichiers remplace la validation normale du nom d’hôte et de la chaîne de confiance, mais le pilote vérifie toujours les dates de validité du certificat serveur. Utilisez un fichier de certificat encodé en PEM ou DER. Les fichiers portant l’extension .cer sont acceptés lorsqu’ils utilisent l’un de ces encodages. Le certificat serveur doit correspondre exactement au certificat dans le fichier spécifié.

SQL_COPT_SS_ACCESS_TOKEN

Utilisez un jeton d’accès Microsoft Entra ID pour l’authentification. Pour plus d’informations, voir Utiliser Microsoft Entra ID avec le pilote ODBC.

Valeur de l’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. 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 de l’attribut Description
CEKEYSTOREDATA * Structure de données de communication pour une bibliothèque fournisseur de magasin 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 de l’attribut Description
char * Chemin vers une bibliothèque de fournisseur de keystore.

SQL_COPT_SS_ENLIST_IN_XA

Pour établir une connexion dans les transactions distribuées XA, appelez SQLSetConnectAttr avec SQL_COPT_SS_ENLIST_IN_XA et un pointeur vers un XACALLPARAM objet. Cette option est prise en charge sur Windows (versions 17.3 et ultérieures), Linux et macOS.

SQLSetConnectAttr(hdbc, SQL_COPT_SS_ENLIST_IN_XA, param, SQL_IS_POINTER);  // XACALLPARAM *param

Pour associer une transaction XA uniquement à une connexion ODBC, spécifiez TRUE ou FALSE avec SQL_COPT_SS_ENLIST_IN_XA à la place du pointeur lors de l’appel à 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
XACALLPARAM objet* 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

Contrôle si le pilote envoie des paramètres longs caractères et binaires comme varchar(max), nvarchar(max) et varbinary(max). Le pilote 18 supporte cette option ; le pilote 17 ne le supporte pas.

Valeur de l’attribut Description
SQL_XL_OFF (0, par défaut) Ne convertis pas les types longs en types max lors de l’envoi.
SQL_XL_ON (1) Convertissez les types longs en types max lors de l’envoi.

Ce sont des valeurs numériques pour SQLSetConnectAttr. Le mot-clé chaîne de connexion correspondant à LongAsMax utilise No et Yes.

SQL_COPT_SS_SPID

Récupère l’ID de session de la connexion. Cette propriété est équivalente à la variable @@SPID Transact-SQL (T-SQL), sauf qu'elle n'entraîne pas un aller-retour supplémentaire vers le serveur.

Valeur de l’attribut Description
DWORD ID de session.