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.

[atharvgit2005]

For a project anticipating 30–50 models, managing a single monolithic schema.prisma file becomes cumbersome and causes merge conflicts. Here is the standard production architecture recommended for Prisma (version 5.15+ and 6.x/7.x):

1. Enable the Multi-File Schema Feature (prismaSchemaFolder)

In Prisma 5.15+, you no longer need external schema splitters or build scripts. Enable native schema splitting in your schema.prisma:

// prisma/schema/base.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["prismaSchemaFolder"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

[mccrearydamion69-crypto]

What's up thread

[kingofdead6]

One thing I'd clarify in the existing answers is the version-specific part.

For a new Prisma 7 project, I wouldn't recommend enabling prismaSchemaFolder as a preview feature. Multi-file schemas are supported natively now, so the folder can simply be configured through prisma.config.ts.

For example:

// prisma.config.ts
import { defineConfig, env } from "prisma/config";

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

Then I would structure the schema roughly by domain:

prisma/
  schema/
    schema.prisma       # generator + datasource
    users.prisma
    billing.prisma
    products.prisma
    orders.prisma
  migrations/
prisma.config.ts

The important distinction is that these files are still one Prisma schema. Splitting them doesn't create separate modules or separate migration histories, so relations can cross domain files normally.

For 30–50 models, I'd also avoid creating one PrismaClient per domain. Keep a single client instance and organize the application layer around domains instead:

src/
  db/
    client.ts
  users/
    users.service.ts
    users.queries.ts
  billing/
    billing.service.ts
    billing.queries.ts
  orders/
    orders.service.ts
    orders.queries.ts

That gives you domain boundaries without creating multiple connection pools.

For migrations, I'd keep exactly one migration history even with multiple schema files. The migration history represents the database as a whole, not individual Prisma schema files.

So my rule of thumb would be:

• < ~20 models: one schema file is perfectly reasonable.
• 30–50 models: multi-file, domain-oriented schema.
• 50+ models: still domain-oriented, but introduce stronger application-layer boundaries as complexity grows.
• PrismaClient: one application-level instance.
• Migrations: one shared migration directory.
• Production: prisma migrate deploy, not db push.

The main benefit of multi-file schemas at this size isn't performance or a different Prisma architecture — it's reducing merge conflicts and making ownership/navigation clearer for developers.

[rsheth8]

For 30–50 models, the multi-file schema approach (stable since Prisma 5.15, enabled with prismaSchemaFolder) is the way to go. Here is a pattern that scales well:

Directory layout

prisma/
  schema/
    schema.prisma      ← datasource + generator
    user.prisma
    product.prisma
    order.prisma
    ...

schema.prisma

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["prismaSchemaFolder"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

Then each domain file only contains its own models, enums, and relations. Prisma resolves cross-file relations automatically.

Practical tips

• Group by domain, not by type (do not make a separate file for every enum).
• Keep junction/pivot models in the file of the entity that owns the relationship.
• Relations that span domains go in whichever domain you consider the "owner".
• 30–50 models fits comfortably in ~8–12 files; do not over-split.

Single file is fine up to ~20 models. Beyond that, the multi-file approach pays off in readability and merge-conflict reduction alone.