Prisma

Prisma is an open-source ORM for Node.js and TypeScript. It is used as an alternative to writing plain SQL, or using another database access tool such as SQL query builders (like knex.js) or ORMs (like TypeORM and Sequelize). Prisma currently supports PostgreSQL, MySQL, SQL Server and SQLite.

While Prisma can be used with plain JavaScript, it embraces TypeScript and provides a level to type-safety that goes beyond the guarantees other ORMs in the TypeScript ecosystem. You can find an in-depth comparison of the type-safety guarantees of Prisma and TypeORM here.

info Note If you want to get a quick overview of how Prisma works, you can follow the Quickstart or read the Introduction in the documentation. There also are ready-to-run examples for REST and GraphQL in the prisma-examples repo.

Getting started

In this recipe, you’ll learn how to get started with NestJS and Prisma from scratch. You are going to build a sample NestJS application with a REST API that can read and write data in a database.

For the purpose of this guide, you’ll use a SQLite database to save the overhead of setting up a database server. Note that you can still follow this guide, even if you’re using PostgreSQL or MySQL – you’ll get extra instructions for using these databases at the right places.

info Note If you already have an existing project and consider migrating to Prisma, you can follow the guide for adding Prisma to an existing project. If you are migrating from TypeORM, you can read the guide Migrating from TypeORM to Prisma.

Create your NestJS project

To get started, install the NestJS CLI and create your app skeleton with the following commands:

  1. $ npm install -g @nestjs/cli
  2. $ nest new hello-prisma

See the First steps page to learn more about the project files created by this command. Note also that you can now run npm start to start your application. The REST API running at http://localhost:3000/ currently serves a single route that’s implemented in src/app.controller.ts. Over the course of this guide, you’ll implement additional routes to store and retrieve data about users and posts.

Set up Prisma

Start by installing the Prisma CLI as a development dependency in your project:

  1. $ cd hello-prisma
  2. $ npm install prisma --save-dev

In the following steps, we’ll be utilizing the Prisma CLI. As a best practice, it’s recommended to invoke the CLI locally by prefixing it with npx:

  1. $ npx prisma

Expand if you’re using Yarn

If you’re using Yarn, then you can install the Prisma CLI as follows:

  1. $ yarn add prisma --dev

Once installed, you can invoke it by prefixing it with yarn:

  1. $ yarn prisma

Now create your initial Prisma setup using the init command of the Prisma CLI:

  1. $ npx prisma init

This command creates a new prisma directory with the following contents:

  • schema.prisma: Specifies your database connection and contains the database schema
  • .env: A dotenv file, typically used to store your database credentials in a group of environment variables

Set the database connection

Your database connection is configured in the datasource block in your schema.prisma file. By default it’s set to postgresql, but since you’re using a SQLite database in this guide you need to adjust the provider field of the datasource block to sqlite:

  1. datasource db {
  2.   provider = "sqlite"
  3.   url      = env("DATABASE_URL")
  4. }
  6. generator client {
  7.   provider = "prisma-client-js"
  8. }

Now, open up .env and adjust the DATABASE_URL environment variable to look as follows:

  1. DATABASE_URL="file:./dev.db"

SQLite databases are simple files; no server is required to use a SQLite database. So instead of configuring a connection URL with a host and port, you can just point it to a local file which in this case is called dev.db. This file will be created in the next step.

Expand if you’re using PostgreSQL or MySQL

With PostgreSQL and MySQL, you need to configure the connection URL to point to the database server. You can learn more about the required connection URL format here.

PostgreSQL

If you’re using PostgreSQL, you have to adjust the schema.prisma and .env files as follows:

schema.prisma

  1. datasource db {
  2.   provider = "postgresql"
  3.   url      = env("DATABASE_URL")
  4. }
  6. generator client {
  7.   provider = "prisma-client-js"
  8. }

.env

  1. DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=SCHEMA"

Replace the placeholders spelled in all uppercase letters with your database credentials. Note that if you’re unsure what to provide for the SCHEMA placeholder, it’s most likely the default value public:

  1. DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

If you want to learn how to set up a PostgreSQL database, you can follow this guide on setting up a free PostgreSQL database on Heroku.

MySQL

If you’re using MySQL, you have to adjust the schema.prisma and .env files as follows:

schema.prisma

  1. datasource db {
  2.   provider = "mysql"
  3.   url      = env("DATABASE_URL")
  4. }
  6. generator client {
  7.   provider = "prisma-client-js"
  8. }

.env

  1. DATABASE_URL="mysql://USER:PASSWORD@HOST:PORT/DATABASE"

Replace the placeholders spelled in all uppercase letters with your database credentials.

Create two database tables with Prisma Migrate

In this section, you’ll create two new tables in your database using Prisma Migrate. Prisma Migrate generates SQL migration files for your declarative data model definition in the Prisma schema. These migration files are fully customizable so that you can configure any additional features of the underlying database or include additional commands, e.g. for seeding.

Add the following two models to your schema.prisma file:

  1. model User {
  2.   id    Int     @default(autoincrement()) @id
  3.   email String  @unique
  4.   name  String?
  5.   posts Post[]
  6. }
  8. model Post {
  9.   id        Int      @default(autoincrement()) @id
  10.   title     String
  11.   content   String?
  12.   published Boolean? @default(false)
  13.   author    User?    @relation(fields: [authorId], references: [id])
  14.   authorId  Int?
  15. }

With your Prisma models in place, you can generate your SQL migration files and run them against the database. Run the following commands in your terminal:

  1. $ npx prisma migrate dev --name init

This prisma migrate dev command generates SQL files and directly runs them against the database. In this case, the following migration files was created in the existing prisma directory:

  1. $ tree prisma
  2. prisma
  3. ├── dev.db
  4. ├── migrations
  5. │   └── 20201207100915_init
  6. │       └── migration.sql
  7. └── schema.prisma

Expand to view the generated SQL statements

The following tables were created in your SQLite database:

  1. -- CreateTable
  2. CREATE TABLE "User" (
  3.     "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
  4.     "email" TEXT NOT NULL,
  5.     "name" TEXT
  6. );
  8. -- CreateTable
  9. CREATE TABLE "Post" (
  10.     "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
  11.     "title" TEXT NOT NULL,
  12.     "content" TEXT,
  13.     "published" BOOLEAN DEFAULT false,
  14.     "authorId" INTEGER,
  16.     FOREIGN KEY ("authorId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE
  17. );
  19. -- CreateIndex
  20. CREATE UNIQUE INDEX "User.email_unique" ON "User"("email");

Install and generate Prisma Client

Prisma Client is a type-safe database client that’s generated from your Prisma model definition. Because of this approach, Prisma Client can expose CRUD operations that are tailored specifically to your models.

To install Prisma Client in your project, run the following command in your terminal:

  1. $ npm install @prisma/client

Note that during installation, Prisma automatically invokes the prisma generate command for you. In the future, you need to run this command after every change to your Prisma models to update your generated Prisma Client.

info Note The prisma generate command reads your Prisma schema and updates the generated Prisma Client library inside node_modules/@prisma/client.

Use Prisma Client in your NestJS services

You’re now able to send database queries with Prisma Client. If you want to learn more about building queries with Prisma Client, check out the API documentation.

When setting up your NestJS application, you’ll want to abstract away the Prisma Client API for database queries within a service. To get started, you can create a new PrismaService that takes care of instantiating PrismaClient and connecting to your database.

Inside the src directory, create a new file called prisma.service.ts and add the following code to it:

  1. import { INestApplication, Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
  2. import { PrismaClient } from '@prisma/client';
  4. @Injectable()
  5. export class PrismaService extends PrismaClient
  6.   implements OnModuleInit {
  8.   async onModuleInit() {
  9.     await this.$connect();
  10.   }
  12.   async enableShutdownHooks(app: INestApplication) {
  13.     this.$on('beforeExit', async () => {
  14.       await app.close();
  15.     });    
  16.   }
  17. }

info Note The onModuleInit is optional — if you leave it out, Prisma will connect lazily on its first call to the database. We don’t bother with onModuleDestroy, since Prisma has its own shutdown hooks where it will destroy the connection. For more info on enableShutdownHooks, please see Issues with enableShutdownHooks

Next, you can write services that you can use to make database calls for the User and Post models from your Prisma schema.

Still inside the src directory, create a new file called user.service.ts and add the following code to it:

  1. import { Injectable } from '@nestjs/common';
  2. import { PrismaService } from './prisma.service';
  3. import {
  4.   User,
  5.   Prisma
  6. } from '@prisma/client';
  8. @Injectable()
  9. export class UserService {
  10.   constructor(private prisma: PrismaService) {}
  12.   async user(userWhereUniqueInput: Prisma.UserWhereUniqueInput): Promise<User | null> {
  13.     return this.prisma.user.findUnique({
  14.       where: userWhereUniqueInput,
  15.     });
  16.   }
  18.   async users(params: {
  19.     skip?: number;
  20.     take?: number;
  21.     cursor?: Prisma.UserWhereUniqueInput;
  22.     where?: Prisma.UserWhereInput;
  23.     orderBy?: Prisma.UserOrderByInput;
  24.   }): Promise<User[]> {
  25.     const { skip, take, cursor, where, orderBy } = params;
  26.     return this.prisma.user.findMany({
  27.       skip,
  28.       take,
  29.       cursor,
  30.       where,
  31.       orderBy,
  32.     });
  33.   }
  35.   async createUser(data: Prisma.UserCreateInput): Promise<User> {
  36.     return this.prisma.user.create({
  37.       data,
  38.     });
  39.   }
  41.   async updateUser(params: {
  42.     where: Prisma.UserWhereUniqueInput;
  43.     data: Prisma.UserUpdateInput;
  44.   }): Promise<User> {
  45.     const { where, data } = params;
  46.     return this.prisma.user.update({
  47.       data,
  48.       where,
  49.     });
  50.   }
  52.   async deleteUser(where: Prisma.UserWhereUniqueInput): Promise<User> {
  53.     return this.prisma.user.delete({
  54.       where,
  55.     });
  56.   }
  57. }

Notice how you’re using Prisma Client’s generated types to ensure that the methods that are exposed by your service are properly typed. You therefore save the boilerplate of typing your models and creating additional interface or DTO files.

Now do the same for the Post model.

Still inside the src directory, create a new file called post.service.ts and add the following code to it:

  1. import { Injectable } from '@nestjs/common';
  2. import { PrismaService } from './prisma.service';
  3. import {
  4.   Post,
  5.   Prisma,
  6. } from '@prisma/client';
  8. @Injectable()
  9. export class PostService {
  10.   constructor(private prisma: PrismaService) {}
  12.   async post(postWhereUniqueInput: Prisma.PostWhereUniqueInput): Promise<Post | null> {
  13.     return this.prisma.post.findUnique({
  14.       where: postWhereUniqueInput,
  15.     });
  16.   }
  18.   async posts(params: {
  19.     skip?: number;
  20.     take?: number;
  21.     cursor?: Prisma.PostWhereUniqueInput;
  22.     where?: Prisma.PostWhereInput;
  23.     orderBy?: Prisma.PostOrderByInput;
  24.   }): Promise<Post[]> {
  25.     const { skip, take, cursor, where, orderBy } = params;
  26.     return this.prisma.post.findMany({
  27.       skip,
  28.       take,
  29.       cursor,
  30.       where,
  31.       orderBy,
  32.     });
  33.   }
  35.   async createPost(data: Prisma.PostCreateInput): Promise<Post> {
  36.     return this.prisma.post.create({
  37.       data,
  38.     });
  39.   }
  41.   async updatePost(params: {
  42.     where: Prisma.PostWhereUniqueInput;
  43.     data: Prisma.PostUpdateInput;
  44.   }): Promise<Post> {
  45.     const { data, where } = params;
  46.     return this.prisma.post.update({
  47.       data,
  48.       where,
  49.     });
  50.   }
  52.   async deletePost(where: Prisma.PostWhereUniqueInput): Promise<Post> {
  53.     return this.prisma.post.delete({
  54.       where,
  55.     });
  56.   }
  57. }

Your UserService and PostService currently wrap the CRUD queries that are available in Prisma Client. In a real world application, the service would also be the place to add business logic to your application. For example, you could have a method called updatePassword inside the UserService that would be responsible for updating the password of a user.

Implement your REST API routes in the main app controller

Finally, you’ll use the services you created in the previous sections to implement the different routes of your app. For the purpose of this guide, you’ll put all your routes into the already existing AppController class.

Replace the contents of the app.controller.ts file with the following code:

  1. import {
  2.   Controller,
  3.   Get,
  4.   Param,
  5.   Post,
  6.   Body,
  7.   Put,
  8.   Delete,
  9. } from '@nestjs/common';
  10. import { UserService } from './user.service';
  11. import { PostService } from './post.service';
  12. import { User as UserModel, Post as PostModel } from '@prisma/client';
  14. @Controller()
  15. export class AppController {
  16.   constructor(
  17.     private readonly userService: UserService,
  18.     private readonly postService: PostService,
  19.   ) {}
  21.   @Get('post/:id')
  22.   async getPostById(@Param('id') id: string): Promise<PostModel> {
  23.     return this.postService.post({ id: Number(id) });
  24.   }
  26.   @Get('feed')
  27.   async getPublishedPosts(): Promise<PostModel[]> {
  28.     return this.postService.posts({
  29.       where: { published: true },
  30.     });
  31.   }
  33.   @Get('filtered-posts/:searchString')
  34.   async getFilteredPosts(
  35.     @Param('searchString') searchString: string,
  36.   ): Promise<PostModel[]> {
  37.     return this.postService.posts({
  38.       where: {
  39.         OR: [
  40.           {
  41.             title: { contains: searchString },
  42.           },
  43.           {
  44.             content: { contains: searchString },
  45.           },
  46.         ],
  47.       },
  48.     });
  49.   }
  51.   @Post('post')
  52.   async createDraft(
  53.     @Body() postData: { title: string; content?: string; authorEmail: string },
  54.   ): Promise<PostModel> {
  55.     const { title, content, authorEmail } = postData;
  56.     return this.postService.createPost({
  57.       title,
  58.       content,
  59.       author: {
  60.         connect: { email: authorEmail },
  61.       },
  62.     });
  63.   }
  65.   @Post('user')
  66.   async signupUser(
  67.     @Body() userData: { name?: string; email: string },
  68.   ): Promise<UserModel> {
  69.     return this.userService.createUser(userData);
  70.   }
  72.   @Put('publish/:id')
  73.   async publishPost(@Param('id') id: string): Promise<PostModel> {
  74.     return this.postService.updatePost({
  75.       where: { id: Number(id) },
  76.       data: { published: true },
  77.     });
  78.   }
  80.   @Delete('post/:id')
  81.   async deletePost(@Param('id') id: string): Promise<PostModel> {
  82.     return this.postService.deletePost({ id: Number(id) });
  83.   }
  84. }

This controller implements the following routes:

GET
  • /post/:id: Fetch a single post by its id
  • /feed: Fetch all published posts
  • /filter-posts/:searchString: Filter posts by title or content
POST
  • /post: Create a new post
    • Body:
      • title: String (required): The title of the post
      • content: String (optional): The content of the post
      • authorEmail: String (required): The email of the user that creates the post
  • /user: Create a new user
    • Body:
      • email: String (required): The email address of the user
      • name: String (optional): The name of the user
PUT
  • /publish/:id: Publish a post by its id
DELETE
  • /post/:id: Delete a post by its id

Issues with enableShutdownHooks

Prisma interferes with NestJS enableShutdownHooks. Prisma listens for shutdown signals and will call process.exit() before your application shutdown hooks fire. To deal with this, you would need to add a listener for Prisma beforeExit event.

  1. // main.ts
  2. ...
  3. import { PrismaService } from './services/prisma/prisma.service';
  4. ...
  5. bootstrap() {
  6.   ...
  7.   const prismaService: PrismaService = app.get(PrismaService);
  8.   prismaService.enableShutdownHooks(app)
  9.   ...
  10. }

You can read more about Prisma handling of shutdown signal, and beforeExit event.

Summary

In this recipe, you learned how to use Prisma along with NestJS to implement a REST API. The controller that implements the routes of the API is calling a PrismaService which in turn uses Prisma Client to send queries to a database to fulfill the data needs of incoming requests.

If you want to learn more about using NestJS with Prisma, be sure to check out the following resources: