# @toolctrl/db

Database ownership package.

This package owns the server-side Prisma client boundary, the generated Prisma TypeScript client, and the repository database command surface while the root schema and migrations remain in their existing locations.

Current ownership:

- Schema: `prisma/schema`
- Migrations: `prisma/migrations`
- Generated client: `packages/db/generated/prisma/client`
- Prisma 7 TypeScript entrypoints: `packages/db/generated/prisma/client/client.ts` and `packages/db/generated/prisma/client/browser.ts`
- Server client API: `@toolctrl/db/client.server`

Use `getDbClient()` from `@toolctrl/db/client.server` for server-side Prisma client creation and development singleton reuse.

Transaction helpers are available from `@toolctrl/db/transactions.server` and the root package export. `runDbTransaction(callback, client?)` wraps interactive Prisma transactions behind an injectable client, while `runDbTransactionBatch(operations, client?)` runs batch operations without forcing app imports.

Seed helpers are available from `@toolctrl/db/seed.server` and the root package export. `runDbSeed({ nodeEnv, adminEmail, adminPassword, seedCredentials, seed, diagnostics })` runs exactly one caller-provided seed callback, rejects production runs that still use local default seed emails or the default `password`, emits `start` / `success` / `failure` diagnostics, and never includes password values in diagnostic events. Use `assertSafeSeedCredentials(options)` when a caller needs to perform the production credential guard separately.

Package scripts delegate to the current root Prisma config while keeping callers on the `@toolctrl/db` package:

- `pnpm --filter @toolctrl/db prisma:generate`
- `pnpm --filter @toolctrl/db prisma:migrate:deploy`
- `pnpm --filter @toolctrl/db seed`
- `pnpm --filter @toolctrl/db permissions:sync`
- `pnpm --filter @toolctrl/db typecheck`

For the non-E2E database CI status gate, see [Database CI runbook](../../docs/db-ci.md). The root `pnpm run verify:db-migrate-status` command checks Prisma migration status through this package boundary and requires a configured `DATABASE_URL` secret.

Root-facing scripts use the same package boundary instead of invoking Prisma or the seed file directly:

- `pnpm run db:generate`
- `pnpm run db:migrate:deploy`
- `pnpm run seed`
- `pnpm run permissions:sync`
- `pnpm run build`
- `pnpm run typecheck`

Planned ownership:

- Migrate app, API and worker database imports to package APIs.
- Keep schema and migrations in `prisma/` until a separate migration explicitly moves those files.

Decision records:

- [ORM Decision Record](./ORM-DECISION.md): preserve Prisma for now; evaluate Prisma 7 vs Drizzle after database package boundaries are stable.