Database CI runbook

Purpose

The database CI gate verifies that the repository can reach its configured database and that Prisma reports migration status through the package-owned database boundary. The root command pnpm run verify:db-migrate-status shells through pnpm --filter @toolctrl/db prisma:migrate:status, so CI and local checks use the same @toolctrl/db command surface instead of invoking Prisma directly.

This is a non-E2E gate. Auto-Mode does not run browser, Playwright, Cypress, or other E2E checks for this task, and the database job must not include browser automation commands.

Required secret

Configure a CI secret named DATABASE_URL for the database status check. The secret must be scoped to the migrate-status step, not the whole job, so unrelated CI steps do not receive database credentials.

Use placeholder names in documentation and CI examples only:

secret name: DATABASE_URL
command: pnpm run verify:db-migrate-status

Do not paste connection strings, credentials, usernames, passwords, hosts, or database names into docs, issues, comments, or logs.

Local dry run

To run the same status verifier locally, set DATABASE_URL in your shell environment using your normal secret-management workflow and run:

pnpm run verify:db-migrate-status

The verifier fails before spawning Prisma when DATABASE_URL is absent. It does not print the secret value.

CI job order

The Gitea workflow includes a database job that depends on quality. The job installs dependencies with the pinned pnpm setup, generates the database client through @toolctrl/db, and then runs the non-E2E status verifier.

The database job runs migration status only. It must not run migrate deploy, seed commands, browser automation, or E2E checks.

Status outcomes

pnpm run verify:db-migrate-status reports diagnostic fields intended for CI logs and local troubleshooting:

phase: where the verifier is running or failing, such as preflight, spawn, or completion
command: the package-bound command being executed
exit code: the process exit code when Prisma finishes
status outcome: success or failure classification
sanitized stdout/stderr excerpt: a bounded output excerpt with secrets redacted

A success means Prisma migration status completed through the @toolctrl/db boundary. It does not apply migrations, seed data, or prove browser-facing behavior.

Failure diagnostics

Common failures and first checks:

Missing DATABASE_URL: confirm the CI secret exists and is scoped to the migrate-status step.
Spawn failure: confirm pnpm dependencies are installed and the @toolctrl/db package scripts are available.
Non-zero Prisma exit: inspect the sanitized stdout/stderr excerpt and the Prisma status message in CI logs.
Workflow contract failure: run pnpm run verify:gitea-ci-workflow and fix the database job shape before changing the database verifier.

The primary inspection surfaces are CI job logs, pnpm run verify:db-migrate-status, pnpm run verify:gitea-ci-workflow, and this runbook.

Redaction expectations

Diagnostics must never print DATABASE_URL or embedded credentials. The verifier redacts the literal configured value and credential-like URL components before showing output excerpts. If a failure report includes secret material, treat it as a security incident: remove the exposed value from the report, rotate the credential, and fix the redaction path before sharing more logs.

3.4 KiB Raw Blame History