kater admin connection

A connection is a folder under connections/ that holds one connection.yaml. The file names the warehouse, its settings without secrets, and the databases and schemas that Kater reads. See Connections and schema sync.

1
id: d5c8ffbf-4c47-4195-b949-cc9fcd0186f2
2
name: snowflake_prod_connection
3
warehouse_metadata:
4
  warehouse_type: snowflake
5
  snowflake_account_id: myorg-myaccount
6
  warehouse: COMPUTE_WH
7
  role: SYSADMIN
8
  auth_method: key_pair
9
label: Snowflake production
10
databases:
11
- db__database: DEMO_DB
12
  name: demo_db
13
  timezone: UTC
14
  schemas:
15
  - db__schema: ANALYTICS_AD_REPORTING
16
    name: analytics_ad_reporting
17
    tables: []
18
    exclude_tables: []
19
query_timezone_conversion: do_not_convert
20
query_timeout: 300

Commands

About connection.yaml

• Edit it by hand, or with kater admin connection update. Both make the same changes. update rewrites only the lines that it changes, so the file keeps your comments.
• The id never changes. kater admin connection create writes it one time.
• The file holds no credentials. Kater stores each warehouse’s credential on its server, encrypted. A key such as password or user in the file is an error.
• A change reaches Kater when you push it. Commit the change in your local copy, then run kater git push.
• Sync after a selection change. After you change the databases, schemas or tables, run kater sync --resource-type db_dataset.

Warehouse settings

Each settings option writes one key under warehouse_metadata. create and update refuse an option that belongs to another warehouse.

• Names are read as the warehouse reads them. This covers --database, --schema, --table, the selection options of update, --timezone and sync --sources. In Snowflake, analytics and ANALYTICS are one database, and "Analytics" is another.
• Create the connection first. create makes a new folder, so create the connection before you put its file in connections/.
• Both writers preview. create and update take --dry-run, which prints the YAML and saves nothing. They also take --json.
• Removing a schema leaves its files. Its DDL files stay until kater sync --resource-type db_dataset --prune runs.

Checks on connection.yaml

Kater checks connection.yaml wherever it reads it.

• In VS Code, problems show on the line that they are about, as you type.
• On compile, a compile of a connection’s whole modeling scope, or of the whole root, lists them under connection_checks. kater compile exits with an error code when one is an error, so CI cannot merge a broken file.
• Selection drift gives a warning in the same places. A selected schema or a listed table with no file needs kater sync --resource-type db_dataset. Files left for an unselected schema or an excluded table need kater sync --resource-type db_dataset --prune.
• Files only. These checks read files only. Tables that are new in the warehouse show only when a sync queries it.

Who can run it

• Creating a connection, and sign-in, need the settings:manage permission.
• Changing a connection needs edit access to its connection.yaml.
• test and objects reach the warehouse through Kater’s API, with your organisation’s stored credential. They need the connections:query permission. Your computer never holds a warehouse credential.

Run kater admin connection in your own terminal. The Kater MCP’s kater tool and the Files terminal in Kater do not run it.

Examples

# List the connections you can read
kater admin connection list
# Check a connection's file and its credential
kater admin connection show snowflake_prod_connection
# Check that Kater can reach the warehouse
kater admin connection test snowflake_prod_connection
# Take a schema out of the connection's selection
kater admin connection update snowflake_prod_connection --remove-schema DEMO_DB.ANALYTICS_VELIR_GA4
# Replace the connection's stored sign-in with a new key pair
kater admin connection sign-in snowflake_prod_connection --user kater_service --private-key-file ~/.ssh/kater_key.p8

See also

• kater admin
• All commands