接続の管理¶
Snowflakeに対してステートメントを実行するには、最初に接続を確立する必要があります。Snowflake Node.jsドライバーを使用すると、次のように接続を確立できます。
重要
Snowflakeバージョン8.24から、ネットワーク管理者は、Snowflakeへのすべての接続に多要素認証 (MFA) を要求するオプションがあります。管理者がこの機能を有効にすることを決定した場合、Snowflakeへの接続時に MFA を使用するようにクライアントまたはドライバを設定する必要があります。詳細については、次をご参照ください:
単一の接続の作成¶
Snowflakeへの単一の接続を作成するには、
snowflake.createConnection
を呼び出して新しいConnection
オブジェクトを作成し、 接続オプション を指定する JavaScript オブジェクトを渡します。Connection
オブジェクトを使用してconnect
メソッドを呼び出し、接続を確立します。注釈
authenticator
オプションをEXTERNALBROWSER
(ブラウザーベースの SSO を使用するため)、またはhttps://<Oktaアカウント名>.okta.com
(Oktaを介したネイティブ SSO を使用するため)に設定した場合、connect
メソッドではなくconnectAsync
メソッドを呼び出します。接続エラーを処理するには、次の署名を持つコールバック関数を渡します。
function(err, conn)
条件:
err
は、 JavaScriptError
オブジェクトです。conn
は、現在のConnection
オブジェクトです。
接続中にエラーが発生した場合、
connect
メソッドはError
オブジェクトをコールバック関数に渡します。コールバック関数でこのオブジェクトを使用すると、エラーの詳細を取得できます。現在のConnection
オブジェクトに関する情報が必要な場合は、コールバック関数に渡されたconn
引数を使用できます。
次の例では、接続を確立し、認証にパスワードを使用します。他の認証方法を使用するには、 認証オプション をご参照ください。
// 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(); } } );
接続を作成するときは、 オプションのリファレンス の説明に従って接続オプションを設定できます。
接続がクエリを受信する準備ができていることの確認¶
Snowflakeクエリを送信する前に、 connection.isValidAsync()
メソッド(バージョン 1.6.23以降)を使用して、接続が確立され、Snowflakeでリクエストを実行する準備ができていることを確認できます。このメソッドは、接続の準備ができている場合には true
を返し、そうでない場合には 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
接続プールの作成¶
クライアントアプリケーションがSnowflakeにアクセスする必要があるたびに接続を作成する代わりに、必要に応じて再利用するSnowflake接続のキャッシュを定義できます。接続プーリングは、通常、接続を確立するための遅延時間を短縮します。ただし、DNS の問題が発生すると、代替の DNS へのクライアントフェールオーバーが遅くなる可能性があります。
接続プールを作成するには、
snowflake.createPool(connectionOptions, poolOptions)
を呼び出して新しいConnectionPool
オブジェクトを作成し、 接続オプション とプールオプションを指定する2つの JavaScript オブジェクトを渡します。注釈
Snowflake Node.jsドライバーは、接続プールを実装するためにオープンソースの ノード-プール ライブラリを使用します。サポートされている
poolOptions
については、 ノードプールライブラリのドキュメント のopts
引数の説明をご参照ください。ConnectionPool
オブジェクトを使用して、use
関数を呼び出し、接続プール内にある単一の接続のステートメントを実行します。接続エラーを処理するには、次の署名を持つコールバック関数を渡します。
function(err, stmt, rows)
条件:
err
は、 JavaScriptError
オブジェクトです。stmt
は、ステートメントのリテラルテキストを含む、実行された SQL ステートメントに関する情報を持つオブジェクトです。rows
は、ステートメントの「結果セット」を含む配列です。
ステートメントの実行中にエラーが発生した場合、
connect
メソッドはError
オブジェクトをコールバック関数に渡します。コールバック関数でこのオブジェクトを使用すると、エラーの詳細を取得できます。
次の例では、最大10個のアクティブな接続をサポートする接続プールを作成します。認証にパスワードを使用します。他の認証方法を使用するには、 認証オプション をご参照ください。
// 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 } );
次の例では、プール内の接続を使用して SQL ステートメントを実行するために、 connectionPool.use
メソッドを使用します。 clientConnection.execute
メソッドは、実行する SQL ステートメントを指定し、コールバック関数を定義します。
// 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'); }); } }); });
接続プールを作成するときは、 オプションのリファレンス の説明に従って接続オプションを設定できます。
アイドル接続の処理¶
node-poolの:codenowrap:evictionRunIntervalMillis
オプションのデフォルト設定が0に設定されている場合、アイドル接続の除去チェックは実行されません。アプリケーションの実行時間が長い場合、この動作によって終了した接続が接続プールに残ってしまい、ドライバーがそれを取得してSnowflakeにクエリを送信しようとするとエラーが発生します。
長時間稼動するアプリケーションでこの動作に対処するには、次のような方法が考えられます。
Evictorが有効なSnowflake
ConnectionPool
を作成します。次の例に示すように、プール・オプションに:codenowrap:
evictionRunIntervalMillis
オプションを追加することができます。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, }, );
この例では、1分ごとにevictorを実行し、1分以上アイドル状態の接続をすべて退去させます。また、
numTestsPerEvictionRun
(デフォルト: 3)を微調整して、各除去実行時にチェックするリソースの数を変更することもできます。詳細やその他のオプションについては、ノードプールライブラリ
ドキュメント < https://github.com/coopernurse/node-pool/blob/master/README.md>
をご参照ください。既存の接続をプールで維持
1時間ごとよりも頻繁に接続を維持する必要がある場合は、プール・オプションに以下を追加できます。
clientSessionKeepAlive: true
clientSessionKeepAliveHeartbeatFrequency: n
,n
は900 (15m)秒から3600 (1h)秒の間(デフォルト:3600)。
以下の例では、クライアントからのクエリなど他のアクティビティが発生しなくても接続を維持するために、15分ごとにkeep-aliveハートビートを送信しています。
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, }, );
また、プール接続を使用せずに:codenowrap:
clientSessionKeepAlive
オプションを使用することもできます。セッション・キープアライブの詳細情報については、 Node.jsオプションリファレンス をご覧ください。
プロキシ経由での接続¶
Connection
オブジェクトを作成する際に接続オプションとして詳細を指定することで、プロキシ経由で Snowflake に接続することができます。
次の例は、 HTTP を使ってプロキシに接続する方法を示しています。
var connection = snowflake.createConnection({
account: "account",
username: "user",
password: "password",
proxyHost: "localhost",
proxyPort: 3128,
});
バージョン 1.15.0 以降、Snowflake Node.js ドライバーは、対応する接続パラメーターに加えて、 HTTP_PROXY
HTTPS_PROXY
、および:codenowrap:NO_PROXY
環境変数を完全にサポートします。
デフォルトでは、新しい:codenowrap:useEnvProxy
グローバル構成設定は:codenowrap:true
にセットされ、環境変数のサポートが有効になります。
これらのプロキシを:codenowrap:Connection
オブジェクトと環境変数の両方でセットできるため、ドライバーは以下の階層を使用して、使用する値を決定します。
Connection
でプロキシが定義されている場合は、そちらが優先されます。ドライバーは:codenowrap:HTTP_PROXY
とHTTPS_PROXY
環境変数を無視します。接続がプロキシ値をセットしない場合、ドライバーは、環境変数
HTTP_PROXY
および:codenowrap:HTTPS_PROXY
が定義されていれば、その値を使用します。useEnvProxy
接続設定が:codenowrap:false
にセットされている場合、HTTP_PROXY
と:codenowrap:HTTPS_PROXY
環境変数が定義されていれば、ドライバーは無視します。
プロキシ環境変数のサポートを無効にしたい場合は、以下のようにグローバル構成で無効にする必要があります。
const snowflake=require('snowflake-sdk');
snowflake.configure({ useEnvProxy: false });
注釈
環境変数は Linux と MacOS では大文字と小文字が区別されます。Windowsでは違います。
同じ環境変数に対して、小文字 (
https_proxy
) と大文字 (HTTPS_PROXY
) の両方の変数が定義されている場合、ドライバーは小文字 (https_proxy
) の値を使用します。大文字と小文字 (
HTTPS_PROXY
) のバリアントだけが存在する場合、ドライバーは大文字の変数の値を使用します。
認証されたプロキシを介した接続¶
Connection
オブジェクトを作成するときに、接続オプションとして認証情報を提供することにより、認証されたプロキシを介してSnowflakeに接続できます。
注釈
Snowflake Node.jsドライバーのバージョン1.6.4以降、認証済みプロキシサーバーを介した接続がサポートされています。
次の例は、HTTP を使用して認証されたプロキシに接続する方法を示しています。
var connection = snowflake.createConnection({
account: "account",
username: "user",
password: "password",
proxyHost: "localhost",
proxyPort: 3128,
proxyUser: "myname",
proxyPassword: "mypass"
});
HTTPS を使用して認証済みプロキシに接続するには、以下に示すように proxyProtocol
接続プロパティも指定する必要があります。
var connection = snowflake.createConnection({
account: "account",
username: "user",
password: "password",
proxyHost: "localhost",
proxyPort: 3128,
proxyUser: "myname",
proxyPassword: "mypass",
proxyProtocol: "https"
});
SnowCD を使用したSnowflakeへのネットワーク接続の確認¶
ドライバーを設定したら、 SnowCD を使用して、Snowflakeへのネットワーク接続を評価およびトラブルシューティングできます。
初期設定プロセス中にオンデマンドで SnowCD をいつでも使用して、Snowflakeへのネットワーク接続を評価およびトラブルシューティングできます。
OCSP(オンライン証明書状態プロトコル)¶
ドライバーが接続すると、Snowflakeは証明書を送信して、Snowflakeを偽装しているホストではなく、Snowflakeへの接続であることを確認します。ドライバーはその証明書を OCSP (オンライン証明書状態プロトコル)サーバーに送信し、証明書が失効していないことを確認します。
ドライバーが証明書を確認するために OCSP サーバーに到達できない場合、ドライバーは "fail open" or "fail closed" できます。
接続の終了¶
connection.destroy()
メソッドを呼び出すことにより、接続を終了できます。これにより、実行中のステートメントの完了を待たずに、接続に関連付けられたセッションが直ちに終了します。
connection.destroy(function(err, conn) { if (err) { console.error('Unable to disconnect: ' + err.message); } else { console.log('Disconnected connection with id: ' + connection.getId()); } });