Verwalten von Verbindungen

Um Anweisungen in Snowflake auszuführen, müssen Sie zunächst eine Verbindung herstellen. Mit dem Snowflake-Node.js-Treiber können Sie Verbindungen wie folgt einrichten:

Wichtig

Ab Snowflake Version 8.24 haben Administratoren im Netzwerk die Möglichkeit, eine mehrstufige Authentifizierung (MFA) für alle Verbindungen zu Snowflake zu verlangen. Wenn Ihr Administrator beschließt, dieses Feature zu aktivieren, müssen Sie Ihren Client oder Treiber so konfigurieren, dass er bei der Verbindung mit Snowflake MFA verwendet. Weitere Informationen finden Sie in den folgenden Ressourcen:

Erstellen einer einzelnen Verbindung

So erstellen Sie eine einzelne Verbindung zu Snowflake:

  1. Rufen Sie snowflake.createConnection auf, um ein neues Connection-Objekt zu erstellen, und übergeben Sie ein JavaScript-Objekt, das die Verbindungsoptionen angibt.

  2. Rufen Sie mit dem Connection-Objekt die Methode connect auf, um eine Verbindung herzustellen.

    Bemerkung

    Wenn Sie die Option authenticator auf EXTERNALBROWSER einstellen (um browserbasiertes SSO zu verwenden) oder auf https://<Name_des_Okta-Kontos>.okta.com (um natives SSO über Okta zu verwenden), rufen Sie die Methode connectAsync und nicht die Methode connect auf.

    Um Verbindungsfehler zu behandeln, übergeben Sie eine Callback-Funktion, die folgende Signatur hat:

    function(err, conn)
    
    Copy

    Wobei:

    • err ist ein JavaScript-Error-Objekt.

    • conn ist das aktuelle Connection-Objekt.

    Wenn bei der Verbindung ein Fehler auftritt, übergibt die Methode connect ein Error-Objekt an Ihre Callback-Funktion. Sie können dieses Objekt in Ihrer Callback-Funktion verwenden, um Details über den Fehler abzurufen. Wenn Sie Informationen über das aktuelle Connection-Objekt benötigen, können Sie das an Ihre Callback-Funktion übergebene conn-Argument verwenden.

Das folgende Beispiel baut eine Verbindung auf und verwendet ein Kennwort zur Authentifizierung. Informationen zu weiteren Authentifizierungsmethoden finden Sie unter Authentifizierungsoptionen.

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

Beim Erstellen einer Verbindung können Sie die Verbindungsoptionen wie unter Optionsübersicht beschrieben einstellen.

Überprüfen, ob Verbindung abfragebereit ist

Bevor Sie Abfragen an Snowflake übermitteln, können Sie die Methode connection.isValidAsync() (ab Version 1.6.23) verwenden, um sicherzustellen, dass die Verbindung hergestellt und bereit ist, Anforderung an Snowflake auszuführen. Die Methode gibt true zurück, wenn die Verbindung bereit ist, andernfalls false.

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

Erstellen eines Verbindungspools

Anstatt jedes Mal eine neue Verbindung zu erstellen, wenn Ihre Clientanwendung auf Snowflake zugreifen muss, können Sie einen Cache für Snowflake-Verbindungen definieren, der bei Bedarf wiederverwendet werden kann. Verbindungspooling verringert normalerweise die Verzögerungszeit beim Herstellen einer Verbindung. Es kann jedoch das Client-Failover auf ein alternatives DNS verlangsamen, wenn ein DNS-Problem auftritt.

So erstellen Sie einen Verbindungspool:

  1. Rufen Sie snowflake.createPool(connectionOptions, poolOptions) auf, um ein neues ConnectionPool-Objekt zu erstellen, und übergeben Sie zwei JavaScript-Objekte, die die Verbindungsoptionen und die Pooloptionen angeben.

    Bemerkung

    Der Snowflake-Node.js-Treiber verwendet die Open-Source-Bibliothek node-pool zur Implementierung von Verbindungspools. Weitere Informationen zu den unterstützten poolOptions finden Sie in der Beschreibung des Arguments opts in der Dokumentation zur node-pool-Bibliothek.

  2. Rufen Sie mit dem Objekt ConnectionPool die Funktion use auf, um Anweisungen für eine einzelne Verbindung im Verbindungspool auszuführen.

    Um Verbindungsfehler zu behandeln, übergeben Sie eine Callback-Funktion, die folgende Signatur hat:

    function(err, stmt, rows)
    
    Copy

    Wobei:

    • err ist ein JavaScript-Error-Objekt.

    • stmt ist ein Objekt mit Informationen zu der ausgeführte SQL-Anweisung, einschließlich des wörtlichen Textes der Anweisung.

    • rows ist ein Array, das das „Resultset“ der Anweisung enthält.


    Wenn beim Ausführen der Anweisung ein Fehler auftritt, übergibt die Methode connect ein Error-Objekt an Ihre Callback-Funktion. Sie können dieses Objekt in Ihrer Callback-Funktion verwenden, um Details über den Fehler abzurufen.

Im folgenden Beispiel wird ein Verbindungspool erstellt, der maximal zehn aktive Verbindungen unterstützt. Zur Authentifizierung wird ein Kennwort verwendet. Informationen zu weiteren Authentifizierungsmethoden finden Sie unter Authentifizierungsoptionen.

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

Im folgenden Beispiel wird die Methode connectionPool.use verwendet, um eine SQL-Anweisung unter Verwendung der Verbindungen im Pool auszuführen. Die Methode clientConnection.execute gibt die auszuführende SQL-Anweisung an und definiert eine Callback-Funktion.

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

Beim Erstellen eines Verbindungspools können Sie die Verbindungsoptionen wie unter Optionsübersicht beschrieben einstellen.

Umgang mit inaktiven Verbindungen

Wenn die Standardeinstellung der Option evictionRunIntervalMillis des Node-Pools auf 0 eingestellt ist, werden keine Überprüfungen zur Entfernung inaktiver Verbindungen durchgeführt. Bei Anwendungen mit längerer Laufzeit kann dieses Verhalten dazu führen, dass abgebrochene Verbindungen im Verbindungspool verbleiben. Wenn der Treiber diese Verbindungen abruft und versucht, eine Abfrage über sie an Snowflake zu senden, führt dies zu einem Fehler.

Um dieses Verhalten in einer Anwendung mit längerer Laufzeit zu vermeiden, können Sie die folgenden Möglichkeiten in Betracht ziehen:

  • Erstellen der Snowflake ConnectionPool mit einem aktivierten Evictor.

    Sie können die Option evictionRunIntervalMillis zu den Pool-Optionen hinzufügen, wie im folgenden Beispiel gezeigt:

    const pool = snowflake.createPool(
        {
          account: account,
          username: username,
    
          //rest of the connection options
    
        },
        {
          evictionRunIntervalMillis: 60000 // default = 0, off
          idleTimeoutMillis: 60000, // default = 30000
          max: 2,
          min: 0,
        },
    );
    
    Copy

    In diesem Beispiel wird der Evictor jede Minute ausgeführt und alle Verbindungen, die länger als eine Minute inaktiv sind, werden entfernt. Sie können auch numTestsPerEvictionRun (Standard: 3) einstellen, um die Anzahl der Ressourcen zu ändern, die bei jedem Bereinigungslauf überprüft werden.

    Weitere Informationen und Optionen finden Sie in der Dokumentation der Node-Pool-Bibliothek < https://github.com/coopernurse/node-pool/blob/master/README.md>.

  • Bestehende Verbindungen im Pool aufrechterhalten

    Wenn Sie eine Verbindung häufiger als einmal pro Stunde aufrechterhalten müssen, können Sie Folgendes zu den Pool-Optionen hinzufügen:

    • clientSessionKeepAlive: true

    • clientSessionKeepAliveHeartbeatFrequency: n, wobei n zwischen 900 (15 m) und 3600 (1 h) Sekunden liegt (Standard: 3600).

    Das folgende Beispiel sendet alle 15 Minuten einen Keep-Alive-Heartbeat, um die Verbindung aufrechtzuerhalten, auch wenn keine andere Aktivität, wie z. B. eine Abfrage von einem Client, stattfindet.

    const pool = snowflake.createPool(
        {
          account: account,
          username: username,
    
          // rest of the connection options
    
          clientSessionKeepAlive: true,  // default = false
          clientSessionKeepAliveHeartbeatFrequency: 900 // default = 3600
        },
        {
          max: 2,
          min: 0,
        },
    );
    
    Copy

    Sie können auch die Option clientSessionKeepAlive verwenden, ohne gepoolte Verbindungen zu nutzen.

    Weitere Informationen zu Session-Keep-Alive, siehe Übersicht der Node.js-Optionen.

Verbindung über einen Proxy

Sie können sich über einen Proxy mit Snowflake verbinden, indem Sie die Details als Verbindungsoptionen beim Erstellen eines Connection-Objekts angeben.

Im folgenden Beispiel wird gezeigt, wie Sie über HTTP eine Verbindung zu einem Proxy herstellen:

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

Ab Version 1.15.0 unterstützt der Snowflake Node.js-Treiber zusätzlich zu den entsprechenden Verbindungsparametern vollständig die Umgebungsvariablen HTTP_PROXY, HTTPS_PROXY und NO_PROXY.

Standardmäßig ist die neue globale Konfigurationseinstellung useEnvProxy auf true festgelegt, wodurch die Unterstützung für die Umgebungsvariablen aktiviert wird.

Da diese Proxys sowohl im Connection-Objekt als auch in den Umgebungsvariablen festgelegt werden können, verwendet der Treiber die folgende Hierarchie, um zu bestimmen, welche Werte genutzt werden:

  • Wenn ein Proxy in der Connection definiert ist, hat er Vorrang. Der Treiber ignoriert die Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY.

  • Wenn die Verbindung keine Proxy-Werte festlegt, verwendet der Treiber die Werte in den Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY, sofern sie definiert sind.

  • Wenn die Verbindungseinstellung useEnvProxy auf false festgelegt ist, ignoriert der Treiber die Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY, falls sie definiert sind.

Wenn Sie die Unterstützung für Proxy-Umgebungsvariablen deaktivieren möchten, müssen Sie dies in der globalen Konfiguration wie folgt tun:

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

Bemerkung

Bei den Umgebungsvariablen wird unter Linux und MacOS die Groß-/Kleinschreibung beachtet. Unter Windows ist dies nicht der Fall.

  • Wenn sowohl die Variante mit Kleinbuchstaben (https_proxy) als auch die Variante mit Großbuchstaben (HTTPS_PROXY) für dieselbe Umgebungsvariable definiert sind, verwendet der Treiber den Wert der Variable mit Kleinbuchstaben (https_proxy).

  • Wenn nur die Variante mit Großbuchstaben (HTTPS_PROXY) vorhanden ist, verwendet der Treiber den Wert der Variablen mit Großbuchstaben.

Verbinden über einen authentifizierten Proxy

Sie können eine Verbindung zu Snowflake über einen authentifizierten Proxy herstellen, indem Sie beim Erstellen eines Connection-Objekts Authentifizierungsdaten als Verbindungsoptionen angeben.

Bemerkung

Die Verbindung über einen authentifizierten Proxyserver wird ab Version 1.6.4 des Snowflake-Node.js-Treibers unterstützt.

Das folgende Beispiel zeigt, wie eine Verbindung zu einem authentifizierten Proxy mit HTTP hergestellt wird:

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

Um eine Verbindung zu einem authentifizierten Proxy mit HTTPS herzustellen, müssen Sie auch die Verbindungseigenschaft proxyProtocol angeben, wie unten gezeigt:

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

Überprüfen der Netzwerkverbindung zu Snowflake mit SnowCD

Nach der Konfiguration des Treibers können Sie die Netzwerkkonnektivität zu Snowflake mit SnowCD testen und Probleme beheben.

Sie können während der Erstkonfiguration und bei Bedarf jederzeit SnowCD verwenden, um Ihre Netzwerkverbindung zu Snowflake zu testen und Probleme zu beheben.

OCSP (Online Certificate Status Protocol)

Wenn der Treiber eine Verbindung herstellt, sendet Snowflake ein Zertifikat, um zu bestätigen, dass die Verbindung zu Snowflake und nicht zu einem Host besteht, der sich als Snowflake ausgibt. Der Treiber sendet dieses Zertifikat an einen OCSP (Online Certificate Status Protocol)-Server, um zu überprüfen, ob das Zertifikat widerrufen wurde.

Wenn der Treiber den OCSP-Server nicht erreichen kann, um das Zertifikat zu überprüfen, kann beim Treiber „Fail-open“ oder „Fail-close“ auftreten.

Beenden einer Verbindung

Eine Verbindung kann durch Aufruf der Methode connection.destroy() beendet werden. Dadurch wird die Verbindung zur Sitzung sofort beendet, ohne darauf zu warten, dass die in Ausführung befindlichen Anweisungen abgeschlossen werden:

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