NestJS Prisma Module

Installation

To use this package, first install it:

1npm i @sabinthedev/nestjs-prisma-tenants

Basic Usage

In order to use this package, you will need one or more Prisma Client set up in your project.

1import { Module } from '@nestjs/common';
2import { AppController } from './app.controller';
3import { AppService } from './app.service';
4import { PrismaClient } from '@prisma/client';
5import { PrismaModule } from './modules/prisma';
6
7@Module({
8  imports: [
9    PrismaModule.register({
10      client: PrismaClient,
11      name: 'PRISMA'
12    })
13  ],
14  controllers: [AppController],
15  providers: [AppService],
16})
17export class AppModule { }

There are also various options you may pass to the register function to customize how Prisma Client is instantiated and how to handle connections and requests.

Multitenancy

This plugin allows you to handle multi-tenant applications by abstracting a service layer above Prisma Client to cache Prisma Client instances in-memory and select the appropriate tenant connection on each request.

Below is an example of how to configure PrismaModule to handle multiple tenants:

1import { Module } from '@nestjs/common';
2import { AppController } from './app.controller';
3import { AppService } from './app.service';
4import { PrismaClient } from '@prisma/client';
5import { PrismaModule } from './modules/prisma';
6
7@Module({
8  imports: [
9    PrismaModule.register({
10      client: PrismaClient,
11      name: 'PRISMA',
12      multitenancy: true,
13      datasource: 'postgresql://johndoe:randompassword@localhost:5432/mydb'
14    })
15  ],
16  controllers: [AppController],
17  providers: [AppService],
18})
19export class AppModule { }

When configuring multi-tenancy, the datasource key is required as it is used as the base URL on which the tenant database is added.

To access a specific tenant database, add a header to your HTTP request named x-tenant-id whose value is the name of the tenant DB you wish to access. PrismaModule will generate a new instance of Prisma Client using the base URL you provided along with the specification for the tenant database.

Example Request:

In the scenario below, your server is at localhost:3000 and has an endpoint /users. The client accessing the resource requesting data from a tenant database named tenant-name.

1curl -XGET -H 'x-tenant-id: tenant-name' 'localhost:3000/users'

Supported Database Providers

Note: SQLite (or any database servers that do not support multiple databases) is not supported.

The list of supported database providers for this feature are as follows:

• PostgreSQL
• MySQL
• SQL Server
• MongoDB

More to be added soon...

API

register(options)

The register function registers PrismaModule and allows you to pass in options that change the behavior of the module and the generated Prisma Client instances. This function takes in a single parameter, options. This is an object with the following available keys:

Parameter	Type		Description
name	string	Required	The dependency injection token to use with @Inject. See the docs for more info.
logging	boolean	Optional	Enables logging within the module that gives insights how your connections are being handled.
client	PrismaClient class or ClientConfig	Required	The PrismaClient class to be instantiated, or an object containing a reference to a PrismaClient class and a callback function that allows you to modify the instantiated class on a per-tenant basis.
options	PrismaClient constructor args	Optional	See the Prisma Client API reference
multitenancy	boolean	Optional*	A flag that turns on the multi-tenancy capabilities of this module.
datasource	string	Optional*	A datasource URL that is used to manually override Prisma Client's datasource. This is used as the base URL when dynamically selecting tenant databases.

Note: If multitenancy OR datasources are present, both are required. The built-in type-safety will make this apparent.

ClientConfig

An object of the ClientConfig type is able to be provided instead of a PrismaClient class to the client option key. This object should contain:

Parameter	Type		Description
client	PrismaClient	Required	A PrismaClient class
initializer	Initializer	Required	A function that is called when a PrismaClient is instantiated.

initializer(client: PrismaClient, tenant: string) => PrismaClient

This function gives you access to the generated client and the associated tenant name (if any) so you can customize the client instance with functions such as $on, $use and more. The available client methods can be found here.

Within this function, you can provide any function you would like to run when a Prisma Client is instantiated.

The return of this function must be the Prisma Client.

Advanced Usage

In the scenario below, the module is configured to:

• Use multi-tenancy
• Log info on the connection handling
• Initialize PrismaClient with logging enabled at the info level (see Prisma's docs on logging)
• Hook into the $on('info') logging event to customize the message so it is more appropriate for a multi-tenant system

1import { Module } from '@nestjs/common';
2import { AppController } from './app.controller';
3import { AppService } from './app.service';
4import { PrismaClient } from '@prisma/client';
5import { PrismaModule } from './modules/prisma';
6
7@Module({
8  imports: [
9    PrismaModule.register({
10      client: {
11        class: PrismaMock,
12        initializer: (client, tenant) => {
13          client.$on('info', (e) => {
14            console.log(`${tenant} INFO | ${e.message}`)
15          })
16          return client;
17        },
18      },
19      logging: true,
20      multitenancy: true,
21      datasource: 'file:./dev.db',
22      name: 'PRISMA',
23    }),
24  ],
25  controllers: [AppController],
26  providers: [AppService],
27})
28export class AppModule { }

Multiple Prisma Modules

You may register this module multiple times within your application to provide access to different databases.

Configure a new Prisma schema. Make sure to specify a custom output in the client generator if your first client used the default location. This ensures the newly generated client does not override the one at node_modules/@prisma/client.

You can then register a second client in a way similar to the following:

1import { Module } from '@nestjs/common';
2import { AppController } from './app.controller';
3import { AppService } from './app.service';
4import { PrismaModule } from './modules/prisma';
5
6// Import your clients 
7import { PrismaClient as AuthClient } from '../prisma-clients/auth';
8import { PrismaClient as UsersClient } from '../prisma-clients/users';
9
10@Module({
11  imports: [
12    // Register the module once for each client
13    PrismaModule.register({
14      client: AuthClient,
15      name: 'AUTH',
16    }),
17    PrismaModule.register({
18      client: UsersClient,
19      name: 'USERS',
20    }),
21  ],
22  controllers: [AppController],
23  providers: [AppService],
24})
25export class AppModule { }

In the above scenario, you may be working in a microservice architecture who's Authentication service uses a separate database than the Users service. The configuration above registers both clients as separate providers.

You, of course, have all of the granular control and options as before when registering multiple modules.

Author

I'm Sabin Adams!

Contributors

None yet! But contributions are welcome!

License

Licensed under MIT.