Node.js 드라이버 사용하기¶

단일 연결 만들기¶

Snowflake에 대한 단일 연결을 만들려면:

1. snowflake.createConnection 을 호출하여 새 Connection 오브젝트를 생성하고 연결 옵션 을 지정하는 JavaScript 오브젝트를 전달합니다.

2. Connection 오브젝트를 사용하여 connect 메서드를 호출해 연결합니다.

   참고

   authenticator 옵션을 EXTERNALBROWSER (브라우저 기반 SSO 를 사용하기 위해) 또는 https://<okta_계정_이름>.okta.com (Okta를 통해 기본 SSO 를 사용하기 위해)으로 설정한 경우에는 connect 메서드가 아닌 connectAsync 메서드를 호출합니다.

   연결 오류를 처리하려면 다음 서명이 있는 콜백 함수를 전달합니다.

   function(err, conn)
   

   여기서:

   • err 은 JavaScript Error 오브젝트입니다.

   • 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에 액세스해야 할 때마다 연결을 생성하는 대신, 필요에 따라 재사용할 수 있는 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)
   

   여기서:

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

다음 예제에서는 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');
            });
        }
    });
});

연결 풀을 생성 때 연결 옵션 설정 의 설명과 같이 연결 옵션을 설정할 수 있습니다.

연결 옵션 설정하기¶

새 Connection 오브젝트를 구성할 때 연결에 대한 옵션(예: 계정 식별자, 사용자 이름 등)을 지정하는 JavaScript 오브젝트를 전달합니다. 다음 섹션에서는 설정이 가능한 옵션에 대해 설명합니다. 옵션을 설정하려면 옵션의 이름을 JavaScript 오브젝트의 속성 이름으로 지정합니다.

• 필수 연결 옵션

• 인증 옵션

• 추가 연결 옵션

Snowflake에 인증하기¶

Snowflake에 인증하기 위해서는 다음 옵션 중 1개를 사용할 수 있습니다.

• 비밀번호 기반 인증. 이 옵션을 사용하려면 연결할 때 password 옵션을 설정합니다.

• 웹 브라우저를 통한 Single Sign-On(SSO).

• Okta를 통한 기본 SSO.

• 키 페어 인증.

• OAuth.

// Use a browser to authenticate via SSO.
var connection = snowflake.createConnection({
  ...,
  authenticator: "EXTERNALBROWSER"
});
// Establish a connection. Use connectAsync, rather than connect.
connection.connectAsync(
  function (err, conn)
  {
    ... // Handle any errors.
  }
).then(() =>
{
  // Execute SQL statements.
  var statement = connection.execute({...});
});

// Use native SSO authentication through Okta.
var connection = snowflake.createConnection({
  ...,
  username: '<user_name_for_okta>',
  password: '<password_for_okta>',
  authenticator: "https://myaccount.okta.com"
});

// Establish a connection.
connection.connectAsync(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

// Execute SQL statements.
var statement = connection.execute({...});

// Use OAuth for authentication.
var connection = snowflake.createConnection({
  ...
  authenticator: "OAUTH",
  token: "<your_oauth_token>"
});

// Establish a connection.
connection.connect(
  function (err, conn)
  {
    ... // Handle any errors.
  }
);

// Execute SQL statements.
var statement = connection.execute({...});

페일 오픈 또는 페일 클로즈 모드 선택하기¶

1.2.0 이전 버전의 Node.js 드라이버의 모드는 기본적으로 페일 클로즈입니다. 1.2.0 이상 버전의 경우에는 기본적으로 페일 오픈입니다. snowflake.createConnection() 메서드를 호출하기 전 ocspFailOpen 전역 매개 변수를 설정하여 기본 동작을 재정의할 수 있습니다. 매개 변수는 true 또는 false로 설정할 수 있습니다.

snowflake.configure( {ocspFailOpen: false} );
const connection = snowflake.createConnection(
    {
    account: <account_identifier>,
    ...
    }
);

OCSP 커넥터 또는 드라이버 버전 확인하기¶

드라이버 또는 커넥터 버전, 구성 및 OCSP 동작에 대한 자세한 내용은 OCSP 구성 를 참조하십시오.

문 매개 변수 바인딩하기¶

종종 문의 데이터와 자리 표시자를 바인딩해야 하는 경우가 있습니다. 이러한 방식으로 문을 실행하는 것은 SQL 삽입 공격을 방지할 수 있으므로 유용합니다. 다음 문을 살펴보겠습니다.

connection.execute({
  sqlText: 'select c1 from (select 1 as c1 union all select 2 as c1) where c1 = 1;'
});

다음 바인딩을 사용하여 동일한 결과를 얻을 수 있습니다.

connection.execute({
  sqlText: 'select c1 from (select :1 as c1 union all select :2 as c1) where c1 = :1;',
  binds: [1, 2]
});

바인딩을 위한 ? 구문도 지원됩니다.

connection.execute({
  sqlText: 'select c1 from (select ? as c1 union all select ? as c1) where c1 = ?;',
  binds: [1, 2, 1]
});

SQL 문 일괄 실행하기(다중 문 지원)¶

Node.js의 버전 1.6.18 이상에서는 세미콜론으로 구분된 SQL 문 배치를 전송하여 단일 요청에서 실행되도록 할 수 있습니다.

여러 명령문이 포함된 쿼리는 단일 명령문이 포함된 쿼리와 동일한 방식으로 실행할 수 있지만, 쿼리 문자열에 세미콜론으로 구분된 여러 명령문이 포함된다는 점이 다릅니다.

다중 문은 다음의 2가지 방법으로 사용할 수 있습니다.

• Statement.setParameter("MULTI_STATEMENT_COUNT", n) 을 호출하여 한 번에 이 문을 실행할 수 있는 문의 수를 지정합니다.

• 다음 명령 중 하나를 실행하여 세션 수준 또는 계정 수준에서 MULTI_STATEMENT_COUNT 매개 변수를 설정합니다.

  alter session set MULTI_STATEMENT_COUNT = 0;
  

  또는:

  alter account set MULTI_STATEMENT_COUNT = 0;
  

  매개 변수를 0으로 설정하면 무제한 수의 문이 허용됩니다. 매개 변수를 1로 설정하면 한 번에 1개의 문만 허용됩니다.

다음 예에서는 세션 수준에서 문 수를 무제한으로 설정한 다음 SQL 문 세 개를 실행합니다.

var statement = connection.execute({
  alter session set MULTI_STATEMENT_COUNT = 0;
  sqlText: 'create table test(n int); insert into test values (1), (2); select * from test order by n',
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      // code to process the results
    }
  }
});

일괄 삽입을 위한 배열 바인딩하기¶

일괄 INSERT 연산을 위한 데이터 배열 바인딩이 지원됩니다. 배열의 배열을 다음과 같이 전달합니다.

connection.execute({
  sqlText: 'insert into t(c1, c2, c3) values(?, ?, ?)',
  binds: [[1, 'string1', 2.0], [2, 'string2', 4.0], [3, 'string3', 6.0]]
});

문 취소하기¶

문은 statement.cancel() 메서드를 호출하여 취소할 수 있습니다.

statement.cancel(function(err, stmt) {
  if (err) {
    console.error('Unable to abort statement due to the following error: ' + err.message);
  } else {
    console.log('Successfully aborted statement');
  }
});

요청 다시 제출하기¶

어쩌면 네트워크 오류 또는 시간 초과로 인해 Snowflake가 SQL 문을 성공적으로 실행했는지 확실하지 않은 경우 요청 ID를 사용하여 같은 문을 다시 제출할 수 있습니다. 예를 들어, 데이터를 추가하려고 INSERT 명령을 제출했지만 적시에 확인을 받지 못했는데, 명령에 어떤 문제가 있는지는 모른다고 가정해 보십시오. 이런 상황에서는 똑같은 명령을 새 명령으로 실행하면 명령을 두 번 실행하여 데이터 중복을 일으킬 수 있으므로 그렇게 하고 싶지는 않을 것입니다.

SQL 문에 요청 ID를 포함하면 데이터 중복 가능성을 피할 수 있습니다. 초기 요청에서 요청 ID로 요청을 다시 제출하면 초기 요청이 실패하는 경우에만 다시 제출된 명령이 실행됩니다. 자세한 내용은 SQL 문 실행 요청 다시 제출하기 를 참조하십시오.

다음 코드 샘플에서는 요청 ID를 저장하고 사용하여 문을 다시 제출하는 방법을 보여줍니다. 문을 실행할 때 getRequestId() 함수를 사용하여 제출된 요청의 ID를 검색할 수 있습니다. 그런 다음 해당 ID를 사용하여 나중에 같은 문을 실행할 수 있습니다. 다음 예제에서는 INSERT 문을 실행하고 requestId 변수에 요청 ID를 저장합니다.

var requestId;
connection.execute({
  sqlText: 'INSERT INTO testTable VALUES (1);',
    complete: function (err, stmt, rows)
    {
      var stream = stmt.streamRows();
      requestId = stmt.getRequestId();   // Retrieves the request ID
      stream.on('data', function (row)
      {
        console.log(row);
      });
      stream.on('end', function (row)
      {
        console.log('done');
      });
    }
});

명령이 성공적으로 실행되었다는 확인을 받지 못한 경우 그림과 같이 저장된 요청 ID를 사용하여 요청을 다시 제출할 수 있습니다.

connection.execute({
  sqlText: 'INSERT INTO testTable VALUES (1);',  // optional
    requestId: requestId,  // Uses the request ID from before
    complete: function (err, stmt, rows)
    {
      var stream = stmt.streamRows();
      stream.on('data', function (row)
      {
        console.log(row);
      });
      stream.on('end', function (row)
      {
        console.log('done');
      });
  }
});

requestId 와 sqlText 를 사용하여 요청을 다시 제출하기로 할 때 다음 상호 작용에 유의하십시오.

• requestId 가 이미 존재하는 경우, 즉 다시 제출하는 요청이 이전 요청과 일치하는 경우, 이 명령은 sqlText 쿼리를 무시하고 원래 명령에서 쿼리를 다시 제출합니다.

• requestId 가 존재하지 않는 경우, 즉 이전 요청과 일치하지 않는 경우, 이 명령은 sqlText 쿼리를 실행합니다.

인라인 결과 반환하기¶

결과를 사용하는 가장 일반적인 방법은 complete 콜백을 connection.execute() 로 전달하는 방법입니다. 문의 실행이 종료되고 결과를 사용할 수 있으면, 결과 행이 인라인으로 반환되면서 complete 콜백이 호출됩니다.

connection.execute({
  sqlText: 'select * from sometable',
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      console.log('Number of rows produced: ' + rows.length);
    }
  }
});

결과 스트리밍하기¶

결과를 행의 스트림으로 사용할 수도 있습니다. 이는 statement.streamRows() 메서드를 호출하여 수행할 수 있으며, 이를 통해 수신될 때 행을 사용하기 위해 사용될 수 있는 Node.js Readable 스트림이 반환됩니다. Readable 스트림에 대한 자세한 내용은 Node.js 설명서 를 참조하십시오.

예:

var statement = connection.execute({
  sqlText: 'select * from sometable'
});

var stream = statement.streamRows();

stream.on('error', function(err) {
  console.error('Unable to consume all rows');
});

stream.on('data', function(row) {
  // consume result row...
});

stream.on('end', function() {
  console.log('All rows consumed');
});

일괄 처리 결과¶

기본적으로 statement.streamRows() 메서드에서는 결과의 모든 행이 포함되는 스트림이 생성됩니다. 그러나 하위 결과 세트만을 사용하거나 결과 행을 일괄적으로 사용하려는 경우에는 start 및 end 인자를 사용하여 streamRows() 를 호출할 수 있습니다. 이러한 추가 옵션이 지정되면 요청된 범위 내의 행만 스트리밍됩니다.

connection.execute({
  sqlText: 'select * from sometable',
  streamResult: true, // prevent rows from being returned inline in the complete callback
  complete: function(err, stmt, rows) {
    // no rows returned inline because streamResult was set to true
    console.log('rows: ' + rows); // 'rows: undefined'

    // only consume at most the last 5 rows in the result
    rows = [];
    stmt.streamRows({
      start: Math.max(0, stmt.getNumRows() - 5),
      end: stmt.getNumRows() - 1,
    })
    .on('error', function(err) {
      console.error('Unable to consume requested rows');
    })
    .on('data', function(row) {
      rows.push(row);
    })
    .on('end', function() {
      console.log('Number of rows consumed: ' + rows.length);
    });
  }
})

데이터 타입 캐스팅¶

결과 행이 생성되면 드라이버는 SQL 데이터 타입을 해당 JavaScript 데이터 타입으로 자동으로 매핑합니다. 예를 들어, TIMESTAMP 및 DATE 타입의 값은 JavaScript 날짜 오브젝트로 반환됩니다.

JavaScript를 SQL 데이터 타입으로 완전하게 매핑하려면 아래 테이블을 참조하십시오.

SQL 데이터 타입	JavaScript 데이터 타입	참고
VARCHAR, CHAR, CHARACTER, STRING, TEXT	문자열
INT, INTEGER, BIGINT, SMALLINT	숫자	기본 매핑입니다. 세션 매개 변수 JS_TREAT_INTEGER_AS_BIGINT를 사용하여 JavaScript Bigint로 매핑합니다.
NUMBER(전체 자릿수, 소수 자릿수), DECIMAL(p, s), NUMERIC(p, s), 여기서 scale = 0	숫자	기본 매핑입니다. 세션 매개 변수 JS_TREAT_INTEGER_AS_BIGINT를 사용하여 JavaScript Bigint로 매핑합니다.
NUMBER(전체 자릿수, 소수 자릿수), DECIMAL(p, s), NUMERIC(p, s), 여기서 scale > 0	숫자
FLOAT, FLOAT4, FLOAT8, DOUBLE, DOUBLE PRECISION, REAL	숫자
TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ	날짜	TIMESTAMP_NTZ 값은 UTC 시간으로 반환됩니다.
DATE	날짜
TIME	문자열	SQL의 TIME 데이터 타입에 해당하는 타입이 JavaScript에는 없으며, 그러므로 JavaScript 문자열로 매핑됩니다.
BOOLEAN	부울
VARIANT, ARRAY, OBJECT	JSON

정수 데이터 타입을 Bigint로 가져오기¶

기본적으로, Snowflake INTEGER 열(BIGINT, NUMBER(p, 0) 등 포함)은 JavaScript의 Number 데이터 타입으로 변환됩니다. 하지만 가장 큰 올바른 Snowflake 정수 값은 가장 큰 올바른 JavaScript Number 값보다 큽니다. Snowflake INTEGER 열을 JavaScript Number보다 큰 값을 저장할 수 있는 JavaScript Bigint로 변환하려면 세션 매개 변수 JS_TREAT_INTEGER_AS_BIGINT를 설정합니다.

이 매개 변수는 다음의 2가지 방법으로 설정할 수 있습니다.

• 아래와 같이 ALTER SESSION 문을 사용합니다.

  connection.execute( {
                      sqlText: 'ALTER SESSION SET JS_TREAT_INTEGER_AS_BIGINT = TRUE',
                      complete: function ...
                      }
                    );
  

• 연결 구성 정보에 매개 변수를 지정합니다.

  var connection = snowflake.createConnection(
        {
        username: 'fakeusername',
        password: 'fakepassword',
        account: 'fakeaccountidentifier',
        jsTreatIntegerAsBigInt: true
        }
      );
  

데이터 타입을 문자열로 가져오기¶

connection.execute() 가 호출될 때 fetchAsString 옵션을 설정하여 모든 숫자 또는 날짜를 문자열로 강제 반환하도록 설정할 수 있습니다. 이를 통해 얻을 수 있는 결과는 다음과 같습니다.

• DATE 또는 TIMESTAMP(또는 베리언트) 타입 값의 타입이 지정된 버전.

• 전체 자릿수가 손실되지 않고 JavaScript 숫자로 변환할 수 없는 숫자 SQL 타입의 문자열 버전.

예:

connection.execute({
  sqlText: 'select 1.123456789123456789123456789 as "c1"',
  fetchAsString: ['Number'],
  complete: function(err, stmt, rows) {
    if (err) {
      console.error('Failed to execute statement due to the following error: ' + err.message);
    } else {
      console.log('c1: ' + rows[0].c1); // c1: 1.123456789123456789123456789
    }
  }
});