연결 관리하기

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.com (Okta를 통해 기본 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 쿼리를 제출하기 전에 (버전 1.6.23 이상에서) connection.isValidAsync() 메서드를 사용하여 연결이 설정되어 있고 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 드라이버는 오픈 소스 node-pool 라이브러리를 사용하여 연결 풀을 구현합니다. 지원되는 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

다음 예제에서는 connectionPool.use 메서드를 사용하여 풀의 연결을 사용해 SQL 문을 실행합니다. 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

연결 풀을 만들 때 옵션 참조 의 설명과 같이 연결 옵션을 설정할 수 있습니다.

유휴 연결 처리하기

노드 풀의 evictionRunIntervalMillis 옵션의 기본 설정이 0으로 설정되어 있으면 유휴 연결 제거 검사가 실행되지 않습니다. 실행 시간이 긴 애플리케이션이 있는 경우 이 동작으로 인해 종료된 연결이 연결 풀에 남아 있을 수 있으며, 드라이버가 이를 획득하고 이를 통해 Snowflake에 쿼리를 보내려고 할 때 오류가 발생할 수 있습니다.

장기 실행 애플리케이션에서 이 동작을 해결하려면 다음과 같은 방법을 고려할 수 있습니다.

  • 활성화된 제거기를 사용하여 Snowflake ConnectionPool 을 만듭니다.

    다음 예시와 같이 풀 옵션에 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분마다 제거기를 실행하여 1분 이상 유휴 상태인 연결을 모두 제거합니다. numTestsPerEvictionRun (기본값: 3)을 조정하여 각 제거 실행 중에 확인되는 리소스 수를 변경할 수도 있습니다.

    자세한 내용과 더 많은 옵션은 노드 풀 라이브러리 설명서 < https://github.com/coopernurse/node-pool/blob/master/README.md> 를 참조하십시오.

  • 풀에서 기존 연결 유지하기

    매시간보다 더 자주 연결을 유지해야 하는 경우 풀 옵션에 다음을 추가할 수 있습니다.

    • clientSessionKeepAlive: true

    • clientSessionKeepAliveHeartbeatFrequency: n, 여기서 n 은 900초(15분)~3,600초(1시간)입니다(기본값: 3600).

    다음 예는 15분마다 연결 유지 하트비트를 전송하여 클라이언트의 쿼리 등 다른 활동이 발생하지 않더라도 연결을 유지합니다.

    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

    풀링된 연결을 사용하지 않고 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_PROXY, HTTPS_PROXYNO_PROXY 환경 변수를 완벽하게 지원합니다.

기본적으로 새로운 useEnvProxy 전역 구성 설정은 환경 변수를 지원할 수 있는 true 로 설정되어 있습니다.

이러한 프록시를 Connection 오브젝트와 환경 변수 모두에서 설정할 수 있는 기능을 통해 드라이버는 다음 계층 구조를 사용하여 사용할 값을 결정합니다.

  • Connection 에 프록시가 정의되어 있으면 이 프록시가 우선합니다. 드라이버는 HTTP_PROXYHTTPS_PROXY 환경 변수를 무시합니다.

  • Connection에서 프록시 값을 설정하지 않은 경우 드라이버는 HTTP_PROXYHTTPS_PROXY 환경 변수가 정의된 경우 해당 변수의 값을 사용합니다.

  • useEnvProxy 연결 설정이 false 로 설정된 경우 드라이버는 HTTP_PROXYHTTPS_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 서버에 연결할 수 없는 경우 드라이버는 “페일 오픈” 또는 “페일 클로즈” 메시지를 표시할 수 있습니다.

연결 종료하기

연결은 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