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~3,600초)을 지정합니다.

기본값은 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 Crypto 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(자바 가상 머신)에 전달할 수 있습니다.

코드에서 시스템 속성을 설정하려면 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

페일 오픈 또는 페일 클로즈 모드 선택하기¶

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(온라인 인증서 상태 프로토콜) 서버 중 1개에 클라이언트 인증서 요청을 전송하여 인증서의 해지 상태를 확인합니다.

OCSP 서버의 응답이 적절한 시간 이상 동안 지연되면 연결이 실패하게 됩니다. 해지 상태를 유지하여 이러한 문제를 완화하는 데 도움이 되는 캐시는 다음과 같습니다.

• 메모리 캐시, 프로세스의 수명 동안 지속됩니다.

• 파일 캐시, 캐시 디렉터리(예: ~/.cache/snowflake 또는 ~/.snowsql/ocsp_response_cache)가 삭제될 때까지 지속됩니다.

• Snowflake OCSP 응답 캐시 서버, 매시간 CA의 OCSP 서버에서 OCSP 응답을 가져와 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* 에 위치합니다.

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.

자세한 내용은 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 환경 변수.

• 파일 이름을 sf_client_config.json 으로 지정해야 하는 JDBC 드라이버 설치 디렉터리.

• 파일 이름을 sf_client_config.json 으로 지정해야 하는 사용자의 홈 디렉터리.

속성이 올바르게 설정되었는지 확인하기¶

DriverManager.getConnection() 메서드는 미리 정의된 특정 이름(“비밀번호”, “웨어하우스” 등)과 일치하는 속성 매개 변수의 값만 읽습니다. 속성 이름에 맞춤법 오류가 있거나 추가 속성이 포함된 경우, 드라이버는 오류 또는 경고 메시지를 표시하지 않고 해당 속성을 무시합니다. 이로 인해 사소한 맞춤법 오류를 감지하는 것이 어려울 수 있습니다.

연결 문자열 및 계정에서 올바른 값 사용하기¶

연결을 설정할 수 없는 경우, JDBC 연결 문자열에 계정 식별자가 올바르게 지정되었는지 확인하십시오. 계정 식별자에 대한 자세한 내용은 계정 식별자 를 참조하십시오.