# 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:

```sh
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.