# Connect to Snowflake

> Read a Snowflake schema into a Schemity ERD with a key pair or an access token. Every connection field, the read-only role's grants, and what a refresh reads, without a warehouse.

Source: https://schemity.com/doc/connect-snowflake/

Connecting a Snowflake diagram lets Schemity read one schema of your warehouse and draw it: tables, columns, keys, views and dynamic tables. The connection is read-only. Schemity reads the schema and never changes it, so there is no migration on a Snowflake diagram. To design changes, keep using a design-only diagram as described in [Snowflake schema design](https://schemity.com/doc/snowflake/).

## How do I connect Schemity to Snowflake?

Click **+** above the diagram list, set **DB type** to **Snowflake**, click **Connect to a database**, and leave **Connect via** on **Direct connection**. Schemity talks to Snowflake's SQL REST API over HTTPS, so there is no SSH Tunnel, port or encryption setting. Fill in the fields below and click **Test** to check them before you save.

## What do the Snowflake connection fields mean?

- **Identifier** - `ORGNAME-ACCOUNTNAME` as Snowsight shows it under **Account details**, the legacy `locator.region` form, or the full host for a private link or China (a value ending in `snowflakecomputing.com` or `snowflakecomputing.cn`).
- **User** - the Snowflake user Schemity signs in as.
- **Role** - the role every statement runs as. It is required: what the diagram shows is what this role can see.
- **Credential** - **Private key** or **Access token**.
  - With **Private key**: **Private key** is the `.p8` key file (Schemity stores only its path, and the file stays where you keep it), and **Passphrase** is the key's passphrase. Leave the passphrase blank for an unencrypted key, or to keep the current one.
  - With **Access token**: **Token source** is **Token**, to type or paste the token, or **Command**, a shell command whose output is the token, run on every connect. A typed token is stored in your keychain; leave it blank when editing to keep the current one.
- **Database** and **Schema** - the one schema the diagram reads. Type them as Snowflake shows them. A name created in double quotes, such as a lower-case one, is typed with its quotes. Once **Database** is filled in, the refresh button inside **Schema** lists the schemas the role can see.

The passphrase and the token are kept in your operating system's keychain, never in the diagram file. The command source works the same way as a password command; see [credentials from a command](https://schemity.com/doc/connections-overview/#can-the-password-come-from-a-command-instead-of-being-stored).

## How do I create a key pair for the Schemity user?

Generate an encrypted private key, then its public key:

```bash
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes-256-cbc -out rsa_key.p8
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```

For an unencrypted key, use `-nocrypt` in place of `-v2 aes-256-cbc`. Then register the public key on the user, pasting the body of `rsa_key.pub` without its `BEGIN` and `END` lines:

```sql
ALTER USER svc SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
```

Pick `rsa_key.p8` in **Private key** and type the passphrase you chose. A key encrypted with an older scheme such as DES3 is refused with a message that says how to re-encrypt it with AES.

## How do I use a programmatic access token instead?

Create one in Snowsight under **Governance & security > Users & roles**, or with SQL:

```sql
ALTER USER svc ADD PROGRAMMATIC ACCESS TOKEN schemity_read ROLE_RESTRICTION = 'SCHEMITY_READER';
```

Snowflake shows the token once, so copy it then. A token lasts 15 days by default and up to 365. Two Snowflake rules apply to tokens:

- A human user (`TYPE=PERSON`) must be subject to a network policy to sign in with a token, unless your admin changes `NETWORK_POLICY_EVALUATION` in the token policy.
- A service user's token needs a role restriction, as in the example.

Choose **Access token** in **Credential** and paste the token, or set **Token source** to **Command** to fetch it from a secret manager.

## Which grants does the role need?

A read-only role needs `USAGE` on the database and the schema, and `SELECT` on the tables:

```sql
CREATE ROLE SCHEMITY_READER;
GRANT USAGE ON DATABASE ANALYTICS TO ROLE SCHEMITY_READER;
GRANT USAGE ON SCHEMA ANALYTICS.PUBLIC TO ROLE SCHEMITY_READER;
GRANT SELECT ON ALL TABLES IN SCHEMA ANALYTICS.PUBLIC TO ROLE SCHEMITY_READER;
GRANT SELECT ON ALL VIEWS IN SCHEMA ANALYTICS.PUBLIC TO ROLE SCHEMITY_READER;
GRANT ROLE SCHEMITY_READER TO USER svc;
```

`GET_DDL` silently leaves out what the role cannot see, so a table without a grant is missing from the diagram, along with any foreign key that points to it.

Columns with a masking policy or a tag need `APPLY MASKING POLICY` or `APPLY TAG` (with `USAGE` on the database and schema) for `GET_DDL` to name the policy or tag. Without them, Snowflake writes `#UNKNOWN_POLICY` or `#UNKNOWN_TAG` in their place; Schemity removes those placeholders and the column reads as a plain column. These privileges also let a role apply policies and tags.

Schemity sends the role you name with every statement. A user whose default secondary roles are on (new users get `ALL`) may see through those roles as well. To make the diagram show exactly what the named role sees, turn them off for the Schemity user:

```sql
ALTER USER svc SET DEFAULT_SECONDARY_ROLES = ();
```

## What does a refresh read, and does it use warehouse credits?

Opening or refreshing the diagram runs metadata statements only: `GET_DDL` for the schema, `SHOW TABLES`, `SHOW VIEWS` and `SHOW DYNAMIC TABLES` for the list of objects and the row counts, and `SHOW COLUMNS` for each object `GET_DDL` does not describe. Schemity names no warehouse in any request, and in the spikes the account's warehouse stayed suspended through connect, open and refresh.

Every object the listings name appears on the diagram:

- **Tables** come from `GET_DDL`, with their columns, types, defaults, keys, foreign keys, `CHECK` constraints, clustering keys and comments. Column comments become field descriptions.
- **Views** and **dynamic tables** are read-only, with `view` or `dyn` in the footer.
- **Objects `GET_DDL` could not read** show their columns only, without keys or constraints, and a notice names them.

Row counts come from `SHOW TABLES` metadata, not from a `COUNT(*)`.

## What can I change on a connected Snowflake diagram?

The structure comes from the warehouse: tables, columns, keys and foreign keys cannot be added, edited or removed, and the dialogs say so: "Read from Snowflake. Schemity reads this schema and does not change it. To design changes, import the schema into a design-only Snowflake diagram."

Everything that belongs to the diagram stays editable: descriptions, layout, colours, legends, context views and [virtual relations](https://schemity.com/doc/virtual-relations/). **Save** writes the diagram file only. There is no **Impact**, **Preview changes** or **Migrate** on a connected Snowflake diagram. The SQL dialog still exports the full `CREATE` script, with table and column `COMMENT`s from the descriptions. An AI agent connected through Schemity's MCP server follows the same rule: it can read the diagram and edit descriptions, legends and context views, and a structural change is refused with the same sentence.

To design changes, import the schema into a design-only Snowflake diagram with **Import SQL**, as [Snowflake schema design](https://schemity.com/doc/snowflake/) describes.

## What happens when a table disappears from the warehouse?

On open and refresh, **Database changed** lists what is different from the saved diagram, with an undo step. A role reads only what it is granted, so Schemity cannot tell a dropped table from a revoked grant. A table or foreign key that is gone reads as "No longer visible to role ROLE: dropped, or access lost".

If a read sees no tables at all for a diagram that had some, Schemity asks before clearing anything: **Keep the diagram** changes nothing, and **Clear the diagram** empties it.

## Can I connect a Snowflake diagram I designed offline?

Yes. Edit its connection and click **Connect to a database**. On the first open, Schemity merges what the warehouse has onto your drawing and shows **Database changed** with an undo step. Nothing from the design is sent to Snowflake. From then on the diagram is structure-locked; to keep designing, keep a design-only copy.

## What do the Snowflake error messages mean?

- **"No Snowflake account answers at HOST."** The account identifier is wrong. Copy it from **Account details** in Snowsight.
- **"Snowflake did not accept this key for user USER."** The user name is wrong, or the public key is not set on the user (`ALTER USER ... SET RSA_PUBLIC_KEY`).
- **"Snowflake did not accept this token."** The token expired or was revoked, or the user is not under a network policy, which Snowflake requires for tokens.
- **"Role ROLE does not exist or is not granted to USER."** Check the role name and `GRANT ROLE ... TO USER`.
- **"The private key could not be decrypted. Check the passphrase."** The passphrase is wrong or missing for an encrypted key.
- **"Snowflake is still preparing the schema after two minutes."** Try again; a very large schema can take longer the first time.

A missing schema or a role without `USAGE` on it returns Snowflake's own message.

## Do I need a license to connect to Snowflake?

Snowflake diagrams are a licensed feature of the desktop app, available during the trial. Connecting to a live database is unlocked by a one-time desktop license, as for every engine.

## Next

See the other engines in the [connections overview](https://schemity.com/doc/connections-overview/), or tidy the layout on [The ERD Canvas](https://schemity.com/doc/erd-canvas/).