Skip to content

Latest commit

 

History

History
121 lines (85 loc) · 10.8 KB

photonjs.md

File metadata and controls

121 lines (85 loc) · 10.8 KB
Raw

Photon JS generator

The Photon JS generator can be used in a Prisma schema file to generate the Photon database client for Node.js and TypeScript. The API of the generated client is documented here.

Node.js requirements

The generated data access code of the photonjs generator targets ES2016 which means you need Node.js 8.x or newer to be able to use it.

Specifying the right platform for Photon JS

Photon JS depends on a query engine that's running as a binary on the same host as your application. When deploying your Photon-based application to production, you need to ensure that the binary used by Photon can run in your production environment, i.e. it needs to be compatible with the runtime of your deployment provider.

The query engine binary is downloaded when you run prisma2 generate, it is then stored alongside the generated Photon code inside node_modules/@generated (or the custom output path you specified). This section explains how you can determine which binary should be downloaded when prisma2 generate is executed to ensure compatibility at runtime.

You can read more about this topic in the specification.

Terminology

A platform is a managed environment. This includes deployment providers such as AWS Lambda, Google Cloud Functions and Netlify as well as operating systems such as Mac OS and Windows. A platform represents a runtime environment, i.e. the concrete version of the operating system and the installed packages available at runtime.

Generator options

To determine the platform Photon is running on, you can provide two options to the photonjs generator:

Name Required Description Purpose
platforms No An array of binaries that are required by the application. Either a file path to a binary, a package name from the available binaries or the special value "native". Default: ["native"]. Declarative way to download the required binaries.
pinnedPlatform Only if platforms contains a file path to a binary A string that points to the name of an object in the platforms field (typically an environment variable). Requires the platforms options to be a non-empty array. Declarative way to define which binary to use at runtime.

Default: The native platform

When no generator options are passed to the photonjs generator in your Prisma schema file, the Prisma CLI will download the binary for the operating system on which prisma2 generate was executed. The following two configurations are therefore equivalent, because ["native"] is the default value for platforms:

generator photon {
  provider = "photonjs"
  platforms = ["native"]
}

has the same behaviour as:

generator photon {
  provider = "photonjs"
}

In both cases, the Prisma CLI determines the current operating system where prisma2 generate was invoked and downloads the compatible binary to store it in node_modules.

Available binaries

Package Known Platforms Needs libssl? Query Engine Migration Engine Prisma Format
darwin (Local development) prisma-query-engine prisma-migration-engine prisma-fmt
windows (Local development) prisma-query-engine prisma-migration-engine prisma-fmt
linux-glibc-libssl1.0.1 Lambda Node 8, ZEIT ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-glibc-libssl1.0.2 Lambda (Node 10) ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-glibc-libssl1.1.0 ? ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-glibc-libssl1.1.1 ? ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-musl-libssl1.0.1 Alpine ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-musl-libssl1.0.2 Alpine ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-musl-libssl1.1.0 Alpine ✓ prisma-query-engine prisma-migration-engine prisma-fmt
linux-musl-libssl1.1.1 Alpine ✓ prisma-query-engine prisma-migration-engine prisma-fmt

Example

This example shows the configuration of a Photon JS generator for local development (native can resolve to any other platform) and AWS Lambda (Node 10) as the production environment.

generator photon {
    provider = "photonjs"
    platforms = ["native", "linux-glibc-libssl1.0.2"] // For Lambda (Node 10) 
    pinnedPlatform = env("PLATFORM")                  // Local: "native"; In production: "linux-glibc-libssl1.0.2"
}

Example

To invoke the generator, you need to add a generator block to your schema file and specify the photonjs provider:

generator js {
  provider = "photonjs"
}

// ... the file should also contain connectors and a data model definition

Once added, you can invoke the generator using the following command:

prisma2 generate

It will then store the generated Photon API in the specified ./generated/photon directory. Learn more about the generated Photon API.

Mapping types from the data model

The Photon JS generator provides the following mapping from data model scalar types to JavaScript/TypeScript types:

Type JS / TS
String string
Boolean boolean
Int number
Float number
Datetime Date

Reserved model names

When generating Photon JS based on your data model definition, there are a number of reserved names that you can't use for your models. Here is a list of the reserved names:

  • String
  • Int
  • Float
  • Subscription
  • DateTime
  • WhereInput
  • IDFilter
  • StringFilter