Configuration du pilote JDBC

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

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_name>.snowflakecomputing.com/?<connection_params>

Paramètres de connexion

<nom_compte>

Spécifie le nom complet de votre compte (fourni par Snowflake). Notez que votre nom de compte complet peut inclure des segments supplémentaires identifiant la région et la plate-forme Cloud où votre compte est hébergé.

Exemples de noms de compte par région

Si votre localisateur de compte est xy12345:

Plate-forme Cloud / région .

Localisateur de compte . (avec des segments supplémentaires si nécessaire)

Amazon Web Services (AWS)

US Ouest (Oregon)

xy12345

US Est (Ohio)

xy12345.us-east-2.aws

US Est (Virginie du Nord)

xy12345.us-east-1

US Est (Gouvernement commercial - Virginie du Nord)

xy12345.us-east-1-gov.aws

Canada (Centre)

xy12345.ca-central-1.aws

EU (Irlande)

xy12345.eu-west-1

Europe (Londres)

xy12345.eu-west-2.aws

EU (Francfort)

xy12345.eu-central-1

Asie-Pacifique (Tokyo)

xy12345.ap-northeast-1.aws

Asie Pacifique (Mumbai)

xy12345.ap-south-1.aws

Asie-Pacifique (Singapour)

xy12345.ap-southeast-1

Asie-Pacifique (Sydney)

xy12345.ap-southeast-2

Google Cloud Platform (GCP)

US Central1 (Iowa)

xy12345.us-central1.gcp

Europe Ouest2 (Londres)

xy12345.europe-west2.gcp

Europe Ouest4 (Pays-Bas)

xy12345.europe-west4.gcp

Microsoft Azure

Ouest US 2 (Washington)

xy12345.west-us-2.azure

Est US 2 (Virginie)

xy12345.east-us-2.azure

US Gov Virginia

xy12345.us-gov-virginia.azure

Canada Central (Toronto)

xy12345.canada-central.azure

Europe de l’Ouest (Pays-Bas)

xy12345.west-europe.azure

Suisse Nord (Zurich)

xy12345.switzerland-north.azure

Asie du Sud-Est (Singapour)

xy12345.southeast-asia.azure

Australie Est (Nouvelle-Galles du Sud)

xy12345.australia-east.azure

Important

Si l’une des conditions suivantes est remplie, votre localisateur de compte est différent de la structure décrite dans les exemples ci-dessus :

<id_région>Obsolète

Spécifie l’ID de la région où se trouve votre compte.

Ce paramètre n’est plus utilisé, car les informations de région, si nécessaires, sont incluses dans le nom de compte complet. Elle n’est documentée ici que pour des raisons de rétrocompatibilité.

<params_connexion>

Spécifie une série d’un ou plusieurs paramètres, 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 :

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

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

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

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>.snowflakecomputing.com/", props);

Vous pouvez définir les paramètres suivants dans la chaîne de connexion ou dans un objet Properties :

user=<nom_connexion>

Spécifie le nom de connexion de l’utilisateur pour la connexion.

password=<chaîne>

Spécifie le mot de passe de l’utilisateur spécifié.

Il existe deux manières de spécifier le mot de passe :

  • La première consiste à transmettre l’ID et le mot de passe de l’utilisateur directement à la méthode getConnection :

    String user = "<user>";          // replace "<user>" with your user name
    String password = "<password>";  // replace "<password>" with your password
    Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.com/", user, password);
    
  • La deuxième consiste à créer un objet Properties, à mettre à jour l’objet avec le mot de passe et à le transmettre à la méthode getConnection :

    String user = "<user>";          // replace "<user>" with your user name
    String password = "<password>";  // replace "<password>" with your password
    Properties props = new Properties();
    props.put("user", user);
    props.put("password", password);
    Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.com/", props);
    

Attention

Nous vous recommandons fortement de ne pas inclure le mot de passe utilisateur directement dans la chaîne de connexion JDBC, car le mot de passe pourrait être exposé par inadvertance par l’application client qui utilise la chaîne pour se connecter à Snowflake. Utilisez plutôt les interfaces fournies par l’application pour spécifier le mot de passe utilisateur.

authenticator=<chaîne>

Spécifie l’authentificateur à utiliser pour vérifier les informations d’identification d’utilisateur :

  • snowflake pour utiliser l’authentificateur interne Snowflake.

  • externalbrowser sur utilise votre navigateur Web pour vous authentifier avec Okta, des ADFS ou tout autre fournisseur d’identification conforme à SAML 2.0 (IdP) qui a été défini pour votre compte.

  • https://<nom_compte_okta>.okta.com (c.-à-d. le point de terminaison d’URL pour votre compte Okta) pour vous authentifier via Okta natif (uniquement pris en charge si votre IdP est Okta).

  • oauth pour vous authentifier à l’aide de OAuth. Lorsque OAuth est spécifié comme authentificateur, vous devez également définir le paramètre token pour spécifier le jeton OAuth (voir ci-dessous).

  • snowflake_jwt pour vous authentifier à l’aide de l’authentification par paire de clés. Pour plus de détails sur l’authentification par paire de clés, voir Utilisation de l’authentification par paires de clés et rotation des clés.

  • username_password_mfa pour s’authentifier avec la mise en cache du jeton MFA. Pour plus de détails, voir Utilisation de l’authentification multifactorielle (dans cette rubrique).

La valeur par défaut est snowflake.

Si la chaîne de connexion spécifie une paire de clés, l’authentification par paire de clés sera utilisée même si le paramètre d’authentificateur n’est pas défini ou est défini sur « Snowflake ».

Pour plus d’informations sur l’authentification, voir Gestion/utilisation de l’authentification fédérée et OAuth avec les clients, les pilotes et les connecteurs.

token=<chaîne>

Spécifie le jeton OAuth à utiliser pour l’authentification, où <chaîne> est le jeton. Ce paramètre est requis uniquement lorsque le paramètre authenticator=oauth est défini.

La valeur par défaut est aucun.

role=<nom>

Spécifie le rôle de contrôle d’accès par défaut à utiliser dans la session Snowflake initiée par le pilote. Le rôle spécifié doit être un rôle existant qui a déjà été affecté à l’utilisateur spécifié pour le pilote. Si le rôle spécifié n’a pas déjà été affecté à l’utilisateur, il n’est pas utilisé lorsque la session est lancée par le pilote.

Après la connexion, la commande USE ROLE peut être exécutée pour définir un rôle différent pour la session.

Pour plus d’informations sur les rôles et le contrôle d’accès, voir Contrôle d’accès dans Snowflake.

db=<nom>

Spécifie la base de données par défaut à utiliser une fois la connexion effectuée, ou une chaîne vide. La base de données spécifiée doit être une base de données existante pour laquelle le rôle par défaut spécifié a des privilèges.

Après la connexion, la commande USE DATABASE peut être exécutée pour définir une base de données différente pour la session.

schema=<nom>

Spécifie le schéma par défaut à utiliser pour la base de données spécifiée une fois connecté, ou une chaîne vide. Le schéma spécifié doit être un schéma existant pour lequel le rôle par défaut spécifié possède des privilèges.

Après la connexion, la commande USE SCHEMA peut être exécutée pour définir un schéma différent pour la session.

warehouse=<nom>

Spécifie l’entrepôt virtuel à utiliser une fois connecté, ou une chaîne vide. L’entrepôt spécifié doit être un entrepôt existant pour lequel le rôle par défaut spécifié possède des privilèges.

Après la connexion, la commande USE WAREHOUSE peut être exécutée pour définir un entrepôt différent pour la session.

tracing=<chaîne>

Spécifie le niveau de journal du conducteur. Le pilote utilise l’utilitaire de journal Java standard. Les valeurs valides pour le niveau de journal sont les suivantes :

OFF , SEVERE , WARNING , INFO , CONFIG , FINE , FINER , FINEST , ALL.

La valeur par défaut est INFO.

passcode=<chaîne>

Spécifie le code à utiliser pour l’authentification multifactorielle.

Pour plus d’informations sur l’authentification multifactorielle, voir Authentification multifactorielle (MFA).

passcodeInPassword=<chaîne>

Indique si le code pour l’authentification multifactorielle est ajouté au mot de passe :

  • on (ou true) spécifie que le code est ajouté.

  • off (ou false) ou toute autre valeur spécifie que le code n’est pas ajouté.

La valeur par défaut est off.

loginTimeout

Indique le temps d’attente pour l’obtention d’une réponse lors de la connexion au service Snowflake avant de renvoyer une erreur d’échec de connexion.

La valeur par défaut est 60 secondes.

networkTimeout

Indique le temps d’attente pour l’obtention d’une réponse lors d’une interaction avec le service Snowflake avant de renvoyer une erreur. Zéro (0) indique qu’aucun délai d’attente réseau n’est défini.

La valeur par défaut est 0 seconde.

queryTimeout=<nombre>

Indique le temps d’attente pour qu’une requête se termine avant de renvoyer une erreur. Zéro (0) indique une attente indéfinie.

La valeur par défaut est 0 seconde.

application=<chaîne>

Pour partenaire Snowflake uniquement : spécifie le nom d’une application partenaire à connecter via JDBC.

disableSocksProxy=<chaîne>

Indique si le pilote doit ignorer la configuration proxy SOCKS spécifiée dans les options système Java (le cas échéant) :

  • on (ou true) spécifie d’ignorer le proxy.

  • off (ou false) ou toute autre valeur spécifie d’utiliser le proxy.

La valeur par défaut est off.

Remarque : le réglage de ce paramètre de connexion modifiera le comportement de toutes les connexions d’une même JVM (machine virtuelle Java).

stringsQuotedForColumnDef=<booléen>

Si ce paramètre est défini sur true, alors lorsque DatabaseMetaData.getColumns() et DatabaseMetaData.getProcedureColumns() renvoient une valeur de type String dans la colonne COLUMN_DEF, cette valeur est intégrée dans des guillemets simples. (Si le type de données de la valeur n’est pas String, la valeur n’est pas entre guillemets, quel que soit le réglage de ce paramètre.)

  • true spécifie que les valeurs de chaîne doivent être intégrées entre guillemets simples (les guillemets font partie de la chaîne, pas des délimiteurs). Ceci est conforme à la norme JDBC.

  • false spécifie que les valeurs de chaîne ne sont pas intégrées entre guillemets simples.

La valeur par défaut est false.

Autres paramètres

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

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.

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

Exemples

Compte en US Ouest :

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

Compte en EU (Francfort) :

jdbc:snowflake://xy12345.eu-central-1.snowflakecomputing.com/?user=peter&warehouse=mywh&db=mydb&schema=public

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 paires de clés et rotation des 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 paires de clés et rotation des 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

    chemin/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.

    phrasesecrète_clé_privée

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

    compte

    Indiquez le nom de votre compte (fourni par Snowflake).

    utilisateur

    Indiquez votre nom de connexion Snowflake.

    nom_base_de_données

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

    nom_schéma

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

    nom_entrepôt

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

    rôle

    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
    

    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
    

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>.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://exampleaccount.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://exampleaccount.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.

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.

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

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>

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|xy12345.snowflakecomputing.com|192.168.91.*"

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

Vous pouvez spécifier l’adresse IP et le numéro de port d’un serveur proxy directement dans la chaîne de connexion JDBC :

jdbc:snowflake://<compte>.<id_region>.snowflakecomputing.com/?warehouse=<nom_entrepôt> &useProxy=true&proxyHost=<adresse_ip>&proxyPort=<port>&proxyUser=test&proxyPassword=test

Par exemple :

jdbc:snowflake://xy12345.us-east-1.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.

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

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>

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%7Cxy12345.snowflakecomputing.com%7C192.168.91.*

Note

Les exemples ci-dessus contiennent un espace pour la lisibilité. Si vous copiez et collez l’un ou l’autre de ces exemples, veuillez supprimer cet espace supplémentaire.

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.

Astuce

Le modèle de sécurité de Snowflake ne permet pas les proxys Secure Sockets Layer (SSL) (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 SSL, 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".

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

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/SSL 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 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 blanche 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=chaîne

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=chaîne au lancement.

SF_OCSP_RESPONSE_CACHE_DIR=chaîne

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=chaîne 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

  • Façade de journalisation simple pour Java

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

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

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 connexion est déterminé par le paramètre de connexion tracing (voir ci-dessus).

Astuces de dépannage

Assurez-vous 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 », « compte », 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

Une cause fréquente de problèmes de connexion est de fournir trop ou pas assez d’informations lorsqu’un compte, un nom de compte ou une chaîne de connexion est demandé.

Les informations de compte ont généralement la structure suivante en fonction de la région et de la plate-forme Cloud sur lesquelles votre compte est hébergé :

  • compte

  • compte.id_région

  • compte.id_région.plate-forme

Par exemple :

  • xy12345

  • xy12345.us-east-1

  • xy12345.east-us-2.azure

La chaîne de connexion JDBC ressemble généralement à ceci :

  • jdbc:snowflake://xy12345.east-us-2.azure.snowflakecomputing.com

L’utilisation de la chaîne de connexion lorsque les informations de compte sont attendues (ou inversement) peut entraîner des problèmes de débogage difficiles.

Si vous ne pouvez pas établir de connexion lorsqu’un compte vous est demandé, essayez à la forme minimale (par exemple, xy12345) et le nom complet du compte (par exemple, xy12345.east-us-2.azure, mais sans .snowflakecomputing.com), en prenant soin de ne pas inclure la chaîne jdbc:snowflake://.

Si vous ne pouvez pas établir de connexion lorsque vous êtes invité à fournir une chaîne de connexion JDBC, utilisez la forme complète de la chaîne de connexion, comme indiqué ci-dessus.

Pour plus d’informations sur les noms de compte, voir Paramètres de connexion.