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.
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
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
secretis specified, the service does not require authentication. Learn more.
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.
- 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
- 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.
prod, ...). If no service stage is specified, it defaults to
Putting it all together, the endpoint for a service might look as follows:
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.
http://localhost:4466/default/default can always be written as
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: