YAML Structure

Overview

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: Secret for securing the API endpoint.
• schema: Path to the GraphQL schema for the Prisma API.
• 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.
• hooks: Define CLI commands to be executed before/after specific actions of the Prisma CLI

The exact structure of prisma.yml is defined with JSON schema. You can find the corresponding schema definition here.

datamodel (required)

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

Type

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

Examples

The data model is defined in a file called types.graphql.

datamodel: types.graphql

The data model is defined in two files called types.graphql and enums.graphl. When 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 API.
• Workspace (only Prisma Cloud): The name of the Workspace you configured through Prisma Cloud.
• Service name: A descriptive name for your Prisma API.
• Stage: The development stage of your cluster (e.g. dev, staging, prod).

Note that the endpoint is actually required to deploy your Prisma API. However, if you don't specify it in prisma.yml before running prisma deploy, the CLI will use a wizard to prompt you with a few questions and add the endpoint to prisma.yml for you.

Type

The endpoint property expects a string.

Examples

The following example endpoint encodes this information:

• Prisma server: localhost:4466 means you're using Docker to deploy the API on your local machine (on port 4466).
• Service name: default
• Stage: default

Note: 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 this information:

• Prisma server: eu1.prisma.sh means you're using a Prisma Sandbox to deploy your Prisma API.
• Workspace: public-helixgoose-752 is a randomly generated string that identifies the Prisma Cloud workspace for your Sandbox.
• Service name: myservice
• Stage: dev

endpoint: https://eu1.prisma.sh/public-helixgoose-752/myservice/dev

The following example endpoint encodes this information:

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

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

secret (optional)

A secret is used to generate (or sign) authentication tokens (JWT). One of these authentication tokens needs to be attached to the HTTP request (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.

Read more about Database authentication here.

WARNING: If the Prisma API is deployed without a secret, it does not require authentication. This means everyone with access to the endpoint is able to send arbitrary queries and mutations and can therefore read and write to the database!

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}

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.
• 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 event 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_ENDPOINT_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 two kinds of files:
  • either a path to a .graphql file with GraphQL operations
  • or 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). 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

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 match the names of the currently availale 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.yml
3. Invoke code generation as specified in .graphqlconfig.yml

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

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

projects:
  prisma:
    schemaPath: generated/prisma.graphql
    extensions:
      prisma: prisma.yml
      prepare-binding:
        output: generated/prisma.ts
        generator: prisma-ts