CLI reference

Every command, with its help as the binary prints it.

pgzest

PostgreSQL language toolchain

Usage: pgzest <COMMAND>

Commands:
  check     Type-check SQL files, printing diagnostics. Exits 1 if any errors are found
  describe  Describe named queries (parameters, columns, nullability, cardinality, dependencies) as JSON descriptors
  macros    List available macros: the ones shipped with the tool, plus the project's own from `[macros] directory`
  build     Expand macros in a `.pgsql` file and print standard SQL
  dev       Apply the routines of the project's schema files to a development database — with run logs and snapshots by default — then again on each save
  db        Database subcommands
  lint      Lint a SQL file for style and best-practice violations
  migrate   Migration subcommands
  schema    Schema subcommands
  emit      Parse and re-emit the SQL AST (normalization round-trip)
  lsp       Run the language server over stdio (what editors start)
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

pgzest check

Type-check SQL files, printing diagnostics. Exits 1 if any errors are found.

All positional files are checked. Any `--schema` files contribute to the schema context and trigger map without themselves being checked. If no `--schema` is given and a single file is passed, it is analysed in self-contained mode (DDL inside the file seeds its own schema).

Usage: pgzest check [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          SQL files to check (at least one required)

Options:
      --schema <SCHEMAS>
          Extra DDL/schema files that provide context (can be repeated)

      --on-unparsable <ON_UNPARSABLE>
          How to report statements the parser could not read. Overrides `[parse] unparsable` from pgzest.toml

          Possible values:
          - ignore: Report nothing
          - warn:   Report without failing
          - error:  Report and fail

      --on-unsupported <ON_UNSUPPORTED>
          How to report valid statements the AST does not model. Overrides `[parse] unsupported`

          Possible values:
          - ignore: Report nothing
          - warn:   Report without failing
          - error:  Report and fail

      --no-project
          Ignore pgzest.toml: do not index the project, use only `--schema` and the target files themselves

  -h, --help
          Print help (see a summary with '-h')

pgzest describe

Describe named queries (parameters, columns, nullability, cardinality, dependencies) as JSON descriptors.

Each file is a named-query file (`-- name: …` headers). The schema is the project's (pgzest.toml) plus any `--schema` files. Exits 1 if a query cannot be described; nothing is ever guessed.

Usage: pgzest describe [OPTIONS] [FILES]...

Arguments:
  [FILES]...
          Named-query files to describe

Options:
      --sql <SQL>
          A single query given inline instead of (or in addition to) files

      --name <NAME>
          Name of the `--sql` query

          [default: query]

      --schema <SCHEMAS>
          Extra DDL/schema files that provide context (can be repeated)

      --no-project
          Ignore pgzest.toml

      --cache
          Also write each descriptor to `.pgzest/queries/<fingerprint>.json`

      --rust
          Print the generated Rust module (as `pgzest-build` writes it) instead of the JSON descriptors

  -h, --help
          Print help (see a summary with '-h')

pgzest macros

List available macros: the ones shipped with the tool, plus the project's own from `[macros] directory`

Usage: pgzest macros [OPTIONS]

Options:
      --verbose  Show each macro's header pattern and its expansion template
  -h, --help     Print help

pgzest build

Expand macros in a `.pgsql` file and print standard SQL.

With `--out-dir`, writes one `.sql` per input instead of printing.

Usage: pgzest build [OPTIONS] <FILES>...

Arguments:
  <FILES>...
          `.pgsql` files to expand (at least one required)

Options:
      --out-dir <OUT_DIR>
          Directory to write the generated `.sql` files into

      --log <LOG>
          What the PL/pgSQL routines record of their runs (default: `[log]` of pgzest.toml, else `none`). `debug` also makes `@snapshot` copy the temp tables and variables into `pgzest_debug`. The tables written to are created first

          Possible values:
          - none:  Nothing
          - info:  One entry per run: routine, start, duration, handled error
          - step:  Plus one entry per INSERT, UPDATE, DELETE or EXECUTE
          - debug: Plus the `@snapshot` copies

      --log-target <LOG_TARGET>
          Where the log entries go (default: `[log]` of pgzest.toml, else `table`)

          Possible values:
          - table:  `pgzest_log.run` and `pgzest_log.step`
          - notify: `pg_notify('pgzest_log', …)`
          - notice: `RAISE NOTICE 'pgzest_log'`, sent to the client at once (tracing)

  -h, --help
          Print help (see a summary with '-h')

pgzest dev

Apply the routines of the project's schema files to a development database — with run logs and snapshots by default — then again on each save.

Functions, procedures and triggers only (`CREATE OR REPLACE`); tables go through migrations. A routine a file no longer declares is dropped if this session created it.

Usage: pgzest dev [OPTIONS] --url <URL>

Options:
      --url <URL>
          Database URL (default: `DATABASE_URL`)

          [env: DATABASE_URL=]

      --log <LOG>
          What the routines record of their runs (see `pgzest build`)

          Possible values:
          - none:  Nothing
          - info:  One entry per run: routine, start, duration, handled error
          - step:  Plus one entry per INSERT, UPDATE, DELETE or EXECUTE
          - debug: Plus the `@snapshot` copies

          [default: debug]

      --log-target <LOG_TARGET>
          Where the log entries go

          Possible values:
          - table:  `pgzest_log.run` and `pgzest_log.step`
          - notify: `pg_notify('pgzest_log', …)`
          - notice: `RAISE NOTICE 'pgzest_log'`, sent to the client at once (tracing)

          [default: table]

      --once
          Apply once and exit instead of watching

  -h, --help
          Print help (see a summary with '-h')

pgzest db

Database subcommands

Usage: pgzest db <COMMAND>

Commands:
  check  Compare a database with what its migrations produce: what was changed in it by hand (a routine, an index, a trigger…). Exits 1 if it differs
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

pgzest db check

Compare a database with what its migrations produce: what was changed in it by hand (a routine, an index, a trigger…). Exits 1 if it differs.

The migrations it received (`_prisma_migrations`, `__diesel_schema_migrations`, or all of them) are replayed in an empty database created on the server, then dropped; both are described by PostgreSQL itself.

Usage: pgzest db check [OPTIONS] --url <URL>

Options:
      --url <URL>
          Database URL (default: `DATABASE_URL`)

          [env: DATABASE_URL=]

      --scratch-url <SCRATCH_URL>
          Server the migrations are replayed on, same PostgreSQL version (default: the database's; needs the CREATEDB privilege)

      --until <UNTIL>
          Last migration the database received, for a database without migrations table

  -h, --help
          Print help (see a summary with '-h')

pgzest lint

Lint a SQL file for style and best-practice violations

Usage: pgzest lint <FILE>

Arguments:
  <FILE>  SQL file to lint

Options:
  -h, --help  Print help

pgzest migrate

Migration subcommands

Usage: pgzest migrate <COMMAND>

Commands:
  diff    Migration between two schemas (SQL files or directories), without a project: both are replayed and their catalogs compared
  create  Generate the next migration of a declarative project (`[schema] declarative = true`): what separates the state reached by the migrations from the declarative schema, checked by replay before it is written. It is the simplest migration that reaches the schema: steps that lose data or may fail on a populated database are listed in its header, for the developer to adapt
  check   Fail if the migrations do not reach the declarative schema (CI)
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

pgzest migrate diff

Migration between two schemas (SQL files or directories), without a project: both are replayed and their catalogs compared

Usage: pgzest migrate diff <OLD> <NEW>

Arguments:
  <OLD>  Old schema (file or directory)
  <NEW>  New schema (file or directory)

Options:
  -h, --help  Print help

pgzest migrate create

Generate the next migration of a declarative project (`[schema] declarative = true`): what separates the state reached by the migrations from the declarative schema, checked by replay before it is written. It is the simplest migration that reaches the schema: steps that lose data or may fail on a populated database are listed in its header, for the developer to adapt

Usage: pgzest migrate create [OPTIONS] <NAME>

Arguments:
  <NAME>  Migration name (lowercase, digits, `_`)

Options:
      --dry-run  Print the migration instead of writing it
  -h, --help     Print help

pgzest migrate check

Fail if the migrations do not reach the declarative schema (CI)

Usage: pgzest migrate check

Options:
  -h, --help  Print help

pgzest schema

Schema subcommands

Usage: pgzest schema <COMMAND>

Commands:
  import  Import an existing project: replay its migrations and write the resulting declarative schema (one `<schema>/schema.sql` per PostgreSQL schema) plus a baseline migration with its header
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

pgzest schema import

Import an existing project: replay its migrations and write the resulting declarative schema (one `<schema>/schema.sql` per PostgreSQL schema) plus a baseline migration with its header

Usage: pgzest schema import [OPTIONS] <MIGRATIONS>

Arguments:
  <MIGRATIONS>
          Migrations directory

Options:
      --layout <LAYOUT>
          How migrations are laid out

          Possible values:
          - flat:   All `.sql` files, recursively, sorted by path
          - prisma: Prisma: `<timestamp>_<name>/migration.sql`
          - diesel: Diesel: `<timestamp>_<name>/up.sql`

          [default: flat]

      --out <OUT>
          Output directory for the declarative schema

          [default: schema]

      --baseline <BASELINE>
          Baseline migration file (default: `<out>/baseline.sql`)

      --force
          Write even if the replay reported errors

  -h, --help
          Print help (see a summary with '-h')

pgzest emit

Parse and re-emit the SQL AST (normalization round-trip)

Usage: pgzest emit <FILE>

Arguments:
  <FILE>  SQL file to emit

Options:
  -h, --help  Print help

pgzest lsp

Run the language server over stdio (what editors start)

Usage: pgzest lsp

Options:
  -h, --help  Print help