62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# 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.
|