Redirecting Client Connections

Client Redirect enables redirecting your client connections to Snowflake accounts in different regions for business continuity and disaster recovery, or when migrating your account to another region or cloud platform.

In this Topic:

Introduction to Client Redirect

Client Redirect is implemented through a Snowflake connection object. The connection object stores a secure connection URL that you use with a Snowflake client to connect to Snowflake.

The hostname in the connection URL is composed of your organization name and the connection object name in addition to a common domain name:

organization_name-connection_name.snowflakecomputing.com

The connection object name must be unique across all connection and account names in the organization.

Note that this hostname does not specify the account to which you are connecting. An account administrator determines the account to use by designating the connection in that account to serve as the primary connection. When you use the connection URL to connect to Snowflake, you are connecting to the account that contains the primary connection.

If an outage occurs in a region or cloud platform and the outage affects the account with the primary connection, the administrator can promote a connection in a different account in a different region or cloud platform to serve as the primary connection.

Through this outage, you can continue to use the same connection URL to connect to Snowflake. Snowflake resolves the connection URL to the account with the newly promoted connection (the account outside of the region or cloud platform affected by the outage).

Note

The Snowflake accounts that store the primary and secondary connections must be hosted in different regions.

Client Redirect Flow

  1. Complete the steps in Configuring Client Redirect (in this topic) to create a connection URL for client connections. This includes creating a primary connection and linked secondary connection(s).

  2. Update Snowflake clients to connect using the connection URL. Using a Connection URL (in this topic) contains a list of supported clients and connection details.

  3. In the event of a service outage in the region where the primary connection is located, complete the steps in Redirecting Client Connections (in this topic) to update the connection URL to redirect to a secondary connection.

  4. When the outage is resolved, complete the steps in Redirecting Client Connections to redirect client connections back to the original primary connection.

The following diagrams illustrate the Client Redirect flow for two accounts in the same organization but different regions (Region A and Region B) on either the same or different cloud platforms.

The connection URL for client connections is configured for an account in Region A:

Normal client connections

A service outage in Region A results in failed client connections:

Failed client connections

The connection URL for client connections is now configured for an account in Region B:

Redirected client connections

Example

The following SQL statements go through the client redirect workflow. Each step is explained in detail in the sections that follow in this topic.

Normal Client Connections: Configure Client Redirect

Executed on Source Account
-- Create a new primary connection
CREATE CONNECTION myconnection;

-- View accounts in your organization that are enabled for replication
-- Note the value in the account_name column for the ALTER CONNECTION statement below
SHOW REPLICATION ACCOUNTS;

-- Configure failover accounts for the primary connection
ALTER CONNECTION myconnection
  ENABLE FAILOVER TO ACCOUNTS myorg.myaccount2, myorg.myaccount3;

-- View the details for the connection
SHOW CONNECTIONS;
Executed on Target Account
-- Create a secondary connection linked to the primary connection
-- The secondary connection must be created in an account in a different region from the source account,
-- and the secondary connection name must be the same as the primary connection name
CREATE CONNECTION myconnection
  AS REPLICA OF myorg.myaccount1.myconnection;

-- If either AWS PrivateLink or Azure Private Link is enabled for your account, you must create
-- or update a DNS CNAME record for your connection URL. See the relevant section in this topic for details.

Outage Occurs in Source Region: Failover

Executed on Target Account
-- If an outage occurs in the region where the primary connection is located,
-- promote a secondary connection in a different region to serve as the primary connection
ALTER CONNECTION myconnection PRIMARY;

-- If either AWS PrivateLink or Azure Private Link is enabled for your account, you must
-- update the DNS CNAME record for your connection URL. See the relevant section in this topic for details.

Outage Resolved: Failback

Executed on Source Account
-- Once the outage is resolved, promote the original primary connection back to primary
-- Executed from the account with the connection you want to promote to primary
ALTER CONNECTION myconnection PRIMARY;

-- If either AWS PrivateLink or Azure Private Link is enabled for your account, you must
-- update the DNS CNAME record for your connection URL. See the relevant section in this topic for details.

Configuring Client Redirect

This section describes how to create a primary connection and one or more secondary connections in a connection group.

Prerequisite

Contact Snowflake Support to enable the Client Redirect feature on your accounts. Enabling this feature requires that the Organizations feature must also be enabled on your accounts.

Note

Only account administrators (users with the ACCOUNTADMIN role) can execute the SQL commands in this section.

Create a Primary Connection

Caution

Snowflake assigned your organization a unique, generated name when it was created in the system. The organization name is a part of the connection URL defined in a connection object and submitted by Snowflake clients to access an account. Before you create any connection objects, verify that your organization name in Snowflake is satisfactory. To change your organization name in the system, contact Snowflake Support.

  1. Create a new primary connection using CREATE CONNECTION. The name of each primary connection must be unique across all connection and account names in the organization.

    The connection name is included as part of the connection URL used to connect to Snowflake accounts.

    For example, to create a connection named myconnection:

    CREATE CONNECTION myconnection;
    
  2. Modify this primary connection using an ALTER CONNECTION … ENABLE FAILOVER TO ACCOUNTS statement. Provide a comma-separated list of accounts in your organization that can store a failover option for this connection (i.e. a secondary connection).

    Any account that stores a secondary connection must be hosted in a region different from the account that stores the primary connection. Client Redirect only operates successfully across regions. For example, if you try to redirect client connections from account1 to account2 in the same region, client redirect does not work.

    To see the complete list of accounts in your organization that are enabled for replication, execute SHOW REPLICATION ACCOUNTS.

    For example, allow accounts myaccount2 and myaccount3 in the myorg organization to each store a secondary connection for the myconnection connection:

    ALTER CONNECTION myconnection ENABLE FAILOVER TO ACCOUNTS myorg.myaccount2, myorg.myaccount3;
    
  3. Execute the SHOW CONNECTIONS command to view the details for the connection.

    SHOW CONNECTIONS;
    
    +--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+-------------------------------------------+
    | snowflake_region   | created_on                    | account_name        | name              | comment         | is_primary    | primary                       | failover_allowed_to_accounts        | connection_url                            |
    |--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------|-------------------------------------|-------------------------------------------|
    | AWS_US_WEST_2      | 2020-07-19 14:49:11.183 -0700 | MYORG.MYACCOUNT1    | MYCONNECTION      | NULL            | true          | MYORG.MYACCOUNT1.MYCONNECTION | MYORG.MYACCOUNT2, MYORG.MYACCOUNT3  | MYORG-MYCONNECTION.snowflakecomputing.com |
    +--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+-------------------------------------------+
    

Create a Secondary Connection

Create a secondary connection in one or more accounts, linked to a primary connection using CREATE CONNECTION … AS REPLICA OF. Note that you can only create a secondary connection in an account specified in the ALTER CONNECTION … ENABLE FAILOVER TO ACCOUNTS statement in Create a Primary Connection.

Execute a CREATE CONNECTION … AS REPLICA OF statement in each target account to create a replica of the specified primary connection.

Important

Each secondary connection must have the same name as its primary connection. The connection name is included in the connection URL.

Execute the SQL statements in this section in the target account where you want to create a secondary connection.

  1. Execute the SHOW CONNECTIONS command to view all connections. Copy the value of the primary column for the primary connection. You will use this value when creating the secondary connection in the next step.

    SHOW CONNECTIONS;
    
    +--------------------+-------------------------------+------------------+-------------------+-----------------+---------------+-------------------------------+------------------------------------+--------------------------------------------+
    | snowflake_region   | created_on                    | account_name     | name              | comment         | is_primary    | primary                       | failover_allowed_to_accounts       | connection_url                             |
    |--------------------+-------------------------------+------------------+-------------------+-----------------+---------------+-------------------------------|------------------------------------|--------------------------------------------|
    | AWS_US_WEST_2      | 2020-07-19 14:49:11.183 -0700 | MYORG.MYACCOUNT1 | MYCONNECTION      | NULL            | true          | MYORG.MYACCOUNT1.MYCONNECTION | MYORG.MYACCOUNT2, MYORG.MYACCOUNT3 | MYORG-MYCONNECTION.snowflakecomputing.com  |
    +--------------------+-------------------------------+------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+-------------------------------------------+
    
  2. Execute the CREATE CONNECTION … AS REPLICA OF command to create a secondary connection.

    For example, create a secondary connection named myconnection that is linked to the myorg.myaccount1.myconnection primary connection. After AS REPLICA OF, paste in the fully qualified name of the primary connection (the name that you copied from the SHOW CONNECTIONS output in the previous step).

    CREATE CONNECTION myconnection
      AS REPLICA OF MYORG.MYACCOUNT1.MYCONNECTION;
    
  3. Execute the SHOW CONNECTIONS command to verify the secondary connection was created.

    SHOW CONNECTIONS;
    
    +--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+--------------------------------------------+
    | snowflake_region   | created_on                    | account_name        | name              | comment         | is_primary    | primary                       | failover_allowed_to_accounts        | connection_url                             |
    |--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------|-------------------------------------|--------------------------------------------|
    | AWS_US_WEST_2      | 2020-07-19 14:49:11.183 -0700 | MYORG.MYACCOUNT1    | MYCONNECTION      | NULL            | true          | MYORG.MYACCOUNT1.MYCONNECTION | MYORG.MYACCOUNT2, MYORG.MYACCOUNT3  | MYORG-MYCONNECTION.snowflakecomputing.com  |
    | AWS_US_EAST_1      | 2020-07-22 13:52:04.925 -0700 | MYORG.MYACCOUNT2    | MYCONNECTION      | NULL            | false         | MYORG.MYACCOUNT1.MYCONNECTION |                                     | MYORG-MYCONNECTION.snowflakecomputing.com  |
    +--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+--------------------------------------------+
    

Using a Connection URL

This section provides instructions for referencing a connection URL in the configuration for various Snowflake clients.

Supported Snowflake Clients

The following Snowflake client versions (and higher) support Client Redirect:

Snowflake Client

Version (and Higher)

SnowSQL

1.1.82

Snowflake Connector for Python

1.8.3

Node.js Driver

1.2.0

Go Snowflake Driver

1.2.0

.NET Driver

1.0.0

JDBC Driver

3.8.4

ODBC Driver

2.19.4

Configure Snowflake Clients

Use the following host name for the connection URL when connecting to Snowflake:

Host name: organization_name-connection_name.snowflakecomputing.com

Where:

organization_name

Name of your Snowflake organization. The Snowflake accounts that your users connect to are contained in this organization.

connection_name

Name of the connection object.

Important

AWS PrivateLink or Azure Private Link

Customers using AWS PrivateLink or Azure Private Link to connect to their Snowflake account: Add a privatelink segment to the URL just before snowflakecomputing.com:

organization_name-connection_name.privatelink.snowflakecomputing.com

Snowflake Classic Web Interface

Enter the following URL in a web browser:

https://<organization_name>-<connection_name>.snowflakecomputing.com/

For example:

https://MYORG-MYCONNECTION.snowflakecomputing.com/

Snowflake New Web Interface

Enter the following in the account name field on app.snowflake.com:

<organization-name>-<connection-name>

For example:

MYORG-MYCONNECTION

When using organization-connection to log in, Snowsight navigates to the specific region and locator of the current primary connection. During an outage, once the connection has been redirected, users must log in again via organization-connection to connect to the new primary.

SnowSQL

Specify the host name for the connection URL in the accountname connection parameter in the SnowSQL config file. For information about the config file, see Configuring SnowSQL.

accountname = <organization_name>-<connection_name>
username = <username>
password = <password>

For example:

accountname = MYORG-MYCONNECTION
username = jsmith
password = mySecurePassword

Snowflake Connector for Python

Specify the host name for the connection URL in the account connection parameter when calling the connect function. For more information, see Python Connector API and Using the Python Connector.

con = snowflake.connector.connect (
      account = <organization_name>-<connection_name>
      user = <username>
      password = <password>
)

For example:

con = snowflake.connector.connect (
      account = MYORG-MYCONNECTION
      user = jsmith
      password = mySecurePassword
)

JDBC Driver

Specify the host name for the connection URL in the connection string. For more information, see Configuring the JDBC Driver.

jdbc:snowflake://<organization_name>-<connection_name>.snowflakecomputing.com/?user=<username>&password=<password>

For example:

jdbc:snowflake://MYORG-MYCONNECTION.snowflakecomputing.com/?user=jsmith&password=mySecurePassword

ODBC Driver

Specify the host name for the connection URL in the Server connection parameter. For more information about the connection parameters, see ODBC Configuration and Connection Parameters.

[ODBC Data Sources]
<account_name> = SnowflakeDSIIDriver

[<dsn_name>]
Description     = SnowflakeDB
Driver          = SnowflakeDSIIDriver
Locale          = en-US
SERVER          = <organization_name>-<connection_name>.snowflakecomputing.com

For example:

[ODBC Data Sources]
myaccount = SnowflakeDSIIDriver

[client_redirect]
Description     = SnowflakeDB
Driver          = SnowflakeDSIIDriver
Locale          = en-US
SERVER          = MYORG-MYCONNECTION.snowflakecomputing.com

Node.js Driver

Specify the host name for the connection URL in the account connection option. For more information about the connection parameters, see Using the Node.js Driver.

var configuration = {
  username: '<username>',
  password: '<password>',
  account: <organization_name>-<connection_name>.
}

var connection = snowflake.createConnection(configuration)

For example:

var configuration = {
  username: 'jsmith',
  password: 'mySecurePassword',
  account: MYORG-MYCONNECTION.
}

var connection = snowflake.createConnection(configuration)

Go Snowflake Driver

Specify the host name for the connection URL in the Account parameter. For more information, see Go Snowflake Driver.

cfg := &Config{
  Account: "<organization_name>-<connection_name>",
  User: "<username>",
  Password: "<password>"
}

dsn, err := DSN(cfg)

For example:

cfg := &Config{
  Account: "MYORG-MYCONNECTION",
  User: "jsmith",
  Password: "mySecurePassword"
}

dsn, err := DSN(cfg)

Authentication and Client Redirect

Users must be provisioned in the source account and on each target account.

Federated Authentication & SSO

Configure federated authentication separately in each target account. Provide the identity provider (IdP) details using the setup options in Advanced SAML SSO Features:

Note

Snowflake recommends configuring your SAML 2.0-compliant identity provider (IdP) with the connection URL rather than an account URL so users are redirected to the correct account in case of failover.

OAuth

Configure a security integration object for OAuth in each target account. The security integration object must be identical to the same object in the source account. For instructions, see the appropriate topic:

To retrieve security integration properties, query the DESCRIBE INTEGRATION command for each security integration in the source account. Then recreate each security integration in a target account by executing the CREATE INTEGRATION command.

OAuth Redirect Behavior

If you are using Snowflake OAuth for authenticating a client connection and are connecting to Snowflake using a connection URL, you are prompted to re-authenticate if the connection URL is redirected to another account (e.g. in case of failover). Snowflake OAuth tokens are valid for use in a specific account. When a connection URL is updated to point to an account in a different deployment, the existing OAuth token becomes invalid.

In the case of a failover, when the connection URL is updated to the new account, the client will disconnect with an invalid OAuth access token error. You must re-authenticate and consent to permissions to re-establish the connection.

Verifying the Connection URL Used by Your Users

Query the LOGIN_HISTORY , LOGIN_HISTORY_BY_USER family of table functions to view the login activity for your users within the last 7 days. The output indicates which users and Snowflake clients have been using a connection URL. The REPORTED_CLIENT_TYPE and REPORTED_CLIENT_VERSION columns display the client and version used for each connection to Snowflake, and the CONNECTION column displays the connection URL used, if any.

For example, retrieve up to 100 login events of every user your current role is allowed to monitor in the last 72 hours:

SELECT *
FROM TABLE(INFORMATION_SCHEMA.LOGIN_HISTORY(DATEADD('HOURS',-72,CURRENT_TIMESTAMP()),CURRENT_TIMESTAMP()))
ORDER BY EVENT_TIMESTAMP;

Redirecting Client Connections

In the event of a service outage in the region where the primary connection is located, redirect the client connection to an account that stores a secondary connection.

Promoting a Secondary Connection to Serve as the Primary Connection

Initiating the redirect involves promoting a secondary connection in an available region to serve as the primary connection using ALTER CONNECTION. Concurrently, the former primary connection becomes a secondary connection.

Execute the SQL statements in this section in the target account containing the current secondary connection that you are promoting.

Example:

-- view all connections
SHOW CONNECTIONS;

+--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+--------------------------------------------+
| snowflake_region   | created_on                    | account_name        | name              | comment         | is_primary    | primary                       | failover_allowed_to_accounts        | connection_url                             |
|--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------|-------------------------------------|--------------------------------------------|
| AWS_US_WEST_2      | 2020-07-19 14:49:11.183 -0700 | MYORG.MYACCOUNT1    | MYCONNECTION      | NULL            | true          | MYORG.MYACCOUNT1.MYCONNECTION | MYORG.MYACCOUNT2, MYORG.MYACCOUNT3  | MYORG-MYCONNECTION.snowflakecomputing.com  |
| AWS_US_EAST_1      | 2020-07-22 13:52:04.925 -0700 | MYORG.MYACCOUNT2    | MYCONNECTION      | NULL            | false         | MYORG.MYACCOUNT1.MYCONNECTION |                                     | MYORG-MYCONNECTION.snowflakecomputing.com  |
+--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+--------------------------------------------+

-- promote the secondary connection to serve as the primary connection
ALTER CONNECTION myconnection PRIMARY;

-- verify that the former secondary connection was promoted successfully
SHOW CONNECTIONS;

+--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+--------------------------------------------+
| snowflake_region   | created_on                    | account_name        | name              | comment         | is_primary    | primary                       | failover_allowed_to_accounts        | connection_url                             |
|--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------|-------------------------------------|--------------------------------------------|
| AWS_US_WEST_2      | 2020-07-19 14:49:11.183 -0700 | MYORG.MYACCOUNT1    | MYCONNECTION      | NULL            | false         | MYORG.MYACCOUNT1.MYCONNECTION |                                     | MYORG-MYCONNECTION.snowflakecomputing.com  |
| AWS_US_EAST_1      | 2020-07-22 13:52:04.925 -0700 | MYORG.MYACCOUNT2    | MYCONNECTION      | NULL            | true          | MYORG.MYACCOUNT1.MYCONNECTION | MYORG.MYACCOUNT2, MYORG.MYACCOUNT3  | MYORG-MYCONNECTION.snowflakecomputing.com  |
+--------------------+-------------------------------+---------------------+-------------------+-----------------+---------------+-------------------------------+-------------------------------------+--------------------------------------------+

Verifying the Connection URL is Updated

To verify the connection URL has been updated, you can confirm the region of your current connection. Use the connection URL to connect to Snowflake and execute the CURRENT_REGION function.

select current_region();

Current Limitations of Client Redirect

  • Client Redirect is currently not supported for Reader Accounts.

  • Private connectivity to the new web interface via AWS PrivateLink or Azure Private Link URLs is not currently supported.

  • Client connections using a connection URL and OAuth integration require re-authentication when the connection URL is updated to point to a different account. See OAuth Redirect Behavior (in this topic) for details.