> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snowflake Connector

> Connecting TextQL to Snowflake

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/DZSbL5OfhKo" title="Connect Snowflake to TextQL | AI Data Analysis Tutorial" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Overview

This guide walks you through connecting TextQL to your Snowflake data warehouse using key-pair authentication. You'll need to generate an RSA key pair and configure your Snowflake account to complete the setup.

<Note>
  **Important Authentication Update**

  As of September 2024, Snowflake announced the deprecation of single-factor password authentication for service users (programmatic/API connections). By October 2026, all service connections to Snowflake must use key-pair authentication.

  TextQL connects to Snowflake as a service user and **only supports key-pair authentication** going forward. Some legacy connectors may still use username/password authentication, but all new Snowflake connectors must be configured with key-pair authentication.

  Learn more: [Snowflake's MFA Rollout Documentation](https://docs.snowflake.com/en/user-guide/security-mfa-rollout)
</Note>

## Prerequisites

To connect TextQL with your Snowflake instance, you will need:

* **Account identifier** (your Snowflake locator)
* **Database name** and **Schema**
* **Warehouse name** (optional)
* **Username** for the Snowflake user
* **RSA private key** for key-pair authentication
* **Role name** (optional)

## Generating Your RSA Key Pair

Before creating the connector in TextQL, you need to generate an RSA key pair and register the public key with Snowflake.

### Step 1: Generate Private and Public Keys

Use OpenSSL to generate a 2048-bit RSA key pair:

```bash theme={null}
# Generate private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

# Generate public key from private key
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```

### Step 2: Register Public Key with Snowflake

Copy the public key content (excluding the header and footer lines) and assign it to your Snowflake user:

```sql theme={null}
ALTER USER <username> SET RSA_PUBLIC_KEY='<public_key_content>';
```

For detailed instructions, see the [video tutorial](https://www.youtube.com/watch?v=DZSbL5OfhKo) or [Snowflake's Key-Pair Authentication Guide](https://docs.snowflake.com/en/user-guide/key-pair-auth).

## Creating the Connector in TextQL

### Step 1: Navigate to Connectors Page

1. Go to the [TextQL Connectors Page](https://app.textql.com/connectors)
2. Click **New Connector**

### Step 2: Select Snowflake

Select **Snowflake** from the available connectors to open the configuration form.

### Step 3: Enter Connection Details

The form requires the following information:

| Field | Description | Example |
| - | - | - |
| **Connector Name** | A descriptive name to identify this connection | `My Snowflake Warehouse` |
| **Account Identifier** | Your Snowflake account locator | `xy12345.us-east-1` |
| **Database** | The name of your target Snowflake database | `ANALYTICS_DB` |
| **Schemas** | Schema names within your database, one per line (optional) | `PUBLIC`, `SALES` |
| **Warehouse** | The compute warehouse to use for queries (optional) | `COMPUTE_WH` |
| **Role** | The Snowflake role to assume for this connection (optional) | `ANALYST_ROLE` |

#### Restrict queries to the configured schemas

Database and Schemas normally set the query defaults and table discovery scope. They do not reduce the Snowflake service account's permissions.

Enable **Restrict queries to these schemas** to make TextQL enforce the configured database and allowed schemas for direct table references. A database and at least one schema are required. Enter one schema per line; the first is the default for unqualified table names. Queries may join tables across the listed schemas. This setting allows read queries only, and cannot be combined with SQL write operations. Existing connectors default to having this setting off.

TextQL checks joins, subqueries, and CTEs before executing SQL and qualifies table references against the configured scope. References to other databases or unlisted schemas are rejected. Commands, role changes, dynamic table names, user-defined functions, and unsupported SQL are rejected. If validation is unavailable, the query does not run. Query results and schema metadata are fetched without reusing cached results while this restriction is enabled.

The restriction applies to tables and views throughout the configured schemas, not a selected list of tables. An allowed view can expose data from another schema. This is a TextQL query restriction and does not revoke Snowflake grants or replace Snowflake access controls. Use a service account with appropriate Snowflake permissions as well.

### Step 4: Configure Key-Pair Authentication

**Username:** Your Snowflake username (the user with the registered public key)

**Private Key:** Paste the contents of your RSA private key file (the entire content including the header and footer lines)

```
-----BEGIN PRIVATE KEY-----
<your private key content>
-----END PRIVATE KEY-----
```

<Warning>
  Keep your private key secure and never share it. The private key should only be stored in secure locations and used for authentication purposes.
</Warning>

### Step 5: Test and Create

1. Click **Test Connection** to verify your credentials and network access
2. Once the test succeeds, click **Create Connector** to save the connection

## Reading the Credential from AWS Secrets Manager

If your Snowflake key pair rotates on a schedule, you can point the connector at an AWS Secrets Manager secret instead of pasting the private key. TextQL reads the secret when it connects, so a rotation needs no change in TextQL and no re-entry of the key in each workspace.

Secrets Manager is not a separate authentication method: it is where the credential for **Key Pair** or **Password** auth is read from, so the connector still authenticates to Snowflake the same way.

<Note>
  Fetched secret values are cached for up to 5 minutes, so a rotation can take that long to take effect. Connections made in that window may still use the previous credential and fail if it has already been revoked.
</Note>

### Setting Up Secrets Manager Authentication

1. In the Snowflake connector form, leave **How should users authenticate?** on **Key Pair** (or **Password**)
2. Turn on **Read the credential from AWS Secrets Manager**
3. Enter the **Secret ARN** of the secret holding the credential
4. Enter the **Username**, or map it from the secret in the next step
5. Fill in the **Secret key name** fields for the values the secret carries
6. (Optional) Enter an **IAM Role ARN** for TextQL to assume when reading the secret, plus the **External ID** its trust policy requires

<Note>
  Once the connector is saved, the **Secret ARN**, **IAM Role ARN** and **External ID** are hidden in the edit form and returned blank (marked redacted) in connector API responses. Leave them blank when editing to keep the stored values. Organization admins, or any role with the organization write permission, can reveal them from the edit form, and every reveal is recorded in the audit log.
</Note>

### Mapping Keys Inside the Secret

A secret often holds more than one connector's data as key/value pairs. The **Secret key name** fields say which key inside the secret's JSON supplies which credential, so unrelated keys in the same secret are ignored.

For a secret shaped like this:

```json theme={null}
{
  "demo_data_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "demo_data_passphrase": "...",
  "demo_data_user": "SVC_TEXTQL",
  "other_system_password": "..."
}
```

set **Secret key name: Private Key** to `demo_data_private_key`, **Secret key name: Private Key Passphrase** to `demo_data_passphrase`, and **Secret key name: Username** to `demo_data_user`. Leave a field blank when the secret does not supply it.

Under **Password** auth the same applies with **Secret key name: Password** in place of the key fields.

If the secret's entire value is the credential rather than a JSON object, leave every **Secret key name** field blank.

<Note>
  Because a secret can hold values for many systems, TextQL cannot tell from the config alone whether the mapping is right. Saving a Secrets Manager connector therefore reads the secret, fills the connection in, and attempts a real connection. If that fails, the connector is not created and the failure is reported inline.
</Note>

### Cross-Account Access with an IAM Role

When the secret lives in a different AWS account than your TextQL deployment, create an IAM role in the secret's account and enter its ARN in the **IAM Role ARN** field. The role needs `secretsmanager:GetSecretValue` on the secret (plus `kms:Decrypt` if it uses a customer-managed key), and its trust policy must grant TextQL's service role **both** `sts:AssumeRole` and `sts:TagSession` in **separate statements**.

See [Cross-Account Access with an IAM Role](/core/datasources/databases/postgresql#cross-account-access-with-an-iam-role) on the PostgreSQL page for the full policy examples and the Secrets Manager troubleshooting table, which apply identically here.

## Troubleshooting

### Connection Fails

**Verify the following:**

* Account identifier is correct (including region)
* Database and schema names are accurate
* Warehouse is running or can be auto-resumed
* Snowflake account is accessible

<Note>
  Having trouble connecting? See the [Network Configuration Guide](/core/datasources/databases/network-configuration) for firewall and IP whitelisting setup.
</Note>

### Authentication Errors

**Check:**

* Username is correct and matches the user with the registered public key
* Private key is properly formatted (includes header and footer)
* Public key is correctly registered in Snowflake (`DESCRIBE USER <username>` should show `RSA_PUBLIC_KEY`)
* User has appropriate permissions and role access

### Public Key Registration Issues

**Common problems:**

* Public key content includes header/footer lines (should only be the key content)
* Extra whitespace or line breaks in the public key
* Public key not matching the private key being used

**To verify public key registration:**

```sql theme={null}
DESCRIBE USER <username>;
-- Check that RSA_PUBLIC_KEY is populated
```

### Timeout Errors

**Possible causes:**

* Warehouse is suspended and taking time to resume
* Network connectivity issues
* Firewall blocking connection
* Incorrect account identifier

## What's Next

Once your Snowflake connector is set up, you can:

* Ask Ana natural language questions about your data
* Generate SQL queries and visualizations
* Create reports and dashboards
* Share insights with your team

The connector automatically handles session management and warehouse resumption. For optimal performance:

* Configure an appropriate warehouse size for your workload
* Set up a dedicated role with appropriate privileges
* Enable **Restrict queries to these schemas** to limit direct table references, and use Snowflake role grants to control database permissions.
* Rotate your key pairs periodically for enhanced security


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.