How To Build a GraphQL Server with Node.js and Prisma


While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.


Prisma is a data layer that turns a database into a GraphQL API. We can look at it as a kind of Object-Relational Mapper (ORM), but it’s much more powerful than traditional ORMs. With Prisma, we get a server (Prisma server) that acts as a proxy for our database and a high-performance query engine that runs on the server, which generates actual database queries for us. In addition to these, we also get a client (Prisma client), which we can use to interact with the server. Prisma also adds an event system to our database, so we can subscribe to database events in realtime.

Prisma works with both new and existing databases. In the case of an existing database, Prisma will generate the datamodel based on the database schema.

In this tutorial, you will build a GraphQL server using Prisma as a data layer.


This tutorial assumes the following:

  • Node.js and npm installed on your computer

  • Basic knowledge of GraphQL

Overview of How Prisma Works

Having seen what Prisma is, let’s take a look at how it works. First, let’s look at how it works with a new database:

New Database with Prisma

  • Create a new Prisma service
  • Set up and connect Prisma with your database
  • Define the datamodel
  • Deploy the Prisma API
  • Generate the Prisma client for your programming language of choice
  • Create a GraphQL server that uses the Prisma client to interact with your database

Now, let’s see how it works with an existing database.

Existing Database with Prisma

  • Create a new Prisma service
  • Set up and connect Prisma with your existing database, using the Prisma Docker image
  • Generate the datamodel from your database schema
  • Deploy the Prisma API
  • Generate the Prisma client for your programming language of choice
  • Create a GraphQL server that uses the Prisma client to interact with your database

Note: To use Prisma locally, you need to have Docker installed on your machine. Also, using an existing database with Prisma currently only works when using PostgreSQL databases.

Step 1 — Setting Up the Project

To get started with Prisma, we need to install the Prisma CLI. There are a couple of ways to install the CLI, but we’ll be installing it using npm:

  • npm install -g prisma

With the CLI installed, we can start using it. We’ll use it to create a new Prisma service:

  • prisma init test-task-manager

Choose Demo server from the prompt to use an hosted demo server that already has a database included, then we’ll be redirected to log in (or sign up if we don’t have an account yet) to Prisma Cloud to grant the CLI permissions to our account.

Prisma Login Screen

Prisma required permissions list

Note: Because we are using the demo server, which is hosted on Prisma cloud, we will need a Prisma cloud account. An account with Prisma cloud is not necessary to use Prisma itself.

Back to the terminal, choose any of the provided regions of the demo server. Then choose the defaults for both the name for our service and the name for our stage, that is, test-task-manager and dev respectively. Lastly, select Prisma JavaScript Client as the programming language for the generated Prisma client.

This will create two files: datamodel.prisma and prisma.yml inside the project directory. Also, a Prisma client will be auto-generated. We’ll go through these files shortly.

Based on the types defined inside datamodel.prisma, a GraphQL API is exposed with CRUD (Create, Read, Update, and Delete) and realtime operations. This API is called the Prisma API.

Now, let’s deploy our newly created Prisma API:

  • cd test-task-manager
  • prisma deploy

This will deploy the default User type that Prisma created for us to our selected region. It will also display the live endpoints (HTTP and Websocket. We are only interested in HTTP in this tutorial) for our Prisma GraphQL database.

Now, we can take our new Prisma API for a spin in the GraphQL Playground:

  • prisma playground

We can access this at http://localhost:3000/playground.

Let’s create a new user with the following mutation:

mutation {
  createUser(data: { name: "Chimezie" }) {

New mutation

Understanding the Prisma Files

Before we dive deep into building the GraphQL server for our app, let’s quickly go through the files Prisma generated for us.

  • prisma.yml: This is the configuration file for Prisma. It contains everything that’s required to set up a Prisma service.
  • datamodel.priama: Specifies the datamodel for our application that will be mapped to the database. In other words, it is used to define our database schema.
  • generated/prisma-client: Contains the auto-generated Prisma client library, which can be used to interact with the Prisma API.

Step 2 — Creating a GraphQL Server

If all our GraphQL API will do is perform basic CRUD operations, then we would be fine with just the GraphQL API Prisma generated for us. In most cases we would want more than that, so we need to create a GraphQL server to handle our domain-specific logic as well as integrate with third-party services.

We’ll be using graphql-yoga to create our GraphQL server. Let’s install it along with the other dependency we’ll be needing:

  • yarn add graphql-yoga prisma-client-lib

prisma-client-lib is needed to run the Prisma client that was generated for us.

Once that’s done installing, create a new directory called src directly within the project’s root directory.

  • mkdir src

Then let’s move the generated directory inside the src directory:

mv generated src

Next, update prisma.yml to reflect the new location:

# prisma.yml

  - generator: javascript-client
    output: ./src/generated/prisma-client/

Within the src directory, create a new file called index.js:

  • cd src
  • touch index.js

Then add the following code to it:

// src/index.js

const { prisma } = require('./generated/prisma-client')
const { GraphQLServer } = require('graphql-yoga')
const resolvers = require('./resolvers')

const server = new GraphQLServer({
  typeDefs: './src/schema.graphql',
  context: {

server.start(() => console.log('Server is running on http://localhost:4000'))

Here we import the Prisma client, graphql-yoga, and our resolver functions (we’ll create in a moment). Then we create a new GraphQL server, passing to it our schema (we’ll create this in a moment), the resolver functions, and lastly the context, which contains the Prisma client. We pass the Prisma client to the context so that we’ll be able to use it inside our resolver functions. Finally, we start the GraphQL server.

Step 3 — Updating the Datamodel

Let’s define the datamodel of our app. The app will be made up of two types: Project and Task. Update datamodel.prisma as follows:

# datamodel.prisma

type Project {
  id: ID! @unique
  name: String!
  tasks: [Task!]!

type Task {
  id: ID! @unique
  title: String!
  project: Project!
  isCompleted: Boolean! @default(value: false)

The Project type has three fields; the ID of the project, the name of the project, and lastly the project’s tasks. We use the @unique directive on the id field because we want it to be unique for each project. It will be set as the primary key on the database table. All the fields are required (denoted with !). The tasks field will return a list of tasks that makes up the project because it is enclosed in []. Notice it has two !, which means the list of tasks cannot contain null, but the whole list can be empty.

The Task type is similar to the Project type. It has a project field, which will be the particular project the task belongs to. Then it has an isCompleted field, which indicates whether a task has been completed or not. We give the field a default value of false using the @default directive.

Note: The default value must always be in double quotes, even for non-string types such as Boolean or Int.

With our datamodel, Project and Type have a one-to-many relationship. A project can have many tasks (because of the tasks field on the Project type) and a task belongs to a project (again, because of the project field on the Task type).

Note: It is required to use the @relation directive to define a relation when a relation is ambiguous.

For the changes on our datamodel to take effect, we need to redeploy the Prisma API:

  • prisma deploy

Warning: If you get this warning You already have nodes for this model. This change will result in data loss for the User type., this is because we created a user earlier and now we don’t need the User type anymore. We just need to force the deploy with prisma deploy --force.

Also, we need to regenerate the Prisma client. We can do that by running the following command:

  • prisma generate

Step 4 — Defining the Schema

Now let’s start defining the schema that would make up our GraphQL API. Within the src directory, create a new file called schema.graphql:

  • touch schema.graphql

Then add the following code in the newly created file:

# src/schema.graphql

type Query {
  projectById(projectId: ID!): Project
  completedTasks: [Task!]!

type Mutation {
  createProject(name: String!): Project
  createTask(title: String!, projectId: ID!): Task
  markTaskAsCompleted(taskId: ID!): Task

type Project {
  id: ID!
  name: String!
  tasks: [Task!]!

type Task {
  id: ID!
  title: String!
  project: Project!
  isCompleted: Boolean!

We define a query to fetch a project by its ID and fetch tasks that have been marked as completed respectively. Also, we define the mutations to create a new project, create a new task, and to mark a task as completed. Finally, we define the schema for the types in our datamodel.

Note: Redefining the schema for the types in the datamodel can be redundant and not easily maintainable, especially for large projects. To avoid redefining them, we can use tools like https://github.com/prisma/graphql-import.

Step 5 — Creating the Resolver Functions

With the schema defined, let’s create the resolver functions that would handle them. Inside the src directory, create a new file called resolvers.js and add the following code in it:

// src/resolvers.js

const resolvers = {
  Query: {
    projectById (root, { projectId }, { prisma }) {
      return prisma.project({ id: projectId })
    completedTasks (root, args, { prisma }) {
      return prisma.tasks({ where: { isCompleted: true } })
  Mutation: {
    createProject (root, { name }, { prisma }) {
      return prisma.createProject({ name })
    createTask (root, { title, projectId }, { prisma }) {
      return prisma.createTask({
        project: { connect: { id: projectId } }
    markTaskAsCompleted (root, { taskId }, { prisma }) {
      return prisma.updateTask({
        where: { id: taskId },
        data: { isCompleted: true }
  Project: {
    tasks (root, args, { prisma }) {
      return prisma.project({ id: root.id }).tasks()
  Task: {
    project (root, args, { prisma }) {
      return prisma.task({ id: root.id }).project()

module.exports = resolvers

We start by creating the resolver functions for the queries. Remember, we passed the Prisma client to the context, so we extract it from the context and use it to interact with the Prisma API. The projectById() returns the project whose ID matches the supplied project ID. The completedTasks() does nearly the same thing, but instead it returns a list of tasks that have been marked as completed (that is, isCompleted is true).

If we look at the generated Prisma client, we’ll see that CRUD operations have been generated for us. All we need to do is use them. The createProject() calls the createProject() on the Prisma client, which accepts the data we want to insert, in our case just the name of the project since the project’s ID will be auto-generated for us. In the same vein, the createTask() uses the createTask() on the Prisma client, but in addition to the data to be inserted, we connect the task to the project (through the supplied project ID) it belongs to. The markTaskAsCompleted() updates a task by setting isCompleted to true. It uses the updateTask(), which accepts two arguments: a where clause to get the task to be updated and the data to update it with.

Lastly, we create the resolver functions to fetch the custom fields (tasks and project) on the types on our schema.

Note: Use the singular form of a model to query for a single object and use the plural form of the model to query for a list of objects. You will notice we are using the singular form of Project to fetch a single project prisma.project({ id: projectId }) and the plural form of Task to fetch a list of tasks prisma.tasks({ where: { isCompleted: true } }).

Step 6 — Testing It Out

Now we can test out our app. First, let’s start the GraphQL server:

node src/index.js

The server will be up and running at http://localhost:4000 and opening it will load up the GraphQL Playground.


In this tutorial, we looked at what Prisma is, then at how to get started with it by building a GraphQL server. We also looked at how to test our GraphQL server using the GraphQL Playground. If you would like to learn more about Prisma, check out the official Prisma docs.

Creative Commons License