Crate pgsafe 

pgsafe is a static safety linter for PostgreSQL DDL migrations.

It parses SQL using the real PostgreSQL parser and checks every statement against a set of rules that flag lock-taking or destructive operations, producing a Finding for each match together with safe-rewrite guidance.

The main entry point is lint_sql. A command-line interface wrapping the same rules is provided by the pgsafe binary.

Modules

cli

Command-line surface (only built with the cli feature). A superset binary can #[command(flatten)] CommonArgs and call resolve to reuse the whole front-end — config discovery, --config/--git-diff/--since input selection, and per-file options — then run its own lint/render loop over the returned ResolvedRun.

Structs

FileReport

Lint results for a single named input.

Finding

A safety finding reported for a specific SQL statement.

Fix

A machine-applicable remediation for a Finding: a short title plus the edits that make the statement safe. Present only for findings whose fix is an unambiguous mechanical change.

FixEdit

A single text edit within the linted SQL: replace bytes [start, end) with replacement. start == end is a pure insertion.

LintOptions

Options that adjust linting beyond the default static analysis.

Location

Source position of a finding’s statement: byte offset plus 1-based line and (character) column of the statement’s first non-whitespace token.

Styling

How the human renderers wrap each span of output. plain() emits neither ANSI escapes nor glyphs (byte-identical to unstyled output); ansi() colors spans and prefixes a per-finding severity glyph. TTY/env detection is the caller’s job — the library only consumes a ready-made Styling.

Suppression

Why a Finding was suppressed by an inline -- pgsafe:ignore directive.

Enums

ColorWhen

When to colorize human output (the CLI --color flag).

FailOn

Minimum finding severity that fails the run (maps to exit code 1).

Format

Output format for the CLI.

LintError

Error returned when pgsafe cannot process the provided SQL.

NameKind

The kind of identifier a naming-convention pattern applies to.

Severity

Severity level of a Finding, ordered by increasing severity (Warning < Error).

Constants

SCHEMA_VERSION

The version of the JSON output envelope (schema_version).

VERSION

The version of the pgsafe crate (its Cargo.toml version).

Functions

gate

Whether findings should fail the run under fail_on.

lint_input

Lint one named input into a FileReport under options, turning a parse failure into the report’s error field instead of returning an error.

lint_sql

Lint sql under options, returning findings in source order.

list_rule_ids

Every lint-rule id this build can emit — the registered AST rules plus the engine-synthesized/policy rules — in stable order. The public rule catalog, e.g. for pgsafe --list-rules and external tooling.

render_errors

Render the stderr block: one "{name}: {error}" line for each report that failed to parse.

render_finding_body

Render one finding’s nested body for the grouped output (plain styling).

render_finding_human

Render one finding as the human block (1–4 newline-terminated lines): the headline, the message, a fix: line (unless suppressed), and the snippet (when present).

render_github

Render findings as GitHub Actions workflow annotation commands (--format github): one ::error/::warning file=…,line=…,col=…,title=pgsafe(rule)::message per finding (suppressed findings skipped), plus ::error file=…::{error} for any file that failed to parse. GitHub turns these into inline annotations on the diff; the process exit code (the gate) still drives the check.

render_human

Render every finding across reports to the plain human block, grouped by statement.

render_human_styled

Render every finding across reports to the human block, grouped by statement, wrapping each span according to st. Findings arrive sorted by statement index, so a group is the run of consecutive findings sharing one index. Parse errors are not included — see render_errors.

render_json

Render reports as the versioned JSON envelope (schema_version 2).

render_sarif

Render reports as a SARIF 2.1.0 log. Findings (including suppressed ones) become results; a file that failed to parse becomes a tool-execution notification and flips executionSuccessful to false.

render_statement_header

Render the grouped-output header for a statement (plain styling).

render_summary

One-line run summary, or None when there are no findings at all (a clean run stays silent). Printed in both plain and color modes; st only colors the counts. Clauses with a zero count are omitted; suppressed findings appear in a trailing (N suppressed) parenthetical (or stand alone when they are the only findings).