接続の管理

Snowflakeに対してステートメントを実行するには、最初に接続を確立する必要があります。Snowflake Node.jsドライバーを使用すると、次のように接続を確立できます。

重要

Snowflakeバージョン8.24から、ネットワーク管理者は、Snowflakeへのすべての接続に多要素認証 (MFA) を要求するオプションがあります。管理者がこの機能を有効にすることを決定した場合、Snowflakeへの接続時に MFA を使用するようにクライアントまたはドライバを設定する必要があります。詳細については、次をご参照ください:

単一の接続の作成

Snowflakeへの単一の接続を作成するには、

  1. snowflake.createConnection を呼び出して新しい Connection オブジェクトを作成し、 接続オプション を指定する JavaScript オブジェクトを渡します。

  2. Connection オブジェクトを使用して connect メソッドを呼び出し、接続を確立します。

    注釈

    authenticator オプションを EXTERNALBROWSERブラウザーベースの SSO を使用するため)、または https://<Oktaアカウント名>.okta.comOktaを介したネイティブ SSO を使用するため)に設定した場合、 connect メソッドではなく connectAsync メソッドを呼び出します。

    接続エラーを処理するには、次の署名を持つコールバック関数を渡します。

    function(err, conn)
    
    Copy

    条件:

    • err は、 JavaScript Error オブジェクトです。

    • conn は、現在の Connection オブジェクトです。

    接続中にエラーが発生した場合、 connect メソッドは Error オブジェクトをコールバック関数に渡します。コールバック関数でこのオブジェクトを使用すると、エラーの詳細を取得できます。現在の Connection オブジェクトに関する情報が必要な場合は、コールバック関数に渡された conn 引数を使用できます。

次の例では、接続を確立し、認証にパスワードを使用します。他の認証方法を使用するには、 認証オプション をご参照ください。

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

接続を作成するときは、 オプションのリファレンス の説明に従って接続オプションを設定できます。

接続がクエリを受信する準備ができていることの確認

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
Copy

接続プールの作成

クライアントアプリケーションがSnowflakeにアクセスする必要があるたびに接続を作成する代わりに、必要に応じて再利用するSnowflake接続のキャッシュを定義できます。接続プーリングは、通常、接続を確立するための遅延時間を短縮します。ただし、DNS の問題が発生すると、代替の DNS へのクライアントフェールオーバーが遅くなる可能性があります。

接続プールを作成するには、

  1. snowflake.createPool(connectionOptions, poolOptions) を呼び出して新しい ConnectionPool オブジェクトを作成し、 接続オプション とプールオプションを指定する2つの JavaScript オブジェクトを渡します。

    注釈

    Snowflake Node.jsドライバーは、接続プールを実装するためにオープンソースの ノード-プール ライブラリを使用します。サポートされている poolOptions については、 ノードプールライブラリのドキュメントopts 引数の説明をご参照ください。

  2. ConnectionPool オブジェクトを使用して、 use 関数を呼び出し、接続プール内にある単一の接続のステートメントを実行します。

    接続エラーを処理するには、次の署名を持つコールバック関数を渡します。

    function(err, stmt, rows)
    
    Copy

    条件:

    • err は、 JavaScript Error オブジェクトです。

    • 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
    }
);
  
Copy

次の例では、プール内の接続を使用して 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');
            });
        }
    });
});
Copy

接続プールを作成するときは、 オプションのリファレンス の説明に従って接続オプションを設定できます。

アイドル接続の処理

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,
        },
    );
    
    Copy

    この例では、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,
        },
    );
    
    Copy

    また、プール接続を使用せずに:codenowrap:clientSessionKeepAlive オプションを使用することもできます。

    セッション・キープアライブの詳細情報については、 Node.jsオプションリファレンス をご覧ください。

プロキシ経由での接続

Connection オブジェクトを作成する際に接続オプションとして詳細を指定することで、プロキシ経由で Snowflake に接続することができます。

次の例は、 HTTP を使ってプロキシに接続する方法を示しています。

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

バージョン 1.15.0 以降、Snowflake Node.js ドライバーは、対応する接続パラメーターに加えて、 HTTP_PROXYHTTPS_PROXY、および:codenowrap:NO_PROXY 環境変数を完全にサポートします。

デフォルトでは、新しい:codenowrap:useEnvProxy グローバル構成設定は:codenowrap:true にセットされ、環境変数のサポートが有効になります。

これらのプロキシを:codenowrap:Connection オブジェクトと環境変数の両方でセットできるため、ドライバーは以下の階層を使用して、使用する値を決定します。

  • Connection でプロキシが定義されている場合は、そちらが優先されます。ドライバーは:codenowrap:HTTP_PROXYHTTPS_PROXY 環境変数を無視します。

  • 接続がプロキシ値をセットしない場合、ドライバーは、環境変数 HTTP_PROXY および:codenowrap:HTTPS_PROXY が定義されていれば、その値を使用します。

  • useEnvProxy 接続設定が:codenowrap:false にセットされている場合、 HTTP_PROXY と:codenowrap:HTTPS_PROXY 環境変数が定義されていれば、ドライバーは無視します。

プロキシ環境変数のサポートを無効にしたい場合は、以下のようにグローバル構成で無効にする必要があります。

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

注釈

環境変数は 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"
});
Copy

HTTPS を使用して認証済みプロキシに接続するには、以下に示すように proxyProtocol 接続プロパティも指定する必要があります。

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

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());
  }
});
Copy