Specifying your Snowflake credentials¶
This topic covers the following subjects:
Before you can use Snowflake CLI, you must add your credentials to connect to Snowflake. You can add your Snowflake credentials by using any of the following methods:
Important
Beginning with Snowflake version 8.24, network administrators have the option to require multi-factor authentication (MFA) for all connections to Snowflake. If your administrator decides to enable this feature, you must configure your client or driver to use MFA when connecting to Snowflake. For more information, see the following resources:
Add credentials using a Snowflake CLI connection command¶
To add Snowflake credentials using the Snowflake CLI connection add
command:
Enter the following shell command:
snow connection add
When prompted, supply the required connection, account, username parameters, and any desired optional parameters:
Name for this connection: <connection-name> Snowflake account name: <account-name> Snowflake username: <user-name> Snowflake password [optional]: <password-value> Role for the connection [optional]: <role-name> Warehouse for the connection [optional]: <warehouse-name> Database for the connection [optional]: <database-name> Schema for the connection [optional]: <schema-name> Connection host [optional]: <host-name> Connection port [optional]: <port-value> Snowflake region [optional]: <region-name>
Snowflake CLI uses the connection context (database, schema, role, and so on) when performing any command. You can change this behavior by using environment variables or by using dedicated connections.
Add Snowflake credentials using a configuration file¶
Snowflake CLI lets you add connection definitions to a configuration file. A connection definition refers to a collection of connection parameters.
Snowflake CLI uses a a global configuration file called config.toml
.
If the file does not exist, running any snow
command for the first time automatically creates an
empty config.toml
file that you can then populate with the desired connections.
For more information about toml
file formats, see TOML (Tom’s Obvious Minimal Language).
Snowflake Python libraries currently support TOML version 1.0.0.
Snowflake CLI looks for the config.toml
file in the following locations, in order:
If you specify the
--config-file
option (such as,snow --config-file ./my-config-file-path
), Snowflake CLI uses the specified configuration file.If a
~/.snowflake
directory exists on your machine, Snowflake CLI uses the~/.snowflake/config.toml
file.Otherwise, Snowflake CLI uses the
config.toml
file in the one of the following locations, based on your operating system:Linux:
~/.config/snowflake/config.toml
, but you can update it with with XDG varsWindows:
%USERPROFILE%\AppData\Local\snowflake\config.toml
Mac:
~/Library/Application Support/snowflake/config.toml
Note
For MacOS and Linux systems, Snowflake CLI requires the config.toml
file to limit its file permissions to read and write for the file owner only. To
set the file required file permissions execute the following commands:
chown $USER config.toml
chmod 0600 config.toml
To add credentials in a configuration file:
In a text editor, open the
config.toml
file for editing, such as the following for the Linux vi editor:vi config.toml
Add a new Snowflake connection definition. You must prefix the configuration with connections.
For example, to add a Snowflake connection called myconnection with the credentials account myaccount, user profile johndoe, and password hunter2, add the following lines to the configuration file:
[connections.myconnection] account = "myaccount" user = "jondoe" password = "hunter2" warehouse = "my-wh" database = "my_db" schema = "my_schema"
Connection definitions support the same configuration options available in the Python Connector.
Snowflake CLI also supports the
connections.toml
configuration file. The file should be placed in the same directory as theconfig.toml
file, and it should contain only connections. Configurations inconnections.toml
require a different section name, withoutconnections
.Note
For MacOS and Linux systems, Snowflake CLI requires the
connections.toml
file to limit its file permissions to read and write for the file owner only. To set the file required file permissions execute the following commands:chown $USER connections.toml chmod 0600 connections.toml
If both the
config.toml
andconnections.toml
configurations contain connections, Snowflake CLI uses only configurations fromconnections.toml
.Optional: Add more connections, as shown:
[connections.myconnection-test] account = "myaccount" user = "jondoe-test" password = "hunter2" warehouse = "my-test_wh" database = "my_test_db" schema = "my_schema"
Save changes to the file.
If you do not want to use the config.toml
file for a specific situation, you can create a temporary connection that relies only on command-line parameters and system environment variables.
Change the default connection for Snowflake CLI¶
By default, Snowflake CLI uses the default
connection. You can change this default value by
changing it in the config.toml
file:
default_connection_name = "my_prod_connection"
You can also change the default connection by setting the SNOWFLAKE_DEFAULT_CONNECTION_NAME
environment variable, as shown:
export SNOWFLAKE_DEFAULT_CONNECTION_NAME="my_prod_connection"
You can quickly switch between multiple connections with the snow connection set-default
command, as shown:
snow connection set-default "my_test_connection"
Default connection set to: my_test_connection
The command also updates the default_connection_name parameter
in the config.toml
file.
Use environment variables for Snowflake credentials¶
You can specify Snowflake credentials in system environment variables instead of in configuration files. You can use the following generic environment variables only to replace connection parameters:
SNOWFLAKE_ACCOUNT
SNOWFLAKE_USER
SNOWFLAKE_PASSWORD
SNOWFLAKE_DATABASE
SNOWFLAKE_SCHEMA
SNOWFLAKE_ROLE
SNOWFLAKE_WAREHOUSE
SNOWFLAKE_AUTHENTICATOR
SNOWFLAKE_PRIVATE_KEY_PATH
SNOWFLAKE_SESSION_TOKEN
SNOWFLAKE_MASTER_TOKEN
You can also use environment variables to override configuration parameters using the following formats:
SNOWFLAKE_<config-section>_<variable>=<value>
SNOWFLAKE_CONNECTIONS_<connection-name>_<param>=<value>
For example:
export SNOWFLAKE_CONNECTIONS_MYCONNECTION_ACCOUNT="myaccount"
You can specify some credentials, such as account and user, in the configuration file, and specify the password in an environment variable as follows:
Define the following connection configuration, as appropriate for your Snowflake account:
[connections] [connections.myconnection] account = "myaccount" user = "jdoe"
Create a generic system environment variable for the password as follows:
export SNOWFLAKE_PASSWORD="xyz2000"
You can also override a value in the configuration file by using a system environment variable. Assume the config.toml
file contains the following:
[connections]
[connections.myconnection]
account = "myaccount"
user = "jdoe"
password = "xyz2000"
You can supply a different password for that connection by creating the following environment variables:
export SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD="pass1234"
In these two examples, Snowflake CLI uses pass1234
for the password.
If you do not want to use the config.toml
file for a specific situation, you can create a temporary connection that relies only on command-line parameters and system environment variables.
Snowflake CLI uses the following precedence hierarchy to determine which value to use when a parameter is defined in multiple locations:
Command-line parameters
Connection-specific environment variables, such as
SNOWFLAKE_CONNECTION_<name>_USER
config.toml
fileGeneric environment variables, such as
SNOWFLAKE_USER
.
Use a private key file for authentication¶
To use private key file for authentication, your connection configuration requires you to set the authenticator
value to SNOWFLAKE_JWT
and provide path to file with your private key similar to the following:
Specify the
--private_key-path
option in thesnow connection add
command, as shown:snow connection add \ --connection-name jwt \ --authenticator SNOWFLAKE_JWT \ --private-key-path "~/.ssh/sf_private_key.p8"
Use the configuration file:
[connections.jwt] account = "my_account" user = "jdoe" authenticator = "SNOWFLAKE_JWT" private_key_path = "~/sf_private_key.p8"
For more details on configuring key pair authentication, see Key-pair authentication and key-pair rotation.
Note
If your private key is passphrase-protected, set the PRIVATE_KEY_PASSPHRASE
environment variable to that passphrase.
Use OAuth authentication¶
To use connect using OATH, you can do either of the following:
Specify the
--token-file-path
option in thesnow connection add
command, as shown:snow connection add --token-file-path "my-token.txt"
In the
config.toml
file, setauthenticator = "oauth"
, and add thetoken_file_path
parameter to the connection definition, as shown:[connections.oauth] account = "my_account" user = "jdoe" authenticator = "oauth" token_file_path = "my-token.txt"
Use multi-factor authentication (MFA)¶
To use MFA:
Set up multi-factor authentication in Snowflake and set the
authenticator
parameter tosnowflake
(which is a default value).If you want to use a Duo-generated passcode instead of the push mechanism, modify the
passcode
orpasscode_in_password
parameters inconfig.toml
as described in Using MFA in Python.
Enable MFA caching¶
To enable MFA caching:
For your account, set
ALLOW_CLIENT_MFA_CACHING = true
.In your
config.toml
file, addauthenticator = username_password_mfa
to your connection.
Use SSO (single sign-on)¶
If you have configured Snowflake to use single sign-on (SSO), you can configure your client application to use SSO for authentication. See Using SSO with client applications that connect to Snowflake for details.