Connecting through SnowSQL¶

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).

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

Copy

Windows:

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

Copy

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

Defining named connections in the configuration file¶

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

   Linux/macOS:

   ~/.snowsql/

   Windows:

   %USERPROFILE%\.snowsql\

2. 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 with the account identifier myorganization-myaccount:

   [connections.my_example_connection]
   accountname = myorganization-myaccount
   username = jsmith
   password = xxxxxxxxxxxxxxxxxxxx
   dbname = mydb
   schemaname = public
   warehousename = mywh
   

   Copy

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

Copy

-a , --accountname¶

Description:

Required

Specifies your account identifier. Specify the account identifer in this form: organization_name-account_name (for example, myorganzation-myaccount).

For instructions on finding the account identifier, see Configuring a client, driver, library, or third-party application to connect to 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=myorganization-myaccount

$ snowsql -a $SNOWSQL_ACCOUNT

Copy

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

Copy

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 identifier you specified (using either -a or --account) and the Snowflake domain (snowflakecomputing.cn).

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. 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

Copy

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 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, 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 (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 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://<okta_account_name>.okta.com).

--token¶

Description:

Specifies the OAuth token to use for authentication. This parameter is required only when you specify --authenticator=oauth.

Value:

String

Default:

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 ...

Copy

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()').

You can also specify multiple queries to run asynchronously by separating the queries with ;>. The following example starts SnowSQL and runs all four queries asynchronously:

snowsql -o log_level=DEBUG -q "select * from SNOWSQLTABLE;> insert into table table1 values(2);> select 5;>select count(*) from testtable;"

Value:

String

Default:

None

--query_tag¶

Description:

Specifies the tags to use when running a query.

The value can be a single tag or a semicolon-separated list of tags.

Value:

String

Default:

Value of the SNOWSQL_QUERY_TAG environment variable.

--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 an interactive password prompt.

By default, SnowSQL uses the password stored in the $SNOWSQL_PWD environment variable. Using this option allows you to override the password defined in $SNOWSQL_PWD.

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.

Caution

While unencrypted private keys are supported, Snowflake strongly recommends using encrypted private keys when connecting to Snowflake.

For more information, see Using Key Pair Authentication & Key Pair Rotation.

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

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

--include_connector_version¶

Description:

Displays the version of the Snowflake Connector for Python software that is packaged in the SnowSQL binary.

Value:

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

Default:

N/A

-? , --help¶

Description:

Shows the command line quick usage guide.

Value:

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

Default:

N/A