配置 JDBC 驱动程序¶

语法¶

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

连接参数¶

<account_identifier>

指定 Snowflake 账户的账户标识符。有关详细信息，请参阅 配置客户端、驱动程序、库或第三方应用程序以连接到 Snowflake。有关在 JDBC 连接字符串中使用账户标识符的示例，请参阅 示例。

<connection_params>

指定一个包含一个或多个 JDBC 连接参数 和 会话参数，每个参数用 & 号字符 (&) 分隔，连接字符串中的任何位置都不能有空格。

如果需要设置使用空格、& 号 (&)、等号 (=) 或其他特殊字符的参数值，则应对特殊字符进行 URL 编码 (link removed)。例如，如果需要在 query_tag 会话参数中指定包含空格、& 号和等号的值，请执行以下操作：

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

Copy

将空间编码为 %20，将 & 号编码为 %26，将等号编码为 %3D：

String connectionURL = "jdbc:snowflake://myorganization-myaccount.snowflakecomputing.cn/?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.cn/", props);

Copy

其他参数¶

连接字符串中可以包含任何会话参数。例如：

BROWSER_RESPONSE_TIMEOUT=<Integer>

指定等待来自外部浏览器的成功身份验证的超时时间（以秒为单位）。

默认值为 120。

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Boolean>

指定是否启用带外遥测。

默认值为 true。

CLIENT_SESSION_KEEP_ALIVE=<Boolean>

指定是在一段时间不活动后保持当前会话处于活动状态，还是强制用户重新登录。如果值为 true，Snowflake 会无限期地保持会话处于活动状态，即使用户没有活动也是如此。如果值为 false，用户在不活动 4 小时后必须重新登录。

默认值为 false。

CLIENT_SESSION_KEEP_ALIVE_HEARTBEAT_FREQUENCY=<Integer>

指定客户端尝试更新会话令牌的间隔秒数 (900-3600)。

默认值为 3600。

有关所有会话参数的说明，请参阅 参数。

示例¶

以下是使用账户名称作为 myorganization 组织中账户 myaccount 标识符 的连接字符串的示例。

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

Copy

以下是使用 账户定位器 xy12345 作为账户标识符的连接字符串的示例：

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

Copy

请注意，此示例使用 AWS US 西部（俄勒冈）区域中的账户。如果账户位于不同的区域，或者账户使用不同的云提供商，则需要 在账户定位器之后指定其他分段。

连接属性中的 privateKey 属性¶

本节举例说明如何将 privateKey 属性设置为文件中的私钥。

此示例使用 ` Bouncy Castle Crypto APIs <https://www.bouncycastle.org/java.html (https://www.bouncycastle.org/java.html)>`_。为了编译和运行此示例，必须在类路径中包含以下 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.cn";
    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。

密钥解密错误¶

如果使用 OpenSSL V3 生成的加密密钥，则可能会收到类似以下内容的错误：

java.security.NoSuchAlgorithmException: 1.2.840.113549.1.5.13 SecretKeyFactory not available

java.security.InvalidKeyException: IOException : DER input, Integer tag error

在这种情况下，您可以使用 Bouncy Castle 通过指定以下 JVM 实参来解密密钥：

-Dnet.snowflake.jdbc.enableBouncyCastle=true

通过设置 Java 系统属性来指定代理服务器¶

要通过代理服务器进行连接，可以设置代理系统属性。您可以在代码中设置这些属性，也可以通过命令行上将其传递给客户端应用程序的 JVM（Java 虚拟机）。

要在代码中设置系统属性，请调用 System.setProperty：

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

Copy

要将命令行上的系统属性传递给 JVM，请使用 -D 命令行选项：

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

Copy

要绕过一个或多个 IP 地址或主机的代理，请将 http.nonProxyHosts 系统属性设置为以下主机的列表：

• 使用竖线符号 (|) 分隔主机名。

• 要指定与模式匹配的主机名，请使用星号 (*) 作为通配符。

下面的示例演示了如何在命令行中设置此系统属性：

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

在 JDBC 连接字符串中指定代理服务器¶

在 JDBC 连接字符串中设置以下参数，即可使用代理服务器：

• useProxy

• proxyHost

• proxyPort

• proxyUser

• proxyPassword

• proxyProtocol

如果代理服务器不需要身份验证，则可以省略 proxyUser 和 proxyPassword 参数。

如果代理服务器连接需要使用代理用户名和代理密码进行身份验证，那么其他应用程序在使用 HTTP 协议时可能会以纯文本形式暴露这些凭据。要避免暴露这些凭据，请使用 proxyProtocol 参数指定 HTTPS 协议。

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

例如：

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

连接字符串中指定的代理设置优先于 JVM 系统属性。

如果设置了代理 JVM 实参，并且您不想代理任何连接，请不要设置 useProxy=false，因为没有任何效果。相反，请使用以下方法，这可以有效地绕过 JVM 代理设置：

useProxy=true
proxyHost=127.0.0.1
proxyPort=8080
nonProxyHosts=*

&nonProxyHosts=<bypass_proxy_for_these_hosts>

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

&proxyProtocol=https

选择故障打开或故障关闭模式¶

3.8.0 之前的 JDBC 驱动程序版本默认为故障关闭。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（在线证书状态协议）服务器发送客户端证书请求，检查证书的撤销状态。

当 OCSP 服务器的响应出现超过合理时间的延迟时，连接会失败。以下缓存会保留撤销状态，这有助于缓解这些问题：

• 内存缓存，在进程的生命周期中保留该状态。

• 文件缓存，将该状态一直保留到缓存目录（例如 ~/.cache/snowflake 或者 ~/.snowsql/ocsp_response_cache）被清除。

• Snowflake OCSP 响应缓存服务器，它每小时提取一次来自 CA 的 OCSP 服务器的 OCSP 响应，并将这些响应存储 24 小时。然后，客户端可以从此服务器缓存中请求给定 Snowflake 证书的验证状态。

  重要

  如果服务器策略拒绝对大多数或所有外部 IP 地址和网站的访问，则 必须 将缓存服务器地址加入允许名单中，以允许正常的服务运行。缓存服务器主机名是 ocsp*.snowflakecomputing.cn:80。

  如果因故需要禁用缓存服务器，请将 SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED 环境变量设置为 false。请注意，该值区分大小写，并且 必须 为小写。

如果没有一个缓存层包含 OCSP 响应，则客户端会尝试直接从 CA 的 OCSP 服务器提取验证状态。

Java core logging facilities (Java.util.logging)¶

要使用此记录器，请为 JVM 指定以下选项：

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

然后，您可以使用日志记录器的应用程序编程接口 (API)，自定义日志记录配置。

例如，创建一个名为 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。

日志记录配置文件¶

或者，您也可以在 sf_client_config.json 配置文件中轻松指定 ` 日志级别 <https://github.com/snowflakedb/snowflake-jdbc/blob/master/src/main/java/net/snowflake/client/log/SFLogLevel.java (https://github.com/snowflakedb/snowflake-jdbc/blob/master/src/main/java/net/snowflake/client/log/SFLogLevel.java)>`_ 和保存日志文件的目录。

此配置文件使用 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 连接字符串中正确指定了账户标识符。有关查找账户标识符的更多信息，请参阅 配置客户端、驱动程序、库或第三方应用程序以连接到 Snowflake。