---
title: "Read Snowflake with no key in your code: the while.sh docs"
url: https://while.sh/en/docs/building-blocks/snowflake/
updated: 2026-11-21
---

# Snowflake

Your app reads a Snowflake warehouse through its SQL API, with a key pair or an access token. The private key, or the access token, stays in while's vault: neither your app nor your agent sees it.

> You, to your AI: Connect our Snowflake warehouse: I want today's sales in the app.

## What your agent writes

Your agent writes it in while.yaml, at the root of your app:

```yaml titre="while.yaml"
apiVersion: while/v1
project: my-app
services:
  - name: web
    port: 3000
    connections: [snowflake]
```

## What your app receives

Your app receives these environment variables at every deployment:

| Variable | What it holds |
|---|---|
| `<NAME>_URL` | The connection's address: SNOWFLAKE_URL for a snowflake connection. The key is not in it; while adds the signed token to every call made through this address. |

## When to use it

Use it to read the data of a Snowflake warehouse from an app or an agent, without copying a key.

## How it works

while calls Snowflake's SQL API for your app, with a key pair or a programmatic access token (PAT). The private key stays in while's vault, and while itself signs the token (JWT) that Snowflake expects.

Setting it up takes five steps.

1. In Snowflake, a person creates a read-only role (USAGE on the warehouse, the database and the schema, SELECT on the tables) and a service user that has only this role (TYPE = SERVICE, DEFAULT_ROLE).

2. They generate a 2048-bit RSA key pair (`openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt`, or a key encrypted with a passphrase), and set the public key on the user: `ALTER USER … SET RSA_PUBLIC_KEY='MIIB…'`.

3. Your agent declares the connection: `declare_connection` `{ name: snowflake, model: snowflake, account: orgname-accountname, user, role, warehouse }`. With a PAT, it is `model: snowflake_pat`, without `user`. while works out the account's address and how to authenticate, then a person who can configure connections approves it.

4. A person pastes the private key, or the PAT, on the connection's page in while. An encrypted key is pasted with its passphrase, in the same place. Neither the key nor its passphrase goes through your agent: while refuses a declaration that contains them.

5. Your agent checks with `call_connection`, running `SELECT CURRENT_VERSION()` through `POST /api/v2/statements`. A 200 gives the version. A 401 means the public key set on the user does not match the private key, or the account or the user is wrong.

## What to know

A query starts with POST `/api/v2/statements`, in JSON (statement, timeout, database, schema, warehouse, role). A short query answers 200 with its rows; a long one answers 202 with a statementHandle, and GET `/api/v2/statements/<statementHandle>` is read again until the 200. A large result is split into partitions (resultSetMetaData.partitionInfo), and each one is read with GET …?partition=\<n>. POST `/api/v2/statements/<statementHandle>/cancel` cancels a query.

while lets these calls through as reads, since the SQL API runs every query with POST. The Snowflake role decides what a query can write: give it a read-only role. The JWT lasts one hour at most, and while signs it again before it expires.

## Pricing

These prices are the same on every plan, excluding VAT:

| Resource | Price | Details |
|---|---|---|
| Gateway calls | €0.30 per 1,000 calls | beyond 500,000 per month, Pro plan |

## Your agent's MCP tools

Your agent handles it with the `declare_connection` and `call_connection` tools.
