docs: add pgfence as complementary migration safety tool#693
docs: add pgfence as complementary migration safety tool#693flvmnt wants to merge 3 commits intosupabase-community:mainfrom
Conversation
Add a section to the CI guide showing how to combine Postgres Language Server with pgfence for comprehensive migration checking. PGLT catches SQL syntax and semantic issues, while pgfence analyzes PostgreSQL lock modes, risk levels, and provides safe rewrite recipes.
There was a problem hiding this comment.
Pull request overview
Adds documentation to the Continuous Integration guide explaining how to run Postgres Language Server (PGLT) alongside pgfence in CI to validate both SQL correctness and migration operational safety.
Changes:
- Adds a new “Combining with pgfence for Migration Safety” section.
- Includes a GitHub Actions workflow example running PGLT checks and pgfence analysis.
- Documents pgfence CI gating flags (
--ci,--max-risk) with examples.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ### Combining with pgfence for Migration Safety | ||
|
|
||
| While Postgres Language Server catches SQL syntax and semantic issues, it does not analyze the **lock modes** and **runtime risk** of DDL statements. [pgfence](https://pgfence.dev) is a complementary CLI that fills this gap — it tells you what PostgreSQL lock each migration statement acquires, what it blocks, and provides safe rewrite recipes when it detects dangerous patterns. |
There was a problem hiding this comment.
Minor grammar: “what PostgreSQL lock each migration statement acquires” reads as singular; consider pluralizing to “locks” (or rephrasing to “lock mode”) for clarity.
| While Postgres Language Server catches SQL syntax and semantic issues, it does not analyze the **lock modes** and **runtime risk** of DDL statements. [pgfence](https://pgfence.dev) is a complementary CLI that fills this gap — it tells you what PostgreSQL lock each migration statement acquires, what it blocks, and provides safe rewrite recipes when it detects dangerous patterns. | |
| While Postgres Language Server catches SQL syntax and semantic issues, it does not analyze the **lock modes** and **runtime risk** of DDL statements. [pgfence](https://pgfence.dev) is a complementary CLI that fills this gap — it tells you which PostgreSQL lock mode each migration statement acquires, what it blocks, and provides safe rewrite recipes when it detects dangerous patterns. |
| - name: Check SQL syntax (PGLT) | ||
| run: postgres-language-server check sql/ | ||
|
|
||
| # 2. Check migration safety with pgfence | ||
| - name: Check migration safety (pgfence) | ||
| run: npx --yes @flvmnt/pgfence analyze --ci migrations/*.sql |
There was a problem hiding this comment.
The pgfence section mixes example paths (postgres-language-server check sql/ vs migrations/*.sql), and the dedicated migrations guide uses supabase/migrations. This is likely to confuse readers; consider using a single consistent migrations path across both tools (or explicitly note that the paths are placeholders to be adjusted).
| npx @flvmnt/pgfence analyze --ci migrations/*.sql | ||
|
|
||
| # Block on MEDIUM or above (stricter) | ||
| npx @flvmnt/pgfence analyze --ci --max-risk medium migrations/*.sql |
There was a problem hiding this comment.
The shell examples use npx @flvmnt/pgfence ... without --yes, while the CI workflow uses npx --yes .... Without --yes, npx can prompt for confirmation in non-interactive environments, potentially hanging CI. Consider adding --yes to these examples (or explaining when it’s required).
| npx @flvmnt/pgfence analyze --ci migrations/*.sql | |
| # Block on MEDIUM or above (stricter) | |
| npx @flvmnt/pgfence analyze --ci --max-risk medium migrations/*.sql | |
| npx --yes @flvmnt/pgfence analyze --ci migrations/*.sql | |
| # Block on MEDIUM or above (stricter) | |
| npx --yes @flvmnt/pgfence analyze --ci --max-risk medium migrations/*.sql |
| run: npx --yes @flvmnt/pgfence analyze --ci migrations/*.sql | ||
| ``` | ||
|
|
||
| pgfence exits with code 1 when it finds high-risk issues, so it integrates naturally as a CI gate. You can adjust the threshold with `--max-risk`: | ||
|
|
||
| ```sh | ||
| # Block on HIGH or above (default) | ||
| npx @flvmnt/pgfence analyze --ci migrations/*.sql | ||
|
|
||
| # Block on MEDIUM or above (stricter) | ||
| npx @flvmnt/pgfence analyze --ci --max-risk medium migrations/*.sql |
There was a problem hiding this comment.
The npx invocations of @flvmnt/pgfence download and execute the latest version of a third-party npm package on every CI run without pinning a version or verifying integrity. If that package or the npm registry is compromised, an attacker could execute arbitrary code in your CI environment (with access to repository contents, tokens, and secrets). To reduce supply-chain risk, pin @flvmnt/pgfence to a specific version or otherwise ensure the code being executed in CI is immutably identified and integrity-checked.
|
Addressed feedback: pinned pgfence version in all examples, ensured --yes flag on all npx commands, removed hidden Unicode characters. |
|
Verified: scanned for hidden Unicode characters (zero-width spaces, bidi marks, BOM) — none found. All three npx commands already include --yes and are pinned to @0.2.1. No changes needed. |
|
Pushed fixes: improved grammar, consistent migration paths across examples. All review feedback addressed. |
Summary
--ciand--max-riskflags for CI gatingWhy
PGLT catches SQL syntax and semantic issues. pgfence adds a complementary layer: it analyzes what PostgreSQL lock mode each DDL statement acquires, what it blocks, scores the runtime risk level, and provides safe rewrite recipes for dangerous patterns (e.g.,
CREATE INDEXwithoutCONCURRENTLY,ADD COLUMN ... NOT NULLwithout the expand/contract sequence).Running both tools in CI gives teams comprehensive migration checking — correctness (PGLT) and safety (pgfence).
Test plan