Prisma Config, Supabase URLs & Shadow Database Separate runtime traffic from migration tooling
Course rule: Prisma CLI, @prisma/client and @prisma/adapter-pg are locked to 7.9.1. Newer Prisma releases are not substituted halfway through the course.
1. Prisma CLI and NestJS Runtime Have Different Connection Jobs
NestJS runtime Prisma CLI Uses DATABASE_URL Uses DIRECT_URL Long-running application traffic Migrations / introspection / Studio PrismaPg / pg pool Needs session semantics Session-capable pooled URL works migrate dev also needs shadow DB well locally
2. Configure prisma.config.ts apps/api/prisma.config.ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";export default defineConfig({ schema: "prisma/schema.prisma", migrations: { path: "prisma/migrations", }, datasource: { // CLI / migrations: direct or session-capable connection. url: env("DIRECT_URL"), }, });
The CLI now reads DIRECT_URL. For Supabase, prefer the direct database URL when your network can reach it. A session pooler connection on port 5432 is an alternative when direct IPv6 connectivity is unavailable. Do not use transaction pooling for migration tooling.
3. Environment Variables apps/api/.env.example
# Runtime application connection (Phase 08 recommends a session-capable pooled URL for local NestJS). DATABASE_URL=
# Prisma CLI / migration connection. Prefer a direct URL when reachable. DIRECT_URL=
# Optional only if migrate dev cannot create an automatic shadow database. # NEVER point this at the same database as DIRECT_URL. SHADOW_DATABASE_URL=
4. Why migrate dev Needs a Shadow Database Prisma Migrate replays migration history in a temporary shadow database to detect drift and evaluate the next migration. That means migrate dev needs either permission to create/drop a shadow database automatically or a separately configured shadow database.
DANGER SHADOW_DATABASE_URL must never point to the same database as DIRECT_URL. A shadow database is reset during migrate dev and can destroy data if misconfigured.
5. Supabase Privileges Supabase's current Prisma guidance recommends a dedicated Prisma database user with the privileges required for migrations, including CREATEDB when automatic shadow-database creation is used. Keep this as a development/migration concern; application runtime access should still follow least privilege as the course matures.
6. If Automatic Shadow Creation Fails Do not immediately switch to db push and ignore migration history. First diagnose whether the database user has CREATEDB. If cloud restrictions prevent automatic shadow creation, create a dedicated shadow database and set SHADOW_DATABASE_URL in prisma.config.ts. Optional prisma.config.ts change
datasource: { url: env("DIRECT_URL"), shadowDatabaseUrl: env("SHADOW_DATABASE_URL"), },
Checkpoint • DATABASE_URL is reserved for runtime PrismaPg.
• DIRECT_URL is used by Prisma CLI/migrations.
• Transaction pooler 6543 is not used for migration tooling.
• Shadow DB configuration is understood before migrate dev is run.
Prisma improves developer ergonomics, but migrations and generated queries still change a real relational database. You should be able to inspect both sides.
Restate the goal of “Prisma Config Supabase URLs and Shadow Database” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: domain intent → Prisma Client → generated SQL → PostgreSQL → mapped result. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: Prisma schema + migration history + generated client + NestJS PrismaService connected to TaskFlow PostgreSQL.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
const tasks = await prisma.task.findMany({
where: { workspaceId },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
take: 20,
});Do not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Verify connection string, host, port, SSL/pooler mode, network reachability, and which environment file the process loaded.
Read the generated SQL before applying it and compare the change against existing production-shaped data.
Without copying the final source, create a second small scenario that applies “Prisma Config Supabase URLs and Shadow Database” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Perform a smoke query through the service, then inspect the created database object independently.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.CLI/client version mismatch
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.