Gerenciamento de conexões¶

Criação de uma única conexão¶

Para criar uma única conexão com o Snowflake:

1. Chame snowflake.createConnection para criar um novo objeto Connection, e passe um objeto JavaScript que especifica as opções de conexão.

2. Usando o objeto Connection, chame o método connect para estabelecer uma conexão.

   Nota

   Se você definir a opção authenticator para EXTERNALBROWSER (para usar SSO baseado em navegador) ou https://<nome_conta_okta>.okta.com (para usar SSO nativo através do Okta), chame o método connectAsync, em vez do método connect.

   Para lidar com erros de conexão, passe uma função de retorno de chamada que tenha a seguinte assinatura

   function(err, conn)
   

   Copy

   onde:

   • err é um objeto JavaScript Error.

   • conn é o objeto atual Connection.

   Se ocorrer um erro durante a conexão, o método connect passa um objeto Error para sua função de retorno de chamada. Você pode usar este objeto em sua função de retorno de chamada para obter detalhes sobre o erro. Se você precisar de informações sobre o objeto Connection atual, você pode usar o argumento conn passado para sua função de retorno de chamada.

O exemplo a seguir estabelece uma conexão e utiliza uma senha para autenticação. Para utilizar outros métodos de autenticação, consulte Opções de autenticação.

// Load the Snowflake Node.js driver.
var snowflake = require('snowflake-sdk');

Copy

// Create a Connection object that we can use later to connect.
var connection = snowflake.createConnection({
    account: account,
    username: user,
    password: password,
    application: application
  });

Copy

// Try to connect to Snowflake, and check whether the connection was successful.
connection.connect( 
    function(err, conn) {
        if (err) {
            console.error('Unable to connect: ' + err.message);
            } 
        else {
            console.log('Successfully connected to Snowflake.');
            // Optional: store the connection ID.
            connection_ID = conn.getId();
            }
    }
);

Copy

Ao criar uma conexão, você pode definir as opções de conexão como descrito em Referência de opções.

Como verificar se uma conexão está pronta para receber consultas¶

Antes de enviar consultas do Snowflake, você pode usar o método connection.isValidAsync() (na versão 1.6.23 e posterior) para garantir que a conexão esteja ativa e pronta para executar solicitações no Snowflake. O método retorna true se a conexão estiver pronta ou false, caso contrário.

// Create a Connection object and connect to Snowflake
// ..

// Verify if connection is still valid for sending queries over it
const isConnectionValid = await connection.isValidAsync();

// Do further actions based on the value (true or false) of isConnectionValid

Criação de um pool de conexões¶

Em vez de criar uma conexão cada vez que seu aplicativo cliente precisar acessar o Snowflake, você pode definir um cache de conexões Snowflake para reutilização conforme necessário. O pool de conexões geralmente reduz o tempo de espera para fazer uma conexão. Entretanto, pode retardar o failover do cliente para um DNS alternativo quando ocorre um problema de DNS.

Para criar um pool de conexões:

1. Chame snowflake.createPool(connectionOptions, poolOptions) para criar um novo objeto ConnectionPool e passe dois objetos JavaScript que especificam as opções de conexão e as opções de pool.

   Nota

   The Snowflake Node.js Driver uses the open-source node-pool library for implementing connection pools. For information about the supported poolOptions, see the description of the opts argument in the node-pool library documentation.

2. Com o objeto ConnectionPool, chame a função use para executar instruções para uma única conexão no pool de conexões.

   Para lidar com erros de conexão, passe uma função de retorno de chamada que tenha a seguinte assinatura

   function(err, stmt, rows)
   

   Copy

   onde:

   • err é um objeto JavaScript Error.

   • stmt é um objeto com informações sobre a instrução SQL que foi executada, incluindo o texto literal da instrução.

   • rows é uma matriz contendo o “conjunto de resultados” da instrução.

   
   

   Se ocorrer um erro durante a execução da instrução, o método connect passa um objeto Error para sua função de retorno de chamada. Você pode usar este objeto em sua função de retorno de chamada para obter detalhes sobre o erro.

O exemplo seguinte cria um pool de conexões que suporta um máximo de dez conexões ativas. Ele usa uma senha para autenticação. Para utilizar outros métodos de autenticação, consulte Opções de autenticação.

// Create the connection pool instance
const connectionPool = snowflake.createPool(
    // connection options
    {
      account: account,
      username: user,
      password: password
    },
    // pool options
    {
      max: 10, // specifies the maximum number of connections in the pool
      min: 0   // specifies the minimum number of connections in the pool
    }
);
  

Copy

O exemplo seguinte usa o método connectionPool.use para executar uma instrução SQL usando as conexões no pool. O método clientConnection.execute especifica a instrução SQL a executar e define uma função de chamada de retorno.

// Use the connection pool and execute a statement
connectionPool.use(async (clientConnection) =>
{
    const statement = await clientConnection.execute({
        sqlText: 'select 1;',
        complete: function (err, stmt, rows)
        {
            var stream = stmt.streamRows();
            stream.on('data', function (row)
            {
                console.log(row);
            });
            stream.on('end', function (row)
            {
                console.log('All rows consumed');
            });
        }
    });
});

Copy

Ao criar um pool de conexões, você pode definir as opções de conexão como descrito em Referência de opções.

Conexão por meio de um proxy¶

Você pode se conectar ao Snowflake por meio de um proxy, fornecendo os detalhes como opções de conexão ao criar um objeto Connection.

O exemplo a seguir mostra como se conectar a um proxy usando HTTP:

var connection = snowflake.createConnection({
      account: "account",
      username: "user",
      password: "password",
      proxyHost: "localhost",
      proxyPort: 3128,
});

A partir da versão 1.15.0, o driver Snowflake Node.js oferece suporte total às variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY, além dos parâmetros de conexão correspondentes.

Por padrão, a nova definição de configuração global useEnvProxy é definida como true, o que permite o suporte às variáveis de ambiente.

Com a capacidade de definir esses proxies no objeto Connection e nas variáveis de ambiente, o driver usa a seguinte hierarquia para determinar quais valores usar:

• Se um proxy for definido na conexão :codenowrap:``, ele terá precedência. O driver ignora as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY.

• Se a conexão não definir os valores de proxy, o driver usará os valores das variáveis de ambiente HTTP_PROXY e HTTPS_PROXY, se estiverem definidas.

• Se a configuração de conexão useEnvProxy for definida como false, o driver ignorará as variáveis de ambiente HTTP_PROXY e HTTPS_PROXY se elas estiverem definidas.

Se quiser desativar o suporte a variáveis de ambiente de proxy, você deve desativá-lo na configuração global, como segue:

const snowflake=require('snowflake-sdk');
snowflake.configure({ useEnvProxy: false });

Conexão por um proxy autenticado¶

Você pode se conectar ao Snowflake através de um proxy autenticado, fornecendo credenciais de autenticação como opções de conexão ao criar um objeto Connection.

O exemplo seguinte mostra como se conectar a um proxy autenticado usando HTTP:

var connection = snowflake.createConnection({
      account: "account",
      username: "user",
      password: "password",
      proxyHost: "localhost",
      proxyPort: 3128,
      proxyUser: "myname",
      proxyPassword: "mypass"
});

Para conectar-se a um proxy autenticado usando HTTPS você também deve fornecer a propriedade de conexão proxyProtocol, como mostrado abaixo:

var connection = snowflake.createConnection({
      account: "account",
      username: "user",
      password: "password",
      proxyHost: "localhost",
      proxyPort: 3128,
      proxyUser: "myname",
      proxyPassword: "mypass",
      proxyProtocol: "https"
});

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.

OCSP (online certificate status protocol)¶

Quando o driver se conecta, o Snowflake envia um certificado para confirmar que a conexão é com o Snowflake e não com um host que está se fazendo passar pelo Snowflake. O driver envia esse certificado para um servidor OCSP (Online Certificate Status Protocol) para verificar se o certificado não foi revogado.

Se o driver não puder chegar ao servidor OCSP para verificar o certificado, ele pode usar “fail-open” ou “fail-close”.

Encerramento de uma conexão¶

Uma conexão pode ser encerrada chamando o método connection.destroy(). Isto encerra imediatamente a sessão associada à conexão sem esperar que as instruções em execução sejam concluídas:

connection.destroy(function(err, conn) {
  if (err) {
    console.error('Unable to disconnect: ' + err.message);
  } else {
    console.log('Disconnected connection with id: ' + connection.getId());
  }
});

Copy