By now, you have probably heard a lot of buzz about GraphQL going around and how it’s going to replace REST but you don’t even know where to begin. You hear a lot of buzzwords about mutations and queries but what you’re used to is GET and POST requests on your different endpoints to fetch data and make changes to your database. Thinking about making a switch to GraphQL and don’t know where to begin? This article is for you.
In this article, we are going to take a look at how to convert a database to a GraphQL API using Prisma.
Prerequisites
To follow through this article, you’ll need the following:
- Basic knowledge of JavaScript
- Node installed on your machine
- Node Package Manager installed on your machine
To confirm your installations, run the command:
node --version
npm --versionIf you get their version numbers as results then you’re good to go!
Using Prisma to connect GraphQL to a database
Prisma is a service that allows you to build a GraphQL server with any database with ease. To get started with using Prisma, you need to install the command line interface first:
npm install -g prismaThis globally installs prisma for future use on your machine. The next thing you need to do is to create a new service. To do this, run the command:
prisma init scotch-prisma-demoWhen you run this command, a prompt will be shown for you to decide what server you want to connect to.
For demo purposes, select the Demo Server option and then a browser prompt will be shown to register with Prisma Cloud. After successful login, click the CREATE A NEW SERVICE option and then copy the key required to log in to Prisma from the page.
Head over to your terminal, close the current process if it’s still running and then login to prisma by pasting the command copied from the browser into the terminal:
Once you’ve successfully signed in, return to the command line and select the region for your demo server and follow the remaining prompts as shown below:
You can also head over here if you want to connect Prisma with own database.
Now that the service has been created, you need to deploy it. To do this, head over to the scotch-prisma-demo directory and run the deploy command:
cd scotch-prisma-demo
prisma deploy
Once deployment is complete, on the Prisma Cloud you can see a list of your deployed services:
To open the GraphQL API and start sending queries and running mutations, run the command:
prisma playground
Updating Schema
When the scotch-prisma-demo folder was created, two files were created in the folder
prisma.yml– containing theendpointanddatamodelfor the server.datamodel.graphql– Containing the schema for the server.
Edit the datamodel.graphql file to look like this:
type User {
id: ID! @unique
name: String!
}This means the schema will contain the ID and name for the user. To update the schema, run the command:
prisma deployUsing Yoga and Prisma Binding to interact with Prisma Service
In the last section, we saw how to use Prisma to turn a database into GraphQL API and then run Queries and mutations from the playground. Here’s the thing though. In a real-life application, leaving all this functionality to anyone who has access to the Prisma means that the client has the entire database exposed to them and this is not good.
To to this, Prisma has the graphql-yoga and prisma-binding which allow you to build a GraphQL server on top of the Prisma service by connecting the resolvers of the GraphQL server to Prisma’s GraphQL API using Prisma binding.
In the scotch-prisma-demo folder initialize a node project using the command:
npm init -yThis automatically creates a package.json file for your project
Installing the necessary modules
To continue building the graphql server, we will need to install the following modules by running the command:
npm install graphgql-yoga prisma-bindingReorganize File Structure
Run the following commands:
mkdir prisma
mv datamodel.graphql prisma/
mv prisma.yml prisma/
mkdir src
touch src/index.js
touch src/schema.graphqlCreating Application Schema
The GraphQL server needs to have a Schema that helps identify the operations that can be carried out on the server. For this application, edit the src/schema.graphql to look like this:
type Query{
user(id: ID!): User
}
type Mutation {
signup(name: String!): User!
}In this case, the schema allows for the following:
- Fetch a single user based on its
id - Signup a user to the system
Downloading Prisma Database Schema
If you look at the schema definition above, you can see that the User is not defined. Ideally, you could redefine the User type in the schema but since there already exists a definition in the Prisma service created earlier, we will use that instead to prevent us from having multiple locations for one definition.
Install the GraphQL CLI by running:
npm install -g graphql-cliand then create a .graphqlconfig in the root directory of the project and update it as follows:
touch .graphqlconfig.ymlprojects:
app:
schemPath: src/schema.graphql
extensions:
endpoints:
default: http://localhost:4000
prisma:
schemaPath: src/generated/prisma.graphql
extensions:
prisma: prisma/prisma.ymlYou can download the Prisma schema by running the following command:
graphql get-schema --project prismaThen, update the src/schema.graphql to look like this:
import User from './generated/prisma.graphql'
type Query{
user(id: ID!): User
}
type Mutation {
signup(name: String!): User!
}You have the Prisma schema downloaded in the /src/generated/prisma.graphql file.
Instantiating Prisma bindings and Implementing Resolvers
The next thing to do is to ensure that Prisma’s GraphQL API can be accessed by the resolvers using the prisma-binding. To do this, update the index.js file to look like this:
// src/index.js
const { GraphQLServer } = require('graphql-yoga')
const { Prisma } = require('prisma-binding')
const resolvers = {
Query: {
user: (_, args, context, info) => {
// ...
}
},
Mutation: {
signup: (_, args, context, info) => {
// ...
}
}
}
const server = new GraphQLServer({
typeDefs: 'src/schema.graphql',
resolvers,
context: req => ({
req,
prisma: new Prisma({
typeDefs: 'src/generated/prisma.graphql',
endpoint: 'PRISMA_ENDPOINT',
}),
}),
})
server.start(() => console.log(`GraphQL server is running on http://localhost:4000`))Note that the
PRISMA_ENDPOINTcan be obtained from your/prisma/prisma.ymlfile.
Update the resolvers in your application by adding the following into your index.js file:
// src/index.js
[...]
const resolvers = {
Query: {
user: (_, args, context, info) => {
return context.prisma.query.user(
{
where: {
id: args.id,
},
},
info
)
}
},
Mutation: {
signup: (_, args, context, info) => {
return context.prisma.mutation.createUser(
{
data: {
name: args.name,
},
},
info
)
}
}
}
[...]Update your package.json file as follows:
{
"name": "scotch-prisma-demo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "node src/index.js",
"test": "echo "Error: no test specified" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {
"graphql-yoga": "^1.14.7",
"prisma-binding": "^2.0.2"
}
}Here, we added the start script to the project. Now, you can run the application by using this command:
npm startThis starts the server and the playground for use. When you head over to the browser and navigate to localhost:4000, you get the following:
Now that we have built the GraphQL server over the Prisma Service, the playground no longer connects directly to the Prisma Endpoint but to the application itself. With this, the client is restricted to only performing actions that have been defined in the new schema on the server.
Conclusion
In the article, we have seen how to create a Prisma service that converts a database to a GraphQL API and how to use GraphQL Yoga and Prisma Binding to build a GraphQL server on the service for use by client applications. Here’s a link to the GitHub repository if interested. Feel free to leave a comment below.