Prisma Basics: Server, Services & Data Model

Main concepts

When working with Prisma, you need to understand the following concepts:

• Prisma Service: Each Prisma service provides a mapping from your database to GraphQL and exposes a CRUD/realtime GraphQL API, called the Prisma API. Working with Prisma, you will spend most of your time developing and consuming the APIs of your Prisma services.
• Prisma Server: One Prisma server provides the runtime environment for many Prisma services. Prisma servers can be deployed anywhere (e.g. using Docker) and are backed by one or more databases. A Prisma server is set up once - after that Prisma services can be deployed to it.

• Service configuration: You can think of the service configuration as the template for a service. To deploy a service, the CLI sends the service configuration to the Prisma server which creates/updates the respective Prisma service. The service configuration consists of:

  • prisma.yml: The root configuration file for a Prisma service (includes the service's endpoint, the service secret, the path to the data model file, ...)
  • Data model: In the data model, you define models which Prisma uses to generate the GraphQL API for your database (and optionally to migrate the underlying database). It's using the declarative GraphQL SDL syntax and is typically stored in a file called datamodel.graphql.
• Prisma CLI: The Prisma CLI is primarily used to manage Prisma services. It lets you initialize and deploy services, generate service tokens, introspect a database to generate an SDL data model, delete services from a Prisma server and more.

Here's a simple diagram showing the interplay of these concepts:

Prisma services

When working with Prisma, you spend most of your time dealing with services. A Prisma service exposes a CRUD/realtime GraphQL API called the Prisma API.

Prisma API features

The Prisma API is GraphQL API that exposes CRUD/realtime operations based on the model definitions in the data model. Here is an overview of the API features:

• Read from database using GraphQL queries (including filtering, ordering and pagination)
• Create, update and delete data using powerful GraphQL mutations
• Receive realtime events using GraphQL subscriptions
• OpenCRUD compliant

Service endpoint and stages

Each Prisma service has exactly one endpoint. The endpoint is composed of the following components:

• Host: The host of your Prisma server (incl. protocol and port), e.g. https://example.com:4466
• Service name: The first path component of the endpoint URL is a name for the Prisma service, e.g. my-service. If no service name is specified, it defaults to default.
• Service stage: The second path component of the endpoint URL is the stage of the service. Like the service name, this can be a random string - but you commonly use terms that describe deployment environments (e.g. dev, staging, prod, ...). If no service stage is specified, it defaults to default.

Putting it all together, the endpoint for a service might look as follows: https://example.com:4466/my-service/dev

Prisma services can also be deployed to endpoints without any path components (e.g. http://localhost:4466), in these cases Prisma uses default for service name and stage. This means http://localhost:4466/default/default can always be written as http://localhost:4466.

Common workflows

Here are common things you might want to do with your services:

• Define and adjust the service's data model which is the foundation for the generated Prisma API.
• Build a GraphQL server (with business logic and a custom schema) based on the auto-generated GraphQL API of a Prisma service.
• Protect your Prisma API by setting a service secret to enable JWT-based authentication.
• Deploy the same service configuration to multiple deployment environments by adjusting the service's endpoint in prisma.yml (e.g. change host and/or stage).
• Configure post-deployment hooks to execute bash commands after a service was deployed (e.g. to download the auto-generated GraphQL schema that defines the Prisma API).
• Initially seed service data or import/export data as the service is running.

See here for more info about Prisma services.

Service configuration

The Prisma service configuration provides a template for a Prisma service. When deployed, the service configuration is used to create/update a Prisma service running on a Prisma server. It consists of the data model and prisma.yml containing various configuration options for the service.

prisma.yml

Here is a minimal example of what a standard prisma.yml looks like:

endpoint: http://localhost:4466/my-service/dev
datamodel: datamodel.graphql
secret: my-secret

These are the configuration properties it contains:

• endpoint: The HTTP endpoint of the Prisma server (plus service name and stage) to which the service is deployed. This endpoint exposes the service's Prisma API.
• datamodel: The file path to the data model which serves as foundation for the GraphQL CRUD/realtime API.
• secret: The service secret is used to secure the service's GraphQL API endpoint using JWT-based authentication. If no secret is specified, the service does not require authentication.

Data model

You can think of the data model as a way to specify your database schema in a declarative way. (Prisma enforces a schema even for schemaless databases.)

The data model is written in GraphQL SDL and contains the service's model definitions. The auto-generated Prisma API exposes CRUD and realtime operations for each model.

Prisma maps each model definition to a table (or an equivalent structure in the case of a non-relational database, e.g. a document) in the underlying database.

The data model is typically located in a file called datamodel.graphql (though it might be named differently or even split across multiple files).

Prisma servers

Prisma servers provide the environment where services are running and therefore are a essential component in your Prisma setup.

They can be run with Docker and deployed to your own infrastructure or a cloud provider of your choice. Prisma servers are set up once and after they're available they can be used as deployment targets for Prisma services.

Maintaining Prisma servers

After a Prisma server is setup and available as a deployment target, there's not much else to do with your Prisma server on a daily basis.

Prisma has a bi-weekly release cycle. It is recommended to keep your Prisma servers up-to-date with the latest releases. Therefore, one major maintenance task is to regularly upgrade Prisma servers to the latest version.

Relation between a Prisma server, services and databases

One Prisma server is connected to one or more databases. The data of the services running on the server can be distributed among the various databases (coming soon).

The Management API

The Management API is available on the /management path of a Prisma server (e.g. http://localhost:4466/management). It is primarily used by the Prisma CLI to deploy and manage the services that are running on the server as well as to perform database migrations.

Running Prisma servers with Docker

Prisma servers can be run using Docker. The latest Prisma Docker image can be pulled from Docker Hub using the docker pull prismagraphql/prisma command of the Docker CLI.

Here's how a Prisma server (backed by some MySQL database) is typically configured in a Docker Compose file:

version: '3'
services:
  prisma:
    image: prismagraphql/prisma:1.15
    restart: always
    ports:
      - '4466:4466'
    environment:
      PRISMA_CONFIG: | # the pipe character denotes the beginning of a string
        port: 4466
        managementApiSecret: my-secret
        databases:
          default:
            connector: mysql
            host: 192.148.24.73
            port: 3306
            user: root
            password: password42
            migrations: true

The PRISMA_CONFIG environment variable contains a (multi-line) string specifying various configuration details about the Prisma server:

• port: The port it will be running on
• managementApiSecret: The Management API secret that's used to validate incoming requests
• databases: Connection and configuration details for one or more databases that are backing the Prisma server.

Managing Prisma servers in Prisma Cloud

Prisma Cloud is a set of tools helping you to manage your Prisma servers and services. It consists of the web-based Prisma Console and parts of the Prisma CLI.

You can host a Prisma server anywhere - be it your on own infrastructure or using your favorite cloud provider (such as AWS, Google Cloud, Digital Ocean, ...). No matter where the Prisma server is hosted, you're still able to manage it through Prisma Cloud. This includes maintenance tasks like upgrading the Prisma version.

To take advantage of these benefits, you need to connect your Prisma server to Prisma Cloud.

With the cloud provider integrations, you're also able to set up your Prisma server directly through the web UI instead of fiddling around with Docker and the APIs/UIs of your cloud provider. As an example, learn how to setup a new Prisma server with a connected database on Heroku.