Conceptual introduction to Prisma 1

Mon Jun 01 2020

I recently joined a new project built with Prisma 1 (opens new window) and it took me a while to understand what exactly Prisma actually does. I thought I'd write a conceptual introduction for other people who find themselves in a similar situation.

If you're looking for setup instructions instead, click here (opens new window) for Prisma 1 or here (opens new window) for Prisma 2.

So what is Prisma in one sentence?

Prisma is software that creates a GraphQL API for your database so that your backend can query your database using either GraphQL directly or Prisma-generated type-safe client libraries (for Go, TypeScript or JavaScript).

You may have heard of Hasura (opens new window). Hasura is similar to Prisma in that it also generates a GraphQL API for your database. However, unlike Hasura, the Prisma GraphQL API is not meant to used outside of your own network.

The setup

Usually this is what your setup would be:

1. Your database (Mongo, MySQL or PostgreSQL).
2. A Prisma server that can connect to your database.
3. Your backend API server that can perform GraphQL queries on your Prisma Server.
4. If your backend server is built in JavaScript, TypeScript or Go, you can use the Prisma Client to call your Prisma Server instead of constructing GraphQL queries yourself.
5. Your frontend or other APIs that can call your backend API.

The setup as illustrated in the Prisma docs:

An example API call

Flipping the stack around, this is what an API call to your backend might look like from start to finish:

1. Your frontend could call a REST endpoint your backend (your backend could use GraphQL or whatever else you like instead). For example, to get all of the users:

GET www.example.com/users

2. When your backend receives the /users call, it can use the Prisma Client library to get the users:

const users = await prisma.users()

3. The Prisma Client library will translate the users() function call to a GraphQL query and send it to your Prisma server:

query {
  users {
    id
    name
  }
}

4. The Prisma Server will then convert the GraphQL query to a database query. For example:

select id, name from users;

Prisma Tooling

The two Prisma tools that we've looked at so far was the Prisma server and the Prisma client.

Prisma Server was built in Scala and the recommended way to run a Prisma Server instance is with Docker (opens new window).

You can also setup a demo server on Prisma Cloud (opens new window) for free.

The Prisma Client consists of generated files that makes it easier for you to make queries on your database. To generate the Prisma client, you need to install the Prisma CLI.

The Prisma CLI is what ties everything together in Prisma. It allows you to change the structure of your database, deploy changes to your Prisma server, open up a Prisma Admin page, etc. You can install it using either brew, yarn or npm.

Finally, Prisma Admin is a visual interface that you can use to manage your database. You can run it with prisma admin. It will open a page in your browser similar to this one:

Prisma Services

One concept we haven't discussed so far is Prisma "services." You'll often see services mentioned in the documentation, but it sounds more complicated than it really is.

Essentially, all it means it that a single Prisma Server has the capability of serving more than one GraphQL API. A Prisma service refers to a single database and its GraphQL API that is served by a Prisma Server.

The following diagram should make things clearer:

Prisma Services Diagram