Skip to content

Database migration preflight

Lints a schema migration, dry-runs it on a replica and checks lock times before it ships.

Source: scripts/dev/review-runbooks/db-migration-preflight.yaml. CI checks it with runbook spec validate; teams, people, skills and called runbooks it names resolve against your server when you publish it.

apiVersion: therunbook.app/v1
kind: Runbook
metadata:
id: db-migration-preflight
title: Database migration preflight
description: Lints a schema migration, dry-runs it on a replica and checks lock times before it ships.
owners: [team:oncall]
tags: [database, deploy, agentic]
spec:
execution:
title: "Preflight ${{ inputs.migration }}"
inputs:
migration: { type: string, required: true }
defaults: { actor: agent }
steps:
- id: lint
title: Lint the migration
check: true
instructions: Run the migration linter on ${{ inputs.migration }}; flag table rewrites and missing concurrent index builds.
- id: dry_run
title: Dry-run on a replica snapshot
check: true
instructions: Restore last night's snapshot to a scratch replica, apply the migration and time it.
outputs:
duration_s: { type: integer, required: true }
- id: locks
title: Lock time under 2 seconds
check: true
instructions: From the dry run, report the longest ACCESS EXCLUSIVE lock held.
outputs:
longest_lock_ms: { type: integer, required: true }

Publish it to a project:

Terminal window
runbook push db-migration-preflight.yaml --project <project> --draft
runbook publish db-migration-preflight --project <project>