server-side-subscriptions

Server Side Subscription

This example demonstrates subscriptions property available to us in prisma.yml.

Get started

Note: prisma is listed as a development dependency and script in this project's package.json. This means you can invoke the Prisma CLI without having it globally installed on your machine (by prefixing it with yarn), e.g. yarn prisma deploy or yarn prisma playground. If you have the Prisma CLI installed globally (which you can do with npm install -g prisma), you can omit the yarn prefix.

1. Download the example & install dependencies

Clone the Prisma monorepo and navigate to this directory or download only this example with the following command:

curl https://codeload.github.com/graphcool/prisma/tar.gz/master | tar -xz --strip=2 prisma-master/examples/server-side-subscriptions

Next, navigate into the downloaded folder and install the NPM dependencies:

cd server-side-subscriptions
yarn install

2. Deploy the Prisma database service

You can now deploy the Prisma service (note that this requires you to have Docker installed on your machine - if that's not the case, follow the collapsed instructions below the code block):

yarn prisma deploy

I don't have Docker installed on my machine

To deploy your service to a public cluster (rather than locally with Docker), you need to perform the following steps:

1. Remove the cluster property from prisma.yml
2. Run yarn prisma deploy
3. When prompted by the CLI, select a public cluster (e.g. prisma-eu1 or prisma-us1)
4. Replace the endpoint in index.js with the HTTP endpoint that was printed after the previous command

3. subscriptions property of prisma.yml

The subscriptions property is used to implement event-based business logic using POST endpoints.

Here is how we have defined the subscription in prisma.yml for this example.

subscriptions:
  welcomeNewUser:
    query: subscription.graphql
    webhook: http://ptsv2.com/t/prisma/post

Let us assume that we want to send a welcome email to new user. We will define that subscription as above.

welcomeNewUser is the name of the subscription.

query: subscription.graphql is the file that contains the subscription query. Note that we are listening to the "CREATED" mutation events.

subscription {
  user(where: { mutation_in: [CREATED] }) {
    mutation
    node {
      id
      name
    }
  }
}

webhook: http://ptsv2.com/t/prisma/post is a mock endpoint consuming this query. On creation of a new User Prisma service will call this endpoint with Post data selected in the subscription query.

3. Testing the server side subscription

The best way to test this subscription logic is to create a user and observe the mock POST endpoint.

Open a Playground

You can either start the desktop app via

yarn playground

Or you can open a Playground by navigating to http://localhost:4466/server-side-subscription in your browser.

Run the following mutation to create a user

mutation M {
  createUser(data: { name: "Graphcool" }) {
    id
    name
  }
}

Observe the mock POST endpoint

http://ptsv2.com/t/prisma

You will notice a dump of your request on this page.