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 @hivegrid/db prisma:migrate:status, so CI and local checks use the same @hivegrid/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 @hivegrid/db, and then runs the non-E2E status verifier.

The database job generates the Prisma client, verifies the generated tenant-policy contract and migration/schema parity, runs the ephemeral live-RLS gate, checks migration status outside pull requests, and executes the database package tests. It must not run migrate deploy, seed commands, browser automation, or browser E2E checks.

Live-RLS-Gate

Der getrennte Gate-Befehl

pnpm run verify:rls-live

startet eine wegwerfbare PostgreSQL-16-Instanz und beweist den vollständigen Rollenvertrag. Er provisioniert hivegrid_migrator, hivegrid_app, hivegrid_portal, hivegrid_worker, hivegrid_authentik_jit und hivegrid_rls_definer, entzieht dem Migrator in einer separaten Negativ-Datenbank absichtlich die Definer-Mitgliedschaft und erwartet dort einen harten Migrationsfehler. Anschließend provisioniert er den korrekten Vertrag erneut, spielt die gesamte Migration-Historie als nicht privilegierter hivegrid_migrator auf eine frische Datenbank und führt die echten App-/Portal-/Worker-Isolationstests aus.

Damit prüft das Gate ausdrücklich nicht nur RLS zur Laufzeit, sondern auch, dass Migrationen keinen Superuser und kein BYPASSRLS auf dem Migrator benötigen. Die Testpasswörter sind nur lokale, kurzlebige Fixtures und werden nicht ausgegeben. Produktions-Secrets dürfen diesem Gate niemals übergeben werden.

Das statische Gegenstück ist:

pnpm run verify:tenant-policy-contract
pnpm run verify:rls-release-readiness

Der erste Befehl verhindert Drift zwischen Scope-Manifest, fachlichem Policy-Vertrag, generiertem SQL-Artefakt und Cutover-Migration. Der zweite prüft, ob jedes laut Manifest RLS-pflichtige Modell in den auslieferbaren Migrationen ENABLE, FORCE und eine kanonische Policy besitzt. Ein grüner statischer Check ersetzt den Live-Test nicht; der Live-Test ersetzt wiederum keinen Staging-/Produktions-Cutover mit den echten Rollen, Secrets, Bestandsdaten und PgBouncer-/Coolify-Einstellungen.

Der aktuelle Implementierungs- und Operations-Handoff steht in security/RLS-HARDENING-2026-07-13.md. Dort ist der Produktions-Rollout ausdrücklich als noch nicht nachgewiesen markiert.

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 @hivegrid/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 @hivegrid/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.

5.4 KiB Raw Blame History