prisma/prisma

config

Active contributors: jacek-prisma, Oleksii Orlenko, Søren Bramer Schmidt

Purpose

@prisma/config is the loader for prisma.config.ts files. It's the single source of truth for "where does Prisma get connection details and project settings". In Prisma 7 it replaced the old pattern of embedding a datasource URL or env() reference directly in schema.prisma.

The package exports the user-facing defineConfig and env helpers, plus the internal PrismaConfigInternal type that the rest of the toolkit reads.

What `prisma.config.ts` looks like

User-facing API:

import { defineConfig, env } from 'prisma/config';

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env<{ DATABASE_URL: string }>('DATABASE_URL'),
  },
});

env() is type-safe via the explicit Env type parameter; if DATABASE_URL is missing at runtime, env() throws.

defineConfig is just a function that types its argument and returns it — there's no hidden state.

Directory layout

packages/config/
├── src/
│   ├── ...                # defineConfig, env, PrismaConfigInternal, loader
│   └── __tests__/
├── helpers/
├── vitest.config.ts
├── vitest.setup.ts
└── package.json

The package uses Vitest (not Jest) — it's one of the newer subsystems written natively for the Prisma 7 stack.

Key abstractions

Symbol	What it does
`defineConfig(config)`	Type-tags the user's config object. Identity at runtime.
`env(name)`	Reads a process environment variable, throws if missing
`PrismaConfigInternal`	The shape the rest of Prisma reads. `loadedFromFile` flags whether the config came from a file
Loader	Resolves and imports `prisma.config.ts` (TypeScript-aware via tsx)

Loading semantics

SQLite URLs are resolved relative to the config file, not the schema file. This is a Prisma 7 change. If the config file is at /project/prisma.config.ts and the URL is file:./dev.db, the resolved path is /project/dev.db.
.env files are not auto-loaded. Users must opt in with import 'dotenv/config' at the top of prisma.config.ts, or use a runtime that loads .env natively (Bun, node --env-file=.env, tsx --env-file=.env).
loadedFromFile is a boolean on PrismaConfigInternal that flags whether the config object came from disk or was synthesized in tests. Studio in particular uses this signal to decide how to resolve relative SQLite URLs.

How tests use it

From AGENTS.md:

Test helpers: ctx.setConfigFile('<name>') (from __helpers__/prismaConfig.ts) overrides the config used for the next CLI invocation and is automatically reset after each test, so no explicit cleanup is needed.

Many migrate fixtures pair a schema variant with a matching config file:

fixtures/some-test/
├── invalid-url.config.ts
├── invalid-url.prisma
├── good.config.ts
└── good.prisma

Tests swap between them with ctx.setConfigFile('invalid-url') etc.

Integration points

packages/cli — every CLI subcommand loads config at startup
packages/migrate — Migrate commands consume PrismaConfigInternal.datasource to know what database to connect to
packages/internals — exposed through loadSchemaContext / config-aware helpers
Test helpers — packages/migrate/src/__tests__/__helpers__/context.ts and prismaConfig.ts

Entry points for modification

Add a new config field: extend PrismaConfigInternal, update the loader, update defineConfig's typed argument, update consumers in cli/migrate/internals
Change resolution semantics: the loader and the relative-path logic
Tighten env validation: env() and the loadedFromFile flag