Configuration du pilote JDBC

Cette rubrique explique comment configurer le pilote JDBC, notamment comment se connecter à Snowflake à l’aide du pilote.

Note

Les paramètres de connexion sont maintenant documentés dans le Référence Paramètre de connexion pilote JDBC.

Dans ce chapitre :

Classe de pilote JDBC

Utilisez net.snowflake.client.jdbc.SnowflakeDriver comme classe de pilote dans votre application JDBC.

Note

  • Ne faites pas référence à d’autres classes ou méthodes Snowflake dans votre code d’application, car elles seront ultérieurement modifiées afin d’y implémenter des améliorations et des corrections.

  • La classe de pilote précédente, com.snowflake.client.jdbc.SnowflakeDriver, est toujours prise en charge mais est obsolète (c’est-à-dire qu’elle sera supprimée dans une prochaine version, TBD). Ainsi, tout code qui fait référence au nom de classe précédent continue de fonctionner, mais vous devez mettre à jour le code pour faire référence au nouveau nom de classe maintenant que la modification a été implémentée.

Chaîne de connexion de pilote JDBC

L’utilisation du pilote JDBC pour se connecter à Snowflake nécessite une chaîne de connexion avec la syntaxe suivante.

Syntaxe

jdbc:snowflake://<account_identifier>.snowflakecomputing.com/?<connection_params>
Copy

Paramètres de connexion

Note

Pour la documentation sur les différents paramètres de connexion, voir le Référence Paramètre de connexion pilote JDBC.

<identificateur_de_compte>

Spécifie l’identificateur de compte pour votre compte Snowflake. Pour plus de détails, voir Identificateurs de compte. Pour des exemples de l’identificateur de compte utilisé dans une chaîne de connexion JDBC, voir Exemples.

<params_connexion>

Spécifie une série d’un ou plusieurs JDBC paramètres de connexion et paramètres de session, sous la forme de <paramètres>=<valeur>, chaque paramètre étant séparé par une esperluette (&), et avec aucun espace dans la chaîne de connexion.

Si vous devez définir des valeurs de paramètres qui utilisent des espaces, des esperluettes (&), des signes égaux (=) ou d’autres caractères spéciaux, vous devez encoder par URL les caractères spéciaux. Par exemple, si vous devez spécifier une valeur qui contient un espace, une esperluette et un signe égal dans le paramètre de session query_tag :

String connectionURL = "jdbc:snowflake://myorganization-myaccount.snowflakecomputing.com/?query_tag='folder=folder1 folder2&'
Copy

codez l’espace comme %20, l’esperluette comme %26, et le signe égal comme %3D :

String connectionURL = "jdbc:snowflake://myorganization-myaccount.snowflakecomputing.com/?query_tag='folder%3Dfolder1%20folder2%26'
Copy

Au lieu de spécifier ces paramètres dans la chaîne de connexion, vous pouvez les définir dans un objet Properties que vous transmettez à la méthode DriverManager.getConnectionIO .

Properties props = new Properties();
props.put("parameter1", parameter1Value);
props.put("parameter2", parameter2Value);
Connection con = DriverManager.getConnection("jdbc:snowflake://<account_identifier>.snowflakecomputing.com/", props);
Copy

Note

Pour la documentation sur les différents paramètres de connexion, voir le Référence Paramètre de connexion pilote JDBC.

Autres paramètres

Tout paramètre de session peut être inclus dans la chaîne de connexion. Par exemple :

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Booléen>

Indique si la télémétrie hors bande doit être activée.

La valeur par défaut est true.

CLIENT_SESSION_KEEP_ALIVE=<Booléen>

Indique si la session en cours doit rester active après une période d’inactivité ou si l’utilisateur doit se reconnecter. Si la valeur est true, Snowflake garde la session active indéfiniment, même s’il n’y a aucune activité de l’utilisateur. Si la valeur est false, l’utilisateur doit se reconnecter après quatre heures d’inactivité.

La valeur par défaut est false.

CLIENT_SESSION_KEEP_ALIVE_HEARTBEAT_FREQUENCY=<Entier>

Nombre de secondes (900-3 600) entre les tentatives du client pour mettre à jour le jeton pour la session.

La valeur par défaut est 3600.

Pour une description de tous les paramètres de session, voir Paramètres.

Exemples

Voici un exemple de la chaîne de connexion qui utilise un identificateur de compte qui spécifie le compte myaccount dans l’organisation myorganization.

jdbc:snowflake://myorganization-myaccount.snowflakecomputing.com/?user=peter&warehouse=mywh&db=mydb&schema=public
Copy

Voici un exemple de chaîne de connexion qui utilise le localisateur de compte xy12345 comme identificateur de compte :

jdbc:snowflake://xy12345.snowflakecomputing.com/?user=peter&warehouse=mywh&db=mydb&schema=public
Copy

Notez que cet exemple utilise un compte dans la région AWS US Ouest (Oregon). Si le compte se trouve dans une autre région ou s’il utilise un autre fournisseur Cloud, vous devez spécifier des segments supplémentaires après le localisateur de compte.

Utilisation de la connexion unique (SSO) pour l’authentification

Si vous avez configuré Snowflake pour utiliser la connexion unique (SSO), vous pouvez configurer votre application cliente pour utiliser SSO pour l’authentification. Voir Utilisation de SSO avec des applications clientes qui se connectent à Snowflake pour plus de détails.

Utilisation de l’authentification multifactorielle

Snowflake prend en charge la mise en cache des jetons MFA, y compris la combinaison de la mise en cache des jetons MFA avec le SSO.

Pour plus d’informations, voir Utilisation de la mise en cache des jetons MFA pour réduire le nombre d’invites lors de l’authentification — Facultatif.

Utilisation de l’authentification par paire de clés et rotation de clés

Le pilote Snowflake JDBC prend en charge l’authentification par paire de clés et la rotation des clés. Cette méthode d’authentification nécessite une paire de clés de 2048 bits (minimum) RSA.

Pour commencer, complétez la configuration initiale pour l’authentification de la paire de clés comme indiqué dans Authentification par paire de clés et rotation de paires de clés.

Ensuite, choisissez l’une des trois options suivantes pour configurer soit les propriétés de connexion JDBC, soit la chaîne de connexion JDBC.

  1. Spécifiez la clé privée via la propriété privateKey dans les propriétés de connexion.

  2. Spécifiez le nom et le mot de passe du fichier de clé privée pour ce fichier en tant que propriétés distinctes dans les propriétés de connexion.

  3. Spécifiez le nom et le mot de passe du fichier de clé privée pour ce fichier dans la chaîne de connexion.

Ces options sont décrites plus en détail dans les trois sections suivantes.

Propriété privateKey dans les propriétés de connexion

Cette section fournit un exemple de paramétrage de la propriété privateKey à une clé privée dans un fichier.

Cet exemple utilise les Crypto APIs de Bouncy Castle. Afin de compiler et d’exécuter cet exemple, vous devez inclure les fichiers JAR suivants dans votre classpath :

  • le fichier JAR du fournisseur (bcprov-jdkversions.jar)

  • le fichier PKIX / CMS / EAC / PKCS / OCSP / TSP / OPENSSL JAR (bcpkix-jdkversions.jar)

versions indique les versions du JDK que le fichier JAR prend en charge.

Pour utiliser cet exemple :

  1. Copiez l’exemple de code sous, et remplacez les caractères de remplacement suivants :

    Caractère de remplacement

    Description

    path/rsa_key.p8

    Définissez le chemin et le nom du fichier de clé privée que vous avez généré précédemment.

    private_key_passphrase

    Si vous avez généré une clé chiffrée, implémentez la méthode getPrivateKeyPassphrase() pour renvoyer la phrase secrète afin de déchiffrer cette clé.

    account_identifier

    Définissez ceci sur votre identificateur de compte.

    user

    Indiquez votre nom de connexion Snowflake.

    database_name

    Indiquez le nom de la base de données que vous voulez utiliser.

    schema_name

    Indiquez le nom du schéma que vous voulez utiliser.

    warehouse_name

    Indiquez le nom de l’entrepôt que vous voulez utiliser.

    role

    Définissez le nom du rôle que vous voulez utiliser.

  2. Compilez et exécutez l’exemple de code. Incluez les fichiers JAR Bouncy Castle dans le classpath.

    Par exemple, sur Linux et macOS :

    javac -cp bcprov-jdk<versions>.jar:bcpkix-jdk<versions>.jar TestJdbc.java
    
    java -cp .:snowflake-jdbc-<ver>.jar:bcprov-jdk<versions>.jar:bcpkix-jdk<versions>.jar TestJdbc.java
    
    Copy

    Sur Windows :

    javac -cp bcprov-jdk<versions>.jar;bcpkix-jdk<versions>.jar TestJdbc.java
    
    java -cp .;snowflake-jdbc-<ver>.jar;bcprov-jdk<versions>.jar;bcpkix-jdk<versions>.jar TestJdbc.java
    
    Copy

Exemple de code

import org.bouncycastle.asn1.pkcs.PrivateKeyInfo;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.openssl.PEMParser;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;
import org.bouncycastle.openssl.jcajce.JceOpenSSLPKCS8DecryptorProviderBuilder;
import org.bouncycastle.operator.InputDecryptorProvider;
import org.bouncycastle.operator.OperatorCreationException;
import org.bouncycastle.pkcs.PKCS8EncryptedPrivateKeyInfo;
import org.bouncycastle.pkcs.PKCSException;

import java.io.FileReader;
import java.io.IOException;
import java.nio.file.Paths;
import java.security.PrivateKey;
import java.security.Security;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.DriverManager;
import java.util.Properties;

public class TestJdbc
{
  // Path to the private key file that you generated earlier.
  private static final String PRIVATE_KEY_FILE = "/<path>/rsa_key.p8";

  public static class PrivateKeyReader
  {

    // If you generated an encrypted private key, implement this method to return
    // the passphrase for decrypting your private key.
    private static String getPrivateKeyPassphrase() {
      return "<private_key_passphrase>";
    }

    public static PrivateKey get(String filename)
            throws Exception
    {
      PrivateKeyInfo privateKeyInfo = null;
      Security.addProvider(new BouncyCastleProvider());
      // Read an object from the private key file.
      PEMParser pemParser = new PEMParser(new FileReader(Paths.get(filename).toFile()));
      Object pemObject = pemParser.readObject();
      if (pemObject instanceof PKCS8EncryptedPrivateKeyInfo) {
        // Handle the case where the private key is encrypted.
        PKCS8EncryptedPrivateKeyInfo encryptedPrivateKeyInfo = (PKCS8EncryptedPrivateKeyInfo) pemObject;
        String passphrase = getPrivateKeyPassphrase();
        InputDecryptorProvider pkcs8Prov = new JceOpenSSLPKCS8DecryptorProviderBuilder().build(passphrase.toCharArray());
        privateKeyInfo = encryptedPrivateKeyInfo.decryptPrivateKeyInfo(pkcs8Prov);
      } else if (pemObject instanceof PrivateKeyInfo) {
        // Handle the case where the private key is unencrypted.
        privateKeyInfo = (PrivateKeyInfo) pemObject;
      }
      pemParser.close();
      JcaPEMKeyConverter converter = new JcaPEMKeyConverter().setProvider(BouncyCastleProvider.PROVIDER_NAME);
      return converter.getPrivateKey(privateKeyInfo);
    }
  }

  public static void main(String[] args)
      throws Exception
  {
    String url = "jdbc:snowflake://<account_identifier>.snowflakecomputing.com";
    Properties prop = new Properties();
    prop.put("user", "<user>");
    prop.put("privateKey", PrivateKeyReader.get(PRIVATE_KEY_FILE));
    prop.put("db", "<database_name>");
    prop.put("schema", "<schema_name>");
    prop.put("warehouse", "<warehouse_name>");
    prop.put("role", "<role_name>");

    Connection conn = DriverManager.getConnection(url, prop);
    Statement stat = conn.createStatement();
    ResultSet res = stat.executeQuery("select 1");
    res.next();
    System.out.println(res.getString(1));
    conn.close();
  }
}
Copy

Note

Utilisez des barres obliques comme séparateurs de chemin d’accès aux fichiers sur tous les systèmes d’exploitation, y compris Windows. Le pilote JDBC remplace les barres obliques par le séparateur de chemin approprié à la plate-forme.

Nom et mot de passe du fichier de clé privée comme propriétés de connexion

Vous pouvez spécifier le nom et le mot de passe du fichier de clé privée en tant que propriétés de connexion distinctes, par exemple :

Properties props = new Properties();
props.put("private_key_file", "/tmp/rsa_key.p8");
props.put("private_key_file_pwd", "dummyPassword");
Connection connection = DriverManager.getConnection("jdbc:snowflake://myorganization-myaccount.snowflake.com", props);
Copy

Si vous spécifiez les paramètres private_key_file et private_key_file_pwd, ne spécifiez pas le paramètre privateKey dans les propriétés de connexion.

Note

Utilisez des barres obliques comme séparateurs de chemin d’accès aux fichiers sur tous les systèmes d’exploitation, y compris Windows. Le pilote JDBC remplace les barres obliques par le séparateur de chemin approprié à la plate-forme.

Nom et mot de passe du fichier de clé privée dans la chaîne de connexion

Vous pouvez spécifier le nom et le mot de passe du fichier de clé privée dans la chaîne de connexion, comme indiqué ci-dessous :

Connection connection = DriverManager.getConnection(
    "jdbc:snowflake://myorganization-myaccount.snowflake.com/?private_key_file=/tmp/rsa_key.p8&private_key_file_pwd=dummyPassword",
    props);
Copy

Note

Utilisez des barres obliques comme séparateurs de chemin d’accès aux fichiers sur tous les systèmes d’exploitation, y compris Windows. Le pilote JDBC remplace les barres obliques par le séparateur de chemin approprié à la plate-forme.

Si vous spécifiez la clé privée et le mot de passe dans la chaîne de connexion, ne spécifiez pas les paramètres private_key_file, private_key_file_pwd ou privateKey dans les propriétés de connexion.

Vérification de la connexion réseau à Snowflake avec SnowCD

Après avoir configuré votre pilote, vous pouvez évaluer et dépanner votre connectivité réseau à Snowflake en utilisant SnowCD.

Vous pouvez utiliser SnowCD pendant le processus de configuration initiale et à la demande à tout moment pour évaluer et dépanner votre connexion réseau à Snowflake.

Connexion à l’aide d’un serveur proxy

Il existe deux façons d’utiliser un serveur proxy avec le pilote JDBC de Snowflake :

  • Définissez les propriétés système de vos paramètres de proxy dans la JVM (Java Virtual Machine) pour votre application client.

  • Incluez les informations d’hôte et de port du proxy dans la chaîne de connexion JDBC ou l’objet Properties transmis à la méthode DriverManager.getConnection() .

Les deux techniques sont documentées ci-dessous.

Note

Les paramètres du proxy dans la chaîne de connexion remplacent les propriétés du système de proxy qui sont définies dans la JVM.

Astuce

Le modèle de sécurité de Snowflake n’autorise pas les proxys de type Transport Layer Security (TLS) (utilisant un certificat HTTPS). Votre serveur de proxy doit utiliser une autorité de certification accessible au public (CA), réduisant ainsi les risques potentiels de sécurité tels qu’une attaque MITM (Man In The Middle) via un proxy compromis.

Si vous devez utiliser votre proxy TLS, nous vous recommandons fortement de mettre à jour la politique du serveur pour passer par le certificat Snowflake, afin qu’aucun certificat ne soit modifié au milieu des communications.

Vous pouvez également définir le paramètre nonProxyHosts dans la chaîne de connexion ou l’objet Properties afin de contourner le proxy pour des communications spécifiques. Par exemple, l’accès Amazon S3 peut être contourné en spécifiant nonProxyHosts=".amazonaws.com".

Spécification d’un serveur proxy en définissant les propriétés du système Java

Pour vous connecter via un serveur proxy, vous pouvez définir les propriétés du système proxy. Vous pouvez soit les définir dans votre code, soit les transmettre sur la ligne de commande à la JVM (Java Virtual Machine) de votre application cliente.

Pour définir les propriétés du système dans votre code, appelez System.setProperty :

System.setProperty("http.useProxy", "true");
System.setProperty("http.proxyHost", "proxyHost Value");
System.setProperty("http.proxyPort", "proxyPort Value");
System.setProperty("https.proxyHost", "proxyHost HTTPS Value");
System.setProperty("https.proxyPort", ""proxyPort HTTPS Value"")
System.setProperty("http.proxyProtocol", "https");
Copy

Pour transmettre les propriétés du système sur la ligne de commande à votre JVM, utilisez l’option de ligne de commande -D :

-Dhttp.useProxy=true
-Dhttps.proxyHost=<proxy_host>
-Dhttp.proxyHost=<proxy_host>
-Dhttps.proxyPort=<proxy_port>
-Dhttp.proxyPort=<proxy_port>
-Dhttp.proxyProtocol="https"
Copy

Pour contourner le proxy pour une ou plusieurs adresses IP ou un ou plusieurs hôtes, définissez la propriété système http.nonProxyHosts comme la liste de ces hôtes :

  • Utilisez un symbole barre verticale (|) pour séparer les noms d’hôtes.

  • Pour spécifier les noms d’hôtes qui correspondent à un modèle, utilisez un astérisque (*) comme caractère générique.

L’exemple suivant montre comment définir cette propriété système sur la ligne de commande :

-Dhttp.nonProxyHosts="*.my_company.com|localhost|myorganization-myaccount.snowflakecomputing.com|192.168.91.*"
Copy

Spécification d’un serveur proxy dans la chaîne de connexion JDBC

Note

La spécification des informations de proxy dans l’URL est moins sécurisée que d’autres méthodes de spécification des informations de proxy.

Pour utiliser un serveur proxy en définissant les paramètres suivants dans la chaîne de connexion JDBC :

Si votre serveur proxy ne nécessite pas d’authentification, vous pouvez omettre les paramètres proxyUser et proxyPassword .

Si la connexion à votre serveur proxy nécessite une authentification à l’aide d’un nom d’utilisateur et d’un mot de passe proxy, ces identifiants de connexion peuvent être exposés en texte clair par d’autres applications lors de l’utilisation du protocole HTTP. Pour éviter d’exposer ces identifiants de connexion, utilisez le paramètre proxyProtocol pour spécifier le protocole HTTPS.

jdbc:snowflake://<account_identifier>.snowflakecomputing.com/?warehouse=<warehouse_name>&useProxy=true&proxyHost=<ip_address>&proxyPort=<port>&proxyUser=test&proxyPassword=test
Copy

Par exemple :

jdbc:snowflake://myorganization-myaccount.snowflakecomputing.com/?warehouse=DemoWarehouse1&useProxy=true&proxyHost=172.31.89.76&proxyPort=8888&proxyUser=test&proxyPassword=test
Copy

Les paramètres du proxy que vous spécifiez dans la chaîne de connexion remplacent les propriétés du système de proxy dans la JVM.

Contourner le serveur proxy

Si vous devez contourner le serveur proxy lors de la connexion à un ou plusieurs hôtes, spécifiez la liste des hôtes dans le paramètre nonProxyHosts :

&nonProxyHosts=<bypass_proxy_for_these_hosts>
Copy

Séparez les noms d’hôtes par un symbole barre verticale avec échappement d’URL(%7C). Vous pouvez également utiliser un astérisque (*) comme caractère générique. Par exemple :

&nonProxyHosts=*.my_company.com%7Clocalhost%7Cmyorganization-myaccount.snowflakecomputing.com%7C192.168.91.*
Copy

Spécifier le protocole utilisé pour se connecter au serveur proxy

Vous pouvez utiliser le paramètre proxyProtocol pour spécifier le protocole utilisé pour se connecter au serveur proxy. La valeur par défaut est http. Les valeurs valides sont http et https.

Par exemple :

&proxyProtocol=https
Copy

OCSP

Lorsque le pilote se connecte, Snowflake envoie un certificat confirmant que la connexion est établie avec Snowflake plutôt qu’avec un hôte empruntant l’identité de Snowflake. Le pilote envoie ce certificat à un serveur OCSP (protocole de statut de certificat en ligne) pour vérifier que le certificat n’a pas été révoqué.

Si le pilote ne peut pas atteindre le serveur OCSP pour vérifier le certificat, il peut entrainer un comportement « Fail open » ou « Fail closed ».

Choix du mode Fail-Open ou Fail-Close

Les versions de pilotes JDBC antérieures à la version 3.8.0 activent le mode Fail Close par défaut. Les versions 3.8.0 et ultérieures s’ouvrent avec le mode Fail-Open par défaut. Vous pouvez remplacer le comportement par défaut de l’une des manières suivantes :

  • Définissez la propriété de connexion ocspFailOpen sur true ou false. Par exemple :

    Properties connection_properties = new Properties();
    connection_properties.put("ocspFailOpen", "false");
    ...
    connection = DriverManager.getConnection(connectionString, connection_properties);
    
    Copy
  • Définissez la propriété système net.snowflake.jdbc.ocspFailOpen sur true ou false. Par exemple :

    Properties p = new Properties(System.getProperties());
    p.put("net.snowflake.jdbc.ocspFailOpen", "false");
    System.setProperties(p);
    
    Copy

Vérification de la version du connecteur ou du pilote OCSP

Pour plus d’informations sur la version du pilote ou du connecteur, la configuration et le comportement OCSP, voir Configuration d’OCSP.

Serveur de cache de réponse OCSP

Note

Le serveur de cache de réponse OCSP est actuellement pris en charge par le pilote Snowflake JDBC 3.6.0 et supérieur.

Les clients Snowflake initient chaque connexion à un point de terminaison de service Snowflake avec un « handshake » qui établit une connexion sécurisée avant de transférer les données. Dans le cadre du « handshake », un client authentifie le certificat TLS pour le point de terminaison de service. Le statut de révocation du certificat est vérifié en envoyant une demande de certificat client à l’un des serveurs OCSP (Online Certificate Status Protocol) pour le CA (autorité de certification).

Une défaillance de connexion se produit lorsque la réponse du serveur OCSP est retardée au-delà d’un délai raisonnable. Les caches suivants persistent le statut de révocation, ce qui permet de limiter ces problèmes :

  • La mémoire cache, qui continue d’exister durant la vie du processus.

  • Le cache de fichier, qui continue d’exister jusqu’à ce que le répertoire de cache (par exemple ~/.cache/snowflake ou ~/.snowsql/ocsp_response_cache) soit purgé.

  • Le serveur de cache de réponse OCSP Snowflake qui collecte toutes les heures les réponses OCSP des serveurs OCSP du CA et les stocke pendant 24 heures. Les clients peuvent alors interroger le statut de validation d’un certificat Snowflake donné à partir de ce cache de serveur.

    Important

    Si votre politique de serveur refuse l’accès à la plupart ou à la totalité des adresses IP et sites Web externes, vous devez ajouter l’adresse du serveur de cache à la liste d’autorisation pour permettre le fonctionnement normal du service. Le nom d’hôte du serveur de cache est ocsp*.snowflakecomputing.com:80.

    Si vous avez besoin de désactiver le serveur de cache pour une raison quelconque, réglez la variable d’environnement SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED sur false. Notez que la valeur est sensible à la casse et doit être en minuscules.

Si aucune des couches du cache ne contient la réponse OCSP, le client tente alors de récupérer le statut de validation directement depuis le serveur OCSP du CA.

Caches de fichiers

Pour une ergonomie accrue, le pilote utilise des caches de fichiers pour l’authentification et les réponses OCSP. Par défaut, ces fichiers sont stockés dans les répertoires suivants :

Linux:

~/.cache/snowflake

macOS:

~/Library/Caches/Snowflake

Windows:

%USERPROFILE%AppDataLocalSnowflakeCaches

Si l’utilisateur de l’application JDBC n’a pas de profil utilisateur dans le système d’exploitation local, le pilote tente de stocker les fichiers cache dans le répertoire temporaire. Vous pouvez configurer le pilote de façon à écrire les fichiers de cache dans un autre répertoire en utilisant les variables d’environnement suivantes :

SF_TEMPORARY_CREDENTIAL_CACHE_DIR=string

Spécifie l’emplacement du fichier temporaire de cache d’informations d’identification dans un répertoire local. Ceci peut également être configuré avec l’option JVM -Dnet.snowflake.jdbc.temporaryCredentialCacheDir=string au lancement.

SF_OCSP_RESPONSE_CACHE_DIR=string

Spécifie l’emplacement du fichier cache de réponse OCSP dans un répertoire local. Ceci peut également être configuré avec l’option JVM -Dnet.snowflake.jdbc.ocspResponseCacheDir=string au lancement.

Pour plus d’informations, voir Serveur de cache de réponse OCSP (dans ce chapitre).

Notez que les options JVM doivent être définies au lancement, et non par programmation (via System.setProperty()). Si la variable d’environnement et les options JVM sont fournies, l’option JVM sera utilisée.

Configuration de la journalisation JDBC

À partir de la version 3.0.4, le pilote JDBC accepte deux frameworks de journalisation :

Fonctions de journalisation principales Java (Java.util.logging)

Pour utiliser ce journaliseur, indiquez l’option suivante pour JVM :

-Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.JDK14Logger

Ensuite, vous pouvez personnaliser la configuration de la journalisation à l’aide de l’API (interface de programmation d’applications) pour le journaliseur. Pour plus de détails, voir la documentation de pack java.util.logging.

Par exemple, créez un fichier nommé logging.properties qui contient le contenu suivant :

###########################################################
#   Default Logging Configuration File
#
# You can use a different file by specifying a filename
# with the java.util.logging.config.file system property.
# For example java -Djava.util.logging.config.file=myfile
############################################################

############################################################
#   Global properties
############################################################

# "handlers" specifies a comma-separated list of log Handler
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# ConsoleHandler and FileHandler are configured here such that
# the logs are dumped into both a standard error and a file.
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers.  For any given facility this global level
# can be overriden by a facility specific level.
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level = INFO

############################################################
# Handler specific properties.
# Describes specific configuration information for Handlers.
############################################################

# default file output is in the tmp dir
java.util.logging.FileHandler.pattern = /tmp/snowflake_jdbc%u.log
java.util.logging.FileHandler.limit = 5000000000000000
java.util.logging.FileHandler.count = 10
java.util.logging.FileHandler.level = INFO
java.util.logging.FileHandler.formatter = net.snowflake.client.log.SFFormatter

# Limit the messages that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = net.snowflake.client.log.SFFormatter

# Example to customize the SimpleFormatter output format
# to print one-line log message like this:
#     <level>: <log message> [<date/time>]
#
# java.util.logging.SimpleFormatter.format=%4$s: %5$s [%1$tc]%n

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

# Snowflake JDBC logging level.
net.snowflake.level = INFO
net.snowflake.handler = java.util.logging.FileHandler
Copy

Spécifiez les paramètres JVM dans la ligne de commande :

java -jar application.jar -Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.JDK14Logger -Djava.util.logging.config.file=logging.properties
Copy

application.jar fait référence au code d’application du pilote JDBC. Les fichiers de journal sont situés dans /tmp/snowflake_jdbc*.

Façade de journalisation simple pour Java (org.slf4j)

Si un pack d’implémentation de journaliseur (c-à-d. org.sl4j:sl4j-jdk14 ou org.sl4j:slf4j-log4j12) ou un journaliseur personnalisé (c-à-d votre propre classe org.slf4j.impl.StaticLoggerBinder) a été défini pour le chemin de classe, alors le pilote utilise automatiquement ce journaliseur.

Vous pouvez également choisir explicitement d’utiliser ce journaliseur en spécifiant l’option JVM suivante :

-Dnet.snowflake.jdbc.loggerImpl=net.snowflake.client.log.SLF4JLogger.

Pour plus d’informations, voir la documentation Façade de journalisation simple pour Java (SLF4J).

Note

Si vous n’indiquez explicitement aucun journaliseur pour le pilote utilisant l’une des options JVM décrites ci-dessus et qu’aucun journaliseur personnalisé n’est défini sur le chemin de classe (ou que vous utilisez une version de pilote antérieure à 3.0.4), le pilote utilise java.util.logging par défaut. Toutefois, le comportement par défaut suivant s’applique :

  • Vous ne pouvez pas spécifier où le fichier journal est écrit. Il est toujours écrit dans le répertoire spécifié par la propriété système java.io.tmpDir :

    • Dans les environnements Linux et macOS, le répertoire par défaut est généralement /tmp ou /var/tmp.

    • Dans les environnements Windows, le répertoire par défaut est généralement C:\temp.

  • Le niveau de journalisation est déterminé par le paramètre de connexion tracing (voir ci-dessus).

Fichier de configuration de journalisation

Sinon, vous pouvez facilement spécifier le niveau de journalisation et le répertoire dans lequel enregistrer les fichiers journaux dans le fichier de configuration sf_client_config.json.

Note

Cette fonction du fichier de configuration de la journalisation ne prend en charge que les niveaux de journalisation suivants :

  • DEBUG

  • ERROR

  • INFO

  • OFF

  • TRACE

  • WARNING

Ce fichier de configuration utilise JSON pour définir les paramètres de journalisation log_level et log_path, comme suit :

{
  "common": {
    "log_level": "DEBUG",
    "log_path": "/home/user/logs"
  }
}
Copy

Le pilote recherche l’emplacement du fichier de configuration dans l’ordre suivant :

  • client_config_file Paramètre de connexion, contenant le chemin complet du fichier de configuration.

  • Variable d’environnement SF_CLIENT_CONFIG_FILE qui contient le chemin complet vers le fichier de configuration.

  • Répertoire d’installation du pilote JDBC, où le fichier doit être nommé sf_client_config.json.

  • Répertoire personnel de l’utilisateur, où le fichier doit être nommé sf_client_config.json.

Note

  • Si le fichier de configuration n’est pas trouvé dans l’un des emplacements précédents, le pilote utilise les fonctions de journalisation principales Java.

  • Si un fichier de configuration spécifié dans le paramètre de connexion client_config_file ou dans la variable d’environnement SF_CLIENT_CONFIG_FILE ne peut être trouvé ou lu, le pilote envoie un message d’erreur.

Désactivation des commandes PUT et GET

Par défaut, le pilote JDBC vous permet d’exécuter les commandes PUT et GET. Si vous ne souhaitez pas autoriser les commandes PUT et GET à accéder au système de fichiers local, vous pouvez désactiver ces commandes de la manière suivante :

  • Réglez le paramètre du serveur JDBC_ENABLE_PUT_GET sur FALSE.

  • Définissez le JDBC enablePutGet paramètre de connexion sur false.

  • Appelez la méthode SFBaseSession.setEnablePutGet(false).

Astuces de dépannage

Vérifier que les propriétés sont définies correctement

La méthode DriverManager.getConnection() lit uniquement les valeurs du paramètre Properties qui correspondent à des noms spécifiques prédéfinis (« mot de passe », « entrepôt », etc.). Si vous épelez un nom de propriété ou si vous incluez des propriétés supplémentaires, le pilote ignore ces propriétés sans émettre de message d’erreur ou d’avertissement. Cela peut rendre difficile la détection de fautes d’orthographe mineures.

Utiliser les bonnes valeurs pour la chaîne de connexion et le compte

Si vous ne parvenez pas à établir une connexion, vérifiez que vous spécifiez correctement l’identificateur du compte dans la chaîne de connexion JDBC. Pour plus d’informations sur les identificateurs de compte, voir identificateur de compte.