prisma-info.md

Data model vs Prisma database schema

When starting out with GraphQL and Prisma, the amount of .graphql-files you're working with can be confusing. Yet, it's crucial to understand what the role of each of them is.

Looking only at Prisma, there are two .graphql-files that are relevant:

• The data model containing the model definitions for your service's APIs, typically called datamodel.graphql.
• The Prisma database schema defining the actual CRUD/realtime operations of the service's API, typically called prisma.graphql.

The Prisma database database schema is generated based on the data model:

The illustration shows a simplified version of the generated Prisma database schema, you can find the full schema here.

The data model

The data model is written manually by the developers of the Prisma service. It defines the models and structures the developer wants to use in their API.

Strictly speaking, the data model is not a valid GraphQL schema because it does not contain any of GraphQL's root types (Query, Mutation, Subscription) and therefore does not define any API operations.

The data model only serves as foundation for the generation of the actual GraphQL schema that defines the GraphQL API of your Prisma service.

The Prisma database schema

The Prisma database schema can be dowloaded from a Prisma service using the get-schema command of the GraphQL CLI or via an introspection query made directly against the service's API.

Downloading the Prisma database schema using the service's endpoint

Assuming http://localhost:4466/myservice/dev is the endpoint of your service, this is the command you need to run in order to download the Prisma database schema and store it in a file called prisma.graphql:

graphql get-schema --endpoint http://localhost:4466/myservice/dev --output prisma.graphql --no-all

Downloading the Prisma database schema using graphql-config and a post-deployment hook

In real-world development setups, you want to keep your local Prisma database schema in sync with the service's API and ensure it gets updated upon every deploy of your Prisma service. That's what you can a use a post-deployment hook for.

This is what a .graphqlconfig.yml and prisma.yml might look like in such as setups:

prisma.yml

datamodel: datamodel.graphql
endpoint: http://localhost:4466/myservice/dev
secret: mysecret
hooks:
  post-deploy:
    - graphql get-schema --project db

.graphqlconfig.yml

project:
  db:
    schemaPath: prisma.graphql
    extensions:
      prisma: prisma.yml

Now, after prisma deploy is executed, the Prisma CLI invokes the post-deploy hook and runs the specified graphql get-schema --project db command. This looks up the db project in .graphqlconfig.yml (which is the API of the Prisma service), downloads its schema and stores it in prima.graphql (as specified in the schemaPath property in .graphqlconfig).

A note on the application schema

If you've already looked into building your own GraphQL server based on Prisma, you might have come across another .graphql-file which is referred to as your application schema (typically called schema.graphql or app.graphql).

This is a valid GraphQL schema (meaning it contains the Query, Mutation and Subscription root types) that defines the API of your application layer. In contrast to Prisma's generic CRUD API, the application layer's API should expose domain-specific operations that are tailored to the needs of your client applications.

The application layer uses Prisma as a data access layer and delegates incoming requests to the service's Prisma API where they're actually resolved against the database.

You typically don't redefine your model definitions in the application schema. Instead, you import them using graphql-import:

# import Post from "prisma.graphql"

type Query {
  feed: [Post!]!
}

graphql-import currently uses SDL comments to import types. In the future, there might be an official import syntax for SDL as has already been discussed in the GraphQL working group.

Learn more about the application schema and building GraphQL servers with Prisma here.