home / skills / openclaw / skills / prisma-migrate-guard

prisma-migrate-guard skill

safe

/skills/daniellummis/prisma-migrate-guard

This skill preflight Prisma migrations before deploy, detecting drift, failed migrations, missing URLs, or unapplied files to gate CI/CD.

npx playbooks add skill openclaw/skills --skill prisma-migrate-guard

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.6 KB

---
name: prisma-migrate-guard
description: Preflight Prisma migration state before deploy; fails fast on drift, failed migrations, missing DB URLs, or unapplied migration files.
version: 1.0.0
metadata: {"openclaw":{"requires":{"bins":["bash","node","npx"]}}}
---

# Prisma Migrate Guard

Use this skill before deploys or CI release steps to verify Prisma migrations are healthy and ready to apply.

## What this skill does
- Verifies required Prisma CLI/runtime tools are available
- Validates migration DB URL inputs (`DATABASE_URL` by default)
- Runs `prisma migrate status` against a target schema
- Fails on common dangerous states:
  - failed migrations
  - migration drift warnings
  - unapplied migration files
  - missing migration history table hints
- Exits non-zero for CI/deploy gating

## Inputs
- Optional env vars:
  - `PRISMA_SCHEMA_PATH` (default: `prisma/schema.prisma`)
  - `PRISMA_MIGRATE_DB_URL_ENV` (default: `DATABASE_URL`)
  - `PRISMA_MIGRATE_GUARD_ALLOW_UNAPPLIED` (`1` to warn instead of fail)
  - `PRISMA_MIGRATE_GUARD_ALLOW_DRIFT` (`1` to warn instead of fail)

## Run

```bash
bash scripts/check-prisma-migrate.sh
```

With explicit schema and env key:

```bash
PRISMA_SCHEMA_PATH=apps/api/prisma/schema.prisma \
PRISMA_MIGRATE_DB_URL_ENV=POSTGRES_PRISMA_URL \
bash scripts/check-prisma-migrate.sh
```

## Output contract
- Prints a concise PASS/FAIL report
- Exit code `0` on healthy status
- Exit code `1` on blocking migration issues

## Notes
- This guard is read-only (`migrate status`), it does not apply migrations.
- Keep it in CI before deploy or startup migration steps.

Overview

This skill is a preflight guard that verifies Prisma migration state before deploys or CI release steps. It detects failed migrations, drift, missing DB URL configuration, and unapplied migration files, then fails fast to prevent unsafe deployments. The tool is read-only and designed to exit non-zero for blocking issues so CI pipelines can gate progress.

How this skill works

The guard checks that Prisma CLI/runtime tools are present and validates the configured database URL environment variable (default: DATABASE_URL). It runs prisma migrate status against the specified schema path and parses the result for failed migrations, unapplied files, drift warnings, or missing migration history. Depending on environment flags, it will either warn or fail on unapplied migrations and drift, then prints a concise PASS/FAIL report and sets the exit code for CI.

When to use it

Before pushing releases or running deploy pipelines
As a CI gating step prior to automated migration/apply stages
Before starting servers that auto-run migrations at startup
When validating environment configuration in staging or production
During pre-deploy checks for database-focused pull requests

Best practices

Run as a mandatory step in CI to enforce migration hygiene
Set PRISMA_SCHEMA_PATH when your schema is not at prisma/schema.prisma
Provide a specific DB env key with PRISMA_MIGRATE_DB_URL_ENV for multi-db projects
Use PRISMA_MIGRATE_GUARD_ALLOW_UNAPPLIED=1 or ALLOW_DRIFT=1 only for non-blocking checks
Keep the guard read-only; apply migrations in controlled deploy steps only

Example use cases

CI job that fails the build if any migration files are unapplied or have failed
Prestart script on container images to verify DB and migrations before starting the app
Nightly health checks that detect schema drift between code and DB
Pre-merge checks in PRs that touch Prisma schema or migration files
Deploy pipeline that gates production rollout until migration status is clean

FAQ

Will this apply migrations automatically?

No. The guard runs prisma migrate status in read-only mode and will not apply migrations.

How do I allow warnings instead of failures for unapplied files or drift?

Set PRISMA_MIGRATE_GUARD_ALLOW_UNAPPLIED=1 or PRISMA_MIGRATE_GUARD_ALLOW_DRIFT=1 to downgrade those conditions to warnings.