The catalog

zsql catalog reads the warehouse’s own metadata — schemas, tables, columns, types, keys, comments — and writes it to catalog/<datasource>.json. That file is what zsql generate drafts a model from and what zsql check validates the model against, so a typo in a physical name is caught without a connection.

The file is committed, not gitignored. It is schema, not data, and a diff in review is where drift wants to be seen: a column that changed type shows up as a line in a pull request rather than as a planning failure later.

zsql catalog read -d warehouse --schema public     # the first read
zsql catalog read -d warehouse sales.orders        # one more table
zsql catalog sync -d warehouse                     # re-read what the file records
zsql catalog search orders                         # find a table
zsql catalog show orders                           # one table's columns

Every one of these is local only. With one datasource in datasources.yml, -d is unnecessary.

read

$ zsql catalog read -d cs --schema main
cs: 0 tables, 20 views, 517 columns (main) -> catalog/cs.json (418 ms)
next: zsql generate

--schema reads a schema whole and is repeatable; on ClickHouse and MySQL it names the database. Naming tables instead reads exactly those, as schema.table or table:

$ zsql catalog read -d cs sim_base.cs_contact_f
cs: since the catalog read 2026-10-24:
  table added:    sim_base.cs_contact_f
added   sim_base.cs_contact_f
cs: 1 tables, 20 views, 602 columns (main, 1 added by name) -> catalog/cs.json (420 ms)

On a terminal, read with nothing named offers a schema picker. Without a terminal it refuses and says what to name:

error: say which: --schema NAME (repeatable), table names, or --all

--all is never the default, because a read of every schema on a large warehouse is slow and mostly noise. zsql datasource test lists the schemas the credential can see, which is the list to pick from.

A read merges. Everything already in the file stays unless the warehouse says it is gone; nothing is dropped because a read failed, only because a read succeeded and did not find it.

Provenance

The file records not just what was read but which reads happened, which is what makes sync able to repeat them exactly:

{
  "datasource": "cs",
  "adapter": "duckdb",
  "read_at": "2026-10-24T11:21:54Z",
  "read_by": "0.6.5",
  "scopes": [{"schema": "main", "read_at": "2026-10-24T11:21:53Z"}],
  "added": [{"schema": "sim_base", "name": "cs_contact_f", "read_at": "2026-10-24T11:21:54Z"}],
  "tables": [
    {
      "schema": "main",
      "name": "cs_contact_subchannel_d",
      "kind": "view",
      "columns": [
        {"name": "contact_subchannel_id", "data_type": "VARCHAR", "nullable": true, "position": 1}
      ]
    }
  ]
}

scopes are the schemas read whole; added are the tables read one at a time. A table in a scope is re-read by sync and dropped when the schema no longer holds it; a table in added is re-read on its own and dropped only when that read says it is gone. kind distinguishes a table from a view. A column carries the warehouse’s own type spelling rather than 0sql’s — mapping the two is generation’s job, and keeping the original is what lets a mapping be corrected later without re-reading — plus its nullability, its ordinal position so a generated model keeps the warehouse’s column order, and its declared character length where it has one (varchar(64) is 64, text is nothing), which is the signal behind the sampling guidance.

A table also carries an approximate row count from the warehouse’s own statistics, never a count, which is what a generated cost comes from; its comment; its primary key, where one is declared; and its declared foreign keys, which is where join inference starts. The warehouses that enforce foreign keys — Postgres, MySQL, SQL Server, SQLite — answer there; Trino and ClickHouse have none to give.

sync

$ zsql catalog sync -d cs
cs: 0 tables, 20 views, 517 columns (main) -> catalog/cs.json (483 ms)

sync re-reads exactly what the file records — every scope and every added table — and reports the drift: tables added, tables gone, columns added or removed, types changed. It drops what the warehouse says is gone and nothing else. Run it when the warehouse changes, commit the diff, and zsql check will tell you which fields the change broke.

search and show

$ zsql catalog search contact
main.cs_contact_f                        view    85 columns   cs
main.cs_contact_skill_d                  view     6 columns   cs
main.cs_contact_subchannel_d             view     3 columns   cs
main.cs_recontact_f                      view    10 columns   cs

search matches the pattern against table names in the file, across every datasource unless -d names one. --live asks the warehouse instead, which is how you find a table you have not read yet — then catalog read it, or generate --live it in one step.

$ zsql catalog show cs_contact_subchannel_d
main.cs_contact_subchannel_d (cs) view
  contact_subchannel_id            VARCHAR
  contact_subchannel_desc          VARCHAR
  contact_channel_id               VARCHAR

show prints one table’s columns with their types, plus its keys and comment when the warehouse has them.

What zsql check does with it

zsql check connects to nothing, and with a catalog present it still catches what a connection would:

$ zsql check
validated customer-service/working-tree: 3 tables, 110 fields, 2 joins, 136 paths, 0 policies, 1 sampled dimensions
catalog cs: 3 tables checked against catalog read 2026-10-24
no tests (tests/*.yml)
-- local 18.1 ms

It reports a physical_name that names no table, a column a field’s expression reads that the table does not have, and a field whose declared data_type disagrees with the warehouse — judged against every column the field maps to at once, so a field mapped on three tables with two types is one finding rather than three. Without a catalog it says so and names the command:

catalog: cs not checked; `zsql catalog read -d cs --schema <name>` reads one

JSON

--json on any of the four, or the global --agent, prints one document per invocation: what was read, the drift, the matches or the table. Counts and schema only — a catalog holds no rows.

Next steps