The project is an API backend for a multi-tenant system, where each tenant has its own schema in our Postgres database.

The problem

In an ideal scenario, we would just need to specify the database schema for every performed query. Unfortunately, Prisma does not support that at the moment. However, it allows passing the database connection string when the PrismaClient is instantiated, skipping the one declared in the .env file. Thanks to that and the power of NestJS we came up with a quite solid solution.

The solution

We decided to dedicate a separate instance of PrismaClient to each tenant schema. Now, obviously, we cannot create an instance for every request, we better find a way to cache instances and reuse them when possible.

It's important to note that in our case we need to handle a relatively small amount of tenants, and we are also working with a database that can handle a large number of connections. This solution would not have been a good fit otherwise, since every instance of PrismaClient requires its own connection to the database.

The idea is to have a manager class that will hold all created instances, provide them, and will eventually create new ones when needed. It would also have to dispose every created instance on server shutdown to free up connections.

Let's now take a look at how we implemented this solution.

The implementation

The manager class is pretty straightforward. It is going to be a simple NestJS provider, holding a "cache" object for instantiated clients as a class property.

In our case tenant IDs are used as database schema names, but you might also provide your own mapping logic.

We need three methods here:

1. getTenantId: this will extract the tenant id from the request object. In our case, it will be extracted from the JWT in the Authorization header, but it may also be deduced from the hostname.
2. getClient: this will be called for every request to retrieve a tenant-dedicated PrismaClient instance, and it does most of the work.
3. onModuleDestroy: this will be called by the framework on application shutdown, and it will be in charge of clients disposal.

import { Injectable, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';
import { Request } from 'express';

@Injectable()
export class PrismaClientManager implements OnModuleDestroy {
  // the client instances cache object
  private clients: { [key: string]: PrismaClient } = {};

  getTenantId(request: Request): string {
    // TODO: retrieve and return the tenant ID from the request object,
    // eventually throw an exception if the ID is not valid
  }

  getClient(request: Request): PrismaClient {
    const tenantId = this.getTenantId(request);
    let client = this.clients[tenantId];

    // create and cache a new client when needed
    if (!client) {
      const databaseUrl = process.env.DATABASE_URL!.replace('public', tenantId);

      client = new PrismaClient({
        datasources: {
          db: {
            url: databaseUrl,
          },
        },
      });

      // setup prisma middlewares if any

      this.clients[tenantId] = client;
    }

    return client;
  }

  async onModuleDestroy() {
    // wait for every cached instance to be disposed
    await Promise.all(
      Object.values(this.clients).map((client) => client.$disconnect()),
    );
  }
}

You may also want to implement type safety and validation for tenant IDs.

Note that the code above assumes the existence of a DATABASE_URL environment variable holding a database connection string with the schema query param set to public, like the one in the .env file generated by Prisma:

DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

Also, make sure to add this provider to a global module, like a DatabaseModule or the AppModule.

Now, the last thing is to find a way to call getClient for every request and pass around the instance based on where we need it.

First approach

The first, really verbose approach is to access the request object from every handler method in every controller and pass it around to every service method we need to call to handle the request.

// controller example method
  @Get()
  findAll(@Req() request: Request) {
    return this.service.findAll(request);
  }

export class MyService {
  constructor(private prismaClientManager: PrismaClientManager) {}

  findAll(request: Request) {
    const prisma = this.prismaClientManager.getClient(request);
    // method logic ...
  }
}

This is extremely verbose, we can definitely do better.

Second approach

Thanks to the NestJS dependency injection system, every registered provider is instantiated the first time it needs to be injected, and then the instance is reused any subsequent time. However, we can take advantage of a built-in mechanism to make a service request-scoped, asking the framework to create a new instance for each incoming request.

To do that we need to add a scope parameter to the Injectable decorator. This way we will also have access to the incoming request object.

import { Injectable, Scope, Inject } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { Request } from 'express';
import { PrismaClientManager } from '../database/prisma-client-manager';

@Injectable({ scope: Scope.REQUEST })
export class MyService {
  private prisma: PrismaClient;

  constructor(
    @Inject(REQUEST) request: Request,
    prismaClientManager: PrismaClientManager,
  ) {
    this.prisma = prismaClientManager.getClient(request);
  }

  findAll() {
    // just use this.prisma to access the database
  }
}

This is less verbose and easier to manage than the first approach, but we still need to add the code above to all of the services from which we need to access the Prisma client.

Let's try to take advantage of dependency injection again to avoid that.

Third approach and final solution

Turns out all we need is a custom factory provider, which will be the only explicitly request-scoped component and will be called by the framework to provide us a PrismaClient whenever we need it to be injected as a service dependency.

// src/database/database.module.ts

import { FactoryProvider, Global, Module, Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { PrismaClient } from '@prisma/client';
import { Request } from 'express';
import { PrismaClientManager } from './prisma-client-manager';

const prismaClientProvider: FactoryProvider<PrismaClient> = {
  provide: PrismaClient,
  scope: Scope.REQUEST,
  inject: [REQUEST, PrismaClientManager],
  useFactory: (request: Request, manager: PrismaClientManager) => manager.getClient(request),
};

@Global()
@Module({
  providers: [PrismaClientManager, prismaClientProvider],
  exports: [PrismaClient],
})
export class DatabaseModule {}

This way we can totally forget about the request-scoped logic and simply use the PrismaClient in our services as if it was a regular provider.

import { Injectable } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class MyService {
  constructor(private prisma: PrismaClient) {}

  findAll() {
    // just use this.prisma to access the database
  }
}

The providers with a dependency on the PrismaClient will still be request-scoped, but we don't need to make it explicit anymore, we can just use them as regular providers.

A complete example of the final implementation can be found in this repo.

This is how we achieved multi-tenancy with Prisma in a NestJS project. Please don't hesitate to ask any questions or leave a comment.

Note: the strategy described above is the same adopted by this great library. If you don't want to write your own implementation or you'd like to take advantage of other features such as a multi-tenant-aware migrations CLI, I highly suggest taking a look at it.

Cheers!

It's a pretty large codebase, and we built the backend with the NestJS framework, which is database agnostic but provides strong integration with TypeORM, which is why I've always decided to use it when I'm working with NestJS.

Since the Prisma team announced V2 I've kept an eye open on their Twitter profile, and when they announced the beta version of Prisma Client I've started to play around and got pretty excited about it. I almost immediately felt like I was looking at a truly next-gen approach to data access in NodeJS, which I always felt could be more than improved.

Prisma became generally available as stable in June 2020, and since there they constantly released new versions with bug fixes and lots of improvements and new features. After only six months it felt utopian to use it in production, especially for our big project, as I was pretty sure there were a lot of edge cases it couldn't be ready to handle. However I was too curious to give it a serious try, and one day, as an experiment, I decided to migrate a single part of the backend and see where it would take me.

The results impressed me so much, the next day we started to migrate the whole project.

First steps

Please note: the migration process is explained in detail here in the Prisma docs. For this reason, I'll focus on my experience rather than the exact steps and the code.

The very first step to introduce Prisma to an existing codebase is schema introspection. It takes a single command for Prisma to analyze your database schema and fill out the schema.prisma file with model definitions, each one corresponding to a table in your schema. There were a couple of things to fix, mostly related to naming and relations handling, but since we're talking about a thirty-two tables schema with every possible form of relation involved, it did a pretty good job.

Now, I decided to make a couple of updates to our database schema to better fit Prisma conventions, to take the most advantage of code generation and avoid current limitations, in particular:

• Join tables need to follow some conventions to represent implicit relations, which means that Prisma will handle the relation completely behind the scenes, reducing complexity a lot. At the same time we can also have explicit many-to-many relations in case we need to add extra data to the join table.

• JSON columns are supported, but query capabilities are pretty limited at the time of writing ( this might change soon ). That's why I decided to get rid of every JSON column, simply changing them to scalar columns or adding new tables. This might be a problem for some cases, but fortunately not for ours.

I also want to spend some words on the editing experience for the Prisma schema. Initially, I didn't like the idea of a separate schema with a new syntax, but I must say the VSCode extension does an impressive job at making things fast and easy to edit, other than giving you hints and warnings about any issue and even fixing those for you.

NestJS integration

If you are not interested specifically in NestJS you can safely skip this paragraph. NestJS basic knowledge is required to understand what I'm about to describe.

Thanks to the NestJS dependency injection system Prisma integration is smooth, and it turns out to be less verbose than TypeORM.

With TypeORM we need to:

1. Register TypeOrmModule in a global Nest module, with the configuration object.
2. Every time a new entity is introduced we need to register it in the entities array ( this may be skipped with entities auto-loading ).
3. Every time we need to use TypeORM repositories in a Nest module we need to add TypeOrmModule.forFeature([EntityClass]) to the imports array for that module.
4. For every TypeORM repository we need to use in a provider class we need to add this to the class constructor:

   constructor(
    @InjectRepository(User)
    private usersRepository: Repository<User>,
   ) {}
   

   Prisma integration, on the other hand, is pretty straightforward. We just need an injectable PrismaService extending the generated PrismaClient, add it to a global module, and it can now be used anywhere we need.

import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {

  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

// any provider we need to access prisma from 
constructor(private prisma: PrismaService) {}

More on the NestJS - Prisma combo can be found on the Prisma website.

Migrations

Prisma also provides Prisma Migrate, which is a very promising tool to handle migrations, but it is not considered production-ready at the time of writing. That's why we decided to rely on an external tool for migrations, which is out of the scope of this article.

At the time of writing, they've just announced a release preview, and I can't wait to try it out and write down my first impressions.

I've also had some not so nice experiences with TypeORM migrations generation, which is why I've always ended up using the CLI to generate empty files and then filling them up myself with raw SQL. Because of that, giving it up wasn't difficult at all.

Developer Experience

The developer experience working with Prisma was definitely above my team's expectations.

Code readability

With TypeORM, most of the queries end up being split into multiple parts, with a lot of the query builder methods scattered all over the function's body. This really hurts code readability, and it takes some time for anyone to fully understand what the query is doing. With Prisma, even the most complex query fits in an extremely well-structured object parameter, making it possible even for developers not really experienced with SQL to easily understand the purpose of the query.

Consistency and predictability

It is pretty common with TypeORM to start with a particular approach on a single query and then switch to another one because of some limitation or unpredictable behavior. There are lots of ways to do the same thing, and it may be confusing for newcomers to figure out which one is the best. With Prisma, there is a single, predictable, and intuitive way to perform any possible operation.

Type safety

Although TypeORM is written in TypeScript, type safety is not really guaranteed. The type of a record in a query result set will always be the defined model class, regardless of any column selection or joined relation. Moreover, the query builder requires passing tables and column names as strings, which to me feels like the complete opposite of type safety.

Prisma generates advanced types based on the schema.prisma model, and thanks to that it manages to provide type safety at its best.

For a query like this:

const users = await this.db.user.findMany({
  select: {
    email: true,
    active: true,
    zones: {
      select: {
        name: true,
        properties: {
          select: {
            name: true,
            address: true,
          },
        },
      },
    },
  },
});

The result type would be:

const users: {
    email: string;
    active: boolean;
    zones: {
      name: string;
      properties: {
        name: string;
        address: string;
      }[];
    }[];
}[]

As you can see, the result type is extremely precise, and it perfectly mirrors the query selection. I highly recommend taking a look at the generated types to better understand how the powerful TypeScript types system has been exploited.

I can confidently say this is the first time I feel like I'm working with a truly type-safe ORM.

More on this and the following paragraphs can be found here in the Prisma docs comparison.

Relations handling

Managing relations has always been painful even with ORMs, and TypeORM makes no exception. For deeply nested and complex queries we end up writing a lot of .leftJoinAndSelect() methods because of the limitations of the ORM capabilities.

This is what a select query with multiple JOINs looks like with Prisma:

const users = await prisma.user.findMany({
  include: {
    posts: {
      include: {
        categories: {
          include: {
            posts: true,
          },
        },
      },
    },
  },
});

Of course, we can add filters and custom selection on every level of the query.

Another example from the Prisma docs: this is a query to retrieve all users records where all posts are published and at least one related post mentions "Prisma":

const result = await prisma.user.findMany({
  where: {
    post: {
      every: {
        published: true
      },
      some: {
        content: {
          contains: "Prisma"
        },
      },
    },
  },
});

Basically, developers don't even need to know how a JOIN works to handle complex queries with relations involved.

Raw queries

Honestly, I expected I'd need to fall back to raw SQL queries all the time. It turned out I was very wrong. While with TypeORM I always needed to give up on the ORM and leverage the query builder, with half of the clauses as non-typed raw strings, with Prisma I only needed to write raw queries a couple of times for complex aggregation queries. I'm talking about really complex aggregations, since simpler ones are nicely supported.

Even for those cases where raw SQL is required, Prisma provides some nice helpers and hints to help us write raw queries, such as tagged templates helpers and utility functions and constants.

One thing that I miss from TypeORM is the possibility to mix type-safe query functions and raw SQL clauses, but I understand this is something the team is trying to avoid because of the consequences it might have on the developer experience and the wrong behavior it might lead to.

Transactions

Prisma lacks a way to handle long-running transactions the way we are used to writing them, such as with multiple operations encapsulated within a callback or batched within a single promise.

This looked like a severe limitation, but we realized any time we need a transaction is because of a sequence of write operations performed atomically, which is something Prisma has always supported with a query like this:

await prisma.post.create({
  data: {
    title: 'Post Title',
    tags: {
      create: [
        { title: 'Tag #1' },
        { title: 'Tag #2' },
        { title: 'Tag #3' },
      ],
    },
  },
});

At the time of writing, they are also working on a new transaction api which might cover every other use case, available right now as a preview feature.

I highly recommend reading this article by the Prisma team to go deeper into this topic.

Documentation

One of the pain points of TypeORM is documentation. I understand that is probably because of the time this library has been available and the number of features. Nonetheless, it lacks lots of things and it is very confusing. Every time you need to look for something you always end up giving up on the docs and search somewhere else.

Prisma is much newer, but the documentation has also been very well curated. Thanks to the intuitive structure and the powerful search tool, is always easy to find what you need.

Current limitations

There are also some things we had to workaround. Please note that most of these issues are being worked on at the time of writing, and they might be solved when you read this.

• Advanced query capabilities for JSON columns, as already mentioned, are not yet supported.
• Cascade deletes present some problems. Even when the foreign key has been declared with an ON DELETE CASCADE clause, Prisma prevents you from deleting the record. This can be solved with a simple raw query:

  prisma.$executeRaw`DELETE FROM "Post" WHERE "id" = ${id}`.
  

• We needed to implement soft delete for some of our entities, and although they provide an example middleware it has some flaws we needed to deal with. I mentioned that on Twitter and the team reached to me to ask for feedback and help me tackle down the issues, which is something I really appreciate and value.

Conclusions

We are really happy with the decision we made. We reduced our codebase by thousands of lines of code, and those of us who struggled with data access are now confidently working even on complex queries.

Even if Prisma is relatively new, it already provides almost all the features we need, and development is constantly active! They solve lots of issues for every release, some of the issues we had at the beginning of the migration were solved when we finished.

With the recent 2.13 release, we can also import generated types in the browser, which paves the way for exciting solutions to some issues we have with our current monorepo setup, but this is for another blog post...

TypeORM was a great companion in our journey and I really appreciate the work of the community on such a big and ambitious piece of software, but for us the time came to replace it with a next-gen solution.

I'm excited about the future of Prisma and thankful for what the team is doing for us, and I also can't wait to know what you think about all the things you just read.

Cheers!