Parâmetros de configuração e conexão do ODBC¶

Definição de parâmetros no Windows¶

No Windows:

• Os parâmetros de configuração são definidos no registro do Windows usando regedit e o seguinte caminho de registro:

  [HKEY_LOCAL_MACHINE\SOFTWARE\Snowflake\Driver]
  

  Copy

• Os parâmetros de conexão são definidos em Nomes das Fontes de Dados (DSNs):

  • DSNs normalmente são criados e editados usando a ferramenta Windows Data Source Administration.

  • Se você desejar, as chaves de registro para DSNs podem ser editadas diretamente no registro do Windows usando regedit. O caminho do registro para as chaves é diferente dependendo se você está usando Windows de 64 bits ou 32 bits e se você está editando um DSN de usuário ou sistema:

    • Windows de 64 bits:

      [HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\<DSN_NAME>]
      
      [HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<DSN_NAME>]
      

      Copy

    • Windows de 32 bits:

      [HKEY_CURRENT_USER\SOFTWARE\WOW6432NODE\ODBC\ODBC.INI\<DSN_NAME>]
      
      [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432NODE\ODBC\ODBC.INI\<DSN_NAME>]
      

      Copy

    Para adicionar um parâmetro de conexão usando regedit, adicione um novo String Value, clique duas vezes no valor criado e depois insira o parâmetro ODBC como o Value name e o valor do parâmetro como o Value data.

Definição de parâmetros em macOS ou Linux¶

No macOS ou Linux:

• Os parâmetros de configuração são definidos no arquivo de configuração (simba.snowflake.ini).

• Os parâmetros de conexão são definidos no arquivo de nome da fonte de dados (DSN) (odbc.ini).

Parâmetros de configuração¶

CABundleFile

Defina a localização do arquivo do pacote da Autoridade Certificadora (CA). Faça referência a um arquivo que inclua uma lista válida de certificados CA.

Para Linux, os instaladores RPM e DEB copiam automaticamente o arquivo e definem este parâmetro.

Para Mac, o instalador PKG copia o arquivo e define este parâmetro.

Para Windows, o instalador MSI copia o arquivo e define este parâmetro.

Uma instalação manual requer que você baixe o arquivo de https://curl.haxx.se/docs/caextract.html e defina a localização do arquivo.

client_config_file

Especifica o caminho de um arquivo de configuração do registro em log que você pode usar para definir o nível de registro em log e o diretório para salvar arquivos de log.

CURLVerboseMode

Defina como true para habilitar o registro extenso cURL. O arquivo de log snowflake_odbc_curl.dmp é criado e atualizado. O driver ODBC do Snowflake usa cURL como a biblioteca HTTP e TLS. Este parâmetro é útil para o diagnóstico de problemas de rede.

DisableOCSPCheck

Defina como true para desabilitar a verificação do status de revogação de certificado TLS pelo Online Certificate Status Protocol (OCSP). Em circunstâncias normais, este sinalizador não deve ser definido. Mas se o problema de disponibilidade do OCSP persistir, o aplicativo poderá definir temporariamente este parâmetro a fim de solucionar problemas de conectividade e removê-lo quando o problema de disponibilidade do OCSP for resolvido.

DisableTelemetry

Especifica se a alternância do manipulador de telemetria em banda está habilitada ou não. Se esta configuração de driver estiver definida como true, o manipulador de telemetria não será criado no driver.

DriverManagerOverride

Por padrão, o driver detecta automaticamente qual gerenciador de driver usar. Entretanto, se sua situação específica exigir isso, a partir do driver ODBC versão 3.9.0, você pode substituir esta detecção automática e especificar manualmente qual gerenciador de driver usar.

Os valores possíveis são: UnixODBC, iODBC, , e .

Se DriverManagerOverride não for especificado, o driver usará a detecção automática para o gerenciamento do driver (chamada backtrace()) para obter informações do gerenciador do driver. Este é o comportamento padrão.

O parâmetro funciona somente em Linux e MacOS.

EnableAutoIpdByDefault

Defina como false para configurar o driver ODBC para definir SQL_ATTR_ENABLE_AUTO_IPD como false (que é o valor normalmente usado no padrão ODBC).

Caso contrário, por padrão, o driver ODBC define SQL_ATTR_ENABLE_AUTO_IPD como true para compatibilidade com ferramentas de terceiros.

Este parâmetro foi introduzido na versão 2.22.0 do driver ODBC.

EnablePidLogFileNames

Defina como true para incluir a ID do processo no nome do arquivo de log. Por exemplo, se a ID do processo for 7394, os arquivos de log serão nomeados:

• snowflake_odbc_connection_7394_0.log

• snowflake_odbc_generic7394_0.log

• snowflake_odbc_curl_7394.dmp

Você pode definir este parâmetro para evitar que processos diferentes substituam os mesmos arquivos de log. Cada processo gerará seu próprio conjunto de arquivos de log.

Por padrão, o valor deste parâmetro é false.

Este parâmetro foi introduzido na versão 2.22.2 do driver ODBC.

get_size_threshold

Especifica o tamanho mínimo de arquivo, em megabytes (MB), para dividir arquivos em partes menores ao baixar arquivos com o comando GET. Os arquivos com tamanhos menores que esse limite não utilizarão o download em várias partes.

O padrão é 5 (MB).

Nota

Você pode substituir esse valor para casos específicos definindo o parâmetro de conexão get_size_threshold correspondente.

KeepLeadingTrailingZeros

Determina como são tratados os zeros à esquerda ou direita em números formatados como valores de cadeia de caracteres. Por padrão, o parâmetro é definido como true, o que significa que o driver retém quaisquer zeros iniciais ou finais. Defina o parâmetro como false para remover zeros à esquerda ou à direita; por exemplo:

• 0.23 é alterado para .23

• 7.00 é alterado para 7

LogFileCount

Define o número máximo de arquivos de log a serem mantidos antes de alternar arquivos mais antigos para dar lugar a novos arquivos de log.

LogFileSize

Especifica o tamanho máximo, em bytes, de um arquivo de log. Quando um arquivo de log atinge o tamanho especificado, o driver ODBC cria automaticamente um novo arquivo de log.

O padrão é 20971520.

LogLevel

Especifica o nível de detalhe registrado para clientes que utilizam o driver ODBC:

• 0 = Desligado

• 1 = Fatal

• 2 = Erro

• 3 = Aviso

• 4 = Informativo

• 5 = Depurar

• 6 = Rastrear

LogPath

Especifica a localização dos arquivos de log do Snowflake para clientes que utilizam o driver ODBC.

MapToLongVarchar

Especifica o comprimento de uma cadeia de caracteres na qual se começa a mapear valores de cadeia para um tipo de dados ODBC SQL_LONGVARCHAR em vez dos tipos de dados ODBC padrão SQL_CHAR ou SQL_VARCHAR.

• < 0 (ou removido): mapeia valores de cadeia de caracteres em seus tipos de dados ODBC padrão. Padrão = -1.

• >= 0: especifica o número máximo de caracteres de cadeia a serem mapeados para os tipos de dados de cadeia de caracteres ODBC padrão. Todas as cadeias de caracteres maiores que este valor são mapeadas para SQL_LONGVARCHAR.

Você também pode especificar este parâmetro como um parâmetro de conexão. (Consulte as instruções para definir os parâmetros no Windows, macOS e Linux). Se definir ambos como um parâmetro de conexão e um parâmetro de configuração, o parâmetro de conexão no DSN (ou cadeia de conexão) tem precedência.

Este parâmetro foi introduzido na versão 2.24.3 do driver ODBC.

NoExecuteInSQLPrepare

Defina como true para configurar o driver ODBC para usar o comportamento ODBC padrão ao passar instruções DDL (tais como CREATE e DROP) para SQLPrepare() e SQLExecute().

No Snowflake, por padrão, quando você passa uma instrução DDL para SQLPrepare(), o driver ODBC envia a instrução para a fonte de dados para execução (não preparação). Quando você passa uma instrução DDL para SQLExecute(), o driver ODBC não envia a instrução para a fonte de dados.

Se você definir NoExecuteInSQLPrepare como true, o driver ODBC segue o comportamento padrão do ODBC. Chamar SQLPrepare() envia a instrução para a fonte de dados para preparação (não para execução). Chamar SQLExecute() envia a instrução para a fonte de dados para execução.

Este parâmetro foi introduzido na versão 2.21.6 do driver ODBC.

NoProxy

Especifica os padrões de nome de host para ignorar o servidor proxy (por exemplo, .amazonaws.com para ignorar o acesso Amazon S3).

Nota

O driver ODBC do Snowflake passa o valor NoProxy para a opção do curl CURLOPT_NOPROXY.

O formato do valor NoProxy pode ser encontrado aqui CURLOPT_NOPROXY explained».

Proxy

Especifica um servidor proxy sob a forma de <host>:<porta> para clientes que utilizam o driver ODBC.

Nota

No Windows, as entradas para LogLevel e LogPath são criadas e preenchidas com valores padrão quando o driver ODBC está instalado; entretanto, uma entrada para Proxy não é criada durante a instalação. Para especificar um proxy a ser usado com o driver, você deve adicionar manualmente a entrada à chave de registro do driver.

Para contornar o proxy para um ou mais endereços IP ou URLs, adicione o parâmetro NoProxy.

SSLVersion

Especifica a versão mínima do SSL/TLS do a ser usada ao iniciar o handshake do TLS. Os valores correspondem às capacidades de libcurl. Para obter mais informações, consulte as entradas CURL_SSLVERSION_* em CURLOPT_SSLVERSION explicado.

Possíveis valores: um dentre TLSv1, SSLv2, SSLv3, TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 (padrão: TLSv1_2).

A Snowflake recomenda deixar essa configuração como padrão quando você não tiver uma necessidade muito específica de alterá-la.

SSLVersionMax

Especifica a versão máxima do SSL/TLS a ser usada ao iniciar o handshake do TLS. Os valores correspondem às capacidades de libcurl. Para obter mais informações, consulte as entradas CURL_SSLVERSION_MAX_* em CURLOPT_SSLVERSION explicado.

Possíveis valores: um dentre TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3 (padrão: TLSv1_3).

A Snowflake recomenda deixar essa configuração como padrão quando você não tiver uma necessidade muito específica de alterá-la.

Parâmetros de conexão¶

Conexão usando o arquivo connections.toml¶

O driver ODBC permite que você adicione definições de conexão a um arquivo de configuração connections.toml. Uma definição de conexão refere-se a uma coleção de parâmetros relacionados à conexão. O driver atualmente oferece suporte à versão 1.0.0 do formato TOML.

Para obter mais informações sobre formatos de arquivo toml, consulte TOML (Tom’s Obvious Minimal Language).

O prefixo da cadeia de caracteres de conexão: odbc:snowflake:auto informa ao driver para procurar a configuração de conexão dentro dos arquivos predefinidos (padrão). O driver ODBC procura o arquivo connections.toml nos seguintes locais, em ordem:

• Se existir um diretório ~/.snowflake em sua máquina, o ODBC usará o arquivo ~/.snowflake/connections.toml.

• Local especificado na variável de ambiente SNOWFLAKE_HOME.

• Caso contrário, o ODBC usará o arquivo connections.toml em um dos seguintes locais, com base em seu sistema operacional:

  • Linux: ~/.config/snowflake/connections.toml, mas é possível atualizá-lo com variáveis XDG

  • Windows: %USERPROFILE%\AppData\Local\snowflake\connections.toml

  • Mac: ~/Library/Application Support/snowflake/connections.toml

É possível gerar as configurações básicas para o arquivo de configuração Snowsight em Snowsight. Para obter mais informações, consulte Configuração de um cliente, driver, biblioteca ou aplicativo de terceiros para se conectar ao Snowflake.

Se quiser alternar entre várias conexões existentes, é possível configurá-las no arquivo connections.toml. A chave padrão é default, mas você altera o nome da conexão padrão configurando a variável de ambiente do shell SNOWFLAKE_DEFAULT_CONNECTION_NAME.

Os arquivos de amostra connections.toml a seguir definem duas conexões:

[default]
account = 'my_organization-my_account'
user = 'test_user'
password = '******'
warehouse = 'testw'
database = 'test_db'
schema = 'test_odbc'
protocol = 'https'
port = '443'


[aws-oauth-file]
account = 'my_organization-my_account'
user = 'test_user'
password = '******'
warehouse = 'testw'
database = 'test_db'
schema = 'test_odbc'
protocol = 'https'
port = '443'
authenticator = 'oauth'
token_file_path = '/Users/test/.snowflake/token'

Especificação de parâmetros em uma cadeia de caracteres de conexão¶

Você pode especificar os parâmetros de conexão como pares nome-valor em uma cadeia de caracteres de conexão, usando um sinal de igual (=) entre cada parâmetro e valor e usando um ponto e vírgula (;) entre os parâmetros. Por exemplo:

driver={SnowflakeDSIIDriver};server=myorganization-myaccount.snowflakecomputing.com;uid=myloginname;pwd=mypassword;database=mydatabase;schema=myschema;warehouse=mywarehouse;role=myrole;...

Você pode gerar a cadeia de caracteres de conexão básica na Snowsight. Para obter mais informações, consulte Configuração de um cliente, driver, biblioteca ou aplicativo de terceiros para se conectar ao Snowflake.

Verificação da conexão da rede ao Snowflake com SnowCD¶

Após configurar seu driver, você pode avaliar e solucionar problemas de conectividade de rede com o Snowflake usando o SnowCD.

Você pode usar o SnowCD durante o processo de configuração inicial e sob demanda a qualquer momento para avaliar e solucionar problemas de sua conexão de rede ao Snowflake.

Conexão por meio de um servidor proxy¶

As instruções para configurar uma conexão de servidor proxy dependem de seu sistema operacional e da versão do driver:

Uso de login único (SSO) para autenticação¶

Se você tiver configurado o Snowflake para usar o login único (SSO), pode configurar seu aplicativo cliente para usar o SSO para autenticação. Consulte Uso de SSO com aplicativos clientes que se conectam ao Snowflake para obter mais detalhes.

Uso da autenticação multifator¶

O Snowflake permite armazenar tokens MFA em cache, incluindo combinar o cache de tokens MFA com SSO.

Para obter mais informações, consulte Uso do armazenamento em cache de tokens MFA para minimizar o número de tentativas durante a autenticação — opcional.

Uso de autenticação de pares de chaves¶

O driver ODBC suporta autenticação de par de chaves e rodízio de chaves.

1. Para começar, complete a configuração inicial para autenticação de par de chaves como mostrado em Autenticação de pares de chaves e rotação de pares de chaves.

2. Modifique as entradas do nome da fonte de dados (DSN) para o driver. Para obter mais informações sobre as entradas do DSN, consulte o tópico apropriado para seu sistema operacional:

   • Instalação e configuração do driver ODBC para Linux

   • Instalação e configuração do driver ODBC para Windows

   Adicione os seguintes parâmetros (diferenciam maiúsculas e minúsculas):

   AUTHENTICATOR = SNOWFLAKE_JWT

   Especifica autenticar a conexão Snowflake usando a autenticação de par de chaves com JSON Web Token (JWT).

   JWT_TIME_OUT = integer

   Opcional. Especifica o tempo que o Snowflake espera para receber o JWT (em segundos) antes de atingir o tempo limite. Se isso acontecer, a autenticação falha e o driver retorna um erro Invalid JWT token. Para resolver ocorrências repetidas do erro, aumente o valor do parâmetro. Padrão: 30

   PRIV_KEY_FILE = path/rsa_key.p8

   Especifica o caminho local para o arquivo de chave privada que você criou (ou seja, rsa_key.p8).

   O valor definido no DSN pode ser substituído chamando a função SQLSetConnectAttr(). Para obter mais detalhes, consulte Comportamento específico do Snowflake da função SQLSetConnectAttr.

   PRIV_KEY_FILE_PWD = <password>

   Especifica a senha para decodificar o arquivo de chave privada.

   Este parâmetro deve ser definido somente se o parâmetro PRIV_KEY_FILE também estiver definido.

   O valor definido no DSN pode ser substituído chamando a função SQLSetConnectAttr(). Para obter mais detalhes, consulte Comportamento específico do Snowflake da função SQLSetConnectAttr.

3. Salve as configurações.

Usar o fluxo do código de autorização OAuth 2.0¶

O fluxo do código de autorização OAuth 2.0 é um método seguro para que um aplicativo cliente obtenha um token de acesso de um servidor de autorização em nome de um usuário, sem revelar as credenciais do usuário.

Para ativar o fluxo do código de autorização OAuth 2.0:

1. Defina o parâmetro de conexão authenticator como oauth_authorization_code.

2. Defina os seguintes parâmetros de conexão OAuth:

   • OAUTH_CLIENT_ID: valor do client id fornecido pelo provedor de identidade para integração do Snowflake (metadados de integração de segurança do Snowflake).

   • OAUTH_CLIENT_SECRET: valor de client secret fornecido pelo provedor de identidade para integração do Snowflake (metadados de integração de segurança do Snowflake).

   • OAUTH_AUTHORIZATION_URL: ponto de extremidade do provedor de identidade que fornece o código de autorização para o driver. Quando o Snowflake é usado como um provedor de identidade, esse valor é derivado dos parâmetros server ou account.

   • OAUTH_TOKEN_REQUEST_URL: ponto de extremidade do provedor de identidade que fornece os tokens de acesso ao driver. Quando o Snowflake é usado como um provedor de identidade, esse valor é derivado dos parâmetros server ou account.

   • OAUTH_SCOPE: escopo solicitado na solicitação de autorização do provedor de identidade. Por padrão, ele é derivado da função. Quando vários escopos são necessários, o valor deve ser uma lista separada por espaços de vários escopos.

   • OAUTH_REDIRECT_URI: URI a ser usado para redirecionamento do código de autorização (metadados de integração de segurança do Snowflake). Padrão: http://127.0.0.1:{randomAvailablePort}.

Usar o fluxo de credenciais de cliente OAuth 2.0¶

O fluxo de credenciais de cliente do OAuth 2.0 oferece uma maneira segura de autenticação máquina para máquina (M2M), como o Snowflake Connector para Python que se conecta a um serviço de back-end. Ao contrário do fluxo do código de autorização OAuth 2.0, esse método não depende de nenhum dado específico do usuário.

Para ativar o fluxo de credenciais de cliente OAuth 2.0:

1. Defina o parâmetro de conexão authenticator como oauth_client_credentials.

2. Defina os seguintes parâmetros de conexão OAuth:

   • OAUTH_CLIENT_ID: valor do client id fornecido pelo provedor de identidade para integração do Snowflake (metadados de integração de segurança do Snowflake).

   • OAUTH_CLIENT_SECRET: valor de client secret fornecido pelo provedor de identidade para integração do Snowflake (metadados de integração de segurança do Snowflake)

   • OAUTH_TOKEN_REQUEST_URL: ponto de extremidade do provedor de identidade que fornece os tokens de acesso ao driver. Quando o Snowflake é usado como um provedor de identidade, esse valor é derivado dos parâmetros server ou account.

   • OAUTH_SCOPE: escopo solicitado na solicitação de autorização do provedor de identidade. Por padrão, ele é derivado da função. Quando vários escopos são necessários, o valor deve ser uma lista separada por espaços de vários escopos.

Autenticação com um token de acesso programático (PAT)¶

O Programmatic Access Token (PAT), ou token de acesso programático, é um método de autenticação específico do Snowflake. O recurso deve ser ativado para a conta antes de ser usado (consulte Pré-requisitos para obter mais informações). A autenticação com PAT não envolve nenhuma interação humana.

Autenticação com federação de identidade de carga de trabalho (WIF)¶

Federação de identidades de carga de trabalho fornece um método de autenticação serviço a serviço para o Snowflake. Esse método permite que aplicativos, serviços ou contêineres sejam autenticados com o Snowflake, aproveitando o sistema de identidade nativo de seu provedor de nuvem, como AWS IAM, Microsoft Entra IDou contas de serviço do Google Cloud. Esta abordagem elimina a necessidade de gerenciar credenciais de longa duração e simplifica a aquisição de credenciais em comparação com outros métodos, como OAuth externo. Os conectores Snowflake são projetados para obter automaticamente credenciais de curta duração do provedor de identidade da plataforma.

Para habilitar o autenticador da federação de identidade da carga de trabalho, faça o seguinte:

1. Defina o parâmetro de conexão autenticador como WORKLOAD_IDENTITY.

2. Defina o parâmetro de conexão workload_identity_provider como AWS, AZURE, GCP ou OIDC, com base na sua plataforma.

3. Para OpenID Connect (OIDC), especifique o parâmetro de conexão token.

Gerenciamento de arquivos de log¶

Para ajudá-lo a rastrear os problemas que possam surgir, você pode habilitar o registro no driver ODBC. O driver ODBC fornece as seguintes opções de configuração que você pode usar para configurar o registro e gerenciar arquivos de log:

• EnablePidLogFileNames: Acrescenta a IDdo processo ao nome de um arquivo de log.

• LogFileCount: Define o número máximo de arquivos de log salvos.

• LogFileSize: Especifica o tamanho máximo de um arquivo de log.

• LogLevel: Especifica os tipos de informações a serem registradas.

• LogPath: Define a localização para os arquivos de log.

Você pode usar estes parâmetros para gerenciar como nomear, armazenar e alternar os arquivos de log. Você pode especificar o tamanho e a quantidade de arquivos de log que deseja manter antes de substituí-los por arquivos de log recém-criados. O exemplo a seguir acrescenta a ID do processo aos nomes dos arquivos para garantir a exclusividade, define o tamanho máximo do arquivo como 30MB e mantém os 100 arquivos de log mais recentes.

EnablePidLogFileNames = true  # Appends the process ID to each log file
LogFileSize = 30,145,728      # Sets log files size to 30MB
LogFileCount = 100            # Saves the 100 most recent log files

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

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

O Snowflake usa OCSP para avaliar a cadeia de certificados ao fazer uma conexão com o Snowflake. A versão do driver ou conector e sua configuração determinam o comportamento OCSP. Para obter mais informações sobre a versão do driver ou conector, sua 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.