pgzest.toml

The format is stable: changes are additive. A key may be added; none changes meaning or disappears without a transition documented here.

The file lives at the project root. The CLI and the language server (pgzest lsp) find it by walking up from the current directory or the opened folder. It is the only source of configuration: the CLI and the editor read the same file, with the same rules.

Principles

• Strict. An unknown key is an error. A typo in a key must never turn into a silently ignored setting.
• Nothing accepted without effect. A key exists in the format only if the tool applies it. Planned changes (at the bottom of the page) are rejected until they are implemented.
• An invalid config stops the analysis. The CLI exits with code 2; the LSP shows the error and does not analyze with a made-up config.
• A single vocabulary of levels: "error", "warn", "info", "off" / "ignore" depending on the section.

Full example

[postgres]
version = 18                       # required

[schema]
directory = "schema"               # declarative schema files
include = ["db/functions"]         # additional directories

[migrations]
directory = "migrations"

[queries]
directory = "queries"              # named queries (reference/named-queries)

[macros]
directory = "macros"               # project *.pgmacro

[log]
level = "info"                     # run logs of the macro routines

[parse]
unparsable = "warn"
unsupported = "warn"

[rules]
"L001" = "off"
"column-not-found" = "error"

[plugins]
builtin = { rls-enforcer = {} }
wasm = ["plugins/my_rules.wasm"]

The minimal valid config:

[postgres]
version = 18

Sections

[postgres] — required

Key	Type	Default	Purpose
version	integer	— (required)	Targeted PostgreSQL major version. Accepted values: 18.

Why required: analyzing with the rules of another version would be guessing. An unsupported version is rejected with the list of available versions. It selects the catalog of built-in types, functions and operators the analysis checks against.

[schema]

Key	Type	Default	Purpose
directory	path	absent	Schema files, walked recursively.
include	list of paths	[]	Additional schema directories.
declarative	boolean	false	The schema alone describes the target state; migrations are generated by pgzest migrate create (guide).

• directory absent: every .sql / .pgsql file in the project, except migrations and named queries, is a schema file.
• directory present: only directory and include are schema files; the other files are queries.
• declarative = false: schema files complement the state reached by the migrations (replayed after them).
• declarative = true: the analysis replays only the schema; migrations are replayed separately, and the gap between the two is reported (schema-drift, level info, configurable in [rules] — "error" for CI, or pgzest migrate check).

Never walked: node_modules/, target/, dist/, .schema-snapshots/ and hidden directories.

[migrations]

Key	Type	Default	Purpose
directory	path	"migrations"	Migrations, indexed in the order of their sequence (numeric prefix of the name).

[queries]

Key	Type	Default	Purpose
directory	path	absent	Named query files, walked recursively. Format: named queries.
include	list of paths	[]	Additional query directories, close to the code that uses them (src/order/queries). Each one is the root of its own module tree (pgzest_macros::queries!).

Files in this directory are checked as queries (no DDL) and according to the named query format. They are never indexed as schema.

[macros]

Key	Type	Default	Purpose
directory	path	"macros"	Project macros (*.pgmacro) and fragments (*.sql, -- fragment: name headers, see fragments). A project macro with the name of a provided macro replaces it; two fragments with the same name, or a fragment and a macro, are an error. Its .sql files are never schema or query files.

[rust]

Key	Type	Default	Purpose
types	Rust path	absent	Module where #[pgzest_macros::types] mod … {} generates the project’s enums ("crate::db"). When present, query code refers to it; required as soon as a sql! query uses an enum.

[log]

Key	Values	Default	Purpose
level	"none" | "info" | "step" | "debug"	"none"	What the PL/pgSQL macro routines record of their runs (run logs). Part of the generated code: analysis, the LSP, pgzest build and pgzest migrate expand the routines at this level, and the migration header records it (log=step).
target	"table" | "notify" | "notice"	"table"	Where the entries go: the unlogged tables pgzest_log.run / .step (part of the schema when the level is not none), pg_notify('pgzest_log', …), or RAISE NOTICE 'pgzest_log' at the start and the end of each run of a sampled trace (traces).

pgzest build --log / --log-target override it for one build; pgzest dev uses debug unless --log is given.

[parse]

Key	Values	Default	Purpose
unparsable	"error" | "warn" | "ignore"	"warn"	Statement the parser could not read, and function body not analyzed.
unsupported	"error" | "warn" | "ignore"	"warn"	Valid statement not modeled by the analysis.

One-off override: pgzest check --on-unparsable error.

[rules]

A code = level table, applied to all diagnostics (checker, lint, named queries), in the CLI as in the editor.

Level	Effect
"error"	Fails check (exit code 1).
"warn"	Reported without failing.
"info"	Information.
"off"	Removed.

Comment directives (-- pgzest-disable-next-line <code>) apply after [rules] and have the last word.

[plugins]

Key	Type	Default	Purpose
builtin	table name = { options }	{}	Provided plugins to enable. Available: rls-enforcer. An unknown name is an error.
wasm	list of paths	[]	WASM plugins, relative to the config file. A plugin that fails to load is an error.

Planned changes (rejected until implemented)

Described here so that projects know where they will land; their exact form is settled when they are implemented.

• [postgres] search_path — the project’s default search_path.
• [schema] namespaces — default PostgreSQL schema for a schema directory, e.g. { "schema/auth" = "auth" }.
• Extensions are not configured here: they are inferred from the CREATE EXTENSION statements in the schema and migrations (see Versions and extensions).