JDBC ドライバーの構成¶

構文¶

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

接続パラメーター¶

<アカウント識別子>

Snowflakeアカウントのアカウント識別子を指定します。詳細については、 アカウント識別子 をご参照ください。JDBC 接続文字列で使用されるアカウント識別子の例については、 例 をご参照ください。

<接続パラメーター>

一連の1つ以上の JDBC 接続パラメーター と セッションパラメーター は、 <パラメーター>=<値> の形式で指定します。各パラメーターはアンパサンド文字（&）で区切られ、接続文字列のいずれにもスペースは使用しません。

スペース、アンパサンド（&）、等号（=）、またはその他の特殊文字を使用するパラメーター値を設定する必要がある場合は、 特殊文字を URL エンコード する必要があります。たとえば、 クエリタグ セッションパラメーターにスペース、アンパサンド、等号を含む値を指定する必要がある場合は、次のようになります。

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

Copy

スペースを %20、アンパサンドを %26、等号を %3D としてエンコードします。

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

Copy

別の方法として、接続文字列でこれらのパラメーターを指定する代わりに、 DriverManager.getConnectionIO メソッドに渡す Properties オブジェクトでこれらのパラメーターを設定できます。

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

Copy

その他のパラメーター¶

任意のセッションパラメーターを接続文字列に含めることができます。例：

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<ブール値>

アウトオブバンドテレメトリを有効にするかどうかを指定します。

デフォルトは true です。

CLIENT_SESSION_KEEP_ALIVE=<ブール値>

非アクティブな状態が一定時間続いた後、現在のセッションをアクティブのままにするか、ユーザーに再度ログインさせるかを指定します。値が true の場合、Snowflakeは、ユーザーからのアクティビティがない場合でも、セッションを無期限にアクティブに保ちます。値が false の場合、ユーザーは4時間の非アクティブ後に再度ログインする必要があります。

デフォルトは false です。

CLIENT_SESSION_KEEP_ALIVE_HEARTBEAT_FREQUENCY=<整数>

クライアントがセッションのトークンの更新を試みる間隔の秒数（900から3600）を指定します。

デフォルトは 3600 です。

すべてのセッションパラメーターの説明については、 パラメーター をご参照ください。

例¶

以下は、組織 myorganization のアカウント myaccount を指定する アカウント識別子 を使用する、接続文字列の例です。

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

Copy

以下は、アカウント識別子として アカウントロケーター xy12345 を使用する、接続文字列の例です。

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

Copy

この例では、 AWS US 西部（オレゴン）リージョンのアカウントを使用しています。アカウントが別のリージョンにある場合、またはアカウントが別のクラウドプロバイダーを使用している場合は、 アカウントロケーターの後に追加のセグメントを指定する 必要があります。

接続プロパティの privateKey プロパティ¶

このセクションでは、 privateKey プロパティをファイルの秘密キーに設定する例を示します。

この例では、 Bouncy Castle暗号化 APIs を使用しています。この例をコンパイルして実行するには、クラスパスに次の JAR ファイルを含める必要があります。

• プロバイダー JAR ファイル（bcprov-jdkversions.jar）

• PKIX / CMS / EAC / PKCS / OCSP / TSP / OPENSSL JAR ファイル（bcpkix-jdkversions.jar）

ここで、 versions は、 JAR ファイルがサポートする JDK のバージョンを指定します。

この例を使用するには、

1. 以下のサンプルコード をコピーし、次のプレースホルダー値を置き換えます。

   プレースホルダー	説明
   path/rsa_key.p8	これを前に生成した秘密キーファイルのパスと名前に設定します。
   private_key_passphrase	暗号化されたキーを生成した場合は、 getPrivateKeyPassphrase() メソッドを実装して、そのキーを復号化するためのパスフレーズを返します。
   account_identifier	これは、使用する アカウント識別子 に設定します。
   user	これをSnowflakeのログイン名に設定します。
   database_name	これを、使用するデータベースの名前に設定します。
   schema_name	これを、使用するスキーマの名前に設定します。
   warehouse_name	これを、使用するウェアハウスの名前に設定します。
   role	これを、使用するロールの名前に設定します。

2. サンプルコードをコンパイルして実行します。クラスパスにBouncy Castle JAR ファイルを含めます。

   たとえば、Linuxおよび 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

サンプルコード

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

接続プロパティとしての秘密キーファイル名とパスワード¶

秘密キーファイル名とパスワードを個別の接続プロパティとして指定できます。次に例を示します。

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

private_key_file および private_key_file_pwd パラメーターを指定する場合は、接続プロパティで privateKey パラメーターを指定しないでください。

接続文字列の秘密キーファイル名とパスワード¶

以下に示すように、接続文字列で秘密キーファイル名とパスワードを指定できます。

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

接続文字列で秘密キーとパスワードを指定する場合は、接続プロパティでパラメーター private_key_file、 private_key_file_pwd、または privateKey を指定しないでください。

Javaシステムプロパティの設定によるプロキシサーバーの指定¶

プロキシサーバーを介して接続するために、 プロキシシステムのプロパティ を設定できます。これらをコードで設定するか、コマンドラインでクライアントアプリケーションの JVM （Java仮想マシン）に渡すことができます。

コードにシステムプロパティを設定するには、 System.setProperty を呼び出します。

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

Copy

コマンドラインのシステムプロパティを JVM に渡すには、 -D コマンドラインオプションを使用します。

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

Copy

1つ以上の IP アドレスまたはホストのプロキシをバイパスするには、 http.nonProxyHosts システムプロパティをこれらのホストのリストに設定します。

• パイプ記号（|）を使用してホスト名を区切ります。

• パターンに一致するホスト名を指定するには、ワイルドカード文字としてアスタリスク（*）を使用します。

次の例は、コマンドラインでこのシステムプロパティを設定する方法を示しています。

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

JDBC 接続文字列によるプロキシサーバーの指定¶

JDBC 接続文字列に次のパラメーターを設定してプロキシサーバーを使用するには、

• useProxy

• proxyHost

• proxyPort

• proxyUser

• proxyPassword

• proxyProtocol

プロキシサーバーが認証を必要としない場合は、 proxyUser および proxyPassword パラメーターを省略できます。

プロキシサーバー接続でプロキシユーザー名とプロキシパスワードを使用した認証が必要な場合に HTTP プロトコルを使用すると、これらの認証情報が他のアプリケーションによってプレーンテキストとして公開される可能性があります。これらの認証情報の公開を回避するには、 proxyProtocol パラメーターを使用して HTTPS プロトコルを指定します。

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

例:

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

接続文字列で指定するプロキシ設定は、 JVM のプロキシシステムプロパティを上書きします。

&nonProxyHosts=<bypass_proxy_for_these_hosts>

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

&proxyProtocol=https

フェールオープンまたはフェールクローズモードの選択¶

JDBC 3.8.0より前のドライバーバージョンは、デフォルトでフェールクローズになります。バージョン3.8.0以降はデフォルトでフェールオープンになります。次のいずれかの方法でデフォルトの動作を上書きできます。

• 接続プロパティ ocspFailOpen を true または false に設定します。例:

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

  Copy

• システムプロパティ net.snowflake.jdbc.ocspFailOpen を true または false に設定します。例:

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

  Copy

OCSP コネクタまたはドライバーバージョンの確認¶

ドライバーまたはコネクタのバージョン、構成、および OCSP の動作の詳細については、 OCSP 設定 をご参照ください。

OCSP 応答キャッシュサーバー¶

Snowflakeクライアントは、実際にデータを転送する前に安全な接続を確立する「ハンドシェイク」を使用して、Snowflakeサービスエンドポイントへのすべての接続を開始します。ハンドシェイクの一部として、クライアントはサービスエンドポイントの TLS 証明書を認証します。証明書の失効ステータスは、 CA （認証機関）の OCSP （オンライン証明書ステータスプロトコル）サーバーの1つにクライアント証明書リクエストを送信することにより確認されます。

OCSP サーバーからの応答が妥当な時間を超えて遅延すると、接続エラーが発生します。次のキャッシュは失効ステータスを保持し、これらの問題の軽減に役立ちます。

• プロセスの存続期間中保持されるメモリキャッシュ。

• ファイルキャッシュ。キャッシュディレクトリ（例： ~/.cache/snowflake または ~/.snowsql/ocsp_response_cache）が削除されるまで保持します。

• Snowflake OCSP 応答キャッシュサーバー。 CA の OCSP サーバーから OCSP 応答を1時間ごとに取得し、24時間保存します。クライアントは、このサーバーキャッシュから特定のSnowflake証明書の検証ステータスをリクエストできます。

  重要

  サーバーポリシーでほとんどまたはすべての外部 IP アドレスおよびウェブサイトへのアクセスが拒否された場合、通常のサービス操作を許可するには、キャッシュサーバーアドレスを許可リストに登録することが 必須 です。キャッシュサーバーのホスト名は ocsp*.snowflakecomputing.com:80 です。

  何らかの理由でキャッシュサーバーを無効化する必要がある場合は、 SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED 環境変数を false に設定します。値は大文字と小文字が区別され、小文字にする 必要がある ことに注意してください。

キャッシュレイヤーに OCSP 応答が含まれていない場合、クライアントは CAの OCSP サーバーから検証ステータスを直接取得しようとします。

Javaコアログ機能（Java.util.logging）¶

このロガーを使用するには、 JVMに次のオプションを指定します。

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

次に、ロガーのアプリケーションプログラミングインターフェイス（API）を使用して、ログ記録の構成をカスタマイズできます。詳細については、 java.util.loggingパッケージのドキュメント をご参照ください。

たとえば、次の内容を含む logging.properties という名前のファイルを作成します。

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

コマンドラインで JVM パラメーターを指定します。

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

Copy

application.jar は JDBC ドライバーのアプリケーションコードを参照します。ログファイルは /tmp/snowflake_jdbc* にあります。

Simple Logging Facade for Java（org.slf4j）¶

ロガー実装パッケージ（つまり、 org.sl4j:sl4j-jdk14 または org.sl4j:slf4j-log4j12）またはカスタムロガー（つまり独自の org.slf4j.impl.StaticLoggerBinder クラス）がクラスパスで定義されている場合、ドライバーはこのロガーを自動的に使用します。

次の JVM オプションを指定して、このロガーを使用することを明示的に選択することもできます。

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

詳細については、 Simple Logging Facade for Java（SLF4J）のドキュメント をご参照ください。

ログ構成ファイル¶

あるいは、 ログレベル と、 sf_client_config.json 構成ファイルにログファイルを保存するディレクトリを簡単に指定できます。

この構成ファイルは、 JSON を使用して、 log_level と log_path のログパラメーターを以下のように定義します。

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

ドライバーは、以下の順序で構成ファイルの場所を検索します。

• client_config_file 接続パラメーター。構成ファイルへの完全なパスが含まれます。

• SF_CLIENT_CONFIG_FILE 環境変数。構成ファイルへの完全なパスが含まれます。

• JDBC ドライバーのインストールディレクトリ。ファイル名は sf_client_config.json にする必要があります。

• ユーザーのホームディレクトリ。ファイル名は sf_client_config.json にする必要があります。

プロパティが正しく設定されていることを確認する¶

DriverManager.getConnection() メソッドは、特定の事前定義された名前（「パスワード」、「ウェアハウス」など）に一致するプロパティパラメーターの値のみを読み取ります。プロパティ名のスペルを間違えたり、余分なプロパティを含めたりすると、ドライバーはエラーまたは警告メッセージを出さずに、それらのプロパティを無視します。これにより、小さなスペルミスの検出が困難になる場合があります。

接続文字列とアカウントに正しい値を使用する¶

接続を確立できない場合は、 JDBC 接続文字列でアカウント識別子を正しく指定していることを確認します。アカウント識別子の詳細については、 アカウント識別子 をご参照ください。