A connection tells Kater which warehouse to read and which schemas to model. Schema sync then reads those schemas and writes the source layer for you: one database dataset per table, and a Kater dataset over each one.

Supported warehouses

Kater stores the warehouse credential, encrypted for your organisation. It is never written to your content. Every query runs on Kater’s server as that one role, including queries started from the CLI, VS Code or an agent.

Create a connection

Make a connection through your agent, in the admin console’s Settings › Connections, or with kater admin connection create in your own terminal. The first one can also be part of onboarding, through kater init. New connection and Schema sync show each way, step by step.

kater admin connection create snowflake_prod --warehouse-type snowflake \
  --account ACCOUNT --warehouse COMPUTE_WH --role ROLE \
  --auth-method key_pair --user USER --private-key-file PATH_TO_KEY \
  --database DEMO_DB --schema DEMO_DB.ANALYTICS_AD_REPORTING

The command does not write the folder in your local copy. The Kater API tests the sign-in, stores the credential and commits connection.yaml to the content store. Then run kater git pull in your local copy to get the connection’s folder. --dry-run prints connection.yaml and saves nothing.

connection.yaml

Each connection folder holds one connection.yaml. It names the warehouse type, that warehouse’s settings and the databases and schemas to sync. It holds no secrets.

1
# Kater connection. Edit by hand or with kater admin connection update. Never change id.
2
# After changing databases, schemas or tables, run kater sync --resource-type db_dataset.
3
# Comments are not kept. Put notes in description.
4

5
id: d5c8ffbf-4c47-4195-b949-cc9fcd0186f2
6
name: duckdb_sample
7
warehouse_metadata:
8
  warehouse_type: duckdb
9
  path: shop.duckdb
10
label: DuckDB sample
11
databases:
12
- db__database: shop
13
  name: shop
14
  timezone: UTC
15
  schemas:
16
  - db__schema: sales
17
    name: sales
18
    tables: []
19
    exclude_tables: []
20
query_timezone_conversion: do_not_convert
21
query_timeout: 300

• Edit by hand or by command. kater admin connection update NAME takes --add-schema, --remove-schema, --add-table, --remove-table, --exclude-table, --include-table, --timezone, --label and --description. It changes only what you give, and keeps the other lines of the file.
• Two lists narrow a schema. tables names the only tables to sync, so a new table in the warehouse does not sync. exclude_tables names the tables never to sync, so a new table syncs. --add-table and --remove-table change tables. --exclude-table and --include-table change exclude_tables. When you clear some tables of a schema in Select schemas, the admin console writes exclude_tables, or changes tables when the schema already lists them.
• Names follow the warehouse. Snowflake folds an unquoted name to upper case, so analytics and ANALYTICS are one database and "Analytics" is another. DuckDB ignores case.

connection_context.md

This file holds what an agent should know about the connection before it answers or changes a model. Agents read it at the start of a conversation, with the organisation’s rules.md.

# Connection Context (duckdb_sample)

This connection reads shop.duckdb, a local DuckDB file in this folder: 240 customers, 3,000 orders from 2025-01-01 to 2026-09-30 and their order events, in schema sales. The data is generated, not a real shop's. Its SQL is DuckDB's.

Run schema sync

Schema sync reads the databases and schemas that connection.yaml selects, writes a database dataset for each table, then creates a Kater dataset for each database dataset that lacks one. It never rewrites what you added to a Kater dataset.

The Files terminal runs the same commands. There, a sync with no --scope works on the shared layer of the connection the terminal’s folder is in, and a real sync needs the settings permission.

• Sync state lives in .kater/dataset-sync/. It keeps reruns stable. Keep it with your content, and never delete it to force a sync.
• Custom SQL datasets are skipped. Sync changes only the Kater datasets it made or adopted.

Sync on a schedule

A job in kater.config.yaml at the content root keeps the connection current. This example schedules a sync at 02:00 UTC and runs the connection’s tests after each sync. The schedule stays off until you set enabled: true.

1
jobs:
2
  sync_snowflake:
3
    command: kater sync
4
    connection: snowflake_prod_connection
5
    deployment: production
6
    schedule:
7
      enabled: false
8
      cron: "0 2 * * *"
9
      timezone: UTC
10
  test_snowflake:
11
    command: kater test
12
    connection: snowflake_prod_connection
13
    deployment: production
14
    after: sync_snowflake

See Scheduled jobs for how jobs run.

Check it worked

If something looks wrong