Prisma ORM

The API app uses Prisma ORM v6.19 for app-owned MongoDB models. Prisma ORM v7 MongoDB support is not the routine upgrade path yet; official Prisma docs currently say to use Prisma ORM v6.19 for MongoDB work.

What It Owns

App-owned API Prisma models in apps/api/prisma/schema.prisma.
MongoDB indexes declared with Prisma attributes such as @@index and @@unique.
Local and production schema/index sync expectations for API-owned collections.
Drift checks that catch unexpected collections, stale fields, and missing expected indexes.

This does not cover Mastra-owned collections, Payload CMS collections, Better Auth collections, or provider-owned external data shapes.

Architecture Decision

Decision: use Prisma only for typed access to API-owned MongoDB models and keep schema/index sync explicit.

Prisma client generation updates TypeScript client output. It does not guarantee MongoDB indexes exist. The repo keeps db push as an explicit operation because it mutates database schema/index metadata.

Current Workflow

For local API Prisma MongoDB schema/index changes:

bun run db:sync-local

db:sync-local runs the guarded local schema/index push first and then the read-only drift audit in strict mode, so any audit error makes the command fail. The push step wraps prisma db push --skip-generate and refuses non-local Mongo hosts. It is intentionally not wired into init, dev, test, build, or start hooks.

db:audit-drift is read-only. It checks the configured API database for Prisma-owned collections, Mastra-owned collections with the mastra_ prefix, unexpected non-API collections, stale API fields/indexes, and expected Prisma indexes that are missing from MongoDB.

When a canonical pre-release chat shape explicitly requires disposable chat data to be reset, keep that destructive action separate. Review the exact scope first, then explicitly execute the guarded reset before syncing the new index:

bun run chat:data:clear
NODE_ENV=development CHAT_DATA_CLEAR_ENABLED=true bun run chat:data:clear -- --execute
bun run db:sync-local

Leave USER_ID unset when the approved reset covers every pre-release chat in the shared local database. The execution step still requires loopback-only targets, no active/running turns, and the exact interactive confirmation phrase. Schema sync never clears chats.

Run bun run --cwd apps/api prisma:generate or the normal app typecheck path when generated Prisma client output needs to be refreshed.

Pre-release one-time API data repair scripts for older local connector, user-settings, provider-upload, chat-thread, chat-share, and automation records were run on 2026-06-24 and removed after the local data reached the canonical shape. If a restored local/pre-release database later reports old-shape drift, clear or regenerate that local data, or add a reviewed one-off repair in the branch that needs it. Do not add runtime compatibility reads for old document shapes.

Production / Customer Clusters

Prisma’s standard MongoDB schema-sync command is prisma db push. Prisma Migrate does not support MongoDB.

For production or customer-cluster releases, do not use the local helper. Schema/index sync must be a reviewed release step or runbook action that uses the target deployment’s own DATABASE_URL.

The production runbook should:

run from the API app context with the intended deployment environment
use prisma db push --skip-generate
never use --accept-data-loss
never use --force-reset
run bun run --cwd apps/api db:audit-drift afterward against the same target database
record any Prisma-reported index removals before proceeding if they were not expected

Because db push syncs the database toward the Prisma schema state, it can remove indexes that exist in MongoDB but are not represented in schema.prisma. Treat any such removal as a release decision, not as routine startup work.

How To Upgrade

Check Prisma’s MongoDB connector docs before any Prisma upgrade.
Do not move API Prisma beyond the documented MongoDB-supported line without updating apps/api/AGENTS.md, the drift docs, and the relevant tests in the same change.

For safe v6 patch/minor updates inside the documented MongoDB line:

# from apps/api
bun update prisma @prisma/client
bun run prisma:generate
bun run check-types
bun run db:audit-drift

Run connector/chat lanes when changed Prisma behavior could affect connector metadata, chat threads, permissions, or retrieval state.

Current Limits

Prisma Migrate is not available for MongoDB in the installed Prisma line.
db push is a state-sync operation, not a versioned migration artifact.
MongoDB’s flexible document model means data backfills and field cleanup still need explicit scripts or reviewed operational actions, such as the dry-run-first user-settings repair command for pre-release optionalChatClarificationRequestsEnabled data.
Prisma’s MongoDB docs call out performance considerations for large collections; use targeted indexes and avoid expensive count paths in hot runtime code.

Canonical Sources

apps/api/prisma/schema.prisma
apps/api/prisma.config.ts
apps/api/package.json
apps/api/scripts/runPrismaDbPushLocal.ts
apps/api/scripts/auditApiDatabaseDrift.ts
apps/api/scripts/localDatabaseSchemaScripts.test.ts
docs/features/connectors/spec.md
apps/api/AGENTS.md