Configuração do driver JDBC¶

Sintaxe¶

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

Parâmetros de conexão¶

<identificador_de_conta>

Especifica o identificador da conta para sua conta Snowflake. Para obter mais detalhes, consulte Identificadores de conta. Para exemplos do identificador de conta utilizado em uma cadeia de conexão JDBC, consulte Exemplos.

<params_conexão>

Especifica uma série de um ou mais parâmetros de conexão JDBC e parâmetros de sessão na forma de <param>=<value>, com cada parâmetro separado pelo caractere de E comercial (&), e sem espaços em nenhum lugar na cadeia de conexão.

Se você precisar definir valores de parâmetros que utilizam espaços, E comerciais (&), sinais de igual (=) ou outros caracteres especiais, você deve codificar na URL os caracteres especiais. Por exemplo, se você precisar especificar um valor que contenha um espaço, um E comercial e um sinal de igual no parâmetro de sessão query_tag:

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

Copy

codifique o espaço como %20, o E comercial como %26 e o sinal de igual como %3D:

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

Copy

Como alternativa, em vez de especificar estes parâmetros na cadeia de conexão, você pode definir estes parâmetros em um objeto Properties que você passa para o método DriverManager.getConnectionIO.

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

Copy

Outros parâmetros¶

Qualquer parâmetro de sessão pode ser incluído na cadeia de conexão. Por exemplo:

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Booleano>

Especifica se a telemetria fora de banda deve ser ativada.

O padrão é true.

CLIENT_SESSION_KEEP_ALIVE=<Booleano>

Especifica se a sessão atual deve ser mantida ativa após um período de inatividade, ou se deve-se forçar o usuário a fazer login novamente. Se o valor for true, o Snowflake mantém a sessão ativa indefinidamente, mesmo que não haja atividade do usuário. Se o valor for false, o usuário deve fazer o login novamente após quatro horas de inatividade.

O padrão é false.

CLIENT_SESSION_KEEP_ALIVE_HEARTBEAT_FREQUENCY=<Inteiro>

Especifica o número de segundos (900-3600) entre as tentativas do cliente para atualizar o token para a sessão.

O padrão é 3600.

Para descrições de todos os parâmetros da sessão, consulte Parâmetros.

Exemplos¶

O seguinte é um exemplo da cadeia de conexão que usa um identificador de conta que especifica a conta myaccount na organização myorganization.

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

Copy

O seguinte é um exemplo de uma cadeia de conexão que utiliza o localizador de conta xy12345 como identificador de conta:

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

Copy

Note que este exemplo usa uma conta na Região Oeste dos EUA (Oregon) da AWS. Se a conta estiver em uma região diferente ou se a conta usar um provedor de nuvem diferente, será necessário especificar segmentos adicionais após o localizador de conta.

Propriedade privateKey em propriedades de conexão¶

Esta seção fornece um exemplo de configuração da propriedade privateKey para uma chave privada em um arquivo.

Este exemplo utiliza as APIs Bouncy Castle Crypto. A fim de compilar e executar esse exemplo, você deve incluir os seguintes arquivos JAR em seu classpath:

• o arquivo JAR do provedor (bcprov-jdkversions.jar)

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

onde versions especifica as versões do arquivo JDK compatíveis com o arquivo JAR.

Para utilizar este exemplo:

1. Copie o código de exemplo abaixo e substitua os seguintes valores de espaço reservado:

   Espaço reservado	Descrição
   path/rsa_key.p8	Defina com o caminho e nome do arquivo de chave privada que você gerou anteriormente.
   private_key_passphrase	Se você gerou uma chave criptografada, implemente o método getPrivateKeyPassphrase() para retornar a senha para descriptografar essa chave.
   account_identifier	Defina com seu identificador de conta.
   user	Defina com seu nome de login Snowflake.
   database_name	Defina com o nome do banco de dados que você deseja utilizar.
   schema_name	Defina com o nome do esquema que você deseja usar.
   warehouse_name	Defina com o nome do warehouse que você deseja usar.
   role	Defina com o nome da função que você deseja usar.

2. Compile e execute o código de exemplo. Inclua os arquivos JAR Bouncy Castle no classpath.

   Por exemplo, no Linux e 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

   No 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

Código de exemplo

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

Nome do arquivo de chave privada e senha como propriedades de conexão¶

Você pode especificar o nome do arquivo de chave privada e a senha como propriedades de conexão separadas, por exemplo:

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

Se você especificar os parâmetros private_key_file e private_key_file_pwd, não especifique o parâmetro privateKey nas propriedades da conexão.

Nome do arquivo de chave privada e senha na cadeia de conexão¶

Você pode especificar o nome do arquivo de chave privada e a senha na cadeia de conexão, como mostrado abaixo:

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

Se você especificar a chave privada e senha na cadeia de conexão, então não especifique os parâmetros private_key_file, private_key_file_pwd ou privateKey nas propriedades da conexão.

Especificação de um servidor proxy pela definição de propriedades do sistema Java¶

Para conectar-se por um servidor proxy, você pode definir as propriedades do sistema proxy. Você pode configurá-las em seu código ou passá-las na linha de comando para a JVM (máquina virtual Java) para seu aplicativo cliente.

Para definir as propriedades do sistema em seu código, chame 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

Para passar as propriedades do sistema na linha de comando para seu JVM, use a opção de linha de comando -D:

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

Copy

Para ignorar o proxy para um ou mais endereços IP ou hosts, defina a propriedade do sistema http.nonProxyHosts com a lista destes hosts:

• Use um símbolo de barra vertical (|) para separar os nomes dos hosts.

• Para especificar os nomes dos hosts que correspondem a um padrão, use um asterisco (*) como um caractere curinga.

O exemplo a seguir demonstra como definir esta propriedade do sistema na linha de comando:

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

Especificação de um servidor proxy na cadeia de conexão JDBC¶

Para utilizar um servidor proxy definindo os seguintes parâmetros na cadeia de conexão JDBC:

• useProxy

• proxyHost

• proxyPort

• proxyUser

• proxyPassword

• proxyProtocol

Se seu servidor proxy não exigir autenticação, você pode omitir os parâmetros proxyUser e proxyPassword.

Se sua conexão ao servidor proxy exigir autenticação usando um nome de usuário proxy e senha proxy, essas credenciais podem ser expostas como texto simples por outros aplicativos ao usar o protocolo HTTP. Para evitar expor estas credenciais, use o parâmetro proxyProtocol para especificar o protocolo HTTPS.

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

Por exemplo:

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

As configurações de proxy especificadas na cadeia de conexão substituem as propriedades do sistema proxy no JVM.

&nonProxyHosts=<bypass_proxy_for_these_hosts>

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

&proxyProtocol=https

Escolha do modo falha-abre ou falha-fecha¶

Versões do driver JDBC anteriores a 3.8.0 usam falha-fecha como padrão. Versões 3.8.0 e posteriores usam falha-abre como padrão. Você pode substituir o comportamento padrão de uma das seguintes maneiras:

• Defina a propriedade de conexão ocspFailOpen como true ou false. Por exemplo:

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

  Copy

• Defina a propriedade do sistema net.snowflake.jdbc.ocspFailOpen como true ou false. Por exemplo:

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

  Copy

Verificação da versão do driver ou conector OCSP¶

Para obter mais informações sobre a versão do driver ou conector, configuração e comportamento OCSP, consulte Configuração do OCSP.

Servidor de cache de resposta OCSP¶

Os clientes Snowflake iniciam cada conexão com um ponto de extremidade do servidor Snowflake com um “handshake” que estabelece uma conexão segura antes de realmente transferir dados. Como parte do handshake, um cliente autentica o certificado TLS do ponto de extremidade do servidor. O status de revogação do certificado é verificado enviando uma solicitação do certificado de cliente para um dos servidores OCSP (Online Certificate Status Protocol) para a CA (autoridade de certificação).

Uma falha na conexão ocorre quando a resposta do servidor OCSP é atrasada além de um tempo razoável. Os seguintes caches persistem no status de revogação, ajudando a aliviar esses problemas:

• Cache de memória, que persiste por toda a vida do processo.

• Cache de arquivos, que persiste até que o diretório de cache (por exemplo, ~/.cache/snowflake ou ~/.snowsql/ocsp_response_cache) seja purgado.

• O servidor de cache de resposta OCSP do Snowflake, que busca respostas OCSP dos servidores OCSP da CA de hora em hora e as armazena por 24 horas. Os clientes podem então solicitar o status de validação de um determinado certificado do Snowflake a partir deste cache do servidor.

  Importante

  Se a política de seu servidor negar acesso à maioria ou a todos os sites e endereços IP externos, você precisará permitir que o endereço do servidor de cache permita a operação normal do serviço. O nome de host do servidor de cache é ocsp*.snowflakecomputing.com:80.

  Se você precisar desativar o servidor de cache por qualquer motivo, defina a variável de ambiente SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED como false. Observe que o valor diferencia maiúsculas e minúsculas e precisa estar em minúsculas.

Se nenhuma das camadas de cache contiver a resposta do servidor OCSP, o cliente tenta obter o status de validação diretamente do servidor OCSP para a CA.

Java Core Logging Facilities (Java.util.logging)¶

Para utilizar este agente de log, especifique a seguinte opção para o JVM:

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

Depois, você pode personalizar a configuração de registro usando a interface de programação de aplicativos (API) para o agente de log. Para obter mais detalhes, consulte a documentação do pacote java.util.log.

Por exemplo, crie um arquivo chamado logging.properties que inclua o seguinte conteúdo:

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

Especifique os parâmetros JVM na linha de comando:

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

Copy

Onde application.jar faz referência ao código de aplicativo para o driver JDBC. Os arquivos de log estão localizados em /tmp/snowflake_jdbc*.

Simple Logging Facade for Java (org.slf4j)¶

Se um pacote de implementação de agente de log (ou seja, org.sl4j:sl4j-jdk14 ou org.sl4j:slf4j-log4j12) ou um agente de log personalizado (ou seja, sua própria classe org.slf4j.impl.StaticLoggerBinder) tiver sido definido no classpath, então o driver automaticamente usa este agente de log.

Você também pode escolher explicitamente usar este agente de log especificando a seguinte opção JVM:

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

Para obter mais informações, consulte a documentação Simple Logging Facade for Java (SLF4J).

Arquivo de configuração do registro em log¶

Alternativamente, você pode facilmente especificar o nível de log e o diretório no qual salvar os arquivos de log no arquivo de configuração sf_client_config.json.

Este arquivo de configuração usa JSON para definir os parâmetros de registro em log log_level e log_path, como segue:

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

O driver procura a localização do arquivo de configuração na seguinte ordem:

• client_config_file Parâmetro de conexão contendo o caminho completo para o arquivo de configuração.

• Variável de ambiente SF_CLIENT_CONFIG_FILE contendo o caminho completo para o arquivo de configuração.

• Diretório de instalação do driver JDBC, onde o arquivo deve ser nomeado sf_client_config.json.

• Diretório inicial do usuário, onde o arquivo deve ser nomeado sf_client_config.json.

Assegure-se de que as propriedades estão corretas¶

O método DriverManager.getConnection() lê apenas os valores do parâmetro Properties que correspondem a nomes específicos e predefinidos (“senha”, “warehouse”, etc.). Se você escrever errado o nome de uma propriedade ou incluir propriedades extras, o driver ignora essas propriedades sem emitir uma mensagem de erro ou aviso. Isto pode dificultar a detecção de pequenos erros ortográficos.

Uso dos valores corretos para a cadeia de caracteres de conexão e conta¶

Se você não conseguir estabelecer uma conexão, verifique se está especificando corretamente o identificador da conta na cadeia de conexão JDBC. Para obter mais informações sobre identificadores de contas, consulte identificador da conta.