Prisma GraphQL APIPrisma Bindings

Reference

Install

npm install --save prisma-binding

Example

Consider the following data model for your Prisma service:

type User {
  id: ID! @unique
  name: String
}

If you instantiate Prisma (i.e. a Prisma binding instance) based on this service, you'll be able to send the following queries/mutations:

// Instantiate `Prisma` based on concrete service
const prisma = new Prisma({
  typeDefs: 'schemas/database.graphql',
  endpoint: 'https://api.graph.cool/simple/v1/my-prisma-service'
  secret: 'my-super-secret-secret'
})

// Retrieve `name` of a specific user
prisma.query.user({ where { id: 'abc' } }, '{ name }')

// Retrieve `id` and `name` of all users
prisma.query.users(null, '{ id name }')

// Create new user called `Sarah` and retrieve the `id`
prisma.mutation.createUser({ data: { name: 'Sarah' } }, '{ id }')

// Update name of a specific user and retrieve the `id`
prisma.mutation.updateUser({ where: { id: 'abc' }, data: { name: 'Sarah' } }, '{ id }')

// Delete a specific user and retrieve the `name`
prisma.mutation.deleteUser({ where: { id: 'abc' } }, '{ id }')

Under the hood, each of these function calls is simply translated into an actual HTTP request against your Prisma service (using graphql-request).

The API also allows to ask whether a specific node exists in your Prisma database:

// Ask whether a post exists with `id` equal to `abc` and whose
// `author` is called `Sarah` (return boolean value)
prisma.exists.Post({
  id: 'abc',
  author: {
    name: 'Sarah',
  },
})

API

Prisma

constructor

constructor(options: PrismaOptions): Prisma

The PrismaOptions type has the following fields:

  • schemaPath (required, string): File path to the schema definition of your Prisma service (typically a file called prisma.graphql)
  • endpoint (required, string): The endpoint of your Prisma service
  • secret (optional, string): The secret of your Prisma service
  • fragmentReplacements (optional, FragmentReplacements): A list of GraphQL fragment definitions, specifying fields that are required for the resolver to function correctly
  • debug (optional, boolean): Log all queries/mutations to the console; default: false

query & mutation

query and mutation are public properties on your Prisma instance (see also the GraphQL Binding documentation for more info). They both are of type Query and expose a number of auto-generated delegate resolver functions that are named after the fields on the Query and Mutation types in your Prisma database schema.

Each of these delegate resolvers in essence provides a convenience API for sending queries/mutations to your Prisma service, so you don't have to spell out the full query/mutation from scratch and worry about sending it over HTTP. This is all handled by the delegate resolver function under the hood.

Delegate resolver have the following interface:

(args: any, info: GraphQLResolveInfo | string): Promise<T>

The input arguments are used as follows:

  • args: An object carrying potential arguments for the query/mutation
  • info: An object representing the selection set of the query/mutation, either expressed directly as a string or in the form of GraphQLResolveInfo (you can find more info about the GraphQLResolveInfo type here)

The generic type T corresponds to the type of the respective field.

exists

exists also is a public property on your Prisma instance. Similar to query and mutation, it also exposes a number of auto-generated functions. However, it exposes only a single function per type. This function is named according to the root field that allows the retrieval of a single node of that type (e.g. User for a type called User). It takes a where object as an input argument and returns a boolean value indicating whether the condition expressed with where is met.

This function enables you to easily check whether a node of a specific type exists in your Prisma database.

request

The request method lets you send GraphQL queries/mutations to your Prisma service. The functionality is identical to the auto-generated delegate resolves, but the API is more verbose as you need to spell out the full query/mutation. request uses graphql-request under the hood.

Here is an example of how it can be used:

const query = `
  query ($userId: ID!){
    user(id: $userId) {
        id
      name
    }
  }
`

const variables = { userId: 'abc' }

prisma.request(query, variables).then(result => console.log(result))
// sample result:
// {"data": { "user": { "id": "abc", "name": "Sarah" } } }