snowflake-sdk/dist/lib/connection/types.d.ts

Node.js driver for Snowflake

import { WorkloadIdentityProviderKey } from '../authentication/auth_workload_identity/types';
import { CRLValidatorConfig } from '../agent/crl_validator';
/**
 * Work In Progress typing for ConnectionOptions
 *
 * TODO:
 * - revisit doc of every option
 * - if an options works only when another option is set - document it
 */
export interface WIP_ConnectionOptions {
    /**
     * Your account identifier.
     */
    account?: string;
    /**
     * Specifies a fully-qualified endpoint for connecting to Snowflake.
     */
    accessUrl?: string;
    /**
     * @deprecated
     * Append a region or any sub domains before snowflakecomputing.com to the
     * end of account parameter after a dot, e.g., account=<account>.<region>.
     */
    region?: string;
    /**
     * The login name for your Snowflake user or your Identity Provider (e.g. your login name for Okta).
     */
    username?: string;
    /**
     * Password for the user.
     */
    password?: string;
    /**
     * Host address to which the driver should connect.
     */
    host?: string;
    /**
     * The default virtual warehouse to use for the session after connecting. Used for performing queries, loading data, etc.
     */
    warehouse?: string;
    /**
     * The default database to use for the session after connecting.
     */
    database?: string;
    /**
     * The default schema to use for the session after connecting.
     */
    schema?: string;
    /**
     * The default security role to use for the session after connecting.
     */
    role?: string;
    /**
     * Specifies the authenticator to use for verifying user login credentials.
     *
     * Available options:
     * * `SNOWFLAKE` - Default authenticator that uses basic username/password authentication
     * * `EXTERNALBROWSER` - Browser-based SSO authentication through your identity provider
     * * `SNOWFLAKE_JWT` - Key pair authentication using a private key and public key pair
     * * `OAUTH` - OAuth authentication using a token obtained from OAuth flow
     * * `USERNAME_PASSWORD_MFA` - Username/password with multi-factor authentication
     * * `PROGRAMMATIC_ACCESS_TOKEN` - Using a programmatic access token set in ConnectionOptions.token or ConnectionOptions.password
     * * `OAUTH_AUTHORIZATION_CODE` - OAuth authorization code flow for web applications
     * * `OAUTH_CLIENT_CREDENTIALS` - OAuth client credentials flow for service-to-service auth
     * * `WORKLOAD_IDENTITY` - Workload identity authentication
     * * `https://<okta_account_name>.okta.com` - Native SSO authentication through Okta
     */
    authenticator?: string;
    /**
     * By default, client connections typically time out approximately 3-4 hours after the most recent query was executed.
     */
    clientSessionKeepAlive?: boolean;
    /**
     * Sets the frequency (interval in seconds) between heartbeat messages.
     */
    clientSessionKeepAliveHeartbeatFrequency?: number;
    /**
     * When true, the session is not destroyed on the server side when the connection
     * is closed. This allows async queries to continue running after disconnect.
     * Any unfinished queries will continue to live in Snowflake and consume credits
     * until they finish.
     *
     * @default false
     */
    serverSessionKeepAlive?: boolean;
    /**
     * Enable MFA/SSO token caching.
     *
     * https://docs.snowflake.com/en/developer-guide/node-js/nodejs-driver-authenticate#authentication-token-caching
     *
     * @default false
     */
    clientStoreTemporaryCredential?: boolean;
    /**
     * When clientStoreTemporaryCredential=true, sets the directory where cached authentication
     * tokens are stored.
     *
     * If not set, the driver resolves the cache directory by checking, in order:
     * 1. The `SF_TEMPORARY_CREDENTIAL_CACHE_DIR` environment variable
     * 2. Platform-specific defaults:
     *    - **Windows**: `<home>/AppData/Local/Snowflake/Caches`
     *    - **Linux**: `$XDG_CACHE_HOME/snowflake`, or `~/.cache/snowflake`
     *    - **macOS**: `~/Library/Caches/Snowflake`
     */
    credentialCacheDir?: string;
    /**
     * Specifies the token to use for authentication. Set this option if you set the authenticator option to
     * * OAUTH
     * * PROGRAMMATIC_ACCESS_TOKEN
     * * WORKLOAD_IDENTITY
     */
    token?: string;
    /**
     * Specifies the path to a file containing the token for authentication.
     *
     * This option works similarly to the `token` property, but retrieves the token value by reading the specified file from disk.
     *
     * If `token` is not provided, the driver will attempt to read the token from this file for suitable token-based authenticators.
     *
     * If both `token` and `tokenFilePath` are set, `token` takes precedence and this file path will be ignored.
     */
    tokenFilePath?: string;
    /**
     * Enable single use refresh tokens for OAuth
     */
    oauthEnableSingleUseRefreshTokens?: boolean;
    /**
     * Value of `client id` provided by the identity provider for Snowflake integration (Snowflake security integration metadata).
     */
    oauthClientId?: string;
    /**
     * Value of the `client secret` provided by the identity provider for Snowflake integration (Snowflake security integration metadata).
     */
    oauthClientSecret?: string;
    /**
     * Identity provider endpoint supplying the authorization code to the driver.
     * When Snowflake is used as an identity provider, this value is derived from the `server` or `account` parameters.
     */
    oauthAuthorizationUrl?: string;
    /**
     * Identity Provider endpoint supplying the access tokens to the driver.
     * When using Snowflake as an Identity Provider, this value is derived from the `server` or `account` parameters.
     */
    oauthTokenRequestUrl?: string;
    /**
     * Scope requested in the Identity Provider authorization request.
     * By default, it is derived from the role.
     * When multiple scopes are required, the value should be a space-separated list of multiple scopes.
     */
    oauthScope?: string;
    /**
     * When authenticator=OAUTH_AUTHORIZATION_CODE, customize the URI for authorization code redirection.
     *
     * @default "http://127.0.0.1:{randomAvailablePort}"
     */
    oauthRedirectUri?: string;
    /**
     * @deprecated
     * FOR TESTING ONLY. Allows to use insecure http requests.
     */
    oauthHttpAllowed?: boolean;
    /**
     * When authenticator=OAUTH_AUTHORIZATION_CODE, customize the code challenge method
     */
    oauthChallengeMethod?: string;
    /**
     * The option to enable the MFA token.
     * @default false
     */
    clientRequestMFAToken?: boolean;
    /**
     * The option to skip the SAML URL check in the Okta authentication
     *
     * @default false
     */
    disableSamlURLCheck?: boolean;
    /**
     * When authenticator=SNOWFLAKE_JWT, specifies the private key (in PEM format).
     *
     * If the key is encrypted, use {@link privateKeyPass} to provide the passphrase.
     */
    privateKey?: string;
    /**
     * When authenticator=SNOWFLAKE_JWT, specifies the local path to the private key file (in PEM
     * format).
     *
     * If the key is encrypted, use {@link privateKeyPass} to provide the passphrase.
     */
    privateKeyPath?: string;
    /**
     * When authenticator=SNOWFLAKE_JWT, specifies the passcode to decrypt the encrypted private key
     * passed in {@link privateKey} or {@link privateKeyPath}.
     */
    privateKeyPass?: string;
    /**
     * Specifies the timeout, in milliseconds, for browser activities related to MFA/SSO authentication.
     *
     * @default 120000 (milliseconds)
     */
    browserActionTimeout?: number;
    /**
     * When authenticator=EXTERNALBROWSER, customize the port of
     * the local server that receives the authentication callback.
     *
     * The server always redirects to `http://localhost:${browserRedirectPort}`.
     *
     * For OAUTH_AUTHORIZATION_CODE, use {@link oauthRedirectUri}
     * instead, which supports customizing both host and port.
     *
     * @default 0 (random available port)
     */
    browserRedirectPort?: number;
    /**
     * Lets you customize the web page a user sees in their browser after they
     * finish signing in, instead of the default confirmation message. Use it to
     * show your own branding, wording, or a "you can close this tab" page.
     *
     * Supported when authenticator is set to:
     * * EXTERNALBROWSER
     * * OAUTH_AUTHORIZATION_CODE
     *
     * Return the full HTML page to display. On success, `error` is `null`.
     * If sign-in failed, `error` contains the message from your identity provider
     * (already HTML-escaped, so it is safe to embed directly).
     *
     * @example
     * browserResponseRenderer: ({ error }) => {
     *   const message = error
     *     ? `<h1>Login failed</h1><p>${error}</p>`
     *     : '<h1>All set! You can close this tab.</h1>';
     *   return `<html><body>${message}</body></html>`;
     * }
     */
    browserResponseRenderer?: (result: {
        error: string | null;
    }) => string;
    /**
     * Specifies a custom callback for opening the browser window during authentication.
     * Supported when the authenticator is set to:
     * * EXTERNALBROWSER
     * * OAUTH_AUTHORIZATION_CODE
     *
     * By default, the npm `open` package is used.
     */
    openExternalBrowserCallback?: (url: string) => void;
    /**
     * When authenticator=WORKLOAD_IDENTITY, specifies the identity provider. Available options:
     * * AWS - Uses `@aws-sdk` to find credentials. Supports two attestation methods:
     *   * `GetCallerIdentity` (default) - encodes a SigV4-signed `GetCallerIdentity` request as the token
     *   * `GetWebIdentityToken` - obtains a signed JWT token, enabled via {@link workloadIdentityAwsUseOutboundToken}
     * * AZURE - Uses `@azure/identity` to find credentials and get JWT token
     * * GCP - Uses `google-auth-library` to find credentials and get JWT token
     * * OIDC - Reads JWT token from `ConnectionOptions.token`
     */
    workloadIdentityProvider?: WorkloadIdentityProviderKey;
    /**
     * When authenticator=WORKLOAD_IDENTITY, specifies a chain of service accounts for transitive impersonation.
     * Each element represents a service account to impersonate in sequence, allowing workloads to authenticate
     * as a different identity than their default attached service account.
     *
     * Supported for AWS and GCP.
     */
    workloadIdentityImpersonationPath?: string[];
    /**
     * When workloadIdentityProvider=AZURE, customize Azure Entra Id Resource
     */
    workloadIdentityAzureEntraIdResource?: string;
    /**
     * When workloadIdentityProvider=AZURE, customize Azure Managed Identity Client Id
     */
    workloadIdentityAzureClientId?: string;
    /**
     * When workloadIdentityProvider=AWS, selects the AWS attestation method.
     *
     * AWS WIF supports two methods:
     * * `GetCallerIdentity` (default, `false`) - the connector encodes a SigV4-signed
     *   `GetCallerIdentity` request as the attestation token.
     * * `GetWebIdentityToken` (`true`) - the connector calls STS `GetWebIdentityToken` and
     *   forwards a standards-based JWT instead. This provides stateless token verification and
     *   compatibility with AWS outbound identity federation. It requires the AWS IAM role to have
     *   `sts:GetWebIdentityToken` permission and the Snowflake service user to be configured with an
     *   `ISSUER`.
     *
     * The `GetWebIdentityToken` method is recommended and may become the default in a future release.
     *
     * See {@link https://docs.snowflake.com/en/user-guide/workload-identity-federation#label-wif-aws-upgrade-jwt}
     * for setup instructions, including the Node.js connector configuration.
     *
     * @default false
     */
    workloadIdentityAwsUseOutboundToken?: boolean;
    /**
     * Enables Certificate Revocation List (CRL) validation.
     *
     * When `ENABLED` is set, it fails if the certificate is revoked or if any error occurs (network, parsing, etc.).
     * When `ADVISORY` is set, it fails only if the certificate is revoked.
     *
     * @default "DISABLED"
     */
    certRevocationCheckMode?: CRLValidatorConfig['checkMode'];
    /**
     * Allows to connect when certificate doesn't have CRL URLs (cRLDistributionPoints)
     *
     * This option applies only when certRevocationCheckMode is `ADVISORY` or `ENABLED`
     *
     * @default false
     */
    crlAllowCertificatesWithoutCrlURL?: CRLValidatorConfig['allowCertificatesWithoutCrlURL'];
    /**
     * Enable CRL caching in memory.
     *
     * This option applies only when certRevocationCheckMode is `ADVISORY` or `ENABLED`
     *
     * @default true
     */
    crlInMemoryCache?: CRLValidatorConfig['inMemoryCache'];
    /**
     * Enable CRL caching on disk. Disk read/write failures are ignored.
     *
     * This option applies only when certRevocationCheckMode is `ADVISORY` or `ENABLED`
     *
     * @default true
     */
    crlOnDiskCache?: CRLValidatorConfig['onDiskCache'];
    /**
     * Controls how many rows are buffered by the stream returned from
     * `statement.streamRows()`. Passed as the `highWaterMark` to the
     * underlying Node.js Readable class.
     *
     * @default 10
     */
    rowStreamHighWaterMark?: number;
    /**
     * Specifies the name of the client application connecting to Snowflake.
     */
    application?: string;
    /**
     * Turn on the validation function which checks whether all the connection configuration from users are valid or not.
     *
     * @default false
     */
    validateDefaultParameters?: boolean;
    /**
     * Specifies a list of hosts that the driver should connect to directly, bypassing the proxy server.
     *
     * - Use a pipe symbol (`|`) to separate multiple hosts.
     * - Use `*` as a wildcard (e.g., `*sub.amazonaws.com`).
     * - A leading dot (e.g., `.amazonaws.com`) matches any subdomain.
     *
     * @example
     * noProxy: ".amazonaws.com|*sub.my_company.com"
     */
    noProxy?: string;
    /**
     * Specifies the hostname of an authenticated proxy server.
     */
    proxyHost?: string;
    /**
     * Specifies the username used to connect to an authenticated proxy server.
     */
    proxyUser?: string;
    /**
     * Specifies the password for the user specified by proxyUser.
     */
    proxyPassword?: string;
    /**
     * Specifies the port of an authenticated proxy server.
     */
    proxyPort?: number;
    /**
     * Specifies the protocol (`http` or `https`) used to connect to the proxy server.
     */
    proxyProtocol?: string;
    /**
     * Optional string that can be used to tag queries and other SQL statements executed within a connection.
     * The tags are displayed in the output of the QUERY_HISTORY , QUERY_HISTORY_BY_* functions.
     */
    queryTag?: string;
}
/**
 * Work In Progress typing for ConnectionConfig instance
 */
export type WIP_ConnectionConfig = Pick<WIP_ConnectionOptions, 'token' | 'workloadIdentityProvider' | 'workloadIdentityImpersonationPath' | 'workloadIdentityAzureEntraIdResource' | 'workloadIdentityAzureClientId' | 'workloadIdentityAwsUseOutboundToken' | 'oauthEnableSingleUseRefreshTokens' | 'rowStreamHighWaterMark'> & {
    browserRedirectPort: number;
    crlValidatorConfig: CRLValidatorConfig;
    getClientType(): string;
    getClientVersion(): string;
    getClientApplication(): string;
    getOauthHttpAllowed(): boolean;
    getOauthClientId(): string;
    getOauthClientSecret(): string;
    getProxy(): {
        [key: string]: any;
    };
    agentCache: Map<string, any>;
    destroyAgentCache(): void;
};