Best practices for organizing Prisma schema in medium-sized projects?

[VIJAYAPANDIANT]

I'm building a full-stack application using Prisma with PostgreSQL and expect around 30–50 models in the future.

What are the recommended practices for organizing the Prisma schema?

• Should I keep everything in one schema file?
• Is the multi-file schema approach recommended?
• How do you organize models, migrations, and Prisma Client in larger projects?

I'd appreciate any advice or examples from production projects.

[paulodearaujo]

For 30–50 models, I would use the multi-file schema, but split by domain rather than creating one file per model.

A practical layout is:

prisma/
  schema/
    schema.prisma      # generator and datasource
    identity.prisma    # User, Session, Role...
    billing.prisma     # Invoice, Subscription...
    catalog.prisma     # Product, Category...
  migrations/
prisma.config.ts

With current Prisma, point schema at the folder and keep one migration history:

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

export default defineConfig({
  schema: 'prisma/schema',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

Prisma loads the .prisma files as one schema, so models and relations can reference each other across files. The files are for navigation and ownership; they are not isolated modules. The current setup is documented under multi-file Prisma schemas and the Prisma config reference.

A few rules have kept this manageable in larger projects:

• Keep generator and datasource in one obvious root file.
• Group tightly related models and enums together. Avoid both a 2,000-line file and 50 tiny files.
• Keep a single migrations/ directory and commit it. Migrations describe changes to the whole database, not one domain file.
• Generate one Prisma Client for that schema. Export a single application-level client from something like src/db.ts; do not create one client per domain.
• Use prisma migrate dev locally and prisma migrate deploy in production. Do not use db push as the production migration workflow.
• Run prisma format, prisma validate, and prisma generate in CI.

If the project is still small and the domain boundaries are unclear, one file is fine. At 30–50 models, though, a domain-based split usually pays for itself without changing how Prisma Client or migrations work.

[MILLERMARRU]

paulodearaujo's folder-per-domain layout is the right shape for the schema side. One thing worth adding for the "how do you organize... Prisma Client" part of your question, since that's less settled than the schema split.

The instinct to avoid a client-per-domain is correct (you'd end up with N connection pools and no single source of truth for $transaction across domains), but that doesn't mean the single client has to stay a flat, undifferentiated object either. With Prisma 7's client extensions API, a pattern that holds up well for a 30-50 model client is splitting extensions by domain and composing them onto one instance:

// src/db/extensions/billing.ts
import { Prisma } from '../generated/client';

export const billingExtension = Prisma.defineExtension({
  name: 'billing',
  model: {
    invoice: {
      async markPaid(id: string) {
        return prisma.invoice.update({ where: { id }, data: { status: 'PAID', paidAt: new Date() } });
      },
    },
  },
});

// src/db.ts
import { PrismaClient } from './generated/client';
import { billingExtension } from './extensions/billing';
import { catalogExtension } from './extensions/catalog';

const prisma = new PrismaClient().$extends(billingExtension).$extends(catalogExtension);

export default prisma;

This gives you the same domain boundaries you already have in the schema files, but on the client side. invoice.markPaid() reads like a domain method instead of a bag of raw CRUD calls scattered across route handlers, without ever creating a second PrismaClient instance. It also composes well with the multi-file schema split, since there's a natural one-to-one mapping between a billing.prisma file and a billing.ts extension file, so new engineers can find both halves of a domain in predictable places.

One more thing worth locking down early at your scale: seed script organization. With prisma.config.ts's migrations.seed entry pointing at a single script, it's tempting to let that script grow into one large file. Splitting it into one seeder function per domain (mirroring the schema folders) and importing them into a single orchestrator in the seed entrypoint keeps it from becoming the one file everyone's afraid to touch as the model count grows.

[jlr2193224-code]

Okay, thanks.

[MILLERMARRU]

IF IT WAS HELP YOU CAN MARK MY ANSWER AS AN ANSWER.

[jlr2193224-code]

Yes

[MILLERMARRU]

thank you very much in advance

[Nithwin]

Good timing on this question — Prisma's multi-file schema support changed things a lot for projects at your scale.

On the schema organization question

For 30–50 models, the multi-file schema is the right move, but the key is splitting by domain rather than by model. One file per model will leave you with 50 tiny files that are hard to navigate. One big file has obvious problems. Domain-based split hits the sweet spot:

prisma/
  schema/
    schema.prisma       # datasource + generator (the only root config)
    identity.prisma     # User, Session, Role, Permission
    billing.prisma      # Invoice, Subscription, PaymentMethod
    catalog.prisma      # Product, Category, Tag, Inventory
    orders.prisma       # Order, OrderItem, Shipment
  migrations/           # single history, not per-domain
  prisma.config.ts

Prisma loads all .prisma files as one schema — models can reference each other across files freely. The split is for developer navigation, not isolation.

On PrismaClient organization

This part trips up a lot of projects at your scale. The core rule: one PrismaClient instance for the whole app. Multiple instances = multiple connection pools, which causes issues under load. Export a singleton:

// src/db/client.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
export const prisma =
  globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

For query organization at 30–50 models, I'd recommend a pragmatic split rather than going full repository pattern everywhere:

• Simple CRUD: call prisma.model.x() directly in your service
• Shared filters/includes: extract as query builder functions in a queries.ts file per domain
• Multi-step writes: put the $transaction boundary in the service or use-case layer

For example:

// src/billing/billing.queries.ts
export const invoiceFilters = {
  forCustomer: (id: string): Prisma.InvoiceWhereInput => ({ customerId: id }),
  unpaid: (): Prisma.InvoiceWhereInput => ({ status: { in: ['PENDING', 'OVERDUE'] } }),
};

// src/billing/billing.service.ts
const invoices = await prisma.invoice.findMany({
  where: {
    ...invoiceFilters.forCustomer(customerId),
    ...invoiceFilters.unpaid(),
  },
});

This avoids the overhead of full repository classes while still keeping reusable query logic in one place.

On migrations

Keep one migrations/ directory regardless of how many schema files you have. Migrations describe changes to the whole database schema as a linear history — splitting them by domain would create ordering nightmares. prisma migrate dev locally, prisma migrate deploy in production. Never db push in production.

Quick summary for your scale

Concern	Recommendation
Schema files	Multi-file, split by domain
PrismaClient	Singleton, one instance
Simple queries	Direct in service
Reused filters	Query builder functions per domain
Complex writes	$transaction at service layer
Migrations	Single history, linear

At 30–50 models you have enough to feel the pain of bad organization but not so much that you need a heavy repository abstraction everywhere — this middle path handles it well.