prisma.yml

Overview

prisma.yml is the root configuration file for a Prisma service. Every Prisma service is defined by exactly one prisma.yml. You can think of prisma.yml as a template for one Prisma service.

prisma.yml specifies a number of properties about the Prisma service, e.g.:

• the service's endpoint (includes name and stage of the service)
• how and where the Prisma client should be generated
• the service secret used to authenticate requests made to the service's API
• the location of the data model file(s)
• hooks that specify shell commands to be executed at some point in the deployment process

Examples

Minimal example

The most minimal version of a valid prisma.yml needs to contain at least two properties:

• datamodel
• endpoint

To be able to specify an endpoint, you need to have access to a Prisma server. If you don't have access to a Prisma server, you can omit the endpoint from prisma.yml and run prisma deploy only with the datamodel property. In that case, a CLI wizard guides you through the process of creating a local Prisma server or lets you deploy to a Demo server in Prisma Cloud. It then writes the endpoint into prisma.yml for you before the service gets deployed:

datamodel: datamodel.prisma

Standard example

The most commonly used properties in prisma.yml are:

• datamodel
• endpoint
• secret
• hooks
• generate

Here's what a standard prisma.yml with these properties might look like:

datamodel: datamodel.prisma
endpoint: http://localhost:4466/myservice/dev
secret: mysecret42

generate:
  - generator: javascript-client
    output: ./generated/prisma

hooks:
  post-deploy:
    - prisma generate

Exhaustive example

Here's an example where all properties of prisma.yml are being used:

# This service is based on the type definitions in the two files
# databasetypes.graphql` and `database/enums.graphql`
datamodel:
  - database/types.graphql
  - database/enums.graphql

# The endpoint represents the HTTP endpoint for your Prisma API.
# It encodes several pieces of information:
# * Prisma server (`localhost:4466` in this example)
# * Service name (`myservice` in this example)
# * Stage (`dev` in this example)
# NOTE: When service name and stage are set to `default`, they
# can be omitted.
# Meaning http://myserver.com/default/default can be written
# as http://myserver.com.
endpoint: http://localhost:4466/myservice/dev

# The secret is used to create JSON web tokens (JWTs). These
# tokens need to be attached in the `Authorization` header
# of HTTP requests made against the Prisma endpoint.
# WARNING: If the secret is not provided, the Prisma API can
# be accessed without authentication!
secret: mysecret123

# Generate a Prisma client in JavaScript and store in
# a folder called `generated/prisma`
generate:
  - generator: javascript-client
    output: ./generated/prisma

# A "post-deployment" hook that first regenerates
# the Prisma client.
hooks:
  post-deploy:
    - prisma generate

# This service has one event subscription configured. The
# corresponding subscription query is located in `database/subscriptions/welcomeEmail.graphql`.
# When the subscription fires, the specified `webhook`
# is invoked via HTTP.
subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail
      headers:
        Authorization: ${env:MY_ENDPOINT_SECRET}

# Points to a `.graphql` file containing GraphQL
# operations that will be executed when initially
# deploying a service.
seed:
  import: database/seed.graphql

# This service only defines one custom variable that's
# referenced in the `webhook` of the `subscription`
custom:
  serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev

This prisma.yml expects the following file structure:

.
│ .graphqlconfig
├── prisma.yml
└── database
    ├── subscriptions
    │   └── welcomeEmail.graphql
    ├── types.graphql
    └── enums.graphql

Using variables

Variables allow you to dynamically replace configuration values in your prisma.yml. They are especially useful when providing secrets for your service and when you have a multi-staging developer workflows.

To use variables inside prisma.yml, you need to reference the values enclosed in ${} brackets:

yamlKeyXYZ: ${variableSource}

A variable source can be either of the following two options:

• A recursive self-reference to another value inside the same service (often used in combination with the custom property)
• An environment variable

You can only use variables in property values - not in property keys. So you can't use variables to e.g. generate dynamic logical IDs in the custom resources section for example.

Recursive self-reference

You can recursively reference other property values that live inside the same prisma.yml file.

When using a recursive self-reference as a variable, the value that you put into the bracket is composed of:

• the prefix self:
• (optional) the path to the referenced property; if no path is specified, the value of the variable will be the entire YAML file.

subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail

custom:
  serverlessEndpoint: example.org

This works for any property inside prisma.yml, not just custom.

Environment variable

You can reference environment variables inside the service definition file.

When using an environment variable, the value that you put into the bracket is composed of:

• the prefix env:
• the name of the environment variable

In the following example, an environment variable is referenced to specify the URL and the authentication token for a webhook:

subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://example.org/sendWelcomeEmail
      headers:
        Authorization: ${env:MY_TOKEN}

Reference

Root properties

The service definition file prisma.yml has the following root properties:

• datamodel (required): Type definitions for database models, relations, enums and other types.
• endpoint: HTTP endpoint for the Prisma API. Can be omitted to prompt CLI deployment wizard.
• secret: Service secret for securing the API endpoint.
• hooks: Define CLI commands to be executed before/after specific actions of the Prisma CLI.
• subscriptions: Configuration of subscription webhooks.
• seed: Points to a file containing mutations for data seeding.
• custom: Used to provide variables which can be referenced elsewhere in prisma.yml.

The exact structure of prisma.yml is defined with JSON schema. You can find the corresponding schema definition here. The JSON schem definition also allows to elevate your tooling and let your code editors and IDEs help you with the right structure of prisma.yml.

datamodel (required)

The datamodel points to one or more .graphql-files containing model definitions written in GraphQL SDL. If multiple files are provided, the CLI simply concatenates their contents at deployment time.

Type

The datamodel property expects a string or a list of strings.

Examples

The datamodel is defined in a file called types.graphql.

datamodel: types.graphql

The datamodel is defined in two files called types.graphql and enums.graphl. When the service gets deployed, the contents of both files will be concatenated by the CLI.

datamodel:
  - types.graphql
  - enums.graphql

endpoint (optional)

The HTTP endpoint for your Prisma API is composed of the following components:

• Prisma server: The server that will host your Prisma service.
• Workspace (only for Demo servers in Prisma Cloud): The name of the Workspace you configured through Prisma Cloud.
• Service name: A descriptive name for your Prisma servic e.
• Service stage: The development stage of your cluster (e.g. dev, staging, prod).

Note that the endpoint is actually required to deploy your Prisma service. However, if you don't specify it in prisma.yml before running prisma deploy, the CLI prompts you with a wizard to help you figure out a Prisma server as deployment target and subsequently writes the endpoint into prisma.yml for you.

Type

The endpoint property expects a string.

Examples

The following example endpoint encodes the following information:

• Prisma server: http://localhost:4466 means you're running a Prisma server locally on your machine (e.g. using Docker).
• Service name: default
• Stage: default

When service name and stage are both set to default, they can be omitted and will be inferred by Prisma. This means this example endpoint is equivalent to writing: http://localhost:4466/

endpoint: http://localhost:4466/default/default

The following example endpoint encodes the following information:

• Prisma server: https://eu1.prisma.sh means you're using a Prisma Demo server as a deployment target for your Prisma service.
• Workspace: jane-doe is the name of your Prisma Cloud workspace.
• Service name: myservice
• Stage: dev

endpoint: https://eu1.prisma.sh/jane-doe/myservice/dev

The following example endpoint encodes the following information:

• Prisma server: http://my-pr-Publi-1GXX8QUZU3T89-413349553.us-east-1.elb.amazonaws.com means you're using a Prisma server hosted on AWS to deploy your Prisma service.
• Service name: cat-pictures
• Stage: prod

endpoint: http://my-pr-Publi-1GXX8QUZU3T89-413349553.us-east-1.elb.amazonaws.com/cat-pictures/prod

secret (optional)

The service secret is used to generate (or sign) authentication tokens (JWT). One of these authentication tokens needs to be attached to the HTTP requests made against the Prisma API exposes by the service (in the Authorization header field).

A secret must follow these requirements:

• must be utf8 encoded
• must not contain spaces
• must be at most 256 characters long

Note that it's possible to encode multiple secrets in this string, which allows for smooth secret rotations.

Type

The secret property expects a string (not a list of strings). If you want to specify multiple secrets, you need to provide them as a comma-separated list (spaces are ignored), but still as a single string value.

Examples

Define one secret with value moo4ahn3ahb4phein1eingaep.

secret: moo4ahn3ahb4phein1eingaep

Define three secrets with values myFirstSecret, SECRET_NUMBER_2 and 3rd-secret. Note that the spaces before the second secret are ignored.

secret: myFirstSecret,    SECRET_NUMBER_2,3rd-secret

Use the value of the MY_SECRET environment variable as the secret(s).

secret: ${env:MY_SECRET}

generate (optional)

The generate property is used to specify how and where a Prisma client (or other files) should be generated.

The following generators are built-into the Prisma CLI:

• Prisma client in JavaScript: javascript-client
• Prisma client in TypeScript: typescript-client
• Prisma client in Flow: flow-client
• Prisma client in Go: go-client
• GraphQL schema of the Prisma API: graphql-schema

Type

The generate property expects a list of objects. There are two properties on these objects:

• generator: One of the available generators from the list above.
• output: Specifies where the generated files should be located.

Examples

generate:
  - generator: javascript-client
    output: ./generated/prisma
  - generator: graphql-schema
    output: ./generated/prisma

hooks (optional)

The hooks property is used to define terminal commands which will be executed by the Prisma CLI before or after certain commands.

The following hooks are currently available:

• post-deploy: Will be invoked after the prisma deploy command

Type

The hooks property expects an object. The properties of that object match the names of the currently available hooks.

Examples

Here is an example that performs three tasks after prisma deploy was executed:

1. Print "Deployment finished"
2. Download the GraphQL schema for the db project specified in .graphqlconfig
3. Invoke code generation as specified in .graphqlconfig

hooks:
  post-deploy:
    - echo "Deployment finished"
    - graphql get-schema --project db
    - graphql codegen

Note that this setup assumes the availability of a .graphqlconfig looking similar to this:

projects:
  db:
    schemaPath: generated/prisma.graphql
    extensions:
      prisma: prisma.yml
      codegen:
        - generator: prisma-binding
          language: typescript
          output:
            binding: src/generated/prisma.ts

subscriptions (optional)

The subscriptions property is used to define all the subscription webhooks for your Prisma service. A subscription needs (at least) two pieces of information:

• a subscription query that defines upon which event a function should be invoked and what the payload looks like
• the URL of a webhook which is invoked via HTTP once the event happens
• (optionally) a number of HTTP headers to be attached to the request that's sent to the URL

Type

The subscriptions property expects an object with the following properties:

• query (required): The file path to the subscription query (stored in a .graphql-file).
• webhook (required): Information (URL and optionally HTTP headers) about the webhook to be invoked. If there are no headers, you can provide the URL to this property directly (see first example below). Otherwise, webhook takes another object with properties url and headers (see second example below).

Examples

Specify one subscription without HTTP headers.

subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail

Specify one event subscription with two HTTP headers.

subscriptions:
  sendWelcomeEmail:
    query: database/subscriptions/sendWelcomeEmail.graphql
    webhook:
      url: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail
      headers:
        Authorization: ${env:MY_SECRET}
        Content-Type: application/json

seed (optional)

Database seeding is a standardised way to populate a service with test data.

Type

The seed property expects an object, with either one of two sub-properties:

• import: Instructions to import data when seeding a service. You can refer to either of two kinds of files:

  • A path to a .graphql file with GraphQL operations.
  • A path to a .zip file that contains a data set in Normalized Data Format (NDF)
• run: Shell command that will be executed when seeding a service. This is meant for more complex seed setups that are not covered by import.

Seeds are implicitly executed when deploying a service for the first time (unless explicitly disabled using the --no-seed flag on prisma deploy). Track this feature request for additional seeding workflows.

Examples

Refer to a .graphql file containing seeding mutations:

seed:
  import: database/seed.graphql

Refer to a .zip file with a data set in NDF:

seed:
  import: database/backup.zip

Run a Node script when seeding:

seed:
  run: node script.js

custom (optional)

The custom property lets you specify any sorts of values you want to reuse elsewhere in your prisma.yml. It thus doesn't have a predefined structure. You can reference the values using variables with the self variable source, e.g.: ${self:custom.myVariable}.

Type

The custom property expects an object. There are no assumptions about the shape of the object.

Examples

Define two custom values and reuse them in the definition of the event subscription.

custom:
  serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev
  subscriptionQueries: database/subscriptions/

subscriptions:
  sendWelcomeEmail:
    query: ${self:custom.subscriptionQueries}/sendWelcomeEmail.graphql
    webhook: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail