Env vars for custom binaries (#538)

* Added illustrations Fixed some typos * Style guide wording * Link fixes * Enum binary * Engine binaries * Update content/02-understand-prisma/05-under-the-hood.mdx * Update content/02-understand-prisma/05-under-the-hood.mdx * Update content/02-understand-prisma/05-under-the-hood.mdx Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> * Update content/02-understand-prisma/05-under-the-hood.mdx Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> * Update content/02-understand-prisma/05-under-the-hood.mdx Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> * Update content/02-understand-prisma/05-under-the-hood.mdx Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> * Update content/02-understand-prisma/05-under-the-hood.mdx Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> * Client constructor (#480) * Added illustrations Fixed some typos * Client constructor page * Constructor docs * Fixed index * Added # to page * Update content/03-reference/01-tools-and-interfaces/02-prisma-client/02-constructor.mdx Co-authored-by: Tim Suchanek <Tim.Suchanek@gmail.com> * Joël fixes * Update content/03-reference/01-tools-and-interfaces/02-prisma-client/02-constructor.mdx * Update 02-constructor.mdx * Update content/03-reference/01-tools-and-interfaces/02-prisma-client/02-constructor.mdx Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> Co-authored-by: Tim Suchanek <Tim.Suchanek@gmail.com> Co-authored-by: Joël Galeran <Jolg42@users.noreply.github.com> Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> * Fixes * Fixes * Fixes Co-authored-by: Joël Galeran <Jolg42@users.noreply.github.com> Co-authored-by: Jan Piotrowski <piotrowski+github@gmail.com> Co-authored-by: Tim Suchanek <Tim.Suchanek@gmail.com>
prisma · Jul 2, 2020 · f686c12 · f686c12
1 parent 36f8616
commit f686c12
Showing 1 changed file with 135 additions and 0 deletions.
diff --git a/content/02-understand-prisma/05-under-the-hood.mdx b/content/02-understand-prisma/05-under-the-hood.mdx
@@ -51,3 +51,138 @@ A Prisma engine is the **direct interface to the database**, any higher-level in
 As an example, Prisma Client connects to the [query engine](../reference/tools-and-interfaces/prisma-client/query-engine) in order to read and write data in a database:
 
 ![](https://i.imgur.com/Nwwx5Cv.png)
+
+### Using custom engine binaries
+
+By default, all binaries are automatically downloaded into the `node_modules/@prisma/cli` folder when you install or update `@prisma/cli`. You might want to use a [custom binary](https://github.com/prisma/prisma-engines) file if:
+
+* Automated download of binaries is not possible.
+* You have created your own engine binary (for testing, or for an OS that is not officially supported).
+
+Use the following environment variables to specify custom locations for your binaries:
+
+* `PRISMA_QUERY_ENGINE_BINARY` (Query engine)
+* `PRISMA_MIGRATION_ENGINE_BINARY` (Migration engine)
+* `PRISMA_INTROSPECTION_ENGINE_BINARY` (Introspection engine)
+* `PRISMA_FMT_BINARY` (for `npx prisma format`)
+
+
+#### The `prisma/.env` file
+
+To set an environment variable in the `prisma/.env` file:
+
+1. Add the environment variable to the `prisma/.env` file:
+
+   <TabbedContent tabs={[<FileWithIcon text="Unix, MacOS" icon="code"/>  , <FileWithIcon text="Windows" icon="display"/>]}>	
+
+   <tab>
+
+   ```
+   PRISMA_QUERY_ENGINE_BINARY=custom/path/my-query-engine-binary
+   ```
+
+   </tab>
+   <tab>
+
+   ```
+   PRISMA_QUERY_ENGINE_BINARY=c:\custom\path\my-query-engine-binary
+   ```
+
+   </tab>
+   </TabbedContent>
+
+2. Run the following command to output the paths to all binaries:
+
+   ```bash-symbol
+   npx prisma -v
+   ```
+
+   The output shows that the query engine path comes from the `PRISMA_QUERY_ENGINE_BINARY` environment variable:
+
+   <TabbedContent tabs={[<FileWithIcon text="Unix, MacOS" icon="code"/>  , <FileWithIcon text="Windows" icon="display"/>]}>	
+
+   <tab>
+
+   ```
+   Current platform     : darwub
+   | Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-windows)
+   Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/migration-engine-windows)
+   Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/introspection-engine-windows)
+   Format Binary        : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/prisma-fmt-windows)
+   ```
+
+    </tab>
+    <tab>
+
+    ```
+    Current platform     : windows
+    | Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\custom\my-query-engine-windows.exe)
+    Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\cli\migration-engine-windows.exe)
+    Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\cli\introspection-engine-windows.exe)
+    Format Binary        : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\cli\prisma-fmt-windows.exe)
+    ```
+
+    </tab>
+    </TabbedContent>
+
+> **Note**: It is possible to [use an `.env` file in a location outside the `prisma` folder](../reference/tools-and-interfaces/prisma-schema#use-multiple-env-files-or-env-files-outside-the-prisma-folder).
+
+#### Global environment variable
+
+To set the an environment variable globally (in this example, `PRISMA_QUERY_ENGINE_BINARY`):
+
+1. Run the following command to set the environment variable:
+
+    <TabbedContent tabs={[<FileWithIcon text="Unix, MacOS" icon="code"/>  , <FileWithIcon text="Windows" icon="display"/>]}>	
+
+    <tab>	
+
+    ```bash-symbol
+    export PRISMA_QUERY_ENGINE_BINARY=/custom/my-query-engine-unix
+    ```
+
+    </tab>
+
+    <tab>
+
+    ```bash-symbol
+    set PRISMA_QUERY_ENGINE_BINARY=c:\custom\my-query-engine-windows.exe
+    ```
+
+    </tab>
+
+    </TabbedContent>
+
+2. Run the following command to output the paths to all binaries:
+
+   ```bash-symbol
+   npx prisma -v
+   ```
+
+   The output shows that the query engine path comes from the `PRISMA_QUERY_ENGINE_BINARY` environment variable:
+
+   <TabbedContent tabs={[<FileWithIcon text="Unix, MacOS" icon="code"/>  , <FileWithIcon text="Windows" icon="display"/>]}>	
+
+   <tab>
+
+   ```
+   Current platform     : darwub
+   | Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /custom/my-query-engine-windows)
+   Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/migration-engine-windows)
+   Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/introspection-engine-windows)
+   Format Binary        : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at /myproject/node_modules/@prisma/cli/prisma-fmt-windows)
+   ```
+
+    </tab>
+    <tab>
+
+    ```
+    Current platform     : windows
+    | Query Engine         : query-engine d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\custom\my-query-engine-windows.exe)
+    Migration Engine     : migration-engine-cli d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\cli\migration-engine-windows.exe)
+    Introspection Engine : introspection-core d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\cli\introspection-engine-windows.exe)
+    Format Binary        : prisma-fmt d6ff7119649922b84e413b3b69660e2f49e2ddf3 (at c:\myproject\node_modules\@prisma\cli\prisma-fmt-windows.exe)
+    ```
+
+    </tab>
+    </TabbedContent>