Setting up Prisma

Goals

On this page, you will learn how to:

• Install the Prisma CLI
• Start a local Prisma server using Docker
• Introspect your existing database and generate a service configuration
• Deploy a Prisma service to the local Prisma server
• Explore the Prisma API in a GraphQL Playground

Prerequisites

Make sure to have connection details for your database at hand. This includes the following pieces of information:

• Host: The host of your Postgres server, e.g. localhost.
• Port: The port where your Postgres server listens, e.g. 5432.
• User & Password: The credentials for your Postgres server.
• Name of existing database: The name of the Postgres database.
• Name of existing schema: The name of the Postgres schema, e.g. public.

You also need to know whether your database server uses SSL.

Install the Prisma CLI

The Prisma CLI is used to deploy and manage Prisma services. You can install it using NPM:

npm install -g prisma
Copy
 

Install Docker

To use Prisma locally, you need to have Docker installed on your machine. If you don't have Docker yet, you can download the Docker Community Edition for your operating system here.

Set up Prisma server

Create Docker Compose file

To launch a Prisma server on your machine, you need a Docker Compose file that configures the Prisma server and specifies to which database it can connect:

touch docker-compose.yml
Copy
 

Add Prisma Docker image

Paste the following contents into the Docker Compose file you just created:

version: '3'
services:
  prisma:
    image: prismagraphql/prisma:1.15
    restart: always
    ports:
      - '4466:4466'
    environment:
      PRISMA_CONFIG: |
        port: 4466
        databases:
          default:
            connector: postgres
            host: __YOUR_POSTGRES_HOST__
            port: __YOUR_POSTGRES_PORT__
            database: __YOUR_POSTGRES_DB__
            schema: __YOUR_POSTGRES_SCHEMA__
            user: __YOUR_POSTGRES_USER__
            password: __YOUR_POSTGRES_PASSWORD__
            migrations: false
            ssl: __SSL_CONNECTION__
Copy
 

Specify database connection

To specify the database to which your Prisma server should connect, replace the placeholders that are spelled all-uppercased in the Docker Compose files with the corresponding values of your database:

• __YOUR_POSTGRES_HOST__: The host of your Postgres server, e.g. localhost.
• __YOUR_POSTGRES_PORT__: The port where your Postgres server listens, e.g. 5432.
• __YOUR_POSTGRES_DB__: The name of your Postgres database.
• __YOUR_POSTGRES_SCHEMA__: The name of your Postgres schema, e.g. public.
• __YOUR_POSTGRES_USER__: The database user.
• __YOUR_POSTGRES_PASSWORD__: The password for the database user.
• __SSL_CONNECTION__: Whether your database server uses SSL, possible values are true and false.

Start Prisma server

To start the Prisma server and launch the connected database, run the following command:

docker-compose up -d
Copy
 

Introspect your database

You now need to introspect your database schema to generate the data model for your Prisma service:

prisma introspect
Copy
 

In the interactive wizard, provide the same database connection details you specified in the Docker Compose file.

The CLI will generate the datamodel-[TIMESTAMP].graphql (e.g. datamodel-1533886167692.graphql) file containing the SDL version of your database schema.

Deploy the Prisma service

Create prisma.yml

Before deploying the Prisma service, you need to create a prisma.yml:

touch prisma.yml
Copy
 

Now add the following contents to it:

endpoint: http://localhost:4466
datamodel: __PATH_TO_YOUR_DATA_MODEL__
Copy
 

Replace the __PATH_TO_YOUR_DATA_MODEL__ placeholder with the name of the file that contains the data model, e.g. datamodel-1533886167692.graphql.

Deploy the service configuration to the local Prisma server

This service configuration now needs to be deployed so you can use the Prisma API of your service:

prisma deploy
Copy
 

Explore the Prisma API in a Playground

The Prisma API of your service exposes CRUD and realtime operations for the types defined in your data model. You can explore the API in a GraphQL Playground using the following command:

prisma playground
Copy
 

The queries and mutations you can send depend on the data model that was generated from the database introspection. The following sample queries assume there is a User type in the data model defined as follows:

type User @pgTable(name: "User") {
  id: Int! @unique
  name: String!
}

Depending on what your data model looks like, you can derive equivalent queries and mutations for your case. You can also use the auto-generated API documentation in the Playground to learn about the available API operations.

mutation {
  createUser(data: { name: "Alice" }) {
    id
  }
}
Copy