add binary/platform docs for the Photon JS generator

docs/core/generators/photonjs.md

@@ -4,36 +4,79 @@ The Photon JS generator can be used in a [Prisma schema file](../../prisma-schem
 
 ## Node.js requirements
 
-The `photonjs` generator targets [ES2016](https://exploringjs.com/es2016-es2017/) & [Node.js 8.x +](https://nodejs.org/en/download/releases/). 
+The generated data access code of the `photonjs` generator targets [ES2016](https://exploringjs.com/es2016-es2017/) & [Node.js 8.x +](https://nodejs.org/en/download/releases/). 
 
-## Compilation target (query engine)
+## Specifying the right platform for Photon JS
 
-Photon JS depends on a query engine that's running as a binary right next to your application. You can set the compilation target of the binary by adding the `target` field to the `photonjs` generator block:
+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](./codegen-and-node-setup.md) 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](https://github.com/prisma/specs/blob/master/binaries/Readme.md).
+
+### 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](#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](#generator-options) are passed to the `photonjs` generator in your [Prisma schema file](../prisma-schema-file.md), 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`:
 
 ```prisma
-generator photonjs {
+generator photon {
   provider = "photonjs"
-  target   = "darwin"
+  platforms = ["native"]
 }
 ```
 
-Note that `darwin` is the default `target`. Here's a list of supported platforms and their targets:
+has the **same behaviour** as:
+
+```prisma
+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](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/darwin/prisma-query-engine.gz)                  | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/darwin/prisma-migration-engine.gz)                  | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/darwin/prisma-fmt.gz)                  |
+| windows                 | (Local development) |                 | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/windows/prisma-query-engine.gz)                 | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/windows/prisma-migration-engine.gz)                 | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/windows/prisma-fmt.gz)                 |
+| linux-glibc-libssl1.0.1 | Lambda Node 8, ZEIT |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.0.1/prisma-query-engine.gz) | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.0.1/prisma-migration-engine.gz) | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.0.1/prisma-fmt.gz) |
+| linux-glibc-libssl1.0.2 | Lambda (Node 10)    |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.0.2/prisma-query-engine.gz) | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.0.2/prisma-migration-engine.gz) | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.0.2/prisma-fmt.gz) |
+| linux-glibc-libssl1.1.0 | ?                   |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.1.0/prisma-query-engine.gz) | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.1.0/prisma-migration-engine.gz) | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.1.0/prisma-fmt.gz) |
+| linux-glibc-libssl1.1.1 | ?                   |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.1.1/prisma-query-engine.gz) | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.1.1/prisma-migration-engine.gz) | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-glibc-libssl1.1.1/prisma-fmt.gz) |
+| linux-musl-libssl1.0.1  | Alpine              |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.0.1/prisma-query-engine.gz)  | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.0.1/prisma-migration-engine.gz)  | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.0.1/prisma-fmt.gz)  |
+| linux-musl-libssl1.0.2  | Alpine              |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.0.2/prisma-query-engine.gz)  | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.0.2/prisma-migration-engine.gz)  | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.0.2/prisma-fmt.gz)  |
+| linux-musl-libssl1.1.0  | Alpine              |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.1.0/prisma-query-engine.gz)  | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.1.0/prisma-migration-engine.gz)  | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.1.0/prisma-fmt.gz)  |
+| linux-musl-libssl1.1.1  | Alpine              |        ✓        | [prisma-query-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.1.1/prisma-query-engine.gz)  | [prisma-migration-engine](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.1.1/prisma-migration-engine.gz)  | [prisma-fmt](https://s3-eu-west-1.amazonaws.com/prisma-native/alpha/latest/linux-musl-libssl1.1.1/prisma-fmt.gz)  |
+
+### 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.
+
+```prisma
+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"
+}
+```
 
-|  **Platform** | **Target** | 
-| :---:  | :---: |
-| Mac OS | `darwin` (default) |
-| Ubuntu, Centos, CodeSandbox	  | `linux-glibc` |
-| Alpine | `linux-musl` |
-| Windows  | `windows` |
-| Lambda Node 8, ZEIT Now | `linux-glibc-libssl1.0.1` |
-| Lambda Node 10  | `linux-glibc-libssl1.0.2` |
-| Heroku | _coming soon_ |
-| Cloudflare Workers | _coming soon_ |
-| Google Cloud Functions | User's choice |
 
-Therefore, when deploying your Photon-based application to production, you need to ensure that you're specifying the right _compilation target_ for the binary.
 
-> **ATTENTION**: The `target` field on the `generator` block is not yet implemented. You can track the progress of the implementation [on GitHub](https://github.com/prisma/prisma2/issues/97). You can also check ou the [specification](https://github.com/prisma/specs/tree/master/binary-workflows) for more details.
 
 ## Example
 

docs/photon/codegen-and-node-setup.md

@@ -8,7 +8,7 @@ Using `node_modules/@generated` as the default `output` for Photon JS is still e
 
 ## Overview
 
-`prisma2 generate` uses the [generators](https://github.com/prisma/prisma2/blob/master/docs/prisma-schema-file.md#generators-optional) specified in the [Prisma schema file](../prisma-schema-file.md) and generates the respective packages on the respective output path(s).
+`prisma2 generate` uses the [generators](../prisma-schema-file.md#generators-optional) specified in the [Prisma schema file](../prisma-schema-file.md) and generates the respective packages on the respective output path(s).
 
 The default Photon JS generator can be specified as follows in your schema file:
 

docs/photon/deployment.md

@@ -1,39 +1,16 @@
 # Deployment
 
-Photon JS depends on a query engine that's running as a binary right next to your application. This binary needs to be executable in your production environment. 
+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.
 
-Therefore, when deploying your Photon-based application to production, you need to ensure that you're specifying the right [compilation target](../core/generators/photonjs.md#compilation-target-query-engine) for the binary.
+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](./codegen-and-node-setup.md) you specified). 
 
-You can determine the compilation target of the binary by adding the `target` field to the `photonjs` generator block:
-
-```prisma
-generator photonjs {
-  provider = "photonjs"
-  target   = "darwin"
-}
-```
-
-Note that `darwin` is the default `target`. Here's a list of supported platforms and their targets:
-
-|  **Platform** | **Target** | 
-| :---  | :--- |
-| Mac OS | `darwin` (default) |
-| Ubuntu <br /> Centos <br /> CodeSandbox	  | `linux-glibc` |
-| Alpine | `linux-musl` |
-| Windows  | `windows` |
-| Lambda Node 8 <br /> ZEIT Now | `linux-glibc-libssl1.0.1` |
-| Lambda Node 10  | `linux-glibc-libssl1.0.2` |
-| Heroku | _coming soon_ |
-| Cloudflare Workers | _coming soon_ |
-| Google Cloud Functions | User's choice |
-
-> **ATTENTION**: The `target` field on the `generator` block is not yet implemented. You can track the progress of the implementation [on GitHub](https://github.com/prisma/prisma2/issues/97). You can also check ou the [specification](https://github.com/prisma/specs/tree/master/binary-workflows) for more details.
+**IMPORTANT**: To ensure the query engine binary is compatible with your production environment, you have to [specify the right platform for Photon JS](#specifying-the-right-platform-for-photon-js).
 
 ## Hosting providers
 
 ### ZEIT Now
 
-You can deploy your "Photon JS"-based application to [ZEIT Now](https://zeit.co/now). 
+You can deploy your "Photon JS"-based application to [ZEIT Now](https://zeit.co/now).
 
 When deploying to ZEIT Now, you must configure the following in your `now.json`:
 
@@ -63,4 +40,4 @@ Here is an example `now.json`:
 }
 ```
 
-You can find an example for a ZEIT Now deployment [here](https://github.com/prisma/photonjs/tree/master/examples/javascript/now).
+You can find an example for a ZEIT Now deployment [here](https://github.com/prisma/photonjs/tree/master/examples/javascript/now). 

docs/prisma-schema-file.md

@@ -132,7 +132,6 @@ datasource mongo {
 
 A generator configures what data source clients are generated and how they're generated. Language preferences and configuration will go in here.
 
-
 #### Fields
 
 | Name | Required | Type | Description |