Configuration du pilote JDBC¶

Syntaxe¶

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

Paramètres de connexion¶

<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

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.

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)

où 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();
  }
}

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

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.

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

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.

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.*"

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

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

• useProxy

• proxyHost

• proxyPort

• proxyUser

• proxyPassword

• proxyProtocol

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

Par exemple :

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

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.

&nonProxyHosts=<bypass_proxy_for_these_hosts>

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

&proxyProtocol=https

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¶

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.

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

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

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.

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"
  }
}

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.

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.