Connecting Through SnowSQL¶

This topic describes how to connect to Snowflake by entering connection parameters manually. The topic then explains how to configure a default connection for ease of use, as well as one or more named connections to use alternative connection settings or create multiple concurrent sessions.

In this Topic:

Connection Syntax
- Specifying Passwords When Connecting
- Using Environment Variables
Configuring Default Connection Settings
Verifying the Network Connection to Snowflake with SnowCD
Using Named Connections
- Defining Named Connections in the Configuration File
- Connecting to Snowflake Using a Named Connection
Using Key Pair Authentication
- Key Rotation
Using a Proxy Server
Using a Web Browser for Federated Authentication/SSO
Verifying the OCSP Connector or Driver Version
OCSP Response Cache Server
Connection Error Handling
Connection Parameters Reference

Connection Syntax¶

$ snowsql <connection_parameters>

Where <connection_parameters> are one or more of the following. For detailed descriptions of each parameter, see Connection Parameters Reference (in this topic).

-a, --accountname TEXT           Name assigned to your Snowflake account. Honors $SNOWSQL_ACCOUNT.
-u, --username TEXT              Username to connect to Snowflake. Honors $SNOWSQL_USER.
-d, --dbname TEXT                Database to use. Honors $SNOWSQL_DATABASE.
-s, --schemaname TEXT            Schema in the database to use. Honors $SNOWSQL_SCHEMA.
-r, --rolename TEXT              Role name to use. Honors $SNOWSQL_ROLE.
-w, --warehouse TEXT             Warehouse to use. Honors $SNOWSQL_WAREHOUSE.
-h, --host TEXT                  Host address for the connection. Honors $SNOWSQL_HOST. (Deprecated)
-p, --port INTEGER               Port number for the connection. Honors $SNOWSQL_PORT. (Deprecated)
--region TEXT                    Region. Honors $SNOWSQL_REGION. (Deprecated; use -a or --accountname instead)
-m, --mfa-passcode TEXT          Token to use for multi-factor authentication (MFA)
--mfa-passcode-in-password       Appends the MFA passcode to the end of the password.
--abort-detached-query           Aborts a query if the connection between the client and server is lost. By default, it won't abort even if the
                                 connection is lost.
--probe-connection               Test connectivity to Snowflake. This option is mainly used to print out the TLS/SSL certificate chain.
--proxy-host TEXT                (DEPRECATED. Use HTTPS_PROXY and HTTP_PROXY environment variables.) Proxy server hostname. Honors $SNOWSQL_PROXY_HOST.
--proxy-port INTEGER             (DEPRECATED. Use HTTPS_PROXY and HTTP_PROXY environment variables.) Proxy server port number. Honors $SNOWSQL_PROXY_PORT.
--proxy-user TEXT                (DEPRECATED. Use HTTPS_PROXY and HTTP_PROXY environment variables.) Proxy server username. Honors $SNOWSQL_PROXY_USER.
                                 Set $SNOWSQL_PROXY_PWD for the proxy server password.
--authenticator TEXT             Authenticator: 'snowflake', 'externalbrowser' (to use any IdP and a web browser),
                                 https://<your_okta_account_name>.okta.com (to use Okta natively), or 'oauth' to authenticate using OAuth.
-v, --version                    Shows the current SnowSQL version, or uses a specific version if provided as a value.
--noup                           Disables auto-upgrade for this run. If no version is specified for -v, the latest version in ~/.snowsql/ is used.
-D, --variable TEXT              Sets a variable to be referred by &<var>. -D tablename=CENUSTRACKONE or --variable db_key=$DB_KEY
-o, --option TEXT                Set SnowSQL options. See the options reference in the Snowflake documentation.
-f, --filename PATH              File to execute.
-q, --query TEXT                 Query to execute.
--config PATH                    Path and name of the SnowSQL configuration file. By default, ~/.snowsql/config.
-P, --prompt                     Forces a password prompt. By default, $SNOWSQL_PWD is used to set the password.
-M, --mfa-prompt                 Forces a prompt for the second token for MFA.
-c, --connection TEXT            Named set of connection parameters to use.
--single-transaction             Connects with autocommit disabled. Wraps BEGIN/COMMIT around statements to execute them as a single transaction,
                                 ensuring all commands complete successfully or no change is applied.
--private-key-path PATH          Path to private key file in PEM format used for key pair authentication. The private key file must be encrypted,
                                 and the passphrase must be specified in the environment variable SNOWSQL_PRIVATE_KEY_PASSPHRASE.
--disable-request-pooling        Disables connection pooling.
-U, --upgrade                    Force upgrade of SnowSQL to the latest version.
-K, --client-session-keep-alive  Keep the session active indefinitely, even if there is no activity from the user.
-?, --help                       Show this message and exit.

Specifying Passwords When Connecting¶

Passwords cannot be passed through connection parameters. Passwords must be specified in one of the following ways:

Entered via interactive prompt in SnowSQL (applies to passwords only).
Defined in the SnowSQL configuration file using the password option. For details, see Configuring Default Connection Settings (in this topic).
Specified using the SNOWSQL_PWD environment variables. For details, see Using Environment Variables (in this topic).

Note

In Windows environments, the Cygwin terminal doesn’t prompt for your account name, username, or password. This is because SnowSQL cannot enable TTY mode in Cygwin terminals.

Using Environment Variables¶

Currently, environment variables can only be used to pre-specify some command line parameter values such as password, host, and database. Environment variables are not available to use in SnowSQL variable substitution unless they are explicitly specified on the command line when starting SnowSQL, using either the -D or --variable connection parameter. For example:

Linux/macOS

$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=$DB_KEY

Windows

$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=%DB_KEY%

In the above example, --variable sets a Snowflake variable named db_key to the DB_KEY environment variable.

Configuring Default Connection Settings¶

We recommend configuring your default connection parameters to simplify the connection process. Thereafter, when connecting to Snowflake, you can omit your Snowflake account name, username, and any other parameters you have configured as your default values.

To configure your default settings:

Open the configuration file in a text editor. By default, the file is located in:

Linux/macOS

~/.snowsql/

Windows

%USERPROFILE%\.snowsql\

Note

You can change the default location by including the --config <path> connection parameter when starting SnowSQL.

In the [connections] section, configure the default connection parameters by removing the comment symbol from any of the following parameters and specifying the correct values:

[connections]
#accountname = <string>   # Account name to connect to Snowflake.
#username = <string>      # User name in the account. Optional.
#password = <string>      # User password. Optional.
#dbname = <string>        # Default database. Optional.
#schemaname = <string>    # Default schema. Optional.
#warehousename = <string> # Default warehouse. Optional.
#rolename = <string>      # Default role. Optional.
#authenticator = <string> # Authenticator: 'snowflake', 'externalbrowser' (to use any IdP and a web browser),  https://<your_okta_account_name>.okta.com (to use Okta natively), 'oauth' to authenticate using OAuth.

Attention

The password is stored in plain text in the config file. You must explicitly secure the file to restrict access. For example, in Linux or macOS, you can set the read permissions to you alone by running chmod:
$ chmod 700 ~/.snowsql/config
If your password includes special characters, you must enclose the password in either single quotes or double quotes.

Verifying the Network Connection to Snowflake with SnowCD¶

After configuration, you can evaluate and troubleshoot your network connectivity to Snowflake using SnowCD.

You can use SnowCD during the initial configuration process and on-demand at any time to evaluate and troubleshoot your network connection to Snowflake.

Using Named Connections¶

To make multiple simultaneous connections to Snowflake, or to simply store different sets of connection configurations, you can define one or more named connections.

Defining Named Connections in the Configuration File¶

Open the config configuration file in a text editor. By default, the file is located in:

Linux/macOS

~/.snowsql/

Windows

%USERPROFILE%\.snowsql\
Add a separate [connections] section with a unique name for each named connection.

For example, the following illustrates a connection named my_example_connection for a Snowflake account in the EU (Frankfurt) region:
[connections.my_example_connection] accountname = xy12345.eu-central-1 username = jsmith password = xxxxxxxxxxxxxxxxxxxx dbname = mydb schemaname = public warehousename = mywh

Connecting to Snowflake Using a Named Connection¶

Use the -c <string> (or --connection <string>) connection parameter to specify a named connection, where <string> is the name of a connection defined in the configuration file.

For example, connect using the my_example_connection connection you created in Defining Named Connections in the Configuration File (in this topic):

$ snowsql -c my_example_connection

Using Key Pair Authentication¶

Snowflake supports using key pair authentication rather than the typical username/password authentication. This authentication method requires a 2048-bit (minimum) RSA key pair. Generate the PEM (Privacy Enhanced Mail) public-private key pair using OpenSSL. The public key is assigned to the Snowflake user who will use the Snowflake client.

To configure the public/private key pair:

From the command line in a terminal window, generate an encrypted private key.

Note that SnowSQL does not support an unencrypted version of the private key.

Execute the following command to generate the private key:
$ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
OpenSSL prompts for a passphrase used to encrypt the private key file. We recommend using a strong passphrase to protect the private key. Record this passphrase in a secure location. You will input it when connecting to Snowflake. Note that the passphrase is only used for protecting the private key and will never be sent to Snowflake.

Sample PEM private key
```
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
...
-----END ENCRYPTED PRIVATE KEY-----
```

From the command line, generate the public key by referencing the private key:

Assuming that the private key is contained in the file named “rsa_key.p8”, use the following command:
$ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
Sample PEM public key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
...
-----END PUBLIC KEY-----

Copy the public and private key files to a local directory for storage. Record the path to the files. Note that the private key is stored using the PKCS#8 (Public Key Cryptography Standards) format and is encrypted using the passphrase you specified in the previous step; however, the file should still be protected from unauthorized access using the file permission mechanism provided by your operating system. It is your responsibility to secure the file when it is not being used.

Assign the public key to the Snowflake user using ALTER USER. For example:

ALTER USER jsmith SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';

Note

Only security administrators (i.e. users with the SECURITYADMIN role) or higher can alter a user.
Exclude the public key header and footer in the SQL statement.

Verify the user’s public key fingerprint using DESCRIBE USER:

DESC USER jsmith;
+-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
| property                      | value                                               | default | description                                                                   |
|-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------|
| NAME                          | JSMITH                                              | null    | Name                                                                          |
...
...
| RSA_PUBLIC_KEY_FP             | SHA256:nvnONUsfiuycCLMXIEWG4eTp4FjhVUZQUQbNpbSHXiA= | null    | Fingerprint of user's RSA public key.                                         |
| RSA_PUBLIC_KEY_2_FP           | null                                                | null    | Fingerprint of user's second RSA public key.                                  |
+-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+

Note

The RSA_PUBLIC_KEY_2_FP property is described in Key Rotation (in this topic).

Specify the path to the private key file either in the configuration file or on the command line:

In the configuration file:
Add the private_key_path connection parameter to your connection settings and specify the local path to the private key file you created. The syntax is not OS-specific:
Supported OS
private_key_path = <path>/rsa_key.p8
Use the SNOWSQL_PRIVATE_KEY_PASSPHRASE environment variable to set the passphrase for decrypting the private key file. The syntax is OS-specific:
Linux/macOS
export SNOWSQL_PRIVATE_KEY_PASSPHRASE='<passphrase>'
Windows
set SNOWSQL_PRIVATE_KEY_PASSPHRASE='<passphrase>'
On the command line:

Include the private-key-path connection parameter and specify the path to your encrypted private key file:
$ snowsql -a <account> -u <user> --private-key-path <path>/rsa_key.p8
SnowSQL prompts you for the passphrase. Alternatively, use the SNOWSQL_PRIVATE_KEY_PASSPHRASE environment variable to set the passphrase for decrypting the private key file (as described above).

Key Rotation¶

Snowflake supports multiple active keys to allow for uninterrupted rotation. Rotate and replace your public and private keys based on the expiration schedule you follow internally.

Currently, you can use the RSA_PUBLIC_KEY and RSA_PUBLIC_KEY_2 parameters for ALTER USER to associate up to 2 public keys with a single user.

To rotate your keys:

Complete the steps in Using Key Pair Authentication to:
- Generate a new private and public key set.
- Assign the public key to the user. Set the public key value to either RSA_PUBLIC_KEY or RSA_PUBLIC_KEY_2 (whichever key value is not currently in use). For example:
  alter user jsmith set rsa_public_key_2='JERUEHtcve...';
Update the code to connect to Snowflake. Specify the new private key.

Snowflake verifies the correct active public key for authentication based on the private key submitted with your connection information.
Remove the old public key from the user profile. For example:
```
alter user jsmith unset rsa_public_key;
```

Using a Proxy Server¶

To use a proxy server, configure the following environment variables:

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

Note

The proxy parameters (i.e. proxy_host, proxy_port, proxy_user and SNOWFLAKE_PROXY_PWD in the command line and config file) are deprecated. Use the environment variables instead.

However, this requires SnowSQL 1.1.20 or higher. To determine your current version, see Understanding SnowSQL Versioning.

For example:

Linux/macOS

export HTTP_PROXY='http://username:password@proxyserver.company.com:80'
export HTTPS_PROXY='http://username:password@proxyserver.company.com:80'

Windows

set HTTP_PROXY=http://username:password@proxyserver.company.com:80
set HTTPS_PROXY=http://username:password@proxyserver.company.com:80

Tip

Snowflake’s security model does not allow Secure Sockets Layer (SSL) proxies (using an HTTPS certificate). Your proxy server must use a publicly-available Certificate Authority (CA), reducing potential security risks such as a MITM (Man In The Middle) attack through a compromised proxy.

If you must use your SSL proxy, we strongly recommend that you update the server policy to pass through the Snowflake certificate such that no certificate is altered in the middle of communications.

Optionally NO_PROXY can be used to bypass the proxy for specific communications. For example, Amazon S3 access can be bypassed by specifying NO_PROXY=".amazonaws.com".

Using a Web Browser for Federated Authentication/SSO¶

To use browser-based SSO authentication for SnowSQL, add --authenticator externalbrowser to your SnowSQL connection parameters:

For example:

$ snowsql -a <accountname> -u <username> --authenticator externalbrowser

For more information about federated authentication/SSO, see Managing/Using Federated Authentication.

Verifying the OCSP Connector or Driver Version¶

Snowflake uses OCSP to evaluate the certificate chain when making a connection to Snowflake. The driver or connector version and its configuration both determine the OCSP behavior. For more information about the driver or connector version, their configuration, and OCSP behavior, see OCSP Configuration.

OCSP Response Cache Server¶

Note

The OCSP response cache server is currently supported by SnowSQL 1.1.55 and higher.

Snowflake clients initiate every connection to a Snowflake service endpoint with a “handshake” that establishes a secure connection before actually transferring data. As part of the handshake, a client authenticates the TLS/SSL certificate for the service endpoint. The revocation status of the certificate is checked by sending a client certificate request to one of the OCSP (Online Certificate Status Protocol) servers for the CA (certificate authority).

A connection failure occurs when the response from the OCSP server is delayed beyond a reasonable time. The following caches persist the revocation status, helping alleviate these issues:

Memory cache, which persists for the life of the process.
File cache, which persists until the cache directory (e.g. ~/.cache/snowflake or ~/.snowsql/ocsp_response_cache) is purged.
Snowflake OCSP response cache server, which fetches OCSP responses from the CA’s OCSP servers hourly and stores them for 24 hours. Clients can then request the validation status of a given Snowflake certificate from this server cache.

Important

If your server policy denies access to most or all external IP addresses and web sites, you must whitelist the cache server address to allow normal service operation. The cache server hostname is ocsp*.snowflakecomputing.com:80.

If you need to disable the cache server for any reason, set the SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED environment variable to false. Note that the value is case-sensitive and must be in lowercase.

If none of the cache layers contain the OCSP response, the client then attempts to fetch the validation status directly from the OCSP server for the CA.

Connection Error Handling¶

Cannot open self /usr/bin/snowsql or archive /usr/bin/snowsql.pkg (Linux Only)

Due to a limitation in pyinstaller (the program that packages SnowSQL into a stand-alone executable from Python source code), prelink mistakenly strips parts of the snowsql executable and causes this error.

To avoid this issue, the SnowSQL installer attempts to update the prelink configuration file in /etc/prelink.conf.d/snowsql.conf for the snowsql executable such that prelink does not alter the file. Unfortunately, this configuration update cannot be made by the SnowSQL auto-upgrade process.

Work with your system administrator to run the following command on your workstation:

$ sudo bash -c "echo '-b snowsql' > /etc/prelink.conf.d/snowsql.conf"

Note

If you install snowsql in your user home directory, this issue is less likely to occur because prelink is configured, by default, to scan the shared binary directories (e.g. /usr/bin or /bin) and does not alter programs in your home directory.

Connection Parameters Reference¶

`-a` , `--accountname`¶

Description

Required

Specifies the full name of your account (provided by Snowflake). Note that your full account name may include additional segments that identify the region and cloud platform where your account is hosted.

Account name examples by region

If your account name is xy12345:

Cloud Platform / Region

Full Account Name

AWS

US West (Oregon)

xy12345

US East (Ohio)

xy12345.us-east-2.aws

US East (N. Virginia)

xy12345.us-east-1

US East (Commercial Gov - N. Virginia)

xy12345.us-east-1-gov.aws

Canada (Central)

xy12345.ca-central-1.aws

EU (Ireland)

xy12345.eu-west-1

EU (Frankfurt)

xy12345.eu-central-1

Asia Pacific (Tokyo)

xy12345.ap-northeast-1.aws

Asia Pacific (Mumbai)

xy12345.ap-south-1.aws

Asia Pacific (Singapore)

xy12345.ap-southeast-1

Asia Pacific (Sydney)

xy12345.ap-southeast-2

GCP

US Central1 (Iowa)

xy12345.us-central1.gcp

Europe West2 (London)

xy12345.europe-west2.gcp

Europe West4 (Netherlands)

xy12345.europe-west4.gcp

Azure

West US 2 (Washington)

xy12345.west-us-2.azure

East US 2 (Virginia)

xy12345.east-us-2.azure

US Gov Virginia

xy12345.us-gov-virginia.azure

Canada Central (Toronto)

xy12345.canada-central.azure

West Europe (Netherlands)

xy12345.west-europe.azure

Switzerland North (Zurich)

xy12345.switzerland-north.azure

Southeast Asia (Singapore)

xy12345.southeast-asia.azure

Australia East (New South Wales)

xy12345.australia-east.azure

Important

If either of the following conditions is true, your account name is different than the structure described in this example:

If your Snowflake Edition is VPS, please contact Snowflake Support for details about your account name.

If AWS PrivateLink is enabled for your account, your account name requires an additional privatelink segment. For more details, see AWS PrivateLink & Snowflake.

This connection parameter can also be set in the configuration file.

Value
String

Also, the value can be an environment variable:

Linux/macOS

$SNOWSQL_ACCOUNT

Windows

%SNOWSQL_ACCOUNT%

For example, in Linux or macOS:
$ export SNOWSQL_ACCOUNT=xy12345

$ snowsql -a $SNOWSQL_ACCOUNT
Default

None

`-u` , `--username`¶

Description

Specifies the login name of the user with whom you connect to the specified account.

This connection parameter can also be set in the configuration file.

Value
String

The value can be an environment variable:

Linux/macOS

$SNOWSQL_USER

Windows

%SNOWSQL_USER%

For example, in Linux or macOS:
$ export SNOWSQL_USER=jdoe

$ snowsql -u $SNOWSQL_USER
Default

None

`-d` , `--dbname`¶

Description

Specifies the database to use by default in the client session (can be changed after login).

Value

String

The value can be an environment variable:

Linux/macOS

$SNOWSQL_DATABASE

Windows

%SNOWSQL_DATABASE%

This connection parameter can also be set in the configuration file.

Default

None

`-s` , `--schemaname`¶

Description

Specifies the database schema to use by default in the client session (can be changed after login).

Value

String

The value can be an environment variable:

Linux/macOS

$SNOWSQL_SCHEMA

Windows

%SNOWSQL_SCHEMA%

This connection parameter can also be set in the configuration file.

Default

None

`-r` , `--rolename`¶

Description

Specifies the role to use by default for accessing Snowflake objects in the client session (can be changed after login).

This connection parameter can also be set in the configuration file.

Value

String

The value can be an environment variable:

Linux/macOS

$SNOWSQL_ROLE

Windows

%SNOWSQL_ROLE%

Default

None

`-w` , `--warehouse`¶

Description

Specifies the virtual warehouse to use by default for queries, loading, etc. in the client session (can be changed after login).

This connection parameter can also be set in the configuration file.

Value

String

The value can be an environment variable:

Linux/macOS

$SNOWSQL_WAREHOUSE

Windows

%SNOWSQL_WAREHOUSE%

Default

None

`-h` , `--host` — Deprecated¶

Description

Provided for backward compatibility/internal use

Specifies the address of the host to which you connect in Snowflake.

This parameter is no longer used because the host address is determined automatically by concatenating the account name you specified (using either -a or --account) and the Snowflake domain (snowflakecomputing.com).

Value

String

Default

None

`-p` , `--port` — Deprecated¶

Description

Provided for backward compatibility/internal use

Specifies the port number to use for connection.

This parameter is no longer used because the port number for Snowflake is always 443.

Value

String

Default

None

`--region` — Deprecated¶

Description

Provided for backward compatibility/internal use

Specifies the ID for the region where your account is located.

This parameter is no longer used. Instead, include the region information as part of the account name; for more details, see -a , --accountname (in this topic).

Value

N/A

Default

N/A

`-m` , `--mfa-passcode`¶

Description

Specifies the second token for MFA (multi-factor authentication) if you pass in the passcode in the command line.

Value

String

Default

None

`--mfa-passcode-in-password`¶

Description
Appends the MFA passcode to the end of the password.

You can force the password prompt and type the password followed by the MFA passcode. For example if the MFA token was 123456 and the password was PASSWORD:
$ snowsql ... -P ...

Password: PASSWORD123456
Value

N/A (parameter doesn’t take a value)

Default

N/A

`--abort-detached-query`¶

Description

Aborts a query if the connection between the client and server is lost.

Value

Boolean

Default

False (i.e. an active query does not abort if the connection is lost)

`--probe-connection`¶

Description

Test connectivity to Snowflake and report the results. Note that this is an experimental option used mainly to print out the TLS/SSL certificate chain.

Value

N/A (parameter doesn’t take a value)

Default

N/A

`--authenticator`¶

Description

Specifies the authenticator to use for verifying user login credentials.

Value

String (Constant):

snowflake uses the internal Snowflake authenticator.

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

https://<your_okta_account_name>.okta.com (i.e. the URL endpoint for Okta) authenticates through native Okta (only supported if your IdP is Okta).

oauth authenticates using OAuth. When OAuth is specified as the authenticator, you must also set the token parameter to specify the OAuth token (see below).

For more information, see Managing/Using Federated Authentication and OAuth with Clients, Drivers, and Connectors.

Default

snowflake

Note

The externalbrowser authenticator is only supported in terminal windows that have web browser access. For example, a terminal window on a remote machine accessed through a SSH (Secure Shell) session may require additional setup to open a web browser.

If you don’t have access to a web browser, but your IdP is Okta, you can use native Okta (i.e. set the authenticator to https://<your_okta_account_name>.okta.com).

token=<string>
Specifies the OAuth token to use for authentication, where <string> is the token. This parameter is required only when the authenticator=oauth parameter is set.

Default is none.

`-v` , `--version`¶

Description

Use the specified SnowSQL version or, if no version is specified, display the latest SnowSQL version installed.

Value

String

Default

None

`--versions`¶

Description

Lists all available versions of SnowSQL that can be installed and run. To install an earlier SnowSQL version from the list, use the -v option and specify the version you want to install.

Value

N/A (parameter doesn’t take a value)

Default

N/A

`--noup`¶

Description

Disables auto-upgrade for this run. If this option is not included and a newer version is available, SnowSQL automatically downloads and installs the new version. The next time you run SnowSQL, the new version is used.

Value

N/A (parameter doesn’t take a value)

Default

N/A

`-D` , `--variable`¶

Description

Defines SnowSQL variables on the command line. This option can be used to set specific variables to use in Snowflake.

Value
String

For example:
$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=$DB_KEY ...
Default

None

`-o` , `--option`¶

Description

Defines SnowSQL configuration options on the command line. These options override any options that have been set in the SnowSQL configuration file. For descriptions of the options you can set/override, see SnowSQL Configuration Options Reference.

Value

String

Default

None

`-f` , `--filename`¶

Description

Specifies a SQL file to execute in batch mode.

The value can be a file name (including the directory path, if needed) or a URL to the file.

Value

String

Default

None

`-q` , `--query`¶

Description

Specifies a SQL query to execute.

The value can be a single SQL query or a semicolon-separated list of queries to execute (e.g. 'select current_user(); select current_role()').

Value

String

Default

None

`--config`¶

Description

Specifies the location (i.e. directory path) for the SnowSQL configuration file. Include this connector parameter if you want to move or copy the configuration file from the default location.

Value

String

Default

OS-specific:

Linux/macOS

~/.snowsql/

Windows

%USERPROFILE%\.snowsql\

`-P` , `--prompt`¶

Description

Forces a password prompt when the password is stored in the SnowSQL configuration file.

Value

N/A (parameter doesn’t take a value)

Default

N/A

`-M`, `--mfa-prompt`¶

Description

Forces a prompt for the second token for MFA. Alternatively use --mfa-passcode <string> if you want to pass in to the command line.

Value

N/A (parameter doesn’t take a value)

Default

N/A

`-c` , `--connection`¶

Description

Specifies a connection to use, where the specified string is the name of a connection defined in the SnowSQL configuration file. For more details, see Using Named Connections (in this topic).

Value

String

Default

None

`--single-transaction`¶

Description

Combined with --filename, --query, or standard input commands, this option wraps BEGIN/COMMIT around the statements to ensure all commands complete successfully or no change is applied.

Value

N/A (parameter doesn’t take a value)

Default

N/A

Note

Note that if the input commands use BEGIN, COMMIT, or ROLLBACK, this option will not work correctly. Also, if any command cannot be executed inside a transaction block, this option will cause the command to fail.

`--private-key-path`¶

Description

Path to private key file in PEM format used for key pair authentication. The private key file must be encrypted, and the passphrase must be specified in the environment variable SNOWSQL_PRIVATE_KEY_PASSPHRASE.

Value

String

Default

None

`--disable-request-pooling`¶

Description

By default, snowsql uses connection pooling. Connection pooling usually reduces the lag time to make a connection. However, it can slow down client failover to an alternative DNS when a DNS problem occurs. This parameter allows you to turn off connection pooling.

This parameter applies only to customers who have replication enabled.

Value

N/A (parameter doesn’t take a value)

Default

N/A

`-U` , `--upgrade`¶

Description

Force upgrade of SnowSQL to the latest version if it is not downloaded in the local directory.

Value

N/A (parameter doesn’t take a value)

Default

N/A

Note

Requires the bootstrap executable of SnowSQL 1.1.63 or newer version. Download it from the UI.

`-K` , `--client-session-keep-alive`¶

Description

Keep the session active indefinitely, even if there is no activity from the user.

Value

N/A (parameter doesn’t take a value)

Default

N/A

Note

Internally the parameter CLIENT_SESSION_KEEP_ALIVE is set to true for the session.

`-?` , `--help`¶

Description

Shows the command line quick usage guide.

Value

N/A (parameter doesn’t take a value)

Default

N/A

Connecting Through SnowSQL¶

Connection Syntax¶

Specifying Passwords When Connecting¶

Using Environment Variables¶

Configuring Default Connection Settings¶

Verifying the Network Connection to Snowflake with SnowCD¶

Using Named Connections¶

Defining Named Connections in the Configuration File¶

Connecting to Snowflake Using a Named Connection¶

Using Key Pair Authentication¶

Key Rotation¶

Using a Proxy Server¶

Using a Web Browser for Federated Authentication/SSO¶

Verifying the OCSP Connector or Driver Version¶

OCSP Response Cache Server¶

Connection Error Handling¶

Connection Parameters Reference¶

-a , --accountname¶

-u , --username¶

-d , --dbname¶

-s , --schemaname¶

-r , --rolename¶

-w , --warehouse¶

-h , --host — Deprecated¶

-p , --port — Deprecated¶

--region — Deprecated¶

-m , --mfa-passcode¶

--mfa-passcode-in-password¶

--abort-detached-query¶

--probe-connection¶

--authenticator¶

-v , --version¶

--versions¶

--noup¶

-D , --variable¶

-o , --option¶

-f , --filename¶

-q , --query¶

--config¶

-P , --prompt¶

-M, --mfa-prompt¶

-c , --connection¶

--single-transaction¶

--private-key-path¶

--disable-request-pooling¶

-U , --upgrade¶

-K , --client-session-keep-alive¶

-? , --help¶

`-a` , `--accountname`¶

`-u` , `--username`¶

`-d` , `--dbname`¶

`-s` , `--schemaname`¶

`-r` , `--rolename`¶

`-w` , `--warehouse`¶

`-h` , `--host` — Deprecated¶

`-p` , `--port` — Deprecated¶

`--region` — Deprecated¶

`-m` , `--mfa-passcode`¶

`--mfa-passcode-in-password`¶

`--abort-detached-query`¶

`--probe-connection`¶

`--authenticator`¶

`-v` , `--version`¶

`--versions`¶

`--noup`¶

`-D` , `--variable`¶

`-o` , `--option`¶

`-f` , `--filename`¶

`-q` , `--query`¶

`--config`¶

`-P` , `--prompt`¶

`-M`, `--mfa-prompt`¶

`-c` , `--connection`¶

`--single-transaction`¶

`--private-key-path`¶

`--disable-request-pooling`¶

`-U` , `--upgrade`¶

`-K` , `--client-session-keep-alive`¶

`-?` , `--help`¶