# Using GraphQL Nexus with a Database URL: https://www.prisma.io/blog/using-graphql-nexus-with-a-database-pmyl3660ncst Published: 2019-02-12 Authors: Nikolas Burk Series: Code-first GraphQL server development with Nexus Description: Learn how to connect GraphQL Nexus to a database with Prisma Client and the Nexus Prisma plugin. > Blog posts describe Prisma as it was on the date shown and are not kept current. Before implementing from a post, check the documentation index at https://www.prisma.io/docs/llms.txt and the changelog at https://www.prisma.io/changelog.md. > For an index of every published post, fetch https://www.prisma.io/blog/llms.txt. [GraphQL Nexus](https://nexus.js.org/) is a code-first, type-safe GraphQL schema construction library for JavaScript/TypeScript. Learn how it can be connected to a database using the Prisma client & the new [`nexus-prisma`](https://github.com/prisma/nexus-prisma) plugin. > ⚠️ **This article is outdated** as it relates to [Prisma 1](https://github.com/prisma/prisma1) which is now [deprecated](https://github.com/prisma/prisma1/issues/5208). To learn more about the most recent version of Prisma, read the [documentation](https://www.prisma.io/docs). ⚠️ ## Recap: Code-first development with GraphQL Nexus [#recap-code-first-development-with-graphql-nexus] In the last article, we introduced [GraphQL Nexus](https://nexus.js.org/docs/getting-started), a GraphQL library that enables code-first development for TypeScript and JavaScript. With Nexus, the GraphQL schema is defined and implemented *programmatically*. It therefore follows proven approaches of GraphQL servers in other languages, such as [`sangria-graphql`](https://github.com/sangria-graphql/sangria) (Scala), [`graphlq-ruby`](https://github.com/rmosolgo/graphql-ruby) or [`graphene`](https://graphene-python.org/) (Python). Today's article is about connecting your Nexus-based GraphQL server to a database, using the Prisma client as well as the new [`nexus-prisma`](https://github.com/prisma/nexus-prisma) plugin. We'll later walk you through a practical example of building a GraphQL API for a blogging app from scratch. > `nexus-prisma` works with PostgreSQL, MySQL and MongoDB. **Find the docs for it [here](https://nexus.js.org/docs/nexus-prisma)**. *** ## TLDR: Benefits of the `nexus-prisma` plugin [#tldr-benefits-of-the-nexus-prisma-plugin] * CRUD operations for your Prisma models in GraphQL * Customize your Prisma models, e.g. *hide certain fields* or *add computed fields* * Full type-safety: Coherent set of types for GraphQL schema and database * Compatible with the GraphQL ecosystem (e.g. `apollo-server`, `graphql-yoga`, ...) ## Understanding the `nexus-prisma` workflow [#understanding-the-nexus-prisma-workflow] ### The Prisma client as an ORM replacement [#the-prisma-client-as-an-orm-replacement] If you haven't worked with Prisma before, here's a quick rundown of how it works: 1. Define your datamodel or let Prisma introspect your existing database 2. Generate your Prisma client, i.e. a type-safe database client 3. Use the Prisma client to access your database in an application (e.g. a GraphQL API) ### The `nexus-prisma` plugin under the hood [#the-nexus-prisma-plugin-under-the-hood] When adding `nexus-prisma` to the mix, there's another step: invoking the `nexus-prisma-generate` codegen CLI. It generates the building blocks of a full-blown GraphQL CRUD API for your Prisma models, e.g. for a **`User`** model it includes: * **Queries** * **`user(...): User!`**: Fetches a single record * **`users(...): [User!]!`**: Fetches a list of records * **`usersConnection(...): UserConnection!`**: [Relay connections](https://graphql.org/learn/pagination/#complete-connection-model) & aggregations * **Mutations** * **`createUser(...): User!`**: Creates a new record * **`updateUser(...): User`**: Updates a record * **`deleteUser(...): User`**: Deletes a record * **`updatesManyUsers(...): BatchPayload!`**: Updates many records in bulk * **`deleteManyUsers(...): BatchPayload!`**: Deletes many records in bulk * [**GraphQL input types**](https://graphql.org/graphql-js/mutations-and-input-types/) * **`UserCreateInput`**: Wraps all fields of the record * **`UserUpdateInput`**: Wraps all fields of the record * **`UserWhereInput`**: Provides filters for all fields of the record * **`UserWhereUniqueInput`**: Provides filters for unique fields of the record * **`UserUpdateManyMutationInput`**: Wraps fields that can be updated in bulk * **`UserOrderByInput`**: Specifies ascending or descending orders by field > `UserCreateInput` and `UserUpdateInput` differ in the way relation fields are treated. When writing your GraphQL server code with `nexus` and `nexus-prisma`, you build upon these operations by exposing and customizing them to your own API needs: ![Writing GraphQL server code with nexus and nexus-prisma](https://www.prisma.io/blog/using-graphql-nexus-with-a-database-pmyl3660ncst/imgs/dbEMHd5.png) After having generated the CRUD building blocks, you can use `prismaObjectType` from `nexus-prisma` to start exposing (and customizing) them. The following code snippets depict an implementation that provides a GraphQL API for a TODO-list app based on Prisma and `nexus-prisma`: ```graphql type Todo { id: ID! @unique title: String! done: Boolean! @default(value: "false") } ``` ```ts import { prismaObjectType } from 'nexus-prisma' import { idArg } from 'nexus-prisma' // Expose the full "Query" building block const Query = prismaObjectType({ name: 'Query', definition: t => t.prismaFields(['*']) }) // Customize the "Mutation" building block const Mutation = prismaObjectType({ name: 'Mutation', definition(t) { // Keep only the `createTodo` mutation t.prismaFields(['createTodo']) // Add a custom `markAsDone` mutation t.field('markAsDone', { args: { id: idArg() }, nullable: true, resolve: (_, { id }, ctx) { return ctx.prisma.updateTodo({ where: { id }, data: { done: true } }) } }) } }) const schema = makePrismaSchema({ types: [Query, Mutation], // More config stuff, e.g. where to put the generated SDL }) // Feed the `schema` into your GraphQL server, e.g. `apollo-server, `graphql-yoga` ``` ```graphql # The fully exposed "Query" building block type Query { todo(where: TodoWhereUniqueInput!): Todo todoes( after: String before: String first: Int last: Int orderBy: TodoOrderByInput skip: Int where: TodoWhereInput ): [Todo!]! todoesConnection( after: String before: String first: Int last: Int orderBy: TodoOrderByInput skip: Int where: TodoWhereInput ): TodoConnection! } # The customized "Mutation" building block type Mutation { createTodo(data: TodoCreateInput!): Todo! markAsDone(id: ID): Todo } # The Prisma model type Todo { done: Boolean! id: ID! title: String! } # More of the generated building blocks: # e.g. `TodoWhereUniqueInput`, `TodoCreateInput`, `TodoConnection`, ... ``` We're applying `prismaObjectType` to `Query` and `Mutation`. For `Query`, we're keeping all fields (i.e. `todo`, `todoes` and `todoesConnection`). For `Mutation` we're using `prismaFields` to customize the exposed operations. `prismaFields` lets us select the operations to be exposed. In this case, we only want to keep the operation to *create* a model (`createTodo`). From the generated CRUD building blocks, we're including neither `updateTodo` nor `deleteTodo` but implement our own `markAsDone(id: ID!)` mutation that checks off a certain `Todo`. *** ## Example: From standard CRUD to a customized GraphQL API [#example-from-standard-crud-to-a-customized-graphql-api] Let's now take a quick tour through a standard Prisma use case and see how to quickly build a GraphQL API for a blogging app in a few easy steps. Here's what we'll do: 1. Setup a Prisma project (using a free demo database) with TypeScript 2. Define models, migrate database and generate the Prisma client 3. Expose full CRUD GraphQL API via `nexus-prisma` 4. Customize the GraphQL API via `nexus-prisma` If you want to follow along, you need to have the Prisma CLI installed: ```shell npm install -g prisma ``` ```shell yarn global add prisma ``` ```shell brew tap prisma/prisma brew install prisma ``` ### 1) Setup Prisma project with TypeScript, `nexus` and `nexus-prisma` [#1-setup-prisma-project-with-typescript-nexus-and-nexus-prisma] This section mostly deals with your project setup. Feel free to skip it if you don't want to code along, otherwise expand the section below. ### See project setup instructions Use the Prisma CLI to create a simple Prisma project: ```shell prisma init myblog ``` In the interactive prompt, select the following options: 1. Select **Demo server** (includes a free & hosted demo database in Prisma Cloud) 2. **Authenticate** with Prisma Cloud in your browser (if necessary) 3. Back in your terminal, **confirm all suggested values** > As an alternative to the Demo server, you can also [run Prisma locally using Docker](https://v1.prisma.io/docs/1.34/prisma-server/deployment-environments/docker-rty1/). Next you need to configure your `nexus-prisma` workflow. Add the following dependencies (inside the `myblog` directory): ```shell npm init -y npm install --save nexus graphql nexus-prisma prisma-client-lib graphql-yoga npm install --save-dev typescript ts-node-dev ``` Next, add the following two lines to the end of your `prisma.yml`: ```yml hooks: post-deploy: - prisma generate - npx nexus-prisma-generate --client ./generated/prisma-client --output ./generated/nexus-prisma ``` This ensures that the Prisma client as well as the generated `nexus-prisma` CRUD building blocks are being updated whenever you make changes to your models. Since we're using TypeScript, let's quickly add a `tsconfig.json`: ```json { "compilerOptions": { "sourceMap": true, "outDir": "dist", "strict": true, "lib": ["esnext", "dom"] } } ``` Finally, go ahead and add a `start` script that you'll use for development. It starts a development server that watches your files in the background and updates the generated SDL and Nexus typings as you code. Add this to your `package.json`: ```json "scripts": { "start": "ts-node-dev --no-notify --respawn --transpileOnly ./" }, ``` ### 2) Define models, migrate database & generate the Prisma client [#2-define-models-migrate-database--generate-the-prisma-client] The `prisma init` command created a default `User` model in `datamodel.prisma`. As we're building a blogging application, let's adjust the models to our application domain: ```graphql type User { id: ID! @unique email: String! @unique name: String posts: [Post!]! } type Post { id: ID! @unique createdAt: DateTime! updatedAt: DateTime! published: Boolean! @default(value: "false") title: String! content: String author: User! } ``` Next you need to migrate the database by applying the datamodel to it. Using the following command, each model defined in `datamodel.prisma` will be mapped to a table in the underlying database: ```shell prisma deploy ``` Because you configured the `post-deploy` hook in `prisma.yml` earlier, your Prisma client and the CRUD building blocks are automatically updated. ### 3) Expose full CRUD GraphQL API via `nexus-prisma` [#3-expose-full-crud-graphql-api-via-nexus-prisma] In the early phase of a project, it's often helpful to have full CRUD capabilities exposed by an API – more constrained API requirements typically emerge over time. `nexus-prisma` perfectly accounts for that by providing a straightforward path to go from full CRUD to customized API operations. Let's start with a GraphQL API that exposes full CRUD for the defined models (note that this includes filters, pagination and sorting). Create a new file called `index.ts` and add the following code to it: ```ts import * as path from 'path' import { GraphQLServer } from 'graphql-yoga' import { makePrismaSchema, prismaObjectType } from 'nexus-prisma' import { prisma } from './generated/prisma-client' import datamodelInfo from './generated/nexus-prisma' const Query = prismaObjectType({ name: 'Query', definition: t => t.prismaFields(['*']), }) const Mutation = prismaObjectType({ name: 'Mutation', definition: t => t.prismaFields(['*']), }) const schema = makePrismaSchema({ types: [Query, Mutation], prisma: { datamodelInfo, client: prisma, }, outputs: { schema: path.join(__dirname, './generated/schema.graphql'), typegen: path.join(__dirname, './generated/nexus.ts'), }, }) const server = new GraphQLServer({ schema, context: { prisma }, }) server.start(() => console.log(`Server is running on http://localhost:4000`)) ``` > We're not paying much attention to file structure in this short tutorial. Check our [`graphql-auth`](https://github.com/prisma/prisma-examples/tree/master/typescript/graphql-auth) example for a proper setup and modularized schema. After running `npm run start`, you can open the GraphQL Playground for your GraphQL server on `http://localhost:4000`. With the little code you wrote above, you already have a full-blown GraphQL CRUD API at your disposal. ### See some example queries and mutations #### Example queries [#example-queries] ```graphql # Fetch all posts with their authors query { posts { id title published author { id name } } } ``` ```graphql # Fetch a certain user by email query { user(where: { email: "alice@prisma.io" }) { id name posts { id title } } } ``` #### Example mutations [#example-mutations] ```graphql # Create a post and its author mutation { createPost(data: { title: "Hello World", author: { create: { email: "bob@prisma.io" } } }) { id published author { id name } } } ``` ```graphql # Update the name of a user mutation { updateUser(data: { name: "Alice" }, where: { email: "alice@prisma.io " }) { id name } } ``` ```graphql # Delete a user mutation { deleteUser(where: { email: "alice@prisma.io " }) { id name } } ``` How does that work? `nexus-prisma-generate` generated a GraphQL schema that provides a CRUD API for Prisma models (your *CRUD building blocks*). This GraphQL schema follows the [OpenCRUD](https://www.opencrud.org/) specification. Using the `prismaObjectType` function, you can now expose and customize the operations of that schema. `prismaObjectType` and `prismaFields` use a *whitelist* approach, meaning you need to explicitly list the fields you want to expose. The wildcard operator `*` includes *all* fields. ![Expose full CRUD GraphQL API via nexus-prisma](https://www.prisma.io/blog/using-graphql-nexus-with-a-database-pmyl3660ncst/imgs/RLsS1lm.png) ### 4) Customize the GraphQL API via `nexus-prisma` [#4-customize-the-graphql-api-via-nexus-prisma] In this section, we'll learn how the CRUD GraphQL API from `nexus-prisma` can be customized. Specifically, we are going to: 1. Hide a field from the `User` model 2. Add a computed field to the `Post` model 3. Hide the `createPost` and `updatePost` mutations 4. Add two custom `createDraft` and `publish` mutations #### 4.1) Hide a field from the `User` model [#41-hide-a-field-from-the-user-model] In this section, we'll hide the `email` field from the `User` model. To customize a model, we need to apply the `prismaObjectType` function to it and pass the `definition(t)` function as an option: ```ts const User = prismaObjectType({ name: 'User', definition(t) { t.prismaFields(['id', 'name', 'posts']) }, }) ``` By calling `prismaFields` on the model `t`, we can customize the exposed fields (and their arguments). Because `email` is not included in the list, it's removed from our GraphQL API. ![Hide a field from the User model](https://www.prisma.io/blog/using-graphql-nexus-with-a-database-pmyl3660ncst/imgs/Zwby9Hs.png) To apply the changes, you need to explicitily pass `User` to the `types` array inside of `makePrismaSchema`: ```ts const schema = makePrismaSchema({ types: [Query, Mutation, User], // ... } ``` Note that your editor is able to suggest what to pass into `prismaObjectType` and `prismaFields` based on the generated CRUD building blocks. This means when you type `prismaObjectType('')` and hit **ctrl+space**, it suggests the names of all generated CRUD building blocks. When calling `t.prismaFields([''])`, it suggests the fields of `t`: #### 4.2) Add a computed field to the `Post` model [#42-add-a-computed-field-to-the-post-model] The new code-first approach with `nexus-prisma` also makes it easy to add computed fields to Prisma models. Say you want to add a field to `Post` that always returns the `title` spelled entirely uppercased. Here's how to implement that: ```ts const Post = prismaObjectType({ name: 'Post', definition(t) { t.prismaFields(['*']) t.string('uppercaseTitle', { resolve: ({ title }, args, ctx) => title.toUpperCase(), }) }, }) ``` We add a new field to our model using the `t.string(...)` API that comes from `graphql-nexus`. Because it's a computed field (and therefore can't be automatically resolved by `nexus-prisma`), we also need to attach a resolver to it. ![Customize the GraphQL API via nexus-prisma](https://www.prisma.io/blog/using-graphql-nexus-with-a-database-pmyl3660ncst/imgs/64ipcsj.png) As before, you need to explicitly add the customized `Post` model to the `types` array: ```ts const schema = makePrismaSchema({ types: [Query, Mutation, User, Post], // ... } ``` #### 4.3) Hide `createPost` and `updatePost` mutations [#43-hide-createpost-and-updatepost-mutations] In the same way that we've hidden the `email` field from the `User` model, we can also hide operations from the `Query`/`Mutation` types that are part of the generated `nexus-prisma` CRUD building blocks. To hide `createPost` and `updatePost` we again need to pass `definition(t)` to `prismaObjectType` as an option. Note that once we call `prismaFields` on a type, we need to explicitly list all fields we want to keep (an empty array would be interpreted as "keep no operations"): ```ts const Mutation = prismaObjectType({ name: 'Mutation', definition(t) { t.prismaFields(['createUser', 'updateUser', 'deleteUser', 'deletePost']) }, }) ``` > The generated CRUD GraphQL API also includes batched and upsert operations that we're excluding here for brevity as well. #### 4. Add two custom `createDraft` and `publish` mutations [#4-add-two-custom-createdraft-and-publish-mutations] Finally, we're adding two custom mutations to our GraphQL API. Here's what their SDL definitions are supposed to look like: ```graphql type Mutation { createDraft(title: String!, content: String): Post! publish(id: ID!): Post } ``` To implement these mutations, you need to add two fields (by calling `t.field( ... )` from the `nexus` API) to the `Mutation` type: ```ts const Mutation = prismaObjectType({ name: 'Mutation', definition(t) { t.prismaFields(['createUser', 'updateUser', 'deleteUser', 'deletePost']) t.field('createDraft', { type: 'Post', args: { title: stringArg(), content: stringArg({ nullable: true }), }, resolve: (parent, { title, content }, ctx) => { return ctx.prisma.createPost({ title, content }) }, }) t.field('publish', { type: 'Post', nullable: true, args: { id: idArg(), }, resolve: (parent, { id }, ctx) => { return ctx.prisma.updatePost({ where: { id }, data: { published: true }, }) }, }) }, }) ``` Be sure to import `stringArg` and `idArg` from the `nexus` package to make this work. GraphQL Nexus also generates the SDL version of your GraphQL schema, you find it in `./generated/schema.graphql`. The final version of our GraphQL API looks as follows: ```graphql type Mutation { createDraft(content: String, title: String): Post! createUser(data: UserCreateInput!): User! deletePost(where: PostWhereUniqueInput!): Post deleteUser(where: UserWhereUniqueInput!): User publish(id: ID): Post updateUser(data: UserUpdateInput!, where: UserWhereUniqueInput!): User } type Query { node(id: ID!): Node post(where: PostWhereUniqueInput!): Post posts( after: String before: String first: Int last: Int orderBy: PostOrderByInput skip: Int where: PostWhereInput ): [Post!]! postsConnection( after: String before: String first: Int last: Int orderBy: PostOrderByInput skip: Int where: PostWhereInput ): PostConnection! user(where: UserWhereUniqueInput!): User users( after: String before: String first: Int last: Int orderBy: UserOrderByInput skip: Int where: UserWhereInput ): [User!]! usersConnection( after: String before: String first: Int last: Int orderBy: UserOrderByInput skip: Int where: UserWhereInput ): UserConnection! } type User { id: ID! name: String posts( after: String before: String first: Int last: Int orderBy: PostOrderByInput skip: Int where: PostWhereInput ): [Post!] } type Post { id: ID! createdAt: DateTime! updatedAt: DateTime! author: User! content: String published: Boolean! title: String! uppercaseTitle: String! } # More generated SDL types ... ``` *** ## 3 key takeways from our code-first GraphQL articles [#3-key-takeways-from-our-code-first-graphql-articles] This was the last part of our articles series on code-first GraphQL server development. [GraphQL Nexus](https://nexus.js.org/) and the `nexus-prisma` plugin implement the learnings we've gathered from being active contributors to the GraphQL ecosystem for well over two years. After having found too many issues with an [SDL-first](https://www.prisma.io/blog/the-problems-of-schema-first-graphql-development-x1mn4cb0tyl3) approach, we're incredibly excited about the new code-first tooling that's currently emerging. We strongly believe that GraphQL Nexus (and other code-first approaches such as [TypeGraphQL](https://github.com/19majkel94/type-graphql)) are going to drastically change the way how GraphQL schemas will be built in the future. Here are our main takeways from the series: 1. Code-first approaches let you build GraphQL servers in language-idiomatic ways without the need for additional tooling ("the only tool you need is your programming language") while retaining the benefits of SDL as a communication tool. 2. GraphQL Nexus lets developers construct their schemas with a flexible and type-safe API. Developers get an amazing experience thanks to auto-completion and build-time error checks. 3. The `nexus-prisma` plugin builds on top of the Prisma models and lets developers build a GraphQL API by exposing and customizing auto-generated CRUD building blocks. ## Try out `nexus-prisma` today 🙌 [#try-out-nexus-prisma-today-] There are several ways for you to try out [`nexus-prisma`](https://github.com/prisma/nexus-prisma). You can either follow the [**Getting Started**](https://nexusjs.org/components-standalone/schema/plugins/prisma)-section in the docs or explore our [**TypeScript GraphQL examples**](https://github.com/prisma/prisma-examples/tree/master/typescript). Please share your feedback by [opening a GitHub issue](https://github.com/prisma/nexus-prisma) or reaching out in our [Slack](https://slack.prisma.io). *** **A huge shoutout to our open-source engineer [Flavian Desverne](https://twitter.com/fdesverne) for his incredible work on the `nexus-prisma` plugin 💪✨**