Installing and Configuring SnowSQL

This topic describes how to download SnowSQL, install it on all supported platforms, and configure it using connection parameters, user options, and variables.

In this Topic:

Downloading the SnowSQL Installer

The SnowSQL installer is provided as a file that can be downloaded from the Snowflake web interface or as an artifact distributed through Amazon S3.

In addition, Snowflake is distributed as a package that can be installed through Homebrew Cask for Mac OS users.

Note

Downloading and installing SnowSQL is only required for major and minor versions. For patch versions (and builds), SnowSQL upgrades automatically by default. For more information, see What is Auto-upgrade?

Web Interface

To download the SnowSQL installer from the web interface:

  1. In the Snowflake web interface, click Help > Download... to display the Downloads dialog.

  2. Select CLI Client (snowsql) on the left, then click the download icon on the right for the installer that matches your client platform:

    Snowflake SnowSQL options in Downloads dialog

Note

The Snowflake GPG Public Key file is provided to optionally verify the signature of the SnowSQL installer for Linux, if you download the package from Amazon S3. For information, see Amazon S3.

Amazon S3

You can download the SnowSQL installer directly from the S3 artifact repository. No authentication is required. To determine the latest SnowSQL version that is available, see Client Changes by Version.

Run curl (or an equivalent command line tool) to download the installer. The curl syntax is as follows:

$ curl -o snowsql-<version>-<os>.[bash|pkg|msi] https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/<bootstrap_version>/<os>/snowsql-<version>-<os>.[bash|pkg|msi]

Where:

<bootstrap_version>
The combined SnowSQL major and minor versions. For example, for version 1.2.3, the major version is 1 and the minor version is 2, so the bootstrap version is 1.2.
<version>
The combined SnowSQL major, minor, and patch versions. For example, for version 1.2.3, the major version is 1, the minor version is 2, and the patch version is 3. So, the version is 1.2.3.

For more information about SnowSQL versions, see Understanding SnowSQL Versioning.

Linux

The S3 URL pattern for Linux is as follows:

https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/<bootstrap_version>/linux_x86_64/snowsql-<version>-linux_x86_64.bash

For example, to download the SnowSQL installer where <bootstrap_version> is 1.1 and <version> is 1.1.22:

$ curl -o snowsql-1.1.22-linux_x86_64.bash https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/1.1/linux_x86_64/snowsql-1.1.22-linux_x86_64.bash

To optionally verify the signature for the downloaded package:

  1. Download and import the latest Snowflake GPG public key from the Snowflake web interface or the public keyserver.

    To download from the web interface,

    1. In the Snowflake web interface, click Help > Download... to display the Downloads dialog.
    2. Select CLI Client (snowsql) on the left, then click the Snowflake GPG Public Key icon on the right.

    To download from the keyserver:

    $ gpg --keyserver hkp://keys.gnupg.net --recv-keys 69BE019A
    
  2. Download the GPG signature along with the bash installer and verify the signature:

    $ curl -o snowsql-1.1.22-linux_x86_64.bash https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/1.1/linux_x86_64/snowsql-1.1.22-linux_x86_64.bash
    $ curl -o snowsql-1.1.22-linux_x86_64.bash.sig https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/1.1/linux_x86_64/snowsql-1.1.22-linux_x86_64.bash.sig
    $ gpg --verify snowsql-1.1.22-linux_x86_64.bash.sig snowsql-1.1.22-linux_x86_64.bash
    gpg: Signature made Wed 22 Feb 2017 04:31:58 PM UTC using RSA key ID 69BE019A
    gpg: Good signature from "Snowflake Computing <snowflake_gpg@snowflake.net>"
    
  3. Your local environment can contain multiple GPG keys; however, for security reasons, Snowflake periodically rotates the public GPG key. As a best practice, we recommend deleting the existing public key after confirming that the latest key works with the latest signed package. For example:

    $ gpg --delete-key "Snowflake Computing"
    

Mac OS

The S3 URL pattern for Mac OS is as follows:

https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/<bootstrap_version>/darwin_x86_64/snowsql-<version>-darwin_x86_64.pkg

For example, to download the SnowSQL installer where <bootstrap_version> is 1.1 and <version> is 1.1.22:

$ curl -o snowsql-1.1.22-darwin_x86_64.pkg https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/1.1/darwin_x86_64/snowsql-1.1.22-darwin_x86_64.pkg

The Mac OS operating system can verify the installer signature automatically, so GPG signature verification is not needed.

Windows

The S3 URL pattern for Windows is as follows:

https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/<bootstrap_version>/windows_x86_64/snowsql-<version>-windows_x86_64.msi

For example, to download the SnowSQL installer where <bootstrap_version> is 1.1 and <version> is 1.1.22:

$ curl -o snowsql-1.1.22-windows_x86_64.msi https://s3-us-west-2.amazonaws.com/sfc-snowsql-updates/bootstrap/1.1/windows_x86_64/snowsql-1.1.22-windows_x86_64.msi

The Windows operating system can verify the installer signature automatically, so GPG signature verification is not needed.

Installing SnowSQL Using the Installer

Linux

  1. Open a terminal window.

  2. Run the Bash script installer:

    $ bash snowsql-linux_x86_64.bash
    
  3. Follow the instructions provided by the installer.

  4. Open a new terminal window to run snowsql.

Note

The installation can be automated by setting the following environment variables:

  • SNOWSQL_DEST: Target directory of the snowsql executable.
  • SNOWSQL_LOGIN_SHELL: The login shell initialization file, which includes the PATH environment update.
$ SNOWSQL_DEST=~/bin SNOWSQL_LOGIN_SHELL=~/.profile bash snowsql-linux_x86_64.bash

Mac OS

  1. Run the PKG file by double-clicking snowsql-darwin_x86_64.pkg.
  2. Follow the instructions provided by the installer.
  3. Open a new terminal window or double-click the SnowSQL application icon to run snowsql.

Note

Double-clicking the SnowSQL application icon starts snowsql in the current Terminal window, if one exists, or opens a new window to start the application. If you cannot see the window running snowsql, ensure the window is not minimized, hidden, or located on a second monitor.

Also, the installation can be automated by running the installer from the command line. The target directory can be set to either CurrentUserHomeDirectory (/Applications directory) or LocalSystem (~/Applications directory):

$ installer -pkg snowsql-darwin_x86_64.pkg -target CurrentUserHomeDirectory

Windows

  1. Run the MSI file by double-clicking snowsql-windows_x86_64.msi.
  2. Follow the instructions provided by the installer.
  3. Open a new terminal window to run snowsql.

Note

The installation can be automated by running the MSI installer msiexec from the command line. The target directory cannot be changed from %ProgramFiles%\Snowflake SnowSQL. For example:

C:\Users\snowflake> msiexec /i snowsql-windows_x86_64.msi /q

Installing SnowSQL Using Homebrew Cask (Mac OS)

Homewbrew Cask is a popular extension of Homebrew used for package distribution, installation, and maintenance. There is no separate SnowSQL installer to download. If Homebrew Cask is installed on your workstation, you can install Snowflake directly.

Run the brew cask command:

$ brew cask install snowflake-snowsql

Understanding SnowSQL Versioning

SnowSQL version numbers consist of three or four digits: <major version>.<minor version>.<patch version>.<build number>.

For example, version 1.2.3.45678 indicates the major version is 1, the minor version is 2, the patch version is 3, and the build number is 45678.

To determine the SnowSQL version that currently starts when you run the client, use the -v option without a value:

$ snowsql -v

  Version: 1.0.0.38165

In general, the following guidelines apply to the different version types:

Major version:A change in the major version indicates dramatic improvements in the underlying Snowflake service. A new major version breaks backward compatibility. You will need to download and install the latest SnowSQL version from the web interface.
Minor version:A change in the minor version indicates improvements to support forward compatibility in either SnowSQL or the underlying Snowflake service. A new minor version does not break backward compatibility, but we strongly recommend that you download and install the latest SnowSQL version from the web interface.
Patch version:A change in the patch version indicates small enhancements or bug fixes were applied. The auto-upgrade feature automatically installs all patch versions.
Build number:A change in the build number indicates SnowSQL was newly built. The auto-upgrade feature automatically installs all new builds.

Note

If a minor version is released, the functionality in your current version should continue to work, but any newly-released bug fixes and features will not be available via the auto-upgrade feature. Therefore, we strongly recommended that you download and install the latest SnowSQL version if the minor version is increased.

What is Auto-upgrade?

By default, SnowSQL upgrades itself automatically to the latest patch version or build. (A new major or minor version requires a manual download and installation.) When a newer patch version or build is available, SnowSQL downloads the new binary in a background process and executes the current version. The next time you run SnowSQL, the new version starts.

To illustrate the process:

  1. For a fresh installation, you download the SnowSQL installer (e.g., version 1.0.0.38102) using the Snowflake web interface and install the client.
  2. Each time you run SnowSQL, the client checks whether a newer version is available in the SnowSQL upgrade repository.
  3. If a newer version (e.g., version 1.0.0.38165) is available, SnowSQL downloads it as a background process while the current installed version.
  4. The next time you run SnowSQL, the client executes version 1.0.0.38165 while checking if a newer version is available.

Disabling Auto-upgrade

The --noup option prevents SnowSQL from downloading a new version, if available. You can specify this option while logging into Snowflake to prevent an auto-upgrade during that specific session. For example:

$ snowsql --noup

Alternatively, add the noup = true option to the configuration file to prevent SnowSQL from auto-upgrading until the option is removed or set to false.

Running a Previous SnowSQL Version

If you encounter an issue with the latest SnowSQL version, e.g., version 1.0.0.38326, you can temporarily run a previous version.

To determine the SnowSQL version that currently starts when you run the client, use the -v option without a value:

$ snowsql -v

  Version: 1.0.0.38165

To display a list of available SnowSQL versions, use the --versions option:

$ snowsql --versions

  1.0.0.38165
  1.0.0.38102

To install an earlier SnowSQL version from the list, use the -v option and specify the version you want to install. For example, to install version 1.0.0.38102:

$ snowsql -v 1.0.0.38102

  Installing version: 1.0.0.38102  [####################################]  100%

Use the same option to specify the version you want to run when you start SnowSQL:

$ snowsql -v 1.0.0.38102

Configuring SnowSQL

Configure SnowSQL by modifying the config configuration file. The file supports the following categories of settings:

The default location of the file is:

Linux/Mac OS:~/.snowsql/
Windows:%USERPROFILE%\.snowsql\

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

Connection Parameters

Optionally set the default connection parameters in the [connections] section, e.g. your account name, username, and the default database and warehouse. This section also supports the ability to define named connections with different connection parameters.

Default Connection

We recommend configuring default connection parameters to simplify your connection process. Configure the default connection parameters by removing the comment symbol from any of the following parameters:

#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.
#proxy_host = <string>    # Proxy server hostname. Optional.
#proxy_port = <string>    # Proxy server port. Optional.

Note

Add the region connection parameter if you connect to one of the following Snowflake regions:

  • US East: region = us-east-1
  • EU (Frankfurt): region = eu-central-1

The default region is US West.

Attention

  • The password is stored in plain text so you must explicitly secure the config file to restrict access. For example, in Linux or Mac OS, you can set the read permissions to you alone by running chmod:

    $ chmod 700 ~/.snowsql/config
    
  • If your password includes special characters, enclose the password in either single quotes or double quotes.

Named Connections

If you want the ability to make multiple simultaneous connections to Snowflake, or if you simply want to store different sets of connection configurations, you can add named connections. In the configuration file, add a separate [connections] section with a unique name. Specify the connection parameters for the named connection.

Following is an example connection named example_connection for a user account in the EU (Frankfurt region):

[connections.example_connection]
accountname = abc123
username = jsmith
password = xxxxxxxxxxxxxxxxxxxx
dbname = mydb
schemaname = public
warehousename = mywh
region = eu-central-1

For information on connecting to Snowflake using a named connection, see Connecting Using a Named Connection.

Configuration Options

Configure the behavior of SnowSQL by adding settings in the [options] section of the configuration file:

[options]
<option_name> = <option_value>

Where:

  • option_name is the name of the option (case-insensitive). If an invalid name is specified, SnowSQL displays an error.
  • option_value specifies a supported value (case-insensitive) for the option, as described below.
+---------------------------+--------------------+-------------------------------------------------------------------------------+
| Name                      | Value              | Help                                                                          |
+---------------------------+--------------------+-------------------------------------------------------------------------------+
| auto_completion           | True               | Displays auto-completion suggestions for commands and Snowflake objects       |
| echo                      | False              | Outputs the SQL command to the terminal when it is executed                   |
| editor                    | vim                | Changes the editor to use for the !edit command                               |
| execution_only            | False              | Executes queries only                                                         |
| exit_on_error             | False              | Quits when SnowSQL encounters an error                                        |
| friendly                  | True               | Hides the splash text and goodbye message                                     |
| header                    | True               | Outputs the header in query results                                           |
| insecure_mode             | False              | Turns off OSCP certificate checks                                             |
| key_bindings              | emacs              | Changes keybindings for navigating the prompt to emacs or vi                  |
| log_bootstrap_file        | ~/.snowsql/log_..  | SnowSQL bootstrap log file location                                           |
| log_file                  | ~/.snowsql/log     | SnowSQL main log file location                                                |
| log_level                 | CRITICAL           | Changes the log level (critical, debug, info, error, warning)                 |
| noup                      | False              | Turns off auto upgrading Snowsql                                              |
| output_file               | None               | Writes output to the specified file in addition to the terminal               |
| output_format             | psql               | Sets the output format for query results.                                     |
| prompt_format             | [user]#[warehou..  | Sets the prompt format. For help, see the documention                         |
| sfqid_in_error            | False              | Turns on/off Snowflake query id in the error message                          |
| quiet                     | False              | Hides all output                                                              |
| remove_comments           | False              | Removes comments before sending query to Snowflake                            |
| remove_trailing_semicolons | True              | Removes trailing semicolons from SQL text before sending queries to Snowflake |
| results                   | True               | If set to off, queries will be sent, but no results will be fetched.          |
| rowset_size               | 1000               | Sets the size of rowsets to fetch from the server.                            |
|                           |                    | Set the option low for smooth output, high for fast output.                   |
| stop_on_error             | False              | Stops all queries yet to run when SnowSQL encounters an error                 |
| syntax_style              | default            | Sets the colors for the text of SnowSQL.                                      |
| timing                    | True               | Turns on/off timing for each query                                            |
| variable_substitution     | False              | Substitutes variables (starting with '&') with values                         |
| wrap                      | True               | Truncates lines at the width of the terminal screen                           |
+---------------------------+--------------------+-------------------------------------------------------------------------------+

See SnowSQL Options Reference for descriptions of all valid options.

Note

When connected to Snowflake, you can also set options using the !set command. For more information, see Commands Reference.

Variables

Configure SnowSQL variables by adding them in the [variables] section of the configuration file:

[variables]
<variable_name> = <variable_value>

Where:

  • variable_name is a string of alphanumeric characters (case-insensitive) representing the name of the variable.
  • variable_value is a string representing the value for the variable. If needed, the string can be enclosed by single or double quotes.

Note

While connected to Snowflake, you can also set variables using the !define command. For more information, see Commands Reference.

For information on using variables, see Using Variables.

SnowSQL Options Reference

Options modify the default SnowSQL behavior. You can set options in the configuration file, or using the !set command while connected to Snowflake.

The following options are supported by SnowSQL:

Note

The option names and values are case-insensitive.

auto_completion

Type:Boolean
Description:Enables context-sensitive auto-completion. If enabled, functions, table names, and variables stored in SnowSQL are auto-completed in interactive mode.
Default:auto_completion=True

echo

Type:Boolean
Description:Echoes local input. When set to True, echoes to both stdout and the output file.
Default:echo=False

editor

Type:String (constant)
Description:Specifies the editor to invoke for the !edit command in SnowSQL. Supported values:
  • emacs
  • vi
  • vim
Default:editor=vim

execution_only

Type:Boolean
Description:If enabled, SnowSQL executes queries without fetching data. This option is useful when you only want to measure execution times. Note that returned values include any network latency and are not pure server-side execution times.
Example:execution_only

exit_on_error

Type:Boolean
Description:If enabled, SnowSQL exits when an error occurs. This behavior is useful to stop running queries when an error is encountered.
Example:exit_on_error=True

friendly

Type:Boolean
Description:If disabled, SnowSQL suppresses the startup and exit messages.
Example:friendly=False

insecure_mode

Type:Boolean
Description:Skips the certificate revocation checks using the Online Certificate Status Protocol (OCSP). This option could be used in an emergency situation in which no OCSP service is accessible. Snowflake strongly recommends that you do not enable this option unless directed by Snowflake Support.
Default:insecure_mode=False

key_bindings

Type:

String (constant)

Description:

Key bindings to use. Possible values:

  • emacs — when Emacs mode is enabled, [CTRL]-a is home, [CTRL]-e is end. All Emacs key bindings for the REPL environment are available.
  • vi — when vi mode is enabled, you can use all modal editing features offered by vi in the REPL environment.
Default:

key_bindings=vi

log_file

Type:String (path)
Description:log_file location.
Default:log_file=~/.snowsql/log

log_level

Type:

String (constant)

Description:

Default log level. Possible values:

  • CRITICAL
  • ERROR
  • WARNING
  • INFO
  • DEBUG
Default:

log_level=DEBUG

noup

Type:Boolean
Description:Prevents SnowSQL from downloading and installing a new version if True. By default, SnowSQL auto-upgrades to the latest version if no version is specified.
Default:noup=False

output_file

Type:String (path and file name)
Description:Writes output to the specified file in addition to the terminal output.
Default:None

output_format

Type:

String (constant)

Description:

Specifies the format of the output displayed in the terminal. Possible values:

  • csv
  • fancy_grid
  • grid
  • html
  • latex
  • latex_booktabs
  • mediawiki
  • orgtbl
  • pipe,
  • plain
  • psql
  • rst
  • simple
  • tsv
  • custom

Recommended values: psql, fancy_grid, or grid

Default:

output_format=fancy_grid

sfqid_in_error

Type:Boolean
Description:Includes the Snowflake query ID in error messages.
Default:sfqid_in_error

quiet

Type:Boolean
Description:Removes all output data from the terminal, but continues to display error messages and diagnostic data.
Default:quiet=True

remove_comments

Type:Boolean
Description:Removes comments from the output.
Default:remove_comments=False

remove_trailing_semicolons

Type:Boolean
Description:Removes trailing semicolons from SQL text before sending queries to Snowflake. Note that removing the semicolons can prevent Snowflake from using cached results from different clients when the USE_CACHED_RESULT parameter is enabled.
Default:remove_trailing_semicolons=True

results

Type:Boolean
Description:Returns the query results. If False, no query result is returned except for the execution status.
Default:results=True

rowset_size

Type:Number
Description:Number of rows to fetch at once in interactive mode. Results are then fetched for output one rowset at a time.
Default:rowset_size=1000

stop_on_error

Type:Boolean
Description:Stops query execution but does not exit when an error is encountered.
Default:stop_on_error=False

syntax_style

Type:String
Description:Sets the text colors for SnowSQL. Currently, the only supported value is default.
Default:default

timing

Type:Boolean
Description:Timing of SQL statements and table rendering.
Default:timing=True

variable_substitution

Type:Boolean
Description:Substitutes variables with the values.
Default:variable_substitution=False

wrap

Type:Boolean
Description:Wraps the output by the terminal width. If False, the outputs are truncated.
Default:wrap=True