prisma-next-runtime

Prisma Next — Runtime (db.ts Wiring)

Edit your data contract. Prisma handles the rest.

This skill covers the runtime entry point — db.ts — and how to compose the database client with extensions, middleware, and environment configuration.

When to Use

• User is wiring up db.ts for the first time (post-init).
• User wants to add middleware (telemetry, lints, budgets, custom).
• User wants per-environment config (dev vs prod, multi-region).
• User wants to switch between the Postgres, SQLite, and Mongo façades.
• User wants to wrap operations in db.transaction(...) (Postgres and SQLite).
• User is running a one-off script (tsx my-script.ts, Node CLI, CI task) and the process won't exit after queries finish, or they need script teardown (db.close(), await using).
• User mentions: db.ts, postgres(), mongo(), middleware, telemetry, lints, budgets, DATABASE_URL, .env, connection pool, poolOptions, dev vs prod, transactions, read replicas, multi-database, script won't exit, hangs, db.close, db.end, close connection, pool.end, await using.

When Not to Use

• User wants to write queries → prisma-next-queries.
• User is on Supabase — the supabase() role-first factory, asUser(jwt) / asAnon() / asServiceRole(), JWT config, RLS → prisma-next-supabase.
• User wants to edit the contract → prisma-next-contract.
• User wants to wire Prisma Next into a build tool (Vite plugin, Next.js, …) → prisma-next-build.
• User wants to debug a connection / runtime error → prisma-next-debug.
• User wants to file a bug or feature request → prisma-next-feedback.

Key Concepts

• db.ts is the runtime entry point. Imports the runtime factory from the @prisma-next/<target> façade (@prisma-next/postgres/runtime, @prisma-next/sqlite/runtime, or @prisma-next/mongo/runtime), the contract artefacts (contract.json + the Contract type from contract.d.ts), and any middleware. Exports a db value the rest of your app imports.
• The façade's runtime factory is the only surface user-authored db.ts imports from. Each factory is a default export. For Postgres: import postgres from '@prisma-next/postgres/runtime'; SQLite: import sqlite from '@prisma-next/sqlite/runtime'; Mongo: import mongo from '@prisma-next/mongo/runtime'. The factory signature is <Target><Contract>(options) — a single type parameter (the Contract type from contract.d.ts), and one options object.
• Lazy connect. The factory does not connect to the database synchronously. Static query surfaces (db.sql, db.orm) are available immediately; the driver / pool is instantiated on the first call that needs a runtime (or when you explicitly call await db.connect({ url })). This is why db.ts can be imported in modules that load before the env is ready.
• Middleware composes in order. The first middleware in the middleware: [...] array runs outermost — it sees the operation first on the way in and last on the way out. Telemetry first means budget / lint failures show up inside telemetry spans.
• prisma-next.config.ts vs .env. The config (defineConfig({ contract, db, extensions, migrations })) is for static project shape: contract path, installed extensions, migrations directory, default connection string. .env is for per-environment values (DATABASE_URL, secrets). The config reads .env automatically via dotenv/config. Hardcoding DATABASE_URL in the config file leaks credentials and bypasses per-env overrides.
• Build-system / dev-server integration is a separate skill. vite dev auto-emit lives in prisma-next-build. The runtime side (this skill) reads contract.json / contract.d.ts regardless of how they got onto disk, so the two skills compose cleanly.