Node.js Connection Options

When constructing a new Connection object, you pass in a JavaScript object that specifies the options for the connection (e.g. your account identifier, your user name, etc.). The following sections describe the options that you can set. To set an option, specify the option name as the property name in the JavaScript object.

Required Connection Options

account

Your account identifier.

username

The login name for your Snowflake user or your Identity Provider (e.g. your login name for Okta).

region (Deprecated)

The ID for the region where your account is located.

Note

This option is deprecated and is included here only for backward compatibility. Snowflake recommends transitioning to embedding the region in the account identifier, as described in Using an Account Locator as an Identifier, such as follows.

var connection = snowflake.createConnection({
  account: "myaccount.us-east-2",
  username: "myusername",
  password: "mypassword"
});
Copy

In addition, you must specify the options for authenticating to the server.

Authentication Options

application

Specifies the name of the client application connecting to Snowflake.

authenticator

Specifies the authenticator to use for verifying user login credentials. You can set this to one of the following values:

Value

Description

SNOWFLAKE

Use the internal Snowflake authenticator. You must also set the password option.

EXTERNALBROWSER

Use your web browser to authenticate with Okta, AD FS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.

https://<okta_account_name>.okta.com

Use Native SSO through Okta.

OAUTH

Use OAuth for authentication. You must also set the token option to the OAuth token (see below).

SNOWFLAKE_JWT

Use key pair authentication. See Using Key Pair Authentication & Key Pair Rotation.

The default value is SNOWFLAKE.

For more information on authentication, see Managing/Using Federated Authentication and Clients, Drivers, and Connectors.

password

Password for the user. Set this option if you set the authenticator option to SNOWFLAKE or the Okta URL endpoint for your Okta account (e.g. https://<okta_account_name>.okta.com) or if you left the authenticator option unset.

token

Specifies the OAuth token to use for authentication. Set this option if you set the authenticator option to OAUTH.

privateKey

Specifies the private key (in PEM format) for key pair authentication. For details, see Using Key Pair Authentication & Key Pair Rotation.

privateKeyPath

Specifies the local path to the private key file (e.g. rsa_key.p8). For details, see Using Key Pair Authentication & Key Pair Rotation.

privateKeyPass

Specifies the passcode to decrypt the private key file, if the file is encrypted. For details, see Using Key Pair Authentication & Key Pair Rotation.

Additional Connection Options

accessUrl

Specifies a fully-qualified endpoint for connecting to Snowflake. The accessUrl includes the full schema and host, as well as an optional port number, similar to https://myaccount.us-east-1.snowflakecomputing.com.

Note

When using the accessUrl option, the value specified in the account option is not used.

arrayBindingThreshold

Sets the maximum number of binds the driver uses in a bulk insert operation. The default value is 100000 (100K).

clientSessionKeepAlive

By default, client connections typically time out approximately 3-4 hours after the most recent query was executed.

If the clientSessionKeepAlive option is set to true, the client’s connection to the server will be kept alive indefinitely, even if no queries are executed.

The default setting of this option is false.

If you set this option to true, make sure that your program explicitly disconnects from the server when your program has finished. Do not exit without disconnecting.

clientSessionKeepAliveHeartbeatFrequency

(Applies only when clientSessionKeepAlive is true)

Sets the frequency (interval in seconds) between heartbeat messages.

You can loosely think of a connection heartbeat message as substituting for a query and restarting the timeout countdown for the connection. In other words, if the connection would time out after at least 4 hours of inactivity, the heartbeat resets the timer so that the timeout will not occur until at least 4 hours after the most recent heartbeat (or query).

The default value is 3600 seconds (one hour). The valid range of values is 900 - 3600. Because timeouts usually occur after at least 4 hours, a heartbeat every 1 hour is normally sufficient to keep the connection alive. Heartbeat intervals of less than 3600 seconds are rarely necessary or useful.

database

The default database to use for the session after connecting.

noProxy

Specifies the lists of hosts that the driver should connect to directly, bypassing the proxy server (e.g. *.amazonaws.com to bypass Amazon S3 access). For multiple hosts, separate the hostnames with a pipe symbol (|). You can also use an asterisk as a wild card. For example:

noProxy: "*.amazonaws.com|*.my_company.com"

proxyHost

Specifies the hostname of an authenticated proxy server.

proxyPassword

Specifies the password for the user specified by proxyUser.

proxyPort

Specifies the port of an authenticated proxy server.

proxyProtocol

Specifies the protocol used to connect to the authenticated proxy server. Use this property to specify the HTTP protocol: http or https.

proxyUser

Specifies the username used to connect to an authenticated proxy server.

resultPrefetch

Number of threads for clients to use to prefetch large result sets. Valid values: 1-10.

role

The default security role to use for the session after connecting.

schema

The default schema to use for the session after connecting.

timeout

Number of milliseconds to keep the connection alive with no response. Default: 60000 (1 minute).

warehouse

The default virtual warehouse to use for the session after connecting. Used for performing queries, loading data, etc.

Some connection options assume that the specified database object (database, schema, warehouse, or role) already exists in the system. If the specified object does not exist, a default is not set during connection.

After connecting, all of the optional connection options can also be set or overridden through the USE <object> command.