Définition des propriétés de connexion
Les propriétés de chaîne de connexion peuvent être spécifiées de plusieurs manières :
En tant que propriétés nom=valeur dans l’URL de connexion, lors de la connexion à l’aide de la classe DriverManager. Pour connaître la syntaxe de la chaîne de connexion, consultez Génération de l’URL de connexion.
En tant que propriétés nom=valeur dans le paramètre Properties de la méthode Connect de la classe DriverManager.
En tant que valeurs dans la méthode setter appropriée de la source de données du pilote. Par exemple :
datasource.setServerName(value) datasource.setDatabaseName(value)
Notes
Les noms de propriétés ne sont pas sensibles à la casse et les noms de propriétés dupliqués sont résolus dans l'ordre suivant :
- Arguments API (utilisateur et mot de passe)
- Collection de propriétés
- Dernière instance de la chaîne de connexion
Les valeurs inconnues sont autorisées dans les noms de propriétés. Le pilote JDBC ne valide pas les valeurs sensibles à la casse.
Les synonymes sont autorisés et sont résolus dans l'ordre, tout comme les noms de propriétés dupliqués.
Propriétés
Le tableau suivant répertorie toutes les propriétés de chaîne de connexion actuellement disponibles pour le pilote JDBC.
| Propriété Type Default |
Description |
|---|---|
| accessToken String null |
(Version 6.0+) Utilisez cette propriété pour vous connecter à une base de données à l’aide d’un jeton d’accès. Il n’est pas possible de définir accessToken avec l’URL de connexion. |
| accessTokenCallbackClass Chaîne null |
(Version 12.4+) Nom de la classe d’implémentation de rappel à utiliser avec le rappel de jeton d’accès. |
| applicationIntent String Lecture/écriture |
(Version 6.0+) Déclare le type de la charge de travail de l’application pour se connecter à un serveur. Les valeurs possibles sont ReadOnly et ReadWrite. Pour plus d’informations sur la reprise d’activité, consultez Prise en charge de la haute disponibilité et de la reprise d’activité par le pilote JDBC. |
| applicationName String [<=128 char] null |
Nom de l’application, ou « Microsoft JDBC Driver pour SQL Server » si aucun nom n’est fourni. Utilisé pour identifier l’application spécifique dans les divers outils de journalisation et de profilage SQL Server. |
| Authentification String NotSpecified |
(Version 6.0+) Cette propriété facultative indique la méthode d’authentification à utiliser pour la connexion. Les valeurs possibles sont ActiveDirectoryIntegrated, ActiveDirectoryPassword, ActiveDirectoryManagedIdentity (version 12.2+), ActiveDirectoryMSI (version 7.2+), ActiveDirectoryInteractive (version 9.2+), ActiveDirectoryServicePrincipal (version 9.2+), SqlPassword et NotSpecified (valeur par défaut). Utilisez ActiveDirectoryIntegrated (version 6.0+) pour vous connecter à SQL avec l’authentification intégrée de Windows. Utilisez ActiveDirectoryPassword (version 6.0+) pour vous connecter à SQL à l’aide d’un nom de principal et d’un mot de passe Microsoft Entra. Utilisez ActiveDirectoryManagedIdentity (version 12.2+) ou ActiveDirectoryMSI (version 7.2+) pour vous connecter à SQL à partir d’une ressource Azure. Par exemple, une machine virtuelle Azure, App Service ou une application de fonction en utilisant l’authentification d’identités managées. Les deux types d’identités managées pris en charge par le pilote en utilisant le mode d’authentification ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI sont les suivants : 1. Identité managée affectée par le système : permet d’acquérir accessToken par défaut. 2. Identité managée affectée par l’utilisateur : permet d’acquérir accessToken si l’ID client d’une identité managée est spécifié avec la propriété de connexion msiClientId. Utilisez ActiveDirectoryInteractive pour vous connecter à une base de données en utilisant un flux d’authentification interactif. Utilisez ActiveDirectoryServicePrincipal (version 9.2+) pour vous connecter à une base de données en utilisant le secret et l’ID client d’une identité de principal de service. Spécifiez l’ID client dans la propriété Nom d'utilisateur et le secret dans la propriété Mot de passe (10.2 +). Utilisez SqlPassword pour vous connecter à SQL avec les propriétés userName/user et password. Utilisez NotSpecified si aucune de ces méthodes d’authentification n’est nécessaire. Important : si l’authentification est définie sur ActiveDirectoryIntegrated, les deux bibliothèques suivantes doivent être installées : mssql-jdbc_auth-<version>-<arch>.dll (disponible dans le package de pilotes JDBC) et la bibliothèque d’authentification Microsoft pour SQL Server (ADAL.DLL). La bibliothèque d’authentification Microsoft peut être installée à partir de Microsoft ODBC Driver for SQL Server ou de Microsoft OLE DB Driver pour SQL Server. Le pilote JDBC ne prend en charge que les versions 1.0.2028.318 et ultérieures d’ADAL.DLL. Remarque : quand la propriété d’authentication est définie avec une valeur autre que NotSpecified, le pilote utilise par défaut le chiffrement TLS (Transport Layer Security), anciennement SSL (Secure Sockets Layer). Pour plus d’informations sur la configuration de l’authentification Microsoft Entra, consultez Utilisation de l’authentification Microsoft Entra. |
| authenticationScheme String NativeAuthentication |
Indique le genre de sécurité intégrée que votre application doit utiliser. Les valeurs possibles sont JavaKerberos, NTLM (version 7.4+) et NativeAuthentication (par défaut). NativeAuthentication fait que le pilote charge mssql-jdbc_auth-<version>-<arch>.dll (par exemple mssql-jdbc_auth-8.2.2.x64.dll) sur Windows, qui est utilisé pour obtenir les informations d’authentification intégrées. (La bibliothèque d’authentification native chargée est nommée sqljdbc_auth.dll lors de l’utilisation des versions 6.0 à 7.4 du pilote.)Si vous utilisez authenticationScheme=JavaKerberos, vous devez spécifier le nom de domaine complet (FQDN) dans la propriété serverName ou la propriété serverSpn. Sinon, une erreur se produit (serveur introuvable dans la base de données Kerberos). Pour plus d’informations sur l’utilisation de authenticationScheme=JavaKerberos, consultez Utilisation de l’authentification intégrée Kerberos pour se connecter à SQL Server. Si vous utilisez authenticationScheme=NTLM, vous devez spécifier le domaine Windows à l’aide de la propriété domain ou domainName, les informations d’identification Windows dans la propriété user ou userName, et la propriété password. Sinon, une erreur se produit (les propriétés de connexion doivent être spécifiées). |
| cacheBulkCopyMetadata booléen ["true" | "false"] false |
(Version 12.8+) Lorsque vous utilisez useBulkCopyForBatchInsert=true, cette propriété est utilisée pour indiquer au pilote s’il doit mettre en cache les métadonnées de colonne de destination au niveau de la connexion. Si la valeur est définie sur true, assurez-vous que la destination ne change pas entre les insertions en bloc, car le pilote n’a pas de moyen de gérer cette modification. |
| calcBigDecimalPrecision booléen ["true" | "false"] false |
(Version 12.6+) Indicateur qui spécifie si le pilote doit calculer la précision pour les entrées BigDecimal, au lieu d’utiliser la valeur maximale autorisée pour la précision (38). |
| cancelQueryTimeout int -1 |
(Version 6.4+) Cette propriété peut être utilisée pour annuler un délai queryTimeout défini sur la connexion. L’exécution de la requête se bloque et ne lève pas d’exception si la connexion TCP au serveur est annulée en mode silencieux. Cette propriété s’applique uniquement si « queryTimeout » est également défini sur la connexion. Le pilote attend la valeur totale en secondes de cancelQueryTimeout + queryTimeout pour annuler la connexion et fermer le canal. La valeur par défaut de cette propriété est -1 et le comportement consiste à attendre indéfiniment. |
| clientCertificate String null |
(Version 8.4+) Spécifie l’emplacement du certificat à utiliser pour l’authentification par certificat client. Le pilote JDBC prend en charge les extensions de fichier PFX, PEM, DER et CER. Pour plus d’informations, consultez Authentification par certificat client pour les scénarios de bouclage. |
| clientKey Chaîne null |
(Version 8.4+) Spécifie l’emplacement de la clé privée pour les certificats PEM, DER et CER spécifiés par l’attribut clientCertificate. Pour plus d’informations, consultez Authentification par certificat client pour les scénarios de bouclage. |
| clientKeyPassword Chaîne null |
(Version 8.4+) Spécifie la chaîne de mot de passe facultative pour accéder à la clé privée du fichier clientKey. Pour plus d’informations, consultez Authentification par certificat client pour les scénarios de bouclage. |
| columnEncryptionSetting String ["Enabled" | "Disabled"] Désactivé |
(Version 6.0+) Affectez la valeur « Enabled » pour utiliser la fonctionnalité Always Encrypted (AE). Quand la fonctionnalité AE est activée, le pilote JDBC chiffre et déchiffre de manière transparente les données sensibles stockées dans des colonnes de base de données chiffrées sur le serveur. Pour plus d’informations sur Always Encrypted, consultez Utilisation d’Always Encrypted avec le pilote JDBC. Remarque : Always Encrypted est disponible avec SQL Server 2016 ou version ultérieure et Azure SQL Database. |
| connectRetryCount int [0..255] 1 |
(Version 9.4+) Nombre de nouvelles tentatives de connexion en cas d’échec de connexion. |
| connectRetryInterval int [1..60] 10 |
(Version 9.4+) Nombre de secondes entre les nouvelles tentatives de connexion. |
| databaseName, database String [<=128 char] null |
Nom de la base de données à laquelle se connecter. S'il n'est pas indiqué, une connexion à la base de données par défaut est établie. |
| datetimeParameterType String ["datetime" | "datetime2" | "datetimeoffset"] datetime2 |
(Version 12.2+) Type de données SQL à utiliser pour les paramètres date/timestamp Java. Les clients qui se connectent à SQL Server 2016 ou ultérieur et qui interagissent avec des valeurs « datetime » héritées peuvent définir la propriété sur « datetime ». Ce paramètre atténue les problèmes de conversion côté serveur entre les valeurs « datetime » et « datetime2 ». Pour plus d’informations, découvrez comment gérer le changement de comportement lié à la conversion de valeurs datetime en datetime2 à partir de SQL Server 2016. |
| delayLoadingLobs boolean ["true" | "false"] true |
Indicateur qui spécifie s’il faut ou non diffuser en continu tous les objets LOB récupérés de ResultSet. Si cette propriété est définie sur « false », l’intégralité de l’objet LOB est chargée dans la mémoire sans diffusion en continu. |
| domainName, domaine String null |
(Version 7.4+) Domaine Windows auprès duquel s’authentifier lors de l’utilisation de l’authentification NTLM. |
| disableStatementPooling boolean ["true" | "false"] true |
Indicateur spécifiant si le regroupement d’instructions doit être utilisé. |
| enablePrepareOnFirst... PreparedStatementCall boolean ["true" | "false"] false |
Affectez la valeur « true » pour activer la création du descripteur d’instruction préparée en appelant sp_prepexec lors de la première exécution d’une instruction préparée. Affectez la valeur « false » pour modifier la première exécution d’une instruction préparée afin d’appeler sp_executesql et de ne pas préparer d’instruction. Si une deuxième exécution se produit, elle appelle sp_prepexec pour configurer un descripteur d’instruction préparée. |
| enclaveAttestationUrl String null |
(Version 8.2+) Cette propriété facultative indique l’URL de point de terminaison du service d’attestation à utiliser pour Always Encrypted avec enclaves sécurisées. Pour plus d’informations sur Always Encrypted avec enclaves sécurisées, consultez Always Encrypted avec enclaves sécurisées. |
| enclaveAttestationProtocol String null |
(Version 8.2+) Cette propriété facultative indique le protocole d’attestation à utiliser pour Always Encrypted avec enclaves sécurisées. Actuellement, les seules valeurs prises en charge pour ce champ sont HGS, AAS et NONE (NONE n’est prise en charge que dans la version 11.2+). Pour plus d’informations sur Always Encrypted avec enclaves sécurisées, consultez Always Encrypted avec enclaves sécurisées. |
| encrypt String null |
Affecter la valeur « true » pour spécifier que SQL Server utilise le chiffrement TLS pour toutes les données envoyées entre le client et le serveur si le serveur a un certificat installé. La valeur par défaut est « true » dans la version 10.2 et versions ultérieures et « false » dans 9.4 et versions ultérieures. Dans les versions 6.0 et ultérieures, un nouveau paramètre de connexion « authentification » utilise le chiffrement TLS par défaut. Pour plus d’informations sur cette propriété, reportez-vous à la propriété « authentication ». Dans la version 11.2.0 et les versions supérieures, le chiffrement a été modifié de booléen à chaîne, ce qui permet la prise en charge de TDS 8.0 lorsque la propriété est définie sur stricte. |
| failoverPartner String null |
Nom du serveur de basculement utilisé dans la configuration de la mise en miroir de bases de données. Cette propriété est utilisée en cas d’échec de connexion initiale au serveur principal. Une fois que vous avez effectué la connexion initiale, cette propriété est ignorée. Doit être utilisée avec la propriété databaseName. Remarque : Le pilote ne prend pas en charge la spécification du numéro de port de l’instance du serveur pour l’instance du partenaire de basculement dans le cadre de la propriété failoverPartner dans la chaîne de connexion. Cependant, le pilote prend en charge la spécification des propriétés serverName, instanceName et portNumber de l'instance du serveur principal et de la propriété failoverPartner de l'instance du partenaire de basculement, dans la même chaîne de connexion. Si vous spécifiez un nom de réseau virtuel dans la propriété de connexion Server, vous ne pouvez pas utiliser la mise en miroir de bases de données. Pour plus d’informations sur la reprise d’activité, consultez Prise en charge de la haute disponibilité et de la reprise d’activité par le pilote JDBC. |
fipsboolean ["true" | "false"] "false" |
Pour la machine virtuelle Java (JVM) compatible FIPS, cette propriété doit être true. |
| fipsProvider String null |
Fournisseur FIPS configuré dans la machine virtuelle Java, par exemple BCFIPS ou SunPKCS11-NSS. Supprimé dans la version 6.4.0. Pour plus d’informations, consultez le problème GitHub n° 460. |
| gsscredential org.ietf.jgss.GSSCredential null |
(Version 6.2 +) Les informations d’identification de l’utilisateur à utiliser pour la délégation Kerberos contrainte peuvent être transmises dans cette propriété. Ce paramètre doit être utilisé avec integratedSecurity défini sur true et JavaKerberos défini sur authenticationScheme. |
| hostNameInCertificate String null |
Nom d’hôte à utiliser pour valider le certificat SQL Server TLS/SSL. L’option hostNameInCertificate peut être utilisée pour spécifier le nom d’hôte dans les situations où le ou les noms utilisés dans le certificat ne correspondent pas au nom passé à la propriété serverName. Toutefois, s’il existe une correspondance, l’option hostNameInCertificate ne doit pas être utilisée. Dans les cas où la propriété hostNameInCertificate n'est pas spécifiée ou si elle a la valeur Null, le pilote JDBC Microsoft pour SQL Server utilise la valeur de propriété serverName sur l'URL de connexion comme nom d'hôte pour valider le certificat TLS/SSL SQL Server. Remarque : comme le décrit le paragraphe ci-dessus, il n’est pas recommandé de définir l’option hostNameInCertificate, sauf si vous pouvez confirmer que le ou les noms dans le certificat ne correspondent pas à celui passé dans l’option serverName. Remarque : cette propriété est utilisée en association avec les propriétés chiffrer/authentication et la propriété trustServerCertificate. Cette propriété affecte la validation du certificat si la connexion utilise le chiffrement TLS et que trustServerCertificate est définie sur « false ». Pour garantir une connexion TLS, vérifiez que la valeur passée à hostNameInCertificate correspond au nom CN (Nom commun) ou DNS dans le nom SAN (Autre nom du sujet) du certificat de serveur. Pour plus d’informations sur la prise en charge du chiffrement, consultez Comprendre la prise en charge du chiffrement. |
| INSTANCENAME String [<=128 char] null |
Nom de l’instance de base de données à laquelle se connecter. Si elle n’est pas spécifiée, une connexion à l’instance par défaut est établie. Si l'instanceName et le port sont tous deux spécifiés, consultez les notes relatives au port. Si vous spécifiez un nom de réseau virtuel dans la propriété de connexion Server, vous ne pouvez pas utiliser la propriété de connexion instanceName. Pour plus d’informations sur la reprise d’activité, consultez Prise en charge de la haute disponibilité et de la récupération d’urgence par le pilote JDBC. |
| integratedSecurity booléen ["true" | "false"] false |
Affectez la valeur « true » pour indiquer que les informations d’identification Windows sont utilisées par SQL Server sur les systèmes d’exploitation Windows. Si la valeur est « true », le pilote JDBC recherche des informations d’identification fournies lors de la connexion de l’utilisateur à l’ordinateur ou au réseau dans la mémoire cache des informations d’identification de l’ordinateur local. Affectez la valeur « true » (avec authenticationscheme=JavaKerberos) pour indiquer que SQL Server utilise les informations d'identification Kerberos. Pour plus d’informations sur l’authentification Kerberos, consultez Utilisation de l’authentification intégrée Kerberos pour se connecter à SQL Server. Affectez la valeur « true » (avec authenticationscheme=NTLM) pour indiquer que SQL Server utilise les informations d’identification NTLM. Si la valeur est « false », le nom d'utilisateur et le mot de passe doivent être fournis. |
| ipaddresspreference String [<=128 char] IPv4First |
Préférence IP utilisée par l’application cliente. Avec IPV4First, le pilote parcourt d’abord les adresses IPv4. Si aucune adresse IPv4 ne peut être connectée, le pilote continue et essaie les adresses IPv6, le cas échéant. Avec IPV6First, le pilote parcourt d’abord les adresses IPv6. Si aucune adresse IPv6 ne peut être connectée, le pilote continue et essaie les adresses IPv4, le cas échéant. Avec UsePlatformDefault, le pilote parcourt toutes les adresses IP dans l’ordre initial à partir de la résolution DNS. |
| jaasConfigurationName String SQLJDBCDriver |
(Version 6.2+) Chaque connexion à SQL Server peut utiliser son propre nom de configuration de connexion JAAS pour établir une connexion Kerberos. Le nom de l’entrée de configuration peut être transmis par le biais de cette propriété. Cette propriété est destinée à être utilisé lors de la création d’un fichier de configuration Kerberos. Par défaut, le pilote recherche le nom SQLJDBCDriver.Si aucune configuration externe n’est trouvée, le pilote configure useDefaultCcache = true pour les machines virtuelles Java IBM et useTicketCache = true pour les autres machines virtuelles Java. |
| keyStoreAuthentication String null |
(Version 6.0+) Cette propriété identifie le magasin de clés à utiliser avec Always Encrypted, et détermine le mécanisme d’authentification utilisé auprès du magasin de clés. Le pilote prend en charge la configuration transparente du magasin de clés Java quand vous définissez « keyStoreAuthentication=JavaKeyStorePassword ». Pour pouvoir utiliser cette propriété, vous devez également définir les propriétés keyStoreLocation et keyStoreSecret pour le magasin de clés Java. Pour plus d’informations sur Always Encrypted, consultez Utilisation d’Always Encrypted avec le pilote JDBC. À compter de Microsoft JDBC Driver 8.4, vous pouvez définir « keyStoreAuthentication=KeyVaultManagedIdentity » ou « keyStoreAuthentication=KeyVaultClientSecret » pour vous authentifier auprès d’Azure Key Vault en utilisant des identités managées. Pour plus d’informations sur Always Encrypted, consultez Utilisation d’Always Encrypted avec le pilote JDBC. |
| keyStoreLocation String null |
(Version 6.0+) Lorsque keyStoreAuthentication=JavaKeyStorePassword, la propriété keyStoreLocation identifie le chemin du fichier de magasin de clés Java qui stocke la clé principale de colonne à utiliser avec les données Always Encrypted. Le chemin doit inclure le nom de fichier du magasin de clés. Pour plus d’informations sur Always Encrypted, consultez Utilisation d’Always Encrypted avec le pilote JDBC. |
| keyStorePrincipalId String null |
(Version 8.4+) En présence dekeyStoreAuthentication=KeyVaultManagedIdentity, la propriété keyStorePrincipalId spécifie un ID client d’application Microsoft Entra valide. Pour plus d’informations sur Always Encrypted, consultez Utilisation d’Always Encrypted avec le pilote JDBC. |
| keyStoreSecret String null |
(Version 6.0+) Quand keyStoreAuthentication=JavaKeyStorePassword, la propriété keyStoreSecret identifie le mot de passe à utiliser pour le magasin de clés et la clé. Lorsque l’un utilise le magasin de clés Java, il est nécessaire que le magasin de clés et le mot de passe de clé soient identiques. Pour plus d’informations sur Always Encrypted, consultez Utilisation d’Always Encrypted avec le pilote JDBC. |
| lastUpdateCount boolean ["true" | "false"] true |
Une valeur « true » retourne uniquement le dernier nombre de mises à jour à partir d’une instruction SQL transmise au serveur. De plus, il est utilisé uniquement sur des instructions SELECT, INSERT ou DELETE uniques pour ignorer d’autres nombres de mises à jour qui sont des déclencheurs de serveur peuvent provoquer. La définition de cette propriété sur « false » fait que tous les nombres de mises à jour sont retournés, y compris les nombres de mises à jour retournés par les déclencheurs du serveur. Remarque : cette propriété est applicable seulement quand elle est utilisée avec les méthodes executeUpdate. Toutes les autres méthodes execute retournent l’ensemble des résultats et des nombres de mises à jour. Cette propriété affecte uniquement les nombres de mises à jour retournés par les déclencheurs du serveur. Elle n’affecte pas les jeux de résultats ou les erreurs provenant de l’exécution du déclencheur. |
| lockTimeout int -1 |
Nombre de millisecondes à attendre avant que la base de données ne rapporte l'expiration d'un délai de verrouillage. Par défaut, la durée de l'attente est indéterminée. Si l'utilisateur n'a pas spécifié de valeur pour cette propriété, cette valeur devient la valeur par défaut pour toutes les instructions de la connexion. Sinon, Statement.setQueryTimeout() peut être utilisé pour définir le délai d’expiration de requête de certaines instructions. La valeur peut être 0, ce qui signifie aucune attente. |
| loginTimeout int [0..65535] 30 (version 11.2 et ultérieures) 15 (version 10.2 et antérieures) |
Nombre de secondes que le pilote doit attendre avant l'expiration d'une connexion qui a échoué. La valeur zéro indique que le délai d'attente correspond au délai d'attente système par défaut. Cette valeur est de 30 secondes (la valeur par défaut dans la version 11.2 et ultérieure) ou de 15 secondes (la valeur par défaut dans la version 10.2 et les versions ultérieures). Une valeur différente de zéro correspond au nombre de secondes que le pilote doit attendre avant l’expiration d’une connexion échouée. Si vous spécifiez un nom de réseau virtuel dans la propriété de connexion Server, vous devez spécifier une valeur de délai de connexion de trois minutes minimum, afin que les connexions de basculement de serveur aient suffisamment de temps pour s’établir. Pour plus d’informations sur la reprise d’activité, consultez Prise en charge de la haute disponibilité et de la reprise d’activité par le pilote JDBC. |
| maxResultBuffer String null |
(Version 9.2+) maxResultBuffer peut être utilisé pour définir le nombre maximal d’octets à lire lors de la lecture d’un jeu de résultats. S’il n’est pas spécifié, le jeu de résultats entier est lu. La taille peut être spécifiée dans deux styles : 1. taille en octets (par exemple 100, 150M, 300K, 400G)2. pourcentage de la mémoire maximale du tas (par exemple 10p, 15pct, 20percent). |
| msiClientId String null |
(Déconseillé) (Version 7.2+) ID client de l’identité managée utilisé pour acquérir accessToken lors de l’établissement d’une connexion avec le mode d’authentification ActiveDirectoryManagedIdentity ou ActiveDirectoryMSI. |
| multiSubnetFailover Boolean false |
Spécifiez toujours MultiSubnetFailover=True pour vous connecter à l’écouteur de groupe de disponibilité d’un groupe de disponibilité SQL Server ou d’une instance de cluster de basculement SQL Server. multiSubnetFailover=true configure le pilote pour accélérer la détection et la connexion au serveur (actuellement) actif. Les valeurs possibles sont true et false. Pour plus d’informations sur la reprise d’activité, consultez Prise en charge de la haute disponibilité et de la récupération d’urgence par le pilote JDBC. Vous pouvez accéder par programmation à la propriété de connexion multiSubnetFailover avec getPropertyInfo, getMultiSubnetFailover et setMultiSubnetFailover. Remarque : à compter de Microsoft JDBC Driver 6.0 pour SQL Server, il n’est plus obligatoire de définir multiSubnetFailover sur « true » pour se connecter à un écouteur de groupe de disponibilité. Une nouvelle propriété, transparentNetworkIPResolution, activée par défaut, assure la détection du serveur (actuellement) actif et la connexion à ce serveur. |
| packetSize int [-1 | 0 | 512..32767] 8000 |
Taille de paquet réseau utilisée pour communiquer avec le serveur, spécifiée en octets. Une valeur de -1 indique qu'il faut utiliser la taille de paquet par défaut du serveur. La valeur 0 indique qu’il faut utiliser la valeur maximale de 32767. Si cette propriété est définie sur une valeur située en dehors des limites acceptables, une exception se produit. Important : l’utilisation de la propriété packetSize n’est pas recommandée quand le chiffrement est activé (encrypt=true). Sinon, le pilote risque de générer une erreur de connexion. Pour plus d’informations sur cette propriété, reportez-vous à la méthode setPacketSize de la classe SQLServerDataSource. |
| mot de passe String [<=128 char] null |
Mot de passe de la base de données, en cas de connexion avec l’utilisateur et le mot de passe SQL. Pour la connexion Kerberos avec le nom de principal et le mot de passe, cette propriété a comme valeur le mot de passe du principal Kerberos. (Version 10.2+) Quand authentication=ActiveDirectoryServicePrincipal, la propriété mot de passe identifie le mot de passe à utiliser pour le principal Active Directory. |
| portNumber, port int [0..65535] 1433 |
Port sur lequel le serveur est à l’écoute. Si le numéro du port est spécifié dans la chaîne de connexion, aucune demande n’est formulée à SQLbrowser. Lorsque le port et instanceName sont spécifiés, la connexion se fait vers le port spécifié. Cependant, instanceName est validé et une erreur est générée s’il ne correspond pas au port. Important : Nous recommandons de toujours spécifier le numéro du port, car cette pratique est plus sûre que l’utilisation de SQLbrowser. |
| prepareMethod String prepexec |
(Version 11.2.0+) Spécifie la méthode de préparation sous-jacente à utiliser par le pilote avec des instructions préparées. Définissez sur prepare pour utiliser sp_prepare comme méthode de préparation. La définition de prepareMethod à cette valeur entraîne un déplacement initial distinct vers la base de données pour préparer l’état, sans que la base de données ne prenne en compte les valeurs initiales dans le plan d'exécution. Définissez sur prepexec pour utiliser sp_prepexec comme méthode de préparation. Cette méthode combine l’action de préparation avec la première exécution, ce qui réduit les allers-retours. Elle fournit également à la base de données des valeurs de paramètre initiales que la base de données peut prendre en compte dans le plan d’exécution. |
| queryTimeout int -1 |
Nombre de secondes à attendre avant expiration du délai d’attente sur une requête. La valeur -1 par défaut signifie un délai infini. La définition de cette valeur sur 0 implique également d’attendre indéfiniment. |
| realm String null |
(Version 9.4 +) Domaine pour l’authentification Kerberos. La définition de cette valeur remplace le domaine d’authentification Kerberos que le pilote détecte automatiquement à partir du domaine du serveur. |
| la réplication boolean ["true" | "false"] false |
(Version 9.4 +) Ce paramètre indique au serveur si la connexion est utilisée pour la réplication. Quand l’option est activée, les déclencheurs avec l’option NOT FOR REPLICATION ne sont pas activés à la connexion. |
| responseBuffering String ["full" | "adaptive"] adaptive |
Si cette propriété a la valeur « adaptive », les données possibles minimales sont mises en mémoire tampon en cas de nécessité. Le mode par défaut est « adaptive ». Si cette propriété est définie sur « full », le jeu de résultats entier est lu à partir du serveur quand une instruction est exécutée. Remarque : à compter de la version 1.2 du pilote JDBC, le comportement de mise en mémoire tampon par défaut est « adaptatif ». Si vous souhaitez conserver le comportement par défaut de la version 1.2 dans votre application, définissez la propriété responseBufferring sur « complète » dans les propriétés de connexion ou utilisez la méthode setResponseBuffering de l’objet SQLServerStatement. |
| selectMethod String ["direct" | "cursor"] directes |
Si cette propriété a la valeur « cursor », un curseur de base de données est créé pour chaque requête créée sur la connexion pour les curseurs TYPE_FORWARD_ONLY et CONCUR_READ_ONLY. Cette propriété n’est généralement requise que si l’application génère de grands jeux de résultats qui ne peuvent pas être entièrement contenus dans la mémoire du client. Si cette propriété est définie sur « cursor », seul un nombre limité de lignes du jeu de résultats est conservé dans la mémoire du client. Le comportement par défaut est que toutes les lignes du jeu de résultats sont conservées dans la mémoire du client. Ce comportement est le plus rapide si l'application doit traiter toutes les lignes. |
| sendStringParameters... AsUnicode boolean ["true" | "false"] true |
Si la propriété sendStringParametersAsUnicode a la valeur « true », les paramètres de chaîne sont envoyés au serveur au format Unicode. Si la propriété sendStringParametersAsUnicode a la valeur « false », les paramètres de chaîne sont envoyés au serveur dans un format non Unicode, par exemple ASCII/MBCS. La valeur par défaut de la propriété sendStringParametersAsUnicode est « true ». Remarque : La propriété sendStringParametersAsUnicode est uniquement vérifiée lors de l’envoi d’une valeur de paramètre avec les types JDBC CHAR, VARCHAR ou LONGVARCHAR. Les nouvelles méthodes JDBC 4.0 prenant en charge les caractères nationaux, comme les méthodes setNString, setNCharacterStream et setNClob des classes SQLServerPreparedStatement et SQLServerCallableStatement. Ces méthodes envoient toujours leurs valeurs de paramètre au serveur en Unicode, quel que soit le paramètre de cette propriété. Pour garantir des performances optimales avec les types de données JDBC CHAR, VARCHAR et LONGVARCHAR, une application doit affecter la valeur « false » à la propriété sendStringParametersAsUnicode et utiliser les méthodes setString, setCharacterStream et setClob et basées sur les caractères non nationaux des classes SQLServerPreparedStatement et SQLServerCallableStatement. Quand l’application définit la propriété sendStringParametersAsUnicode sur « false » et qu’elle utilise une méthode basée sur des caractères non nationaux pour accéder aux types de données Unicode côté serveur (comme nchar, nvarchar et ntext), certaines données risquent d’être perdues si le classement de la base de données ne prend pas en charge les caractères des paramètres de chaîne passés par la méthode utilisant des caractères non nationaux. Une application doit utiliser les méthodes basées sur les caractères nationaux setNString, setNCharacterStream et setNClob des classes SQLServerPreparedStatement et SQLServerCallableStatement pour les types de données JDBC NCHAR, NVARCHAR et LONGNVARCHAR. La modification de cette valeur peut affecter le tri des résultats de la base de données. Les différences de tri sont dues à différentes règles de tri pour les caractères Unicode et non Unicode. |
| sendTemporalDataTypes... AsStringForBulkCopy booléen ["true" | "false"] true |
(Version 8.4+) Cette propriété de connexion, lorsqu’elle a la valeur « false », envoie les types de données DATE, DATETIME, DATIMETIME2, DATETIMEOFFSET, SMALLDATETIME et TIME en tant que leurs types respectifs au lieu de les envoyer en tant que Chaîne. Avec cette propriété de connexion définie sur « false », le pilote accepte seulement le format de littéral de chaîne par défaut de chaque type de données temporel, par exemple : DATE : YYYY-MM-DDDATETIME : YYYY-MM-DD hh:mm:ss[.nnn]DATETIME2 : YYYY-MM-DD hh:mm:ss[.nnnnnnn]DATETIMEOFFSET : YYYY-MM-DD hh:mm:ss[.nnnnnnn] [{+/-}hh:mm]SMALLDATETIME : YYYY-MM-DD hh:mm:ssTIME : hh:mm:ss[.nnnnnnn] |
| sendTimeAsDatetime boolean ["true" | "false"] true |
Cette propriété a été ajoutée dans SQL Server JDBC Driver 3.0. Affectez la valeur « true » pour envoyer les valeurs de temps java.sql. au serveur en tant que valeurs DateHeure. Affectez la valeur « false » pour envoyer les valeurs de temps java.sql. au serveur en tant que valeurs temps. La valeur par défaut de cette propriété, actuellement « true », pourra être modifiée dans une prochaine version. Pour savoir plus en détail comment le pilote JDBC Microsoft pour SQL Server configure les valeurs de temps java.sql. avant de les envoyer au serveur, consultez Configuration de la manière dont les valeurs de temps java.sql. sont envoyées au serveur. |
| serverCertificate, server String null |
(Version 11.2.0+) Chemin d’accès au fichier de certificat du serveur. Utilisé pour la validation lors de l’utilisation du chiffrement défini sur strict. Le pilote prend en charge les fichiers de certificat au format de fichier PEM. |
| serverName, server String null |
L’ordinateur qui exécute SQL Server ou une base de données Azure SQL. Vous pouvez également spécifier le nom du réseau virtuel d’un groupe de disponibilité. Pour plus d’informations sur la reprise d’activité, consultez Prise en charge de la haute disponibilité et de la reprise d’activité par le pilote JDBC. |
| serverNameAsACE boolean ["true" | "false"] false |
(Version 6.0+) Affectez la valeur « true » pour indiquer que le pilote doit traduire le nom du serveur Unicode en codage compatible ASCII (Punycode) pour la connexion. Si ce paramètre a la valeur « false », le pilote utilise le nom du serveur tel qu’il est fourni pour la connexion. Pour plus d’informations sur les fonctionnalités internationales, consultez Fonctionnalités internationales du pilote JDBC. |
| serverPreparedStatement... DiscardThreshold Integer 10 |
(Version 6.2+) Cette propriété permet de contrôler le nombre maximal d’actions d’abandon d’instruction préparée en attente (sp_unprepare) par connexion avant l’exécution d’un appel pour nettoyer les descripteurs en attente sur le serveur. Si elle a la valeur définie sur <= 1, les actions d’annulation de la préparation sont exécutées immédiatement à la fermeture de l’instruction préparée. Si la propriété est définie sur > 1, ces appels sont regroupés pour éviter la surcharge liée aux appels trop fréquents de sp_unprepare. |
| serverSpn String null |
(Version 4.2+) Cette propriété facultative peut être utilisée pour spécifier le nom de principal du service (SPN) pour une connexion Java Kerberos. Elle est utilisée avec authenticationScheme. Pour spécifier le nom de principal du service, vous pouvez utiliser le format « MSSQLSvc/fqdn:port@REALM », où fqdn désigne le nom de domaine complet, port désigne le numéro de port et REALM désigne le domaine Kerberos de SQL Server en majuscules. Remarque : la partie @REALM est facultative si le domaine par défaut du client (comme spécifié dans la configuration Kerberos) est le même que le domaine Kerberos pour le serveur SQL Server. Pour plus d’informations sur l’utilisation de serverSpn avec Java Kerberos, consultez Utilisation de l’authentification intégrée Kerberos pour se connecter à SQL Server. |
| socketFactoryClass String null |
(Version 8.4+) Spécifie le nom de classe d’une fabrique de sockets personnalisée à utiliser à la place de la fabrique de sockets par défaut. |
| socketTimeout int 0 |
Nombre de millisecondes à attendre avant expiration du délai d’attente de lecture ou d’acceptation d’un socket. La valeur 0 par défaut signifie un délai infini. |
| statementPooling… CacheSize int 0 |
(Version 6.4+) Cette propriété permet d’activer la mise en cache des descripteurs d’instructions préparées dans le pilote. Cette propriété définit la taille du cache du regroupement d’instructions. Cette propriété peut être utilisée seulement avec la propriété de connexion disableStatementPooling, qui doit avoir la valeur « false ». Si disableStatementPooling a la valeur « true » ou statementPoolingCacheSize la valeur 0, la mise en cache des handles d’instructions préparées est désactivée. |
| sslProtocol String TLS |
(Version 6.4+) Cette propriété permet de spécifier le protocole TLS à utiliser pendant la connexion sécurisée. Les valeurs possibles sont les suivantes : TLS, TLSv1, TLSv1.1 et TLSv1.2. Pour plus d’informations sur le protocole SSL (Secure Sockets Layer), consultez SSLProtocol. |
| transparentNetwork… IPResolution boolean ["true" | "false"] true |
(Version 6.0+) Cette propriété accélère la détection et la connexion au serveur (actuellement) actif. Les valeurs possibles sont « true » (par défaut) et « false ». Avant la version 6.0 de Microsoft JDBC Driver pour SQL Server, l’application devait définir la chaîne de connexion de façon à inclure « multiSubnetFailover=true » pour indiquer qu’elle se connectait à un groupe de disponibilité AlwaysOn. Si elle ne définissait le mot clé de connexion multiSubnetFailover sur « true », elle risquait de se heurter à un délai d’expiration lors de la connexion au groupe de disponibilité AlwaysOn. Avec les versions 6.0 et ultérieures, une application n’a plus besoin d’affecter la valeur « true » à multiSubnetFailover. Remarque : Lorsque transparentNetworkIPResolution=true, la première tentative de connexion utilise 500 ms comme délai d’expiration. Toutes les tentatives suivantes utilisent la même logique de délai d’attente que la propriété multiSubnetFailover. |
| trustManagerClass String null |
(Version 6.4+) Nom complet de la classe d’une implémentation javax.net.ssl.TrustManager personnalisée. |
| trustManager… ConstructorArg String null |
(Version 6.4+) Argument facultatif à transmettre au constructeur du TrustManager. Si la propriété trustManagerClass est spécifiée et qu’une connexion chiffrée est demandée, c’est le TrustManager personnalisé qui est utilisé à la place du TrustManager par défaut basé sur le magasin de clés de la machine virtuelle Java du système. |
| trustServerCertificate boolean ["true" | "false"] false |
Affectez la valeur « true » pour spécifier que le pilote ne valide pas le certificat TLS/SSL du serveur. Si la valeur est « true », le certificat TLS/SSL du serveur est approuvé automatiquement quand la couche de communication est chiffrée à l’aide du protocole TLS. Si la valeur est « false », le pilote valide le certificat TLS/SSL du serveur. Si la validation du certificat de serveur échoue, le pilote génère une erreur et ferme la connexion. La valeur par défaut est « false ». Pour garantir une connexion TLS/SSL, vérifiez que la valeur passée à serverName correspond exactement au nom CN (Nom commun) ou DNS dans le nom SAN (Autre nom du sujet) du certificat de serveur. Pour plus d’informations sur la prise en charge du chiffrement, consultez Comprendre la prise en charge du chiffrement. Remarque : Cette propriété est utilisée en association avec les propriétés encrypt/authentication. Cette propriété affecte seulement la validation du certificat TLS/SSL de serveur si la connexion utilise le chiffrement TLS. |
| trustStore String null |
Chemin d'accès (y compris le nom de fichier) au fichier trustStore de certificat. Le fichier trustStore contient la liste des certificats approuvés par le client. Quand cette propriété n’est pas spécifiée ou a la valeur null, le pilote se fie aux règles de recherche de la fabrication du gestionnaire d’approbation pour déterminer le magasin de certificats à utiliser. Le TrustManagerFactory SunX509 par défaut essaie de localiser les informations approuvées dans l’ordre de recherche suivant : Un fichier spécifié par la propriété système de machine virtuelle Java (JVM) « javax.net.ssl.trustStore ». fichier <java-home>/lib/security/jssecacerts.fichier <java-home>/lib/security/cacerts.Pour plus d’informations sur l’interface SUNX509 TrustManager, consultez la documentation de l’interface SUNX509 TrustManager sur le site web de Sun Microsystems. Remarque : Cette propriété affecte seulement la recherche du trustStore du certificat si la connexion utilise le chiffrement TLS et que la propriété trustServerCertificate est définie sur « false ». |
| trustStorePassword String null |
Mot de passe utilisé pour vérifier l'intégrité des données trustStore. Si la propriété trustStore est définie mais que la propriété trustStorePassword ne l’est pas, l’intégrité du trustStore n’est pas vérifiée. Quand les propriétés trustStore et trustStorePassword ne sont pas spécifiées, le pilote utilise les propriétés système JVM « javax.net.ssl.trustStore » et « javax.net.ssl.trustStorePassword ». Si la propriété système « javax.net.ssl.trustStorePassword » n’est pas spécifiée, l’intégrité du trustStore n’est pas vérifiée. Si l’utilisateur ne définit pas la propriété trustStore, mais qu’il définit la propriété trustStorePassword, le pilote JDBC utilise le fichier que « javax.net.ssl.trustStore » spécifie comme magasin de confiance. En outre, le pilote vérifie l’intégrité du magasin de confiance à l’aide du trustStorePassword spécifié. Ce paramètre est nécessaire quand l’application cliente ne veut pas stocker le mot de passe dans la propriété système JVM. Remarque : la propriété trustStorePassword affecte uniquement la recherche du trustStore de certificats si la connexion utilise la connexion TLS et que la propriété trustServerCertificate est définie sur « false ». |
| trustStoreType String JKS |
Définissez cette propriété pour spécifier le type de magasin de confiance à utiliser pour le mode FIPS. Les valeurs possibles sont PKCS12 ou le type défini par le fournisseur FIPS. |
| useBulkCopyFor… BatchInsert boolean ["true" | "false"] false |
(Version 9.2+) Cette propriété de connexion peut être activée pour utiliser de manière transparente l’API de copie en bloc lors de l’exécution d’opérations d’insertion par lots avec java.sql.PreparedStatement. Cette fonctionnalité offre potentiellement des performances supérieures lorsqu’elle est activée. Cette fonctionnalité est désactivée par défaut. Affectez la valeur « true » à cette propriété pour activer cette fonctionnalité. Remarque importante : cette fonctionnalité prend uniquement en charge des requêtes INSERT entièrement paramétrables. Si les requêtes INSERT sont combinées avec d’autres requêtes SQL ou contiennent des données dans des valeurs, l’exécution revient à l’opération d’insertion par lots de base. Pour plus d’informations sur l’utilisation de cette propriété, consultez Utiliser l’API de copie en bloc pour les opérations d’insertion par lots. |
| useDefaultGSSCredential booléen ["true" | "false"] false |
(Version 12.6+) Indicateur qui spécifie si le pilote doit créer le GSSCredential au nom de l’utilisateur pour l’utilisation de l’interface native GSS-API pour l’authentification Kerberos. |
| useDefaultJaasConfig booléen ["true" | "false"] false |
(Version 12.6+) Lorsque l’application existe en même temps que les bibliothèques qui configurent JAAS au niveau système, la définition de cette propriété sur true permet au pilote d’utiliser cette même configuration pour effectuer l’authentification Kerberos. |
| useFmtOnly boolean ["true" | "false"] false |
(Version 7.4+) Propose un autre moyen d’interroger les métadonnées des paramètres à partir du serveur. Définissez cette propriété sur « true » pour spécifier que le pilote doit utiliser la logique SET FMTONLY lors de l’interrogation des métadonnées de paramètre. Cette fonctionnalité est désactivée par défaut ; il n’est pas recommandé d’utiliser cette propriété, car SET FMTONLY est déprécié. useFmtOnly n’est utilisable que comme solution de contournement des problèmes et limitations connus dans sp_describe_undeclared_parameters.Cette fonctionnalité ne prend actuellement en charge que les requêtes SELECT/INSERT/UPDATE/DELETE uniques. Si vous essayez de l’utiliser avec des requêtes non prises en charge/multiples, le pilote tente d’analyser la requête, mais une exception se produit probablement.Pour plus d’informations sur cette propriété, consultez Récupérer ParameterMetaData via useFmtOnly. |
| userName, utilisateur String [<=128 char] null |
Utilisateur de la base de données, en cas de connexion avec un utilisateur et un mot de passe SQL. Pour la connexion Kerberos avec un nom de principal et un mot de passe, cette propriété est définie sur le nom du principal Kerberos. (Version 10.2+) Quand authentication=ActiveDirectoryServicePrincipal, la propriété nom d'utilisateur spécifie un ID de client sécurisé Azure Active Directory valide. |
| workstationID String [<=128 char] <empty string> |
ID de station de travail. Sert à identifier la station de travail spécifique dans divers outils de profilage et de journalisation. Si aucune option est spécifiée, <empty string> est utilisé. |
| xopenStates boolean ["true" | "false"] false |
Définir sur « true » pour spécifier que le pilote retourne les codes d'état compatibles XOPEN dans des exceptions. Par défaut, des codes d'état SQL 99 sont retournés. |
Notes
Le pilote JDBC Microsoft pour SQL Server prend les valeurs par défaut du serveur pour les propriétés de connexion à l'exception de ANSI_DEFAULTS et IMPLICIT_TRANSACTIONS. Le pilote JDBC Microsoft pour SQL Server définit automatiquement la valeur ON à ANSI_DEFAULTS et la valeur OFF à IMPLICIT_TRANSACTIONS.
Important
Si l’authentification est définie sur ActiveDirectoryPassword, la bibliothèque suivante doit être incluse dans classpath : microsoft-authentication-library-for-java. Elle se trouve dans le référentiel Maven. Le plus simple pour télécharger la bibliothèque et ses dépendances consiste à utiliser Maven :
- Installez Maven sur votre système.
- Accédez à la page GitHub du pilote.
- Téléchargez le fichier pom.xml.
- Exécutez la commande Maven suivante pour télécharger la bibliothèque et ses dépendances :
mvn dependency:copy-dependencies.