pgfence 0.5: fail-closed migration analysis

pgfence’s Trust Contract says the fatal failure mode is not a false positive. It is false safety: a migration that looks green because the analyzer missed the dangerous part.

0.5 is a trust release. It does not add a flashy new command. It makes the existing analysis harder to fool, easier to review, and clearer about what it could not prove.

Unknown SQL should not look safe

Migration analysis has an uncomfortable edge: ORMs can hide SQL behind builder APIs, dynamic strings, conditionals, callback shapes, and helper functions.

If a tool cannot reconstruct a statement, it has two choices:

1. Pretend the missing statement was not there.
2. Surface the gap and ask for review.

pgfence 0.5 keeps moving toward the second behavior.

Knex, Sequelize, TypeORM, Drizzle, and raw SQL extraction now surface more unsupported or dynamic migration shapes as warnings. Those warnings are marked as unanalyzable when they affect coverage, so CI and reviewers can see the gap directly.

Coverage is now harder to miss

The coverage line matters because it tells you whether the report is complete:

Analyzed 7 SQL statements. 1 dynamic statement not analyzable. Coverage: 88%.

0.5 makes that signal more consistent across the surfaces teams actually use:

• CLI output
• JSON output
• GitHub PR markdown
• SARIF
• GitLab Code Quality

A PR comment that says “no high-risk findings” is not enough if one statement was dynamic and could not be analyzed. The report needs to say both things.

ORM extraction fails closed more often

This release hardens the ORM paths that are easiest to get wrong:

• Knex dynamic builder paths
• Knex incomplete references() metadata
• Knex transaction configuration cases
• Sequelize dynamic foreign key metadata
• Sequelize partial index options
• Sequelize missing up() methods
• TypeORM dynamic SQL calls
• Conditional raw SQL in migration files
• Binary-looking or oversized inputs

The important change is not that pgfence understands every possible ORM pattern. It does not. The important change is that more unsupported patterns now show up as review work instead of disappearing from the report.

Editor behavior got stricter too

The VS Code extension uses the same analysis engine through the LSP server. 0.5 hardens that path:

• Configuration refresh resets cached config correctly.
• Stale diagnostics are less likely to survive a failed analysis.
• Hover, code-action, statement grouping, document symbol, folding range, and inlay hint behavior now have broader tests.
• The documented LSP package export is protected by package-surface tests.

That matters because the editor is where many migration mistakes are cheapest to fix. The PR should not be the first place a developer learns what lock mode their SQL takes.

Release boundaries are tighter

pgfence is open source, and the npm package has to stay clean. 0.5 adds more checks around what gets packed and published:

• Public-boundary checks protect local-only paths.
• Package-surface tests verify shipped exports.
• pnpm pack parsing is more robust.
• CI uses the pinned pnpm version and current Node action runtime.

This is not glamorous work. It is the work that keeps a safety tool boring in the right ways.

What still needs manual review

pgfence is a static analyzer. It does not execute your app code, resolve every runtime variable, or prove every dynamic migration helper.

You should still review:

• Computed table names
• Dynamic SQL strings
• Conditional migration branches
• ORM helper wrappers that generate SQL indirectly
• Migration files that depend on runtime state
• Any report with unanalyzable statement coverage

The difference in 0.5 is that more of those gaps are visible in the report.

Upgrade

npm install -D @flvmnt/pgfence@latest

Or pin the release:

npm install -D @flvmnt/pgfence@0.5.0

If you use the GitHub Action, keep using:

uses: flvmnt/pgfence@v1

Full changelog: CHANGELOG.md

Why this release comes before Cloud

pgfence Cloud will add approval workflows and audit evidence around risky migrations. That governance layer is only useful if the analyzer underneath it is honest about what it did and did not analyze.

So the sequence is intentional: make the free analyzer fail closed, then explore governance workflows around the evidence it produces.

Cloud direction: https://pgfence.com/cloud