CLI Reference

This page reflects pgfence 0.8.0. Run pgfence <command> --help against your installed version when scripting a release gate.

Commands

Command	Purpose
`analyze <files...>`	Statically analyze migrations for lock risk, policy violations, safe rewrites, and coverage gaps.
`trace <files...>`	Compare static predictions with locks observed in a disposable Docker Postgres container.
`explain [sql...]`	Explain one SQL statement from an argument or stdin. Supports CLI and JSON output.
`snapshot`	Read schema metadata from a database and write a local snapshot for later analysis.
`init`	Install a local git hook or scaffold the Prisma GitHub Actions workflow.
`telemetry [action]`	Show, enable, disable, or reset anonymous usage telemetry.
`lsp`	Start the bundled Language Server Protocol server over stdio.

Analyze

bash

pgfence analyze [options] <files...>

Option	Values and behavior
`--format`	`sql`, `typeorm`, `prisma`, `knex`, `drizzle`, `sequelize`, `kysely`, or `auto`. Default: `auto`.
`--output`	`cli`, `json`, `github`, `sarif`, or `gitlab`. Default: `cli`.
`--ci`	Fail when the configured risk gate or a policy error blocks the run.
`--max-risk`	Highest allowed risk in CI. Default: `high`.
`--unknown`	`warn` or `block` for unanalyzable SQL. Default: `warn`.
`--min-pg-version`	Minimum PostgreSQL version assumed by version-sensitive checks. Default: `14`.
`--db-url`	Read live table statistics for size-aware risk scoring.
`--stats-file`	Use a local `pgfence-stats.json` instead of a direct database connection.
`--snapshot`	Use schema snapshot metadata for type and index ownership analysis.
`--plugin`	Load one or more custom rule modules.
`--disable-rules`	Disable specific rule ids.
`--enable-rules`	Run only the listed rule ids.
`--no-lock-timeout`	Disable the `lock_timeout` requirement.
`--no-statement-timeout`	Disable the `statement_timeout` requirement.
`--max-lock-timeout`	Maximum allowed lock timeout in milliseconds. Default: `5000`.
`--max-statement-timeout`	Maximum allowed statement timeout in milliseconds. Default: `600000`.
`--no-cloud-hint`	Hide the hosted-check hint on a blocked CI run without changing the report or exit code.

Fix options

--fix edits raw SQL files in place, but only for the documented mechanical allowlist. It can add concurrent index syntax and missing timeout settings. It refuses unsafe guesses and refuses concurrent index changes inside an explicit transaction.

--fix --split also creates sibling SQL files for supported multi-step recipes. It never edits the original migration for those recipes, and generated backfill templates remain commented out.

bash

pgfence analyze --fix migrations/*.sql
pgfence analyze --fix --split migrations/*.sql

Trace

trace accepts the analysis, policy, output, plugin, snapshot, and CI options above, except for database statistics and fix options. It also accepts:

--pg-version <version>: Docker PostgreSQL version, default 17.
--docker-image <image>: custom image that overrides --pg-version.

Other command options

bash

# Explain one statement
pgfence explain --min-pg-version 14 --output json "ALTER TABLE users DROP COLUMN legacy"

# Generate a schema snapshot
pgfence snapshot --db-url postgres://readonly@replica:5432/app --output pgfence-snapshot.json

# Install hooks or scaffold a Prisma workflow
pgfence init
pgfence init --prisma-github-action

# Inspect or change telemetry
pgfence telemetry status
pgfence telemetry enable
pgfence telemetry disable
pgfence telemetry reset

Exit codes

Code	Meaning
`0`	The command completed and the configured gate passed.
`1`	A CI risk threshold, policy error, blocked unknown statement, trace mismatch, or command error failed the run.
`2`	The run analyzed zero SQL statements, or a bin-like launch could not be confirmed safely.

A file with no statements is reported as [NO STATEMENTS]. If the entire run contains no statements, analyze and trace exit 2. Dynamic SQL that was found but could not be analyzed is reported separately as [UNANALYZABLE].

Configuration files and environment variables are documented in Configuration. Reporter schemas and coverage fields are documented in Output Formats.