ADR: Prisma 7 Migration

Status: Proposed Date: 2026-01-12 Deciders: Architecture Team Related: Prisma Schema Consolidation

Context

Current State

The monorepo uses Prisma 6.x across all packages:

• packages/database: 6.16.3
• apps/miniapp: 6.13.0 (being consolidated)
• Other consumers: Various 6.x versions

Prisma 7 Release

Prisma 7.0.0 was released with major breaking changes:

The datasource property `url` is no longer supported in schema files.
Move connection URLs for Migrate to `prisma.config.ts` and pass either
`adapter` for a direct database connection or `accelerateUrl` for
Accelerate to the `PrismaClient` constructor.

Breaking Changes in Prisma 7

1. Datasource URL removal from schema:

   # No longer supported in schema.prisma
   datasource db {
     provider = "postgresql"
     url      = env("DATABASE_URL")  # ❌ Removed
   }

2. New prisma.config.ts file required:

   // prisma.config.ts
   import { defineConfig } from 'prisma/config'
   
   export default defineConfig({
     datasources: {
       db: {
         url: process.env.DATABASE_URL,
       },
     },
   })

3. PrismaClient constructor changes:

   // New pattern for connection
   import { PrismaClient } from '@prisma/client'
   
   const prisma = new PrismaClient({
     adapter: myAdapter,  // Or accelerateUrl for Accelerate
   })

4. Migration command changes:

   • Migrations now read URL from prisma.config.ts
   • Runtime client uses adapter/constructor config

Decision

Defer Prisma 7 migration until after schema consolidation is complete.

Rationale

1. One Change at a Time: Consolidating schemas first reduces migration surface area
2. Stability: Prisma 6.x is stable and working
3. Breaking Changes: Prisma 7 requires significant refactoring
4. Ecosystem Readiness: Allow time for ecosystem (ORMs, tools) to catch up

Migration Strategy (When Ready)

1. Prerequisites:

   • Schema consolidation complete (single packages/database)
   • All consumers using @emergexyz/db
   • Test coverage for database operations

2. Phase 1: Configuration Migration:

   // packages/database/prisma.config.ts
   import { defineConfig } from 'prisma/config'
   
   export default defineConfig({
     earlyAccess: true,
     datasources: {
       db: {
         url: process.env.DATABASE_URL,
       },
     },
   })

3. Phase 2: Schema Update:

   # Remove url from datasource
   datasource db {
     provider = "postgresql"
     # url removed - now in prisma.config.ts
   }

4. Phase 3: Client Update:

   • Update PrismaClient instantiation pattern
   • Test all database operations
   • Update any direct Prisma CLI usage

5. Phase 4: Dependency Update:

   {
     "dependencies": {
       "@prisma/client": "^7.0.0",
       "prisma": "^7.0.0"
     }
   }

Consequences

Positive (of deferring)

• Reduced Risk: Consolidation is lower risk than version upgrade
• Incremental Progress: Can validate consolidation before adding complexity
• Team Bandwidth: Focus on one migration at a time

Negative (of deferring)

• Technical Debt: Staying on older version temporarily
• Missing Features: Prisma 7 improvements not available yet

Prisma 7 Benefits (when migrated)

• Better Configuration: TypeScript config file
• Improved Adapters: Better support for serverless/edge
• Performance: Various runtime improvements
• Type Safety: Enhanced type inference

Timeline

Phase	Description	Target
1	Schema Consolidation	January 2026
2	Prisma 7 Migration	February 2026
3	Adapter Optimization	March 2026

References

• Prisma 7 Release Notes
• Prisma Config File
• Breaking Changes