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

Parâmetros de conexão requeridos¶

<nome> (Fonte de dados)

Especifica o nome de seu DSN.

port (Porta)

Especifica a porta na qual o driver busca a comunicação do Snowflake.

Nota

Você não precisa alterar o valor padrão Port de 443.

pwd (Senha)

Uma senha é necessária para se conectar ao Snowflake; entretanto, por razões de segurança e autenticação, o Snowflake desencoraja fortemente o armazenamento de credenciais de senha diretamente dentro de qualquer definição DSN.

Normalmente, as credenciais são passadas ao driver de forma programática pelo aplicativo do cliente que está tentando se conectar ao Snowflake.

Nota

No Windows, o driver ODBC exibe um campo Password na ferramenta Data Source Administration; no entanto, o driver não armazena quaisquer valores inseridos no campo. Ao invés disso, o driver exige que as credenciais de login sejam fornecidas no momento da conexão.

server (Servidor)

Especifica o nome de host de sua conta no seguinte formato:

account_identifier.snowflakecomputing.com

Para obter mais informações sobre identificadores de conta, consulte Identificadores de conta.

uid (Usuário)

Especifica o nome de login do usuário do Snowflake a autenticar.

Parâmetros de conexão opcionais¶

BROWSER_RESPONSE_TIMEOUT

Especifica o número de segundos de espera por uma resposta de autenticação em um navegador externo.

O padrão é 120.

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.

database (Banco de dados)

Especifica o banco de dados padrão a ser utilizado para as sessões iniciadas pelo driver.

maxHttpRetries (Banco de dados)

Especifica o número máximo de novas tentativas de HTTP para consultas com solicitações de HTTP com falha antes de retornar um erro. A configuração do maxHttpRetries=0 remove o limite de novas tentativas, mas com isso há o risco de o driver repetir infinitamente chamadas de HTTP com falha.

O valor padrão é 7.

role (Função)

Especifica a função padrão a ser usada nas sessões iniciadas pelo driver. A função especificada deve ter sido atribuída ao usuário especificado para o driver. Se a função especificada não corresponder a nenhuma das funções atribuídas ao usuário, as sessões iniciadas pelo driver não terão nenhuma função inicialmente; entretanto, uma função pode sempre ser especificada a partir da sessão.

schema (Esquema)

Especifica o esquema padrão a ser usado nas sessões iniciadas pelo driver.

O padrão é public.

SecondaryRoles (Função)

Especifica as funções secundárias a serem utilizadas nas sessões iniciadas pelo driver. As funções já devem ser atribuídas ao usuário especificado para o driver. As funções secundárias também podem ser ativadas de uma sessão do usuário usando o comando USE SECONDARY ROLES.

Os valores possíveis incluem:

• Todas: Todas as funções concedidas ao usuário.

• Nenhum: Nenhuma função permitida (desabilita funções secundárias).

tracing (Rastreamento)

O nível de detalhe a ser registrado nos arquivos de rastreamento do driver:

• 0 = Desabilitar o rastreamento

• 1 = Rastreamento apenas de erros fatais

• 2 = Rastreamento de erros

• 3 = Rastreamento de avisos

• 4 = Rastreamento informativo

• 5 = Rastreamento de depuração

• 6 = Rastreamento detalhado

warehouse (Warehouse)

Especifica o warehouse padrão a ser utilizado para sessões iniciadas pelo driver.

Parâmetros adicionais de conexão¶

allowEmptyProxy

Especifica se serão permitidos valores vazios para os parâmetros de conexão proxy e sem_proxy, conforme descrito nas seções a seguir:

• Uso de parâmetros de conexão

• Uso de parâmetros de configuração

• Uso de variáveis de ambiente

Definir esse valor produz os seguintes efeitos:

• true: o driver trata valores de proxy vazios como configurações de proxy válidas e substitui quaisquer configurações ou variáveis de ambiente existentes.

• false: o driver ignora valores de proxy vazios e usa os parâmetros de configuração ou a variável de ambiente especificada.

O padrão é true.

application

Somente para uso por parceiro do Snowflake: especifica o nome de um aplicativo do parceiro para conexão por ODBC.

Este parâmetro também pode ser definido chamando a função SQLSetConnectAttr(). Para obter mais detalhes, consulte Comportamento específico do Snowflake da função SQLSetConnectAttr.

authenticator

Especifica o autenticador a ser usado para verificar as credenciais de login do usuário:

• snowflake (Padrão) para usar o autenticador interno do Snowflake.

• externalbrowser para usar seu navegador para autenticar com Okta, AD FS ou qualquer outro provedor de identidade compatível com SAML 2.0 (IdP) que tenha sido definido para sua conta.

  Nota

  O driver Snowflake ODBC não oferece suporte à autenticação externalbrowser usando o Microsoft Excel com MacOS.

• https://<nome_da_conta_okta>.okta.com (ou seja, o ponto de extremidade da URL para sua conta Okta) para autenticar através de Okta nativo (com suporte apenas se seu IdP for Okta).

• oauth para autenticar usando OAuth. Quando OAuth é especificado como o autenticador, você também deve definir o parâmetro token para especificar o token OAuth (consulte abaixo).

• username_password_mfa para autenticar com o armazenamento em cache de tokens MFA. Para obter mais detalhes, consulte Uso da autenticação multifator (neste tópico).

O padrão é snowflake.

No Windows, você pode usar a Ferramenta de administração da fonte de dados ODBC para definir este parâmetro.

Para obter mais informações sobre autenticação, consulte Gerenciamento/uso da autenticação federada e Clientes, drivers e conectores.

default_binary_size, . default_varchar_size

Especifica o tamanho padrão, em bytes, que o driver usa ao recuperar e converter valores das colunas BINARY ou VARCHAR de tamanhos indeterminados. Defina ao recuperar valores destes tipos de colunas.

Por padrão, o driver usa 8388608 (para colunas BINARY) e 16777216 (para colunas VARCHAR) como os tamanhos padrão ao alocar memória para recuperar o valor de uma coluna de tamanho indeterminado.

Para reduzir a quantidade de memória alocada para estes valores, você pode definir default_binary_size e default_varchar_size para o tamanho máximo dos valores nestes tipos de colunas.

Nota

A definição destes valores muda apenas o campo SQL_DESC_LENGTH no Descritor de linha de implementação (IRD) e os valores correspondentes retornados de SQLDescribeCol/SQLColAttribute/SQLColAttributes. O driver ainda retorna todos os dados mesmo quando o seu comprimento excede a configuração.

Por outro lado, um aplicativo pode alocar um buffer de dados com base no comprimento especificado nestes parâmetros que poderia truncar os dados devido ao espaço insuficiente no buffer. Como melhor prática, a Snowflake recomenda definir o tamanho padrão maior do que o tamanho máximo dos dados típicos (por exemplo, 4000 ou 8000 bytes) para reduzir significativamente o uso de memória dos valores padrão originais de 16777216/8388608 bytes e para minimizar a chance de truncamento de dados.

Observe que você também pode usar estas configurações para evitar o seguinte erro, que pode ocorrer ao usar o fornecedor Microsoft OLE DB (MSDASQL) com um banco de dados Snowflake:

Requested conversion is not supported
Cannot get the current row value of column

Copy

Você pode especificar esses parâmetros como parâmetros de configuração da conexão (por exemplo, no simba.snowflake.ini em macOS e Linux). Se for definido 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.

Estes parâmetros foram introduzidos na versão 2.23.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

A definição desse valor como parâmetro de conexão substitui o valor do parâmetro de configuração get_size_threshold correspondente.

login_timeout

Especifica quanto tempo, em segundos, esperar por uma resposta ao conectar-se ao serviço Snowflake antes de retornar um erro de falha no login.

O padrão é 300 (segundos).

network_timeout

Especifica quanto tempo, em segundos, esperar por uma resposta ao interagir com o serviço Snowflake antes de retornar um erro. Zero (0) indica que não há tempo limite de rede definido.

O padrão é 0 (segundos).

retryTimeout

Especifica quanto tempo, em segundos, esperar antes de retornar um erro para novas tentativas de HTTP de consultas com solicitações HTTP com falha. Zero (0) indica que nenhum tempo limite de nova tentativa está definido.

O padrão é 300 (segundos).

no_proxy

Especifica quais terminações de nome de host devem poder ignorar o servidor proxy (por exemplo, no_proxy=.amazonaws.com significa que o acesso Amazon S3 não precisa passar pelo proxy).

Este parâmetro não tem suporte para curingas. Cada valor especificado deve ser um dos seguintes:

• O fim de um nome de host (ou um nome de host completo), por exemplo:

  • .amazonaws.com

  • minhaorganização-minhaconta.snowflakecomputing.com

• Um endereço IP, por exemplo:

  • 192.196.1.15

Se for especificado mais de um valor, os valores devem ser separados por vírgulas; por exemplo:

no_proxy=localhost,.my_company.com,myorganization-myaccount.snowflakecomputing.com,192.168.1.15,192.168.1.16

Copy

Nota

Este parâmetro é aplicado ao processo. Se outra conexão compartilhar o mesmo processo, a configuração do proxy deverá ser idêntica, ou o comportamento não será previsível.

odbc_use_standard_timestamp_columnsize

Este parâmetro booleano afeta o tamanho da coluna (em caracteres) retornada para SQL_TYPE_TIMESTAMP. Quando este parâmetro é definido como verdadeiro, o driver retorna 29, seguindo o padrão ODBC. Quando este parâmetro é definido como false, o driver retorna 35, o que permite espaço para a diferença de fuso horário (por exemplo, “-08:00”).

Este valor pode ser definido não apenas através do arquivo odbc.ini (Linux ou macOS) ou do registro do Microsoft Windows, mas também por meio da cadeia de conexão.

O padrão é false.

passcode

Especifica a senha a ser usada para autenticação multifator.

Para obter mais informações sobre autenticação multifator, consulte Autenticação multifator (MFA).

passcodeInPassword

Especifica se o código da autenticação multifator está anexado à senha:

• on (ou true) especifica que o código está anexado.

• off (ou false) ou qualquer outro valor especifica que o código não está anexado.

O valor padrão é off.

proxy

Especifica a URL do servidor proxy no formato http://<nome de host>:<porta>/ ou <nome de host>:<número_da_porta> para que todas as comunicações do ODBC utilizem o servidor proxy.

Nota

Este parâmetro é aplicado ao processo. Se outra conexão compartilhar o mesmo processo, a configuração do proxy deverá ser idêntica, ou o comportamento não será previsível.

put_compresslv

Especifica a taxa de compressão que o driver ODBC usa ao transferir dados com o comando PUT. Este parâmetro substitui o nível padrão de compressão gzip. Se você não especificar put_compresslv o driver ODBC usará o nível de compressão padrão.

Os valores válidos são -1 a 9. O valor padrão é -1 e especifica o padrão Z_DEFAULT_COMPRESSION.

Os valores 0 até 9 especificam uma taxa de compressão personalizada. 0 faz com que o driver ODBC utilize uma taxa de compressão menor, e 9 usa uma taxa de compressão maior. O uso de uma taxa de compressão mais alta resulta em velocidades de transferência de dados mais lentas.

Você também pode especificar este parâmetro como um parâmetro de configuração (por exemplo, no simba.snowflake.ini em macOS e Linux). Se for definido 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.23.3 do driver ODBC.

put_fastfail

Se você estiver usando caracteres curinga com o comando PUT para carregar vários arquivos ao mesmo tempo e quiser que o driver pare de carregar os arquivos quando ocorrer um erro, defina este parâmetro como true.

O valor padrão é false, o que significa que se ocorrer um erro com um arquivo, o driver continuará carregando o resto dos arquivos.

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

A partir da versão 2.22.5 do driver ODBC, você também pode especificar este parâmetro como um parâmetro de configuração (por exemplo, no simba.snowflake.ini em macOS e Linux). Se for definido 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.

put_maxretries

Especifica o número de vezes que o driver deve tentar novamente o comando PUT se o comando falhar.

O valor padrão é 5.

O intervalo de valores válido para este parâmetro é 0 a 100. Se você especificar um valor fora deste intervalo, o driver usa o valor padrão de 5.

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

A partir da versão 2.22.5 do driver ODBC, você também pode especificar este parâmetro como um parâmetro de configuração (por exemplo, no simba.snowflake.ini em macOS e Linux). Se for definido 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.

put_tempdir

Especifica o diretório temporário a ser utilizado para solicitações de comando PUT. O driver usa este diretório temporário para criar arquivos compactados temporários antes de carregar esses arquivos no Snowflake.

Se este parâmetro não for definido, o driver cria e usa o diretório temporário /tmp/snowflakeTmp_username, onde username é o nome do usuário atual no sistema operacional.

Você também pode especificar este parâmetro como um parâmetro de configuração (por exemplo, no simba.snowflake.ini em macOS e Linux). Se for definido 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.23.1 do driver ODBC.

query_timeout

Especifica o tempo de espera, em segundos, para que uma consulta seja concluída antes de retornar um erro. Zero (0) indica que se deve esperar indefinidamente.

O padrão é 0 (segundos).

token=<cadeia de caracteres>

Especifica o token OAuth a ser usado para autenticação, onde <string> é o token. Este parâmetro só é necessário quando o parâmetro authenticator=oauth é definido.

O padrão é nenhum.

validateSessionParam

Especifica como responder quando qualquer um dos seguintes parâmetros de conexão de sessão é inválido:

• database
• schema
• warehouse

Os valores possíveis incluem:

• false (padrão): Conecta com sucesso, mas define os valores dos parâmetros database e schema como cadeias de caracteres vazias e define o parâmetro warehouse como seu valor padrão. Para obter mais informações sobre warehouses, consulte Uso de warehouses em sessões.

• true: Rejeita a conexão e gera um erro.

Uso de parâmetros de conexão¶

Para conectar através de um servidor proxy, adicione os seguintes parâmetros de conexão ao DSN:

• proxy

• no_proxy

Por exemplo:

[connection]
Description = SnowflakeDB
Driver      = SnowflakeDSIIDriver
Locale      = en-US
server      = myorganization-myaccount.snowflakecomputing.com
proxy       = http://proxyserver.company:80
no_proxy    = .amazonaws.com

Copy

Consulte parâmetros de conexão para descrições de parâmetros.

Uso de parâmetros de configuração¶

Para conectar através de um servidor proxy, adicione os seguintes parâmetros de configuração:

• Proxy

• NoProxy

Consulte Parâmetros de configuração para descrições de parâmetros.

Uso de variáveis de ambiente¶

Para conectar-se através de um servidor proxy, configure as seguintes variáveis de ambiente:

• http_proxy

• https_proxy

• no_proxy

Por exemplo:

• Linux ou macOS:

  export http_proxy=http://proxyserver.company.com:80
  export https_proxy=http://proxyserver.company.com:80
  

  Copy

  Se o servidor proxy exigir um nome de usuário e senha, inclua as credenciais, por exemplo:

  export https_proxy=http://username:password@proxyserver.company.com:80
  

  Copy

• Windows:

  set http_proxy=http://proxyserver.company.com:80
  set https_proxy=http://proxyserver.company.com:80
  

  Copy

  Se o servidor proxy exigir um nome de usuário e senha, inclua as credenciais, por exemplo:

  set https_proxy=http://username:password@proxyserver.company.com:80
  

  Copy

Opcionalmente, você pode definir no_proxy para ignorar o proxy em comunicações específicas (por exemplo, no_proxy=.amazonaws.com para ignorar o acesso Amazon S3).