Organize Your Prisma Schema into Multiple Files in v5.15

It’s been a long road, but with Prisma ORM 5.15.0 we are finally introducing the ability to use multiple files in your Prisma Schema. This aims to improve the manageability and organization of your database schema, making it easier to work with larger projects. As one of our most requested features, we hope that you'll try out the prismaSchemaFolder Preview feature and let us know what you think on GitHub. Your continued feedback will help us deliver features like this one!

What is included in the multi-file Prisma Schema Preview feature

The new prismaSchemaFolder Preview feature allows you to define multiple files in a schema subdirectory of your prisma directory. Prisma handles the combining of files, allowing you to define a model in one file and then use it in other schema files without the need for importing. We've also included updates to the Prisma Visual Studio Code Extension to handle multiple schema files, including “Go to Definition” and checks for existence.

How to split your Prisma Schema into multiple files

First, make sure that prisma and @prisma/client have been updated to at least 5.15.0. You’ll also need the latest version (5.15.0) of the Prisma VSCode Extension in order to take advantage of these updates in your IDE.

To split your Prisma Schema into multiple files, first enable the prismaSchemaFolder Preview feature by including it in the previewFeatures field of your generator.

Then, create a schema subdirectory under your prisma directory. You can move your schema.prisma into this directory.

Now, you're able to create additional files in your schema directory! All models can be referenced in all files, so relations can cross files like so:

When running prisma generate all schema files are combined, so your workflow will continue as normal. Other Prisma CLI commands, such as validate and format have also been updated to work with multi-file Prisma Schemas.

When to use multi-file schemas

We’ve heard and seen that as a project grows, a single-file Prisma Schema eventually hits a point where it’s simply too large to manage effectively. You’ll see immediate benefits from this feature if you:

• Have a complex schema: if your schema has large models or complex relations, putting related models into a separate file can help make your schema easier to understand and navigate.
• Have a large team: when you have a single Prisma Schema file and have many developers committing, you could run into some pretty annoying merge conflicts during your day. Separating a large schema into several files can help reduce this pain.

Tips for multi-file Prisma Schemas

We’ve found a few patterns work well with this feature and will help you get the most out of it:

• Organize your files by domain: group related models into the same file. For example, keep all user-related models in user.prisma while post-related models go in post.prisma. Try to avoid having “kitchen sink” schema files.
• Use clear naming conventions: schema files should be named clearly and succinctly. Use names like user.prisma and post.prisma and not myModels.prisma or CommentFeaturesSchema.prisma.
• Have an obvious “main” schema file: while you can now have as many schema files as you want, you’ll still need a place where you define datasource and generator blocks. We recommend having a single schema file that’s obviously the “main” file so that these blocks are easy to find. main.prisma, schema.prisma, and base.prisma are a few we’ve seen that work well.

Sample Project

If you’d like to see how this feature looks in the real world, check out our fork of dub from dub.co, one of our favorite OSS projects!

We Want Your Feedback!

We'd love to hear your thoughts on this new feature. Please share your feedback and any issues you may encounter by commenting on our dedicated GitHub discussion.