GraphQL Basics: Part 2 - Prisma (The How)

Prisma (The How)

This is picking up after my last post, Part 1 - Prisma (The Why) where I looked at why you would want to use Prisma for your database. I'm not going much into any of that again so you can check that out if you want. This post is going to be all about how to get Prisma up and running before you set up your GraphQL server. This is going to be very similar to the walkthrough over at Prisma but I wanted to add a few learnings along the way from someone new to the process. Hopefully this can be helpful to others getting started!

Initial Setup

The first thing you'll need to do it head over to Prisma and create an account. Once you're logged in, assuming you don't yet have any workspaces, you'll need to create a workspace. Here I'll make a new one for this example.

One your workspace is created you'll need to deploy a new Prisma service. Click on the "add a service" button.

At this point you are asked to install the Prisma CLI and log in. Before doing this, I actually set up a folder on my computer called 'prisma-graphql-tutorial' first.

Once you log in, you are prompted to run prisma init hello-world, which will create a directory hello-world and ask some questions. Because I already had set up a folder for my project, I just typed in prisma init and got the following prompt:

What we want to do is select the Demo server. This is a nice free database that allows (I think, I'm remembering this from somewhere I read it) 10 read/writes every 10 seconds. Any more and they just get queued up, which is great.

Next we are asked for the region we want our demo server to be, so I selected the workspace I created for this using the west coast server (you can check the latency for the best one).

Finally you're asked for a name for the service, a name for the stage, and the programming language for the Prisma client. You can just hit enter/return for the names for the defaults, and then I selected "Don't generate" for the Prisma client. Honestly, it's because that's what I have always done...and I'm maybe it'll be more useful to those out there using something other than JS to continue on this way anyway.

You should then see the following:

The prisma.yml file is a file that we can use to help define the things we want happening with Prisma when we deploy/generate things, etc. I don't do much here except to add some setting that will automatically generate some files for us, which I'll do later on. The file datamodel.prisma is where we define everything that's going in to our database. The demo uses a mySQL database through AWS, but I was always using Mongo Atlas and mongoose before using Prisma. If you're also used to mongoose and Mongo, the datamodel is similar to creating you Schema and Models in mongoose.

Deploy

At this point you should have 2 files in your directory, the datamodel.prisma and prisma.yml. It's lookin like this on my end:

Finally, because we're just following orders around here blindly, we do what our terminal asks us to do and run prisma deploy and see this:

So, what's going on? Why did we just create this "User" type with all of these fields? Well, that's because when we did prisma init, we actually had a User type pre-filled in out datamodel.prisma file, so deploying essentially told Prisma, "Hey, this is what I want in my database. Do your magic!" You can see it if you open up your datamodel.prisma.

type User {
  id: ID! @unique
  name: String!
}

At this point, you are also given 2 links, right under where it says "Your Prisma GraphQL database endpoint is live." If you follow the links you can see an incredible playground. There are tabs on the right where you can see all the "docs" for you database API and the Schema, all created from your data model you set up in the datamodel.prisma.

Setup of prisma.yml

So this playground is great, but that's all it is. A playground for the db. The next thing I set up is the prisma client and I also add a hook to download that entire schema to my project.

If you head over to prisma.yml you see initially only "endpoint" and "datamodel". Endpoint is simply where the playground is located and the datamodel is the filename of your datamodel, so you could rename it to something like "schema.prisma" and then change the location in prisma.yml so Prisma knows where you are defining your Prisma datamodel. Not rocket science.

The basics I add are the secret, generate object, and hook. You can see this here:

endpoint: http://whateverYourEndpointIs
datamodel: datamodel.prisma
secret: putSomethingHere
generate: 
  - generator: graphql-schema
    output: ./generated/
hooks:
  post-deploy:
    - prisma generate

These set up:

• secret: A secret used when using JWT tokens for authentication.
• generate: This is an object that says you want the "client" (basically a file of the Prisma Schema you can see in the playground) in a certain format.
  • generator: The type of schema you want. I believe it only accepts typescript-client, javascript-client, go-client, or graphql-schema. Honestly I am not too sure what the difference here is between the graphql-schema and using javascript-client. I have only used the graphql one, so unless some smart person comes along enlightens me, I'm sticking to the graphql-schema.
  • output: Where do you want the file to show up in your project?
• hooks: You can set up various hooks here, but what I want here is to run prisma generate every time we deploy to Prisma.

yay! Final step...

Generating the Client & Redeployments

Generating prisma.graphql
Ok, so now you should go ahead and run prisma generate. Following that, you should see a prompt in your terminal that we are "Generating schema" and finally "Saving Prisma GraphQL schema (SDL) at /someplace". You should also see the new structure in your project!

(Don't forget to save the prisma.yml like I did the first time before you run prisma generate, because nothing will happen and you'll think you're terrible at life)

If you open up the prisma.graphql file, you'll see your schema all laid out for you that was created by Prisma!

Adding to datamodel.prisma and Redeployments
Basically, after running prisma generate above, you're good to go! The problem is, you would probably have more than a simple User in your database. Any time you want to add another "Type" to your database, you need to first define it in your datamodel.prisma and then deploy to Prisma again. Let's do that.

First, you create new types using the GraphQL SDL. I am adding an "Item" type to my schema that has an itemId which is required(!) and will be unique to every item (@uniqe). The name and cost are required using the !, while the descriptions are optional.

type User {
  id: ID! @unique
  name: String!
}

type Item {
  itemId: ID! @unique
  name: String!
  cost: Int!
  shortDescription: String
  longDescription: String
}

Once we have added the new type of data we want to be storing in our database, we can redeploy to Prisma. Remember, we have to do this because when you deploy to Prisma, that's when Prisma actually creates the schema. So, again we can prisma deploy in the console. (Don't forget to save the datamodel.prisma first!)

If all goes well you should see that the "Item" type was created, along with all the created fields.

Additionally, you should notice that the prisma.graphql "client" has been re-generated and has been updated because of the prisma generate post-deploy hook that we set up in our prisma.yml file. If all worked out, you should be able to see all sorts of things defined for both User types, and Item types now in the prisma.graphql file.

Next Steps

The next step is to create a GraphQL friendly server. Currently, we are directly accessing only the playground created for us, but if we were to make an application we would need to actually have a server talking to our database. That's the goal of the next post, where we will be setting up a GraphQl Yoga server.

*A side note, I am super new to all of this, so if you have more knowledge you want to drop in the comments, please do!