docs(docs): add pgfence migration safety integration guide#7564
docs(docs): add pgfence migration safety integration guide#7564flvmnt wants to merge 5 commits intoprisma:mainfrom
Conversation
Add pgfence as a Prisma Migrate integration that analyzes SQL migration files for dangerous PostgreSQL lock patterns before deployment. Includes install instructions, CI pipeline setup, and size-aware risk scoring. Also adds a cross-reference in the deploy docs.
|
@flvmnt is attempting to deploy a commit to the Prisma Team on Vercel. A member of the Team first needs to authorize it. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review infoConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughAdds a new pgfence integration guide and registers it in the integrations index; updates the Prisma Migrate deployment guide with a "Pre-deploy migration safety checks" section that demonstrates running pgfence (including a GitHub Actions example) before applying migrations. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/content/docs/guides/integrations/pgfence.mdx`:
- Around line 94-103: The prose states "every push" but the workflow YAML (title
".github/workflows/migration-safety.yml") uses the pull_request trigger; update
the text in the guide to reflect the actual trigger (change "every push" to "on
pull requests" or similar), or alternatively change the YAML trigger to push if
you intended runs on pushes—ensure the sentence containing "every push" and the
workflow header ".github/workflows/migration-safety.yml" are consistent.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
apps/docs/content/docs/guides/integrations/meta.jsonapps/docs/content/docs/guides/integrations/pgfence.mdxapps/docs/content/docs/orm/prisma-client/deployment/deploy-database-changes-with-prisma-migrate.mdx
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive integration documentation for pgfence, a PostgreSQL migration safety analysis tool. The integration helps Prisma users detect dangerous database migration patterns (such as non-concurrent index creation or table-locking DDL operations) before deploying to production. The guide is well-structured and follows existing documentation conventions.
Changes:
- Added a complete pgfence integration guide with installation, local usage, CI/CD setup, and advanced features
- Updated the deployment guide to reference pgfence as a pre-deploy safety check option
- Added pgfence to the integrations navigation menu
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| apps/docs/content/docs/guides/integrations/pgfence.mdx | New integration guide covering pgfence setup, local analysis, CI/CD integration, and risk-based migration safety checks |
| apps/docs/content/docs/guides/integrations/meta.json | Added pgfence entry to integrations menu, positioned after datadog |
| apps/docs/content/docs/orm/prisma-client/deployment/deploy-database-changes-with-prisma-migrate.mdx | Added "Pre-deploy migration safety checks" section with pgfence example and cross-reference to the full guide |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - [pgfence documentation and source code](https://github.com/flvmnt/pgfence) | ||
| - [pgfence on npm](https://www.npmjs.com/package/@flvmnt/pgfence) | ||
| - [Prisma Migrate overview](/orm/prisma-migrate/understanding-prisma-migrate/overview) |
There was a problem hiding this comment.
The link to the Prisma Migrate overview page is incorrect. It should point to "/orm/prisma-migrate" instead of "/orm/prisma-migrate/understanding-prisma-migrate/overview". There is no overview page in the understanding-prisma-migrate subdirectory.
| - [Prisma Migrate overview](/orm/prisma-migrate/understanding-prisma-migrate/overview) | |
| - [Prisma Migrate overview](/orm/prisma-migrate) |
|
Addressed feedback: pinned pgfence version in all examples, removed hidden Unicode characters, verified all internal links. |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/content/docs/guides/integrations/pgfence.mdx`:
- Around line 150-153: The documentation link for generating the pgfence stats
file is too vague; update the section that shows the npx command (the example
producing pgfence-stats.json) to either (A) replace the repo root URL with the
specific README/docs anchor that documents the stats file schema and generation
steps, or (B) inline a minimal example SQL query and a short note on the
required JSON schema that users can run against pg_stat_user_tables to produce
pgfence-stats.json; make the change in the block that references
"pgfence-stats.json" and the npx analyze command so readers can immediately
generate a valid stats file.
- Around line 34-36: Update the npm install command in the docs so it pins the
same version used elsewhere: change the install invocation that currently uses
`@flvmnt/pgfence` without a version to explicitly use `@flvmnt/pgfence`@0.2.1 so all
examples (the various npx commands that reference `@flvmnt/pgfence`@0.2.1) are
consistent and avoid installing an unexpected/latest package.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
apps/docs/content/docs/guides/integrations/pgfence.mdxapps/docs/content/docs/orm/prisma-client/deployment/deploy-database-changes-with-prisma-migrate.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/docs/content/docs/orm/prisma-client/deployment/deploy-database-changes-with-prisma-migrate.mdx
…hars Corrected workflow description to say "every pull request" to match the actual pull_request trigger in the YAML. Verified no hidden Unicode characters remain and all npx commands are pinned to @0.2.1.
|
Pushed fixes: corrected trigger description to match workflow YAML, verified no hidden Unicode characters, all npx commands pinned to @0.2.1. Re-requesting review. |
|
Pushed fixes: pinned version in npm install command, improved stats file documentation link to be actionable. All CodeRabbit findings addressed. |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
apps/docs/content/docs/guides/integrations/pgfence.mdx (1)
108-114: Consider SHA-pinning the GitHub Actions to harden the example workflow.
actions/checkout@v4andactions/setup-node@v4are pinned by mutable version tags, which means a compromised or inadvertently mutated release could silently inject malicious code into workflows that copy this example. GitHub officially recommends pinning Actions to full-length commit SHAs as the primary defense against supply-chain attacks in this space.📝 Proposed fix
- uses: actions/checkout@v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4- uses: actions/setup-node@v4 + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/content/docs/guides/integrations/pgfence.mdx` around lines 108 - 114, Replace the mutable action tags with immutable full commit SHA pins in the workflow: update the "uses" entries for the "Checkout repo" and "Setup Node.js" steps (currently actions/checkout@v4 and actions/setup-node@v4) to their corresponding full-length commit SHAs (e.g., actions/checkout@<full-sha> and actions/setup-node@<full-sha>), ensuring the example shows exact SHA values and keep the step names ("Checkout repo", "Setup Node.js") unchanged so readers can clearly see the pinned actions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/content/docs/guides/integrations/pgfence.mdx`:
- Around line 119-120: The run step that uses the glob pattern
"prisma/migrations/**/migration.sql" will silently fail to recurse in GitHub
Actions bash; fix by enabling globstar before the command (e.g., add a line that
runs shopt -s globstar) so the npx analyze invocation ("npx --yes
`@flvmnt/pgfence`@0.2.1 analyze --ci --max-risk medium
prisma/migrations/**/migration.sql") and the other snippets that use ** (deploy
snippet, local examples, and the stats command) correctly expand nested
directories in Actions and local bash sessions.
- Around line 52-57: The HIGH risk row is inconsistent: the example "ADD FOREIGN
KEY without NOT VALID" acquires SHARE ROW EXCLUSIVE (it blocks writes but not
plain reads), so either move that example to the MEDIUM row (and keep HIGH as
blocking reads+writes) or change the HIGH description to "blocks writes and
competing DDL but not plain reads." Update the table rows referenced by the
"HIGH" and "MEDIUM" labels and the example text "ADD FOREIGN KEY without NOT
VALID" so the description and examples match (ensure MEDIUM lists write-blocking
examples like CREATE INDEX without CONCURRENTLY and ADD FOREIGN KEY, and HIGH
lists operations that truly take ACCESS EXCLUSIVE locks).
---
Nitpick comments:
In `@apps/docs/content/docs/guides/integrations/pgfence.mdx`:
- Around line 108-114: Replace the mutable action tags with immutable full
commit SHA pins in the workflow: update the "uses" entries for the "Checkout
repo" and "Setup Node.js" steps (currently actions/checkout@v4 and
actions/setup-node@v4) to their corresponding full-length commit SHAs (e.g.,
actions/checkout@<full-sha> and actions/setup-node@<full-sha>), ensuring the
example shows exact SHA values and keep the step names ("Checkout repo", "Setup
Node.js") unchanged so readers can clearly see the pinned actions.
- HIGH risk: SHARE ROW EXCLUSIVE blocks writes and competing DDL, not plain reads. Only ACCESS EXCLUSIVE blocks reads. - Add `shopt -s globstar` before ** glob patterns in GitHub Actions workflow examples for correctness.
Summary
@flvmnt/pgfence) — a PostgreSQL migration safety CLI that analyzes SQL migration files for dangerous lock patterns, risk levels, and safe rewrite recipesprisma/migrations/*/migration.sql— pgfence can analyze those directly, making it a natural fit as a pre-deploy safety checkChanges
apps/docs/content/docs/guides/integrations/pgfence.mdx— full integration guide covering installation, local analysis, CI pipeline setup, and size-aware risk scoringapps/docs/content/docs/guides/integrations/meta.json— addedpgfenceto the pages arrayapps/docs/content/docs/orm/prisma-client/deployment/deploy-database-changes-with-prisma-migrate.mdx— added a "Pre-deploy migration safety checks" section with a link to the pgfence guideLinks
Summary by CodeRabbit