Konfigurieren des JDBC-Treibers¶

Syntax¶

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

Verbindungsparameter¶

<Kontobezeichner>

Gibt den Kontobezeichner für Ihr Snowflake-Konto an. Weitere Details dazu finden Sie unter Kontobezeichner. Beispiele für den in einer JDBC-Verbindungszeichenfolge verwendeten Kontobezeichner finden Sie unter Beispiele.

<Verbindungsparameter>

Gibt eine Folge von einem oder mehreren JDBC-Verbindungsparametern und Sitzungsparametern im Format <Parameter>=<Wert> an, wobei jeder Parameter durch das kaufmännische Und-Zeichen (&) getrennt ist und keine Leerzeichen in der Verbindungszeichenfolge vorhanden sind.

Wenn Sie Parameterwerte festlegen müssen, die Leerzeichen, kaufmännisches Und (&), Gleichheitszeichen (=) oder andere Sonderzeichen verwenden, sollten Sie die Sonderzeichen URL-kodieren. Wenn Sie beispielsweise im Abfrage-Tag-Sitzungsparameter einen Wert angeben müssen, der ein Leerzeichen, ein kaufmännisches Und (&) und ein Gleichheitszeichen enthält, müssen Sie Folgendes tun:

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

Copy

Kodieren Sie das Leerzeichen als %20, das kaufmännische Und als %26 und das Gleichheitszeichen als %3D:

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

Copy

Alternativ können Sie anstelle der Angabe dieser Parameter in der Verbindungszeichenfolge diese Parameter auch in einem Properties-Objekt festlegen, das Sie an die DriverManager.getConnectionIO-Methode übergeben.

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

Copy

Weitere Parameter¶

Jeder Sitzungsparameter kann in die Verbindungszeichenfolge aufgenommen werden. Beispiel:

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Boolesch>

Gibt an, ob die Out-of-Band-Telemetrie aktiviert werden soll.

Der Standardwert ist true.

CLIENT_SESSION_KEEP_ALIVE=<Boolesch>

Gibt an, ob die aktuelle Sitzung nach einer Zeit der Inaktivität aktiv bleiben soll oder ob der Benutzer gezwungen werden soll, sich erneut anzumelden. Wenn der Wert true ist, hält Snowflake die Sitzung auf unbestimmte Zeit aktiv, auch wenn es keine Aktivität des Benutzers gibt. Wenn der Wert false ist, muss sich der Benutzer nach vier Stunden Inaktivität erneut anmelden.

Der Standardwert ist false.

CLIENT_SESSION_KEEP_ALIVE_HEARTBEAT_FREQUENCY=<Ganzzahl>

Gibt die Anzahl der Sekunden (900–3.600) zwischen den Versuchen des Clients an, das Token der Sitzung zu aktualisieren.

Der Standardwert ist 3600.

Eine Beschreibung aller Sitzungsparameter finden Sie unter Parameter.

Beispiele¶

Es folgt ein Beispiel für die Verbindungszeichenfolge, die einen Kontobezeichner verwendet, der das Konto myaccount der Organisation myorganization angibt.

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

Copy

Im Folgenden finden Sie ein Beispiel für eine Verbindungszeichenfolge, die den Konto-Locator xy12345 als Kontobezeichner verwendet:

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

Copy

Beachten Sie, dass in diesem Beispiel ein Konto in der Region AWS US West (Oregon) verwendet wird. Wenn sich das Konto in einer anderen Region befindet oder wenn das Konto einen anderen Cloudanbieter verwendet, müssen Sie nach dem Konto-Locator zusätzliche Segmente angeben.

privateKey-Eigenschaft in Verbindungseigenschaften¶

Dieser Abschnitt enthält ein Beispiel für das Festlegen der privateKey-Eigenschaft für einen privaten Schlüssel in einer Datei.

In diesem Beispiel werden die Bouncy Castle Crypto-APIs verwendet. Um dieses Beispiel kompilieren und ausführen zu können, müssen Sie Ihrem Klassenpfad die folgenden JAR-Dateien hinzufügen:

• Anbieter-JAR-Datei (bcprov-jdkversions.jar)

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

wobei versions die Versionen der JDK angibt, die von der JAR-Datei unterstützt werden.

So verwenden Sie dieses Beispiel:

1. Kopieren Sie den Beispielcode unten, und ersetzen Sie die folgenden Platzhalterwerte:

   Platzhalter	Beschreibung
   path/rsa_key.p8	Geben Sie hier den Pfad und den Namen der privaten Schlüsseldatei an, die Sie zuvor generiert haben.
   private_key_passphrase	Wenn Sie einen verschlüsselten Schlüssel generiert haben, implementieren Sie die getPrivateKeyPassphrase()-Methode, um die Passphrase zum Entschlüsseln dieses Schlüssels zurückzugeben.
   account_identifier	Geben Sie hier Ihren Kontobezeichner an.
   user	Geben Sie hier Ihren Snowflake-Anmeldenamen an.
   database_name	Geben Sie hier den Namen der Datenbank an, die Sie verwenden möchten.
   schema_name	Geben Sie hier den Namen des Schemas an, das Sie verwenden möchten.
   warehouse_name	Geben Sie hier den Namen des Warehouses an, das Sie verwenden möchten.
   role	Geben Sie hier den Namen der Rolle an, die Sie verwenden möchten.

2. Kompilieren Sie den Beispielcode, und führen Sie ihn aus. Fügen Sie die Bouncy Castle-JAR-Dateien dem Klassenpfad hinzu.

   Linux und 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

   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

Beispielcode

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

Dateiname und Kennwort des privaten Schlüssels als Verbindungseigenschaften¶

Sie können den Dateinamen und das Kennwort des privaten Schlüssels als separate Verbindungseigenschaften angeben. Beispiel:

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

Wenn Sie die Parameter private_key_file und private_key_file_pwd angeben, geben Sie den Parameter privateKey nicht in den Verbindungseigenschaften an.

Dateiname und Kennwort des privaten Schlüssels in der Verbindungszeichenfolge¶

Sie können den Dateinamen und das Kennwort des privaten Schlüssels in der Verbindungszeichenfolge wie folgt angeben:

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

Wenn Sie den privaten Schlüssel und das Kennwort in der Verbindungszeichenfolge angeben, geben Sie die Parameter private_key_file, private_key_file_pwd oder privateKey nicht in den Verbindungseigenschaften an.

Angeben eines Proxyservers durch Festlegen von Java-Systemoptionen¶

Um eine Verbindung über einen Proxyserver herzustellen, können Sie die Proxysystemeigenschaften einstellen. Sie können diese entweder in Ihrem Code festlegen oder sie über die Befehlszeile an die JVM (Java Virtual Machine) für Ihre Clientanwendung übergeben.

Um die Systemeigenschaften in Ihrem Code einzustellen, rufen Sie System.setProperty auf:

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

Um die Systemeigenschaften auf der Befehlszeile an Ihre JVM zu übergeben, verwenden Sie die Befehlszeilenoption -D:

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

Copy

Um den Proxy für eine oder mehrere IP-Adressen oder Hosts zu umgehen, setzen Sie die Systemeigenschaft http.nonProxyHosts auf die Liste dieser Hosts:

• Verwenden Sie ein Pipe-Symbol (|), um die Hostnamen zu trennen.

• Um Hostnamen anzugeben, die einem Muster entsprechen, verwenden Sie ein Sternchen (*) als Platzhalterzeichen.

Das folgende Beispiel zeigt, wie Sie diese Systemeigenschaft in der Befehlszeile einstellen:

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

Angeben eines Proxyservers in der JDBC-Verbindungszeichenfolge¶

Um einen Proxyserver zu verwenden, setzen Sie die folgenden Parameter in der JDBC-Verbindungszeichenfolge:

• useProxy

• proxyHost

• proxyPort

• proxyUser

• proxyPassword

• proxyProtocol

Wenn Ihr Proxyserver keine Authentifizierung erfordert, können Sie die Parameter proxyUser und proxyPassword weglassen.

Wenn Ihre Proxyserververbindung eine Authentifizierung mit einem Proxybenutzernamen und einem Proxykennwort erfordert, können diese Anmeldeinformationen bei Verwendung des HTTP-Protokolls von anderen Anwendungen als Klartext offengelegt werden. Um zu vermeiden, dass diese Anmeldeinformationen preisgegeben werden, verwenden Sie den Parameter proxyProtocol zur Angabe des HTTPS-Protokolls.

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

Beispiel:

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

Die Proxyeinstellungen, die Sie in der Verbindungszeichenfolge angeben, haben Vorrang vor den Proxysystemeigenschaften der JVM.

&nonProxyHosts=<bypass_proxy_for_these_hosts>

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

&proxyProtocol=https

Auswahl des Fail-open- oder Fail-close-Modus¶

Bei JDBC-Treiberversionen vor 3.8.0 findet standardmäßig „Fail-close“ statt. Bei Versionen 3.8.0 und höher findet standardmäßig „Fail-open“ statt. Sie können das Standardverhalten auf eine der folgenden Arten überschreiben:

• Setzen Sie die Verbindungseigenschaft ocspFailOpen auf true oder false. Beispiel:

  Properties connection_properties = new Properties();
  connection_properties.put("ocspFailOpen", "false");
  ...
  connection = DriverManager.getConnection(connectionString, connection_properties);
  

  Copy

• Setzen Sie die Systemeigenschaft net.snowflake.jdbc.ocspFailOpen auf true oder false. Beispiel:

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

  Copy

Überprüfen der Version von OCSP-Konnektor/Treiber¶

Weitere Informationen zu Treiber- oder Konnektor-Version, Konfiguration und OCSP-Verhalten finden Sie unter OCSP-Konfiguration.

OCSP-Antwort-Cacheserver¶

Snowflake-Clients initiieren jede Verbindung zu einem Snowflake-Dienstendpunkt mit einem „Handshake“, der eine sichere Verbindung herstellt, bevor tatsächlich Daten übertragen werden. Im Rahmen des Handshakes authentifiziert ein Client das TLS-Zertifikat für den Dienstendpunkt. Der Sperrstatus des Zertifikats wird überprüft, indem eine Client-Zertifikatsanforderung an einen der OCSP (Online Certificate Status Protocol)-Server für die CA (Zertifizierungsstelle) gesendet wird.

Ein Verbindungsfehler tritt auf, wenn die Antwort des OCSP-Servers über eine angemessene Zeit hinaus verzögert wird. Die folgenden Caches behalten den Sperrstatus bei und helfen, diese Probleme zu beheben:

• Speichercache, der während der gesamten Lebensdauer des Prozesses beibehalten wird.

• Dateicache, der so lange beibehalten wird, bis das Cacheverzeichnis (z. B. ~/.cache/snowflake oder ~/.snowsql/ocsp_response_cache) gelöscht ist.

• Snowflake-OCSP-Antwort-Cacheserver, der OCSP-Antworten von den OCSP-Servern der CA stündlich abruft und 24 Stunden lang speichert. Clients können dann den Validierungsstatus eines bestimmten Snowflake-Zertifikats von diesem Servercache anfordern.

  Wichtig

  Wenn Ihre Serverrichtlinie den Zugriff auf die meisten oder alle externen IP-Adressen und Websites verweigert, müssen Sie die Adresse des Cacheservers auf die Zulassungsliste setzen, um einen normalen Servicebetrieb zu ermöglichen. Der Hostname des Cacheservers lautet ocsp*.snowflakecomputing.com:80.

  Wenn Sie den Cacheserver aus irgendeinem Grund deaktivieren müssen, setzen Sie die Umgebungsvariable SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED auf false. Beachten Sie, dass der Wert zwischen Groß- und Kleinschreibung unterscheidet und in Kleinbuchstaben angegeben werden muss.

Wenn keine der Cacheschichten die OCSP-Antwort enthält, versucht der Client, den Validierungsstatus direkt vom OCSP-Server der CA abzurufen.

Java-Core-Protokollierungsmöglichkeiten (Java.util.logging)¶

Um diese Protokollierung zu verwenden, geben Sie für die JVM folgende Option an:

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

Anschließend können Sie die Protokollierungskonfiguration über die Anwendungsprogrammierungsschnittstelle (API) für die Protokollierung anpassen. Weitere Details dazu finden Sie in der Dokumentation zum java.util.logging-Paket.

Erstellen Sie beispielsweise eine Datei mit dem Namen logging.properties und folgendem Inhalt:

###########################################################
#   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

Geben Sie die JVM-Parameter in die Befehlszeile ein:

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

Copy

Dabei verweist application.jar auf den Anwendungscode für den JDBC-Treiber. Die Protokolldateien befinden sich unter /tmp/snowflake_jdbc*.

Simple Logging Facade für Java (org.slf4j)¶

Wenn ein Implementierungspaket für die Protokollierung (z. B. org.sl4j:sl4j-jdk14 oder org.sl4j:slf4j-log4j12) oder eine kundenspezifische Protokollierung (z. B. Ihre eigene org.slf4j.impl.StaticLoggerBinder-Klasse) im Klassenpfad definiert wurde, dann verwendet der Treiber diese Protokollierung automatisch.

Sie können diese Protokollierung auch explizit verwenden, indem Sie die folgende JVM-Option angeben:

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

Weitere Informationen dazu finden Sie in der Dokumentation zu Simple Logging Facade für Java (SLF4J).

Protokollierungskonfigurationsdatei¶

Alternativ können Sie den Protokolliergrad und das Verzeichnis, in dem die Protokolldateien gespeichert werden sollen, auch einfach in der Konfigurationsdatei sf_client_config.json angeben.

Diese Konfigurationsdatei verwendet JSON, um die Protokollierungsparameter log_level und log_path wie folgt zu definieren:

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

Der Treiber sucht in der folgenden Reihenfolge nach dem Speicherort der Konfigurationsdatei:

• Verbindungsparameter client_config_file, der den vollständigen Pfad zur Konfigurationsdatei enthält.

• Umgebungsvariable SF_CLIENT_CONFIG_FILE, die den vollständigen Pfad zur Konfigurationsdatei enthält.

• JDBC-Treiberinstallationsverzeichnis, wo die Datei den Namen sf_client_config.json tragen muss.

• Basisverzeichnis des Benutzers, in dem die Datei sf_client_config.json heißen muss.

Sicherstellen, dass die Eigenschaften korrekt eingestellt sind¶

Die DriverManager.getConnection()-Methode liest nur die Werte des Eigenschaftsparameters, die mit bestimmten vordefinierten Namen übereinstimmen (z. B. „Kennwort“, „Warehouse“ usw.). Wenn Sie einen Eigenschaftsnamen falsch schreiben oder zusätzliche Eigenschaften hinzufügen, ignoriert der Treiber diese Eigenschaften, ohne eine Fehler- oder Warnmeldung auszugeben. Dies kann es erschweren, kleine Rechtschreibfehler zu erkennen.

Verwenden der korrekten Werte für Verbindungszeichenfolge und Konto¶

Wenn Sie keine Verbindung herstellen können, überprüfen Sie, ob Sie den Kontobezeichner in der JDBC-Verbindungszeichenfolge korrekt angegeben haben. Weitere Informationen zu Kontobezeichnern finden Sie unter Kontobezeichner.