Gestion des connexions¶

Création d’une connexion unique¶

Pour créer une connexion unique à Snowflake :

1. Appelez snowflake.createConnection pour créer un nouvel objet Connection et transmettez un objet JavaScript qui spécifie les options de connexion.

2. En utilisant l’objet Connection , appelez la méthode connect pour établir une connexion.

   Note

   Si vous attribuez à l’option authenticator la valeur EXTERNALBROWSER (afin d’utiliser SSO basé sur le navigateur) ou https://<nom_compte_okta>.okta.com (afin d’utiliser SSO natif d’Okta), appelez la méthode connectAsync plutôt que la méthode connect .

   Pour gérer les erreurs de connexion, transmettez une fonction de rappel qui a la signature suivante :

   function(err, conn)
   

   Copy

   où :

   • err est un objet JavaScript Error.

   • conn est l’objet Connection actuel.

   Si une erreur se produit pendant la connexion, la méthode connect transmet un objet Error à votre fonction de rappel. Vous pouvez utiliser cet objet dans votre fonction de rappel pour obtenir des détails sur l’erreur. Si vous avez besoin d’informations sur l’objet Connection actuel, vous pouvez utiliser l’argument conn transmis à votre fonction de rappel.

L’exemple suivant établit une connexion et utilise un mot de passe pour l’authentification. Pour utiliser d’autres méthodes d’authentification, voir Options d’authentification.

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

Lors de la création d’une connexion, vous pouvez définir les options de connexion comme décrit dans Référence des options.

Vérification qu’une connexion est prête à recevoir des requêtes¶

Avant de soumettre des requêtes à Snowflake, vous pouvez utiliser la méthode connection.isValidAsync() (à partir de la version 1.6.23) pour vous assurer que la connexion est établie et prête à exécuter des requêtes sur Snowflake. La méthode renvoie true si la connexion est prête ou false dans le cas contraire.

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

Création d’un pool de connexion¶

Au lieu de créer une connexion chaque fois que votre application cliente doit accéder à Snowflake, vous pouvez définir un cache de connexions Snowflake à réutiliser selon les besoins. Le pooling de connexions réduit généralement le temps de latence nécessaire pour établir une connexion. Toutefois, cela peut ralentir le basculement du client vers un DNS alternatif lorsqu’un problème de DNS se produit.

Pour créer un pool de connexion :

1. Appelez snowflake.createPool(connectionOptions, poolOptions) pour créer un nouvel objet ConnectionPool, et transmettez deux objets JavaScript qui spécifient les options de connexion et les options de mutualisation.

   Note

   Le pilote Snowflake Node.js utilise la bibliothèque open-source node-pool pour mettre en œuvre des pools de connexion. Pour plus d’informations sur les poolOptions prises en charge, consultez la description de l’argument opts dans la documentation de la bibliothèque node-pool.

2. Avec l’objet ConnectionPool, appelez la fonction use pour exécuter des instructions pour une seule connexion dans le pool de connexion.

   Pour gérer les erreurs de connexion, transmettez une fonction de rappel qui a la signature suivante :

   function(err, stmt, rows)
   

   Copy

   où :

   • err est un objet JavaScript Error.

   • stmt est un objet contenant des informations sur l’instruction SQL qui a été exécutée, y compris le texte littéral de l’instruction.

   • rows est un tableau contenant le « jeu de résultats » de l’instruction.

   
   

   Si une erreur se produit pendant l’exécution de l’instruction, la méthode connect transmet un objet Error à votre fonction de rappel. Vous pouvez utiliser cet objet dans votre fonction de rappel pour obtenir des détails sur l’erreur.

L’exemple suivant crée un pool de connexion qui prend en charge un maximum de dix connexions actives. Il utilise un mot de passe pour l’authentification. Pour utiliser d’autres méthodes d’authentification, voir Options d’authentification.

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

L’exemple suivant utilise la méthode connectionPool.use pour exécuter une instruction SQL en utilisant les connexions du pool. La méthode clientConnection.execute spécifie l’instruction SQL à exécuter et définit une fonction de rappel.

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

Lors de la création d’un pool de connexion, vous pouvez définir les options de connexion comme décrit dans Référence des options.

Connexion par l’intermédiaire d’un proxy¶

Vous pouvez vous connecter à Snowflake par l’intermédiaire d’un proxy, en fournissant les détails comme options de connexion lors de la création d’un objet Connection.

L’exemple suivant montre comment se connecter à un proxy en utilisant HTTP :

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

À partir de la version 1.15.0, le pilote Snowflake Node.js supporte entièrement les variables d’environnement HTTP_PROXY, HTTPS_PROXY et NO_PROXY en plus de leurs paramètres de connexion correspondants.

Par défaut, le nouveau paramètre de configuration globale useEnvProxy est défini sur vrai, ce qui permet la prise en charge des variables d’environnement.

Avec la possibilité de définir ces proxy à la fois dans l’objet Connexion et dans les variables d’environnement, le pilote utilise la hiérarchie suivante pour déterminer les valeurs à utiliser :

• Si un proxy est défini dans le Connexion, il a la priorité. Le pilote ignore les variables d’environnement HTTP_PROXY et HTTPS_PROXY.

• Si la connexion ne définit pas les valeurs du proxy, le pilote utilise les valeurs des variables d’environnement HTTP_PROXY et HTTPS_PROXY si elles sont définies.

• Si le paramètre de connexion useEnvProxy est défini sur faux, le pilote ignore les variables d’environnement HTTP_PROXY et HTTPS_PROXY si elles sont définies.

Si vous souhaitez désactiver la prise en charge des variables d’environnement de proxy, vous devez la désactiver dans la configuration globale, comme suit :

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

Connexion par le biais d’un proxy authentifié¶

Vous pouvez vous connecter à Snowflake par le biais d’un proxy authentifié en fournissant des identifiants de connexion d’authentification comme options de connexion lors de la création d’un objet Connection.

L’exemple suivant montre comment se connecter à un proxy authentifié en utilisant HTTP :

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

Pour se connecter à un proxy authentifié à l’aide de HTTPS, vous devez également fournir la propriété de connexion proxyProtocol comme indiqué ci-dessous :

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

Vérification de la connexion réseau à Snowflake avec SnowCD¶

Après avoir configuré votre pilote, vous pouvez évaluer et dépanner votre connectivité réseau à Snowflake en utilisant SnowCD.

Vous pouvez utiliser SnowCD pendant le processus de configuration initiale et à la demande à tout moment pour évaluer et dépanner votre connexion réseau à Snowflake.

OCSP (Online Certificate Status Protocol)¶

Lorsque le pilote se connecte, Snowflake envoie un certificat confirmant que la connexion est établie avec Snowflake plutôt qu’avec un hôte empruntant l’identité de Snowflake. Le pilote envoie ce certificat à un serveur OCSP (protocole de statut de certificat en ligne) pour vérifier que le certificat n’a pas été révoqué.

Si le pilote ne peut pas atteindre le serveur OCSP pour vérifier le certificat, il peut entrainer un comportement « Fail open » ou « Fail closed ».

Mettre fin à une connexion¶

Une connexion peut être interrompue en utilisant la méthode connection.destroy(). Ceci met fin immédiatement à la session associée à la connexion sans attendre la fin des instructions en cours d’exécution :

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

Copy