Prisma under the Hood

Prisma & GraphQL

Prisma uses GraphQL as a universal database abstraction, meaning it turns your database into a GraphQL API and enables you to:

• Read and write to your database using GraphQL queries and mutations
• Receive realtime updates for database events using GraphQL subscriptions
• Perform migrations and model your data using GraphQL SDL

When a Prisma client makes a request to a Prisma server, it actually generates GraphQL operations which are being sent to Prisma's GraphQL API. The client then transforms the GraphQL response into the expected result structure and returns it from the method that was invoked.

Prisma services

The GraphQL mapping for a database is provided by a Prisma service. Each service provides its own GraphQL CRUD mapping for a database. The GraphQL API is auto-generated and provides CRUD operations for each model in the service's datamodel.

Prisma services are running on Prisma servers. Prisma servers can be configured to host multiple Prisma services.

A Prisma service is configured using two components:

• prisma.yml: The root configuration file for a Prisma service (includes the service's endpoint, the service secret, the path to the datamodel file, ...)
• Datamodel: In the datamodel, you define models which Prisma uses to generate the GraphQL API for your database. It's using the declarative GraphQL SDL syntax and is typically stored in a file called datamodel.prisma.

A minimal prisma.yml looks similar to this:

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

These are the configuration properties it contains:

• endpoint: The HTTP endpoint of the Prisma server to which the service should be deployed. This endpoint exposes the service's Prisma API.
• datamodel: The file path to the datamodel which serves as foundation for the GraphQL CRUD/realtime API.
• secret: The service secret is used to secure the service's GraphQL API endpoint using JWT-based authentication. If no secret is specified, the service does not require authentication. Learn more.

Learn more about the endpoints of Prisma services

Each Prisma service has exactly one endpoint. The endpoint is composed of the following components:

• Host: The host of your Prisma server (incl. protocol and port), e.g. https://example.com:4466
• Service name: The first path component of the endpoint URL is a name for the Prisma service, e.g. my-service. If no service name is specified, it defaults to default.
• Service stage: The second path component of the endpoint URL is the stage of the service. Like the service name, this can be a random string - but you commonly use terms that describe deployment environments (e.g. dev, staging, prod, ...). If no service stage is specified, it defaults to default.

Putting it all together, the endpoint for a service might look as follows: https://example.com:4466/my-service/dev

Prisma services can also be deployed to endpoints without any path components (e.g. http://localhost:4466), in these cases Prisma uses default for service name and stage.

This means http://localhost:4466/default/default can always be written as http://localhost:4466.

Another exception for the endpoint structure are Demo servers on Prisma cloud that have an additional path component before the service name and stage. This corresponds to the name of your workspace. For example, if your workspace is called john-doe, the endpoint might look as follows: http://prisma-eu1.sh/john-doe/my-service/dev