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:
Rufen Sie
snowflake.createConnection
auf, um ein neuesConnection
-Objekt zu erstellen, und übergeben Sie ein JavaScript-Objekt, das die Verbindungsoptionen angibt.Rufen Sie mit dem
Connection
-Objekt die Methodeconnect
auf, um eine Verbindung herzustellen.Bemerkung
Wenn Sie die Option
authenticator
aufEXTERNALBROWSER
einstellen (um browserbasiertes SSO zu verwenden) oder aufhttps://<Name_des_Okta-Kontos>.okta.com
(um natives SSO über Okta zu verwenden), rufen Sie die MethodeconnectAsync
und nicht die Methodeconnect
auf.Um Verbindungsfehler zu behandeln, übergeben Sie eine Callback-Funktion, die folgende Signatur hat:
function(err, conn)
Wobei:
err
ist ein JavaScript-Error
-Objekt.conn
ist das aktuelleConnection
-Objekt.
Wenn bei der Verbindung ein Fehler auftritt, übergibt die Methode
connect
einError
-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 aktuelleConnection
-Objekt benötigen, können Sie das an Ihre Callback-Funktion übergebeneconn
-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');// Create a Connection object that we can use later to connect. var connection = snowflake.createConnection({ account: account, username: user, password: password, application: application });// 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(); } } );
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
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:
Rufen Sie
snowflake.createPool(connectionOptions, poolOptions)
auf, um ein neuesConnectionPool
-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 Argumentsopts
in der Dokumentation zur node-pool-Bibliothek.Rufen Sie mit dem Objekt
ConnectionPool
die Funktionuse
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)
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
einError
-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 } );
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'); }); } }); });
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, }, );
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
, wobein
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, }, );
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,
});
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 UmgebungsvariablenHTTP_PROXY
undHTTPS_PROXY
.Wenn die Verbindung keine Proxy-Werte festlegt, verwendet der Treiber die Werte in den Umgebungsvariablen
HTTP_PROXY
undHTTPS_PROXY
, sofern sie definiert sind.Wenn die Verbindungseinstellung
useEnvProxy
auffalse
festgelegt ist, ignoriert der Treiber die UmgebungsvariablenHTTP_PROXY
undHTTPS_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 });
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"
});
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"
});
Ü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()); } });