HiveGrid-Wireframes/hivegrid-cloud/docs/database.md

Production Database Operations Guide

Purpose

This guide is the operator-facing entrypoint for PostgreSQL and Prisma database operations in production-facing environments. It explains the safe command boundaries for checking migration status, deploying migrations, generating Prisma client artifacts, and triaging database failures without exposing credentials or customer data.

Use this guide with the existing database CI and local setup references:

• docs/db-ci.md documents the CI migration-status verifier and redacted status output.
• docs/local-dev.md documents local PostgreSQL and Prisma setup for day-to-day development.

Required environment keys

Database operations are driven by key names only. Documentation, issues, CI logs, and runbooks must never include connection strings, database passwords, usernames, hosts, database names, or customer data.

Required or relevant keys:

• DATABASE_URL: Prisma PostgreSQL connection setting used by migration status, migration deploy, runtime database access, and local development.
• DIRECT_URL: optional direct Prisma connection setting for maintenance flows when the deployment environment requires a separate direct connection.

Operators should confirm that the required key names exist in the target secret store, CI setting, or platform environment. Do not paste raw values into tickets, chat, docs, screenshots, or verifier output.

Local PostgreSQL and Prisma workflow

For local development, follow docs/local-dev.md first. Start a local PostgreSQL instance, create a disposable local database, set DATABASE_URL to a local placeholder value, and keep production credentials out of local files.

Local-only Prisma commands may be used while developing schema changes:

pnpm exec prisma migrate dev
pnpm exec prisma migrate status
pnpm exec prisma db push
pnpm exec prisma generate

Use pnpm exec prisma migrate dev for normal local migration authoring. Use pnpm exec prisma migrate status to inspect local drift. Use pnpm exec prisma db push only for deliberate disposable local database bootstraps where migration history is not the source of truth. Refresh generated Prisma client artifacts with pnpm exec prisma generate when local schema or dependency changes require it.

These local commands are not production deployment commands. They must not be copied into production migration automation.

CI migration-status gate

The CI status gate is a read-only verification boundary for migration status:

pnpm run verify:db-migrate-status

This command is documented in docs/db-ci.md and routes through the repository-owned @toolctrl/db package surface. It checks that Prisma can report migration status for the configured PostgreSQL database and emits bounded, redacted diagnostic fields such as phase, command, exit code, status outcome, and sanitized output excerpts.

A passing migration-status gate means the status command completed. It does not deploy migrations, seed data, reset schemas, or prove browser-facing behavior. Do not confuse status checks with deploy migrations.

Production migration deployment

Production migration deployment uses the package-level deployment command:

pnpm run db:migrate:deploy

Run this only in the approved deployment path for the target environment, with the environment's secret store providing DATABASE_URL and any required DIRECT_URL. The command applies already-authored Prisma migrations; it is not a schema authoring workflow and must not be mixed with local-only commands such as pnpm exec prisma migrate dev or pnpm exec prisma db push.

Before deploying, confirm that the intended migration set has passed review and that the CI migration-status gate is healthy. After deployment, inspect the approved deployment logs and the migration-status verifier output for redacted success or failure signals. If deployment fails, do not paste connection details or table contents into the incident record; capture the command name, exit code, diagnostic phase, and sanitized Prisma excerpt only.

Backup and restore expectations

Backups and restores are environment-owned operational responsibilities. Before running production migrations, operators must confirm that the target environment has a current backup or restore point according to the hosting provider or database platform policy.

Restore drills should use platform-approved tooling and should document only high-level evidence: environment name, backup timestamp or restore-point identifier, operator, result, and redacted error code if applicable. Never include database dumps, customer rows, credentials, hosts, usernames, passwords, or full connection strings in repository docs or issue trackers.

For local testing of destructive schema work, use disposable local databases instead of production data. Synthetic fixtures and redacted samples are acceptable; customer data is not.

Prisma client generation

Generated Prisma client artifacts are refreshed through the repository script:

pnpm run db:generate

The root build also generates the database client before building the web runtime. Run pnpm run db:generate after schema changes, dependency updates, or deployment preparation when generated types or client artifacts may be stale.

Generation does not connect to production data and must not be treated as a migration or data validation step. If generation fails, inspect package install state, Prisma schema validity, and sanitized compiler output before investigating database connectivity.

Troubleshooting and safe observability

Use these safe inspection surfaces for database failures:

• CI logs from pnpm run verify:db-migrate-status with sanitized stdout and stderr excerpts.
• Approved deployment logs for pnpm run db:migrate:deploy with secrets redacted.
• Local command output from pnpm exec prisma migrate status against a disposable local PostgreSQL database.
• Package script names, exit codes, diagnostic phases, and redacted Prisma error codes.
• docs/db-ci.md for the CI status verifier contract and docs/local-dev.md for local setup checks.

Common failure patterns:

• Missing DATABASE_URL: confirm that the key exists in the CI secret or platform environment and is scoped only to the database operation that needs it.
• Connection or authentication failure: confirm the secret store and database service health without copying the value, username, password, host, or database name into logs.
• Migration drift: run the status gate, inspect the sanitized Prisma status message, and distinguish read-only status output from deploy behavior before deciding on pnpm run db:migrate:deploy.
• Stale Prisma client: run pnpm run db:generate and re-run the focused check that reported stale generated artifacts.
• Local schema mismatch: use local-only pnpm exec prisma migrate status, pnpm exec prisma migrate dev, or a deliberate disposable pnpm exec prisma db push according to docs/local-dev.md.

If any troubleshooting output reveals a connection string, credential, hostname, username, password, database name, or customer data, treat it as a secret leak. Remove the exposed material from the shared surface, rotate affected credentials, preserve only redacted evidence, and fix the logging or documentation path before continuing.