Connecting to Snowflake

This guide walks you through connecting DataRecs to a Snowflake account. Snowflake connections use RSA key-pair authentication — you generate a key-pair, register the public key on a dedicated Snowflake user, and give DataRecs the private key. There is no password.

Availability

Snowflake connectivity is rolling out. If you don’t see Snowflake in your workspace yet, contact support to have it enabled for your account.

Prerequisites

• A DataRecs account with access to a workspace.
• ACCOUNTADMIN (or a role that can create users, roles, and grants) in Snowflake for the one-time setup.
• Your Snowflake account identifier (org-account form, e.g. MYORG-ACCOUNT1).
• openssl available locally to generate the key-pair.

Step 1 — Generate an RSA key-pair

Generate a 2048-bit RSA key-pair in PKCS#8 format. Keep the private key secret; you’ll give the public key to Snowflake and the private key to DataRecs.

# Private key (unencrypted PKCS#8). Optionally add -aes256 to encrypt it with a passphrase.
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out datarecs_rsa_key.p8 -nocrypt

# Public key
openssl rsa -in datarecs_rsa_key.p8 -pubout -out datarecs_rsa_key.pub

Step 2 — Create a least-privilege read-only role and user in Snowflake

Create a dedicated role, warehouse grant, and service user, then register the public key. Grant only what reconciliation needs to read — no write access, no ACCOUNTADMIN.

-- 1. A dedicated read-only role
CREATE ROLE IF NOT EXISTS DATARECS_RECON_RO;

-- 2. Let it use a warehouse and read your data
GRANT USAGE ON WAREHOUSE DATARECS_WH        TO ROLE DATARECS_RECON_RO;
GRANT USAGE ON DATABASE  ANALYTICS           TO ROLE DATARECS_RECON_RO;
GRANT USAGE ON SCHEMA    ANALYTICS.PUBLIC    TO ROLE DATARECS_RECON_RO;
GRANT SELECT ON ALL TABLES    IN SCHEMA ANALYTICS.PUBLIC TO ROLE DATARECS_RECON_RO;
GRANT SELECT ON FUTURE TABLES IN SCHEMA ANALYTICS.PUBLIC TO ROLE DATARECS_RECON_RO;

-- 3. A dedicated service user for DataRecs
CREATE USER IF NOT EXISTS DATARECS_RECON
  DEFAULT_ROLE      = DATARECS_RECON_RO
  DEFAULT_WAREHOUSE = DATARECS_WH;
GRANT ROLE DATARECS_RECON_RO TO USER DATARECS_RECON;

-- 4. Register the PUBLIC key (paste the key body WITHOUT the -----BEGIN/END----- lines)
ALTER USER DATARECS_RECON SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...IDAQAB';

Tip

Paste only the base64 body of datarecs_rsa_key.pub into RSA_PUBLIC_KEY — strip the -----BEGIN PUBLIC KEY----- / -----END PUBLIC KEY----- header lines and any newlines.

Step 3 — Create the connection in DataRecs

Provide your account identifier, the service user, the warehouse and role, an optional default database/schema, and the private key (datarecs_rsa_key.p8).

Console

1. Navigate to Connections in the sidebar.
2. Click New Connection and select Snowflake.
3. Fill in the connection details:
   • Name — a friendly label for this connection.
   • Account identifier — e.g. MYORG-ACCOUNT1.
   • User — DATARECS_RECON.
   • Warehouse — DATARECS_WH.
   • Role — DATARECS_RECON_RO.
   • Database / Schema — optional defaults (e.g. ANALYTICS / PUBLIC).
   • Private key — paste the contents of datarecs_rsa_key.p8.
   • Private key passphrase — only if you encrypted the key in Step 1.
4. Click Test Connection to validate.
5. Once the test passes, click Save.

DataRecs CLI

The CLI creates a connection from a JSON file:

datarecs connections create --file ./snowflake.json --workspace-id "$WORKSPACE_ID"

snowflake.json:

{
  "name": "analytics-snowflake",
  "type": "snowflake",
  "config": {
    "account": "MYORG-ACCOUNT1",
    "user": "DATARECS_RECON",
    "warehouse": "DATARECS_WH",
    "role": "DATARECS_RECON_RO",
    "database": "ANALYTICS",
    "schema": "PUBLIC",
    "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBg...\n-----END PRIVATE KEY-----\n"
  }
}

Terraform

resource "datarecs_connection" "analytics_snowflake" {
  workspace_id = datarecs_workspace.main.id
  name         = "analytics-snowflake"
  type         = "snowflake"
  credentials = {
    account     = "MYORG-ACCOUNT1"
    user        = "DATARECS_RECON"
    warehouse   = "DATARECS_WH"
    role        = "DATARECS_RECON_RO"
    database    = "ANALYTICS"
    schema      = "PUBLIC"
    private_key = var.snowflake_private_key
  }
}

tofu plan
tofu apply

REST API

curl -X POST https://api.datarecs.io/connections \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analytics-snowflake",
    "type": "snowflake",
    "workspace_id": "<workspace-id>",
    "config": {
      "account": "MYORG-ACCOUNT1",
      "user": "DATARECS_RECON",
      "warehouse": "DATARECS_WH",
      "role": "DATARECS_RECON_RO",
      "database": "ANALYTICS",
      "schema": "PUBLIC",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
    }
  }'

What happens behind the scenes

1. DataRecs validates the connection by authenticating to Snowflake with your key-pair (no password).
2. The private key is envelope-encrypted and stored securely — it is never shown back to you and never leaves the encrypted store in plaintext.
3. Reconciliation reads your tables through the read-only role you granted, aggregating inside Snowflake so only the results leave your account.

Troubleshooting

Issue	Solution
JWT token is invalid	The public key registered on the user doesn’t match the private key you supplied. Re-run Step 2 with the public key from the same key-pair.
Authentication failed	Check the account identifier (org-account form), user, and that the role is granted to the user.
Object does not exist or not authorized	The role is missing a USAGE/SELECT grant on the warehouse, database, schema, or table. Re-check the grants in Step 2.
Key requires a passphrase	If you encrypted the key with -aes256, supply the private key passphrase field too.
No warehouse assigned	Set Warehouse on the connection (and/or DEFAULT_WAREHOUSE on the user).