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 nom de compte est xy12345 :

Plate-forme Cloud/Région

Nom de compte complet

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

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

GCP

US Central1 (Iowa)

xy12345.us-central1.gcp

Europe Ouest2 (Londres)

xy12345.europe-west2.gcp

Europe Ouest4 (Pays-Bas)

xy12345.europe-west4.gcp

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, le nom de votre compte est différent de la structure décrite dans cet exemple :

  • Si votre édition Snowflake est VPS, contactez le support Snowflake pour obtenir des détails sur le nom de votre compte.

  • Si AWS PrivateLink est activé pour votre compte, le nom de votre compte nécessite un segment privatelink supplémentaire. Pour plus de détails, voir AWS PrivateLink et Snowflake.

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

<connection_params>

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 :

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 to use your web browser to authenticate with Okta, ADFS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.

  • https://<votre_nom_compte_okta>.okta.com (c.-à-d. le point de terminaison d’URL pour Okta) pour vous authentifier via Okta (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 paire de clés.

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 par paire de clés

Snowflake utilise l’authentification par paire de clés plutôt que l’authentification par nom d’utilisateur/mot de passe typique. Cette méthode d’authentification nécessite une paire de clés de 2048 bits (minimum) RSA. Générez la paire de clés publiques-privées via OpenSSL. La clé publique est attribuée à l’utilisateur Snowflake qui utilisera le client Snowflake.

Pour configurer la paire de clés publiques/privées :

  1. Depuis la ligne de commande d’une fenêtre de terminal, générez une clé privée.

    Vous pouvez générer une version chiffrée de la clé privée ou une version non chiffrée de la clé privée.

    Pour générer une version non chiffrée, utilisez la commande suivante :

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
    

    Pour générer une version chiffrée, utilisez la commande suivante (qui omet « -nocrypt ») :

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
    

    Il est généralement plus sûr de générer une version chiffrée.

    Si vous utilisez la deuxième commande pour chiffrer la clé privée, OpenSSL vous invite à indiquer une phrase secrète utilisée pour chiffrer le fichier de clé privée. Nous vous recommandons d’utiliser une phrase de chiffrement forte pour protéger la clé privée. Enregistrez cette phrase secrète dans un emplacement sécurisé. Vous l’entrerez lorsque vous vous connecterez à Snowflake. Notez que la phrase de chiffrement n’est utilisée que pour protéger la clé privée et ne sera jamais envoyée à Snowflake.

    Exemple de clé privée PEM

    -----BEGIN ENCRYPTED PRIVATE KEY-----
    MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
    wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
    ...
    -----END ENCRYPTED PRIVATE KEY-----
    
  2. Depuis la ligne de commande, générez la clé publique en faisant référence à la clé privée :

    En supposant que la clé privée soit contenue dans le fichier nommé « rsa_key.p8 », utilisez la commande suivante :

    $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
    

    Exemple de clé publique PEM

    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
    zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
    ...
    -----END PUBLIC KEY-----
    
  3. Copiez les fichiers de clés publiques et privées dans un répertoire local en vue de leur stockage. Enregistrez le chemin d’accès aux fichiers. Notez que la clé privée est stockée au format PKCS#8 (Public Key Cryptography Standards) et est chiffrée à l’aide de la phrase de chiffrement que vous avez spécifiée à l’étape précédente ; toutefois, le fichier doit toujours être protégé contre tout accès non autorisé au moyen du mécanisme d’autorisation de fichier fourni par votre système d’exploitation. Il est de votre responsabilité de sécuriser le fichier lorsqu’il n’est pas utilisé.

  4. Attribuez la clé publique à l’utilisateur Snowflake en utilisant ALTER USER. Par exemple :

    ALTER USER jsmith SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
    

    Note

    • Seuls les administrateurs de sécurité (c’est-à-dire les utilisateurs ayant le rôle SECURITYADMIN) ou ayant un rôle supérieur peuvent modifier un utilisateur.

    • Excluez l’en-tête et le pied de page de la clé publique dans l’instruction SQL.

    Vérifiez l’empreinte de la clé publique de l’utilisateur en utilisant DESCRIBE USER :

    DESC USER jsmith;
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    | property                      | value                                               | default | description                                                                   |
    |-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------|
    | NAME                          | JSMITH                                              | null    | Name                                                                          |
    ...
    ...
    | RSA_PUBLIC_KEY_FP             | SHA256:nvnONUsfiuycCLMXIEWG4eTp4FjhVUZQUQbNpbSHXiA= | null    | Fingerprint of user's RSA public key.                                         |
    | RSA_PUBLIC_KEY_2_FP           | null                                                | null    | Fingerprint of user's second RSA public key.                                  |
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    

    Note

    La propriété RSA_PUBLIC_KEY_2_FP est décrite dans Rotation de clé (dans ce chapitre).

  5. Après avoir créé la paire de clés privées, vous pouvez l’utiliser pour vous authentifier lors de la connexion à Snowflake.

    Vous pouvez utiliser la valeur de la clé privée directement, ou vous pouvez stocker la clé privée dans un fichier et transmettre le nom de fichier et un mot de passe pour ce fichier lors de la connexion :

    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 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 dans la chaîne de connexion.

Chacun d’eux est décrit plus en détail dans l’une des trois sections suivantes.

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

Modifiez et exécutez l’exemple de code ci-dessous. Le code déchiffre le fichier de la clé privée et le transmet au pilote Snowflake pour créer une connexion. Dans l’exemple de code, mettez à jour les paramètres de sécurité et les paramètres de session :

  • Paramètres de sécurité :

    • chemin : spécifie le chemin d’accès local au fichier de clé privée que vous avez créé.

  • Paramètres de session :

    • utilisateur : spécifie votre nom d’utilisateur Snowflake.

    • compte : spécifie le nom de votre compte (fourni par Snowflake).

Exemple de code

import java.util.Properties;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.DriverManager;
import java.io.File;
import java.io.FileInputStream;
import java.io.DataInputStream;
import java.util.Base64;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.KeyFactory;
import java.security.PrivateKey;
import javax.crypto.EncryptedPrivateKeyInfo;
import javax.crypto.SecretKeyFactory;
import javax.crypto.spec.PBEKeySpec;

public class TestJdbc
{
    public static void main(String[] args)
        throws Exception
    {
      File f = new File("<path>/rsa_key.p8");
      FileInputStream fis = new FileInputStream(f);
      DataInputStream dis = new DataInputStream(fis);
      byte[] keyBytes = new byte[(int) f.length()];
      dis.readFully(keyBytes);
      dis.close();

      String encrypted = new String(keyBytes);
      String passphrase = System.getenv("PRIVATE_KEY_PASSPHRASE");
      encrypted = encrypted.replace("-----BEGIN ENCRYPTED PRIVATE KEY-----", "");
      encrypted = encrypted.replace("-----END ENCRYPTED PRIVATE KEY-----", "");
      EncryptedPrivateKeyInfo pkInfo = new EncryptedPrivateKeyInfo(Base64.getMimeDecoder().decode(encrypted));
      PBEKeySpec keySpec = new PBEKeySpec(passphrase.toCharArray());
      SecretKeyFactory pbeKeyFactory = SecretKeyFactory.getInstance(pkInfo.getAlgName());
      PKCS8EncodedKeySpec encodedKeySpec = pkInfo.getKeySpec(pbeKeyFactory.generateSecret(keySpec));
      KeyFactory keyFactory = KeyFactory.getInstance("RSA");
      PrivateKey encryptedPrivateKey = keyFactory.generatePrivate(encodedKeySpec);

      String url = "jdbc:snowflake://<account>.snowflakecomputing.com";
      Properties prop = new Properties();
      prop.put("user", "<user>");
      prop.put("account", "<account>");
      prop.put("privateKey", encryptedPrivateKey);

      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(properties, "jdbc:snowflake://exampleaccount.snowflake.com");

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(properties,
    "jdbc:snowflake://exampleaccount.snowflake.com/?private_key_file=/tmp/rsa_key.p8&private_key_file_pwd=dummyPassword");

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.

Rotation de clé

Snowflake accepte plusieurs clés actives pour permettre une rotation ininterrompue. Faites pivoter et remplacez vos clés publiques et privées en fonction du calendrier d’expiration que vous suivez en interne.

Actuellement, vous pouvez utiliser les paramètres RSA_PUBLIC_KEY et RSA_PUBLIC_KEY_2 pour ALTER USER afin d’associer jusqu’à 2 clés publiques à un seul utilisateur.

Pour faire tourner vos clés :

  1. Effectuez les étapes de la section Utilisation de l’authentification par paire de clés pour :

    • Générer un nouvel ensemble de clés privées et publiques.

    • Attribuer la clé publique à l’utilisateur. Définir la valeur de la clé publique sur RSA_PUBLIC_KEY ou RSA_PUBLIC_KEY_2 (la valeur de la clé qui n’est pas actuellement utilisée). Par exemple :

      alter user jsmith set rsa_public_key_2='JERUEHtcve...';
      
  2. Mettez à jour le code pour vous connecter à Snowflake. Spécifiez la nouvelle clé privée.

    Snowflake vérifie la bonne clé publique active pour l’authentification sur la base de la clé privée soumise avec vos informations de connexion.

  3. Retirez l’ancienne clé publique du profil utilisateur. Par exemple :

    alter user jsmith unset rsa_public_key;
    

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 :

  • Ajoutez des paramètres aux options JVM (Java Virtual Machine) de votre application client.

  • Incluez les informations d’hôte et de port du proxy dans la chaîne de connexion JDBC ou les propriétés transmises à la méthode DriverManager .getConnection().

Les deux techniques sont documentées ci-dessous.

Spécification d’un serveur proxy en définissant les options JVM

Pour vous connecter via un serveur proxy, vous pouvez définir des options dans votre code ou en transmettant des paramètres de ligne de commande à votre application cliente JVM (machine virtuelle Java). Les deux techniques sont équivalentes.

Pour spécifier les options dans votre code, procédez comme suit :

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

Pour spécifier les options via les paramètres de ligne de commande sur votre JVM, procédez comme suit :

-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 URLs, ajoutez les emplacements à vos options JVM : Chaque élément est séparé par une barre verticale. Un élément peut contenir un astérisque (« * ») en tant que caractère générique. Par exemple :

-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://<account>.<id_région>.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

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

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.

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.

En option, NO_PROXY peut être utilisé pour contourner le proxy pour des communications spécifiques. Par exemple, l’accès Amazon S3 peut être contourné en spécifiant NO_PROXY=".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>``.``<platforme>``

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.