Skip to content

Commit

Permalink
rename Photon to Prisma Client JS
Browse files Browse the repository at this point in the history
  • Loading branch information
@nikolasburk
nikolasburk committed Jan 15, 2020
1 parent aca7890 commit 2e27870
Show file tree
Hide file tree
Showing 9 changed files with 139 additions and 138 deletions.
58 changes: 29 additions & 29 deletions docs/photon/codegen-and-node-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,93 +2,93 @@

## TLDR

In order to use Photon.js in your application, you must install the `@prisma/photon` package in your application:
In order to use Prisma Client JS in your application, you must install the `@prisma/client` package in your application:

```
npm install @prisma/photon
npm install @prisma/client
```

The `@prisma/photon` package itself is a [_facade package_](https://github.com/prisma/prisma-client-js/issues/261) (basically a _stub_) that doesn't contain any functional code, such as types or the Photon.js runtime. When installing the `@prisma/photon` package, its `postinstall` hook is being executed to invoke the `prisma2 generate` command and generate the actual Photon.js code into the facade package at `node_modules/@prisma/photon`.
The `@prisma/client` package itself is a [_facade package_](https://github.com/prisma/prisma-client-js/issues/261) (basically a _stub_) that doesn't contain any functional code, such as types or the Prisma Client JS runtime. When installing the `@prisma/client` package, its `postinstall` hook is being executed to invoke the `prisma2 generate` command and generate the actual Prisma Client JS code into the facade package at `node_modules/@prisma/client`.

This means the `prisma2` CLI needs to be available as well. It is typically installed as a development dependency:

```
npm install prisma2 --save-dev
```

## Why is the facade package needed if Photon.js is generated?
## Why is the facade package needed if Prisma Client JS is generated?

The facade package is necessary to enable typical build and deployment workflows of Node.js applications. As an example, the facade package ensures that Photon.js survives the ["pruning"](https://docs.npmjs.com/cli/prune.html) that's often employed by Node.js package managers.
The facade package is necessary to enable typical build and deployment workflows of Node.js applications. As an example, the facade package ensures that Prisma Client JS survives the ["pruning"](https://docs.npmjs.com/cli/prune.html) that's often employed by Node.js package managers.

Note that you'll need to re-execute `prisma2 generate` whenever you make changes to your [Prisma schema](../prisma-schema-file.md) (or perform the changes while are you're running Prisma's [development mode](../development-mode.md).

> **Note**: While this approach has a number of [benefits](#why-is-photon-js-generated-into-node_modulesgenerated-by-default), it is also unconventional and can be a source of confusion for developers new to Photon.js. Using `node_modules/@prisma/photon` as the default `output` for Photon.js is still experimental. Please share your feedback and tell us whether you think this is a good idea or any other thoughts you have on this topic by joining the [discussion on GitHub](https://github.com/prisma/prisma-client-js/issues/88).
> **Note**: While this approach has a number of [benefits](#why-is-photon-js-generated-into-node_modulesgenerated-by-default), it is also unconventional and can be a source of confusion for developers new to Prisma Client JS. Using `node_modules/@prisma/client` as the default `output` for Prisma Client JS is still experimental. Please share your feedback and tell us whether you think this is a good idea or any other thoughts you have on this topic by joining the [discussion on GitHub](https://github.com/prisma/prisma-client-js/issues/88).
## Specifying the target location for Photon.js
## Specifying the target location for Prisma Client JS

`prisma2 generate` invokes 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:
The default Prisma Client JS generator can be specified as follows in your schema file:

```prisma
generator photonjs {
provider = "photonjs"
generator client {
provider = "prisma-client-js"
}
```

Note that this is equivalent to specifying the default `output` path:

```prisma
generator photonjs {
provider = "photonjs"
output = "./node_modules/@prisma/photon"
generator client {
provider = "prisma-client-js"
output = "./node_modules/@prisma/client"
}
```

When running `prisma2 generate` for either of these schema files, Photon.js package will be located in:
When running `prisma2 generate` for either of these schema files, Prisma Client JS package will be located in:

```
node_modules/@prisma/photon
node_modules/@prisma/client
```

You can also specify a custom `output` path on the `generator` configuration, for example:

```prisma
generator photonjs {
provider = "photonjs"
output = "./src/generated/photon"
generator client {
provider = "prisma-client-js"
output = "./src/generated/client"
}
```

## Photon.js should be viewed as an npm package
## Prisma Client JS should be viewed as an npm package

Node.js libraries are typically installed as npm dependencies using `npm install`. The respective packages are then located inside the [`node_modules`](https://docs.npmjs.com/files/folders#node-modules) directory from where they can be imported into application code.

Because Photon.js is a custom API for _your specific database setup_, it can't follow that model. It needs to be generated locally instead of being installed from a central repository like npm. However, the mental model for Photon.js should still be that of an Node.js module.
Because Prisma Client JS is a custom API for _your specific database setup_, it can't follow that model. It needs to be generated locally instead of being installed from a central repository like npm. However, the mental model for Prisma Client JS should still be that of an Node.js module.

## Why is Photon.js generated into `node_modules/@prisma/photon` by default?
## Why is Prisma Client JS generated into `node_modules/@prisma/client` by default?

### Importing Photon.js
### Importing Prisma Client JS

By generating Photon.js into `node_modules/@prisma/photon`, you can import it into your code:
By generating Prisma Client JS into `node_modules/@prisma/client`, you can import it into your code:

```js
import { Photon } from '@prisma/photon'
import { PrismaClient } from '@prisma/client'
```

or

```js
const { Photon } = require('@prisma/photon')
const { PrismaClient } = require('@prisma/client')
```

### Keeping the query engine binary out of version control by default

Photon.js is based on a _query engine_ that's running as a binary alongside your application. This binary is downloaded when `prisma2 generate` is invoked and stored in the `output` path (right next to the generated Photon API).
Prisma Client JS is based on a _query engine_ that's running as a binary alongside your application. This binary is downloaded when `prisma2 generate` is invoked and stored in the `output` path (right next to the generated Prisma Client JS API).

By generating Photon.js into `node_modules`, the query engine is kept out of version control by default (since `node_modules` is typically ignored for version control). If it was not generated into `node_modules`, then developers would need to explicitly ignore it, e.g. for Git they'd need to add the `output` path to `.gitignore`.
By generating Prisma Client JS into `node_modules`, the query engine is kept out of version control by default (since `node_modules` is typically ignored for version control). If it was not generated into `node_modules`, then developers would need to explicitly ignore it, e.g. for Git they'd need to add the `output` path to `.gitignore`.

## Generating Photon.js in the `postinstall` hook of `@prisma/photon`
## Generating Prisma Client JS in the `postinstall` hook of `@prisma/client`

The `@prisma/photon` package defines its own `postinstall` hook that's being executed whenever the package is being installed. This hook invokes the `prisma2 generate` command which in turn generates the Photon.js code into the default location `node_modules/@prisma/photon`. Notice that this requires the `prisma2` CLI to be available, either as local dependency or as a global installation (it is recommended to always install the `prisma2` package as a development dependency, using `npm install prisma2 --save-dev`, to avoid versioning conflicts though).
The `@prisma/client` package defines its own `postinstall` hook that's being executed whenever the package is being installed. This hook invokes the `prisma2 generate` command which in turn generates the Prisma Client JS code into the default location `node_modules/@prisma/client`. Notice that this requires the `prisma2` CLI to be available, either as local dependency or as a global installation (it is recommended to always install the `prisma2` package as a development dependency, using `npm install prisma2 --save-dev`, to avoid versioning conflicts though).

22 changes: 11 additions & 11 deletions docs/photon/deployment.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
# Deployment

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.
Prisma Client JS depends on a query engine that's running as a binary on the same host as your application. When deploying your Prisma-based application to production, you need to ensure that the binary used by Prisma Client JS 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/@prisma` (or the [custom `output` path](./codegen-and-node-setup.md) you specified).
The query engine binary is downloaded when you run `prisma2 generate`, it is then stored alongside the generated Prisma Client JS code inside `node_modules/@prisma` (or the [custom `output` path](./codegen-and-node-setup.md) you specified).

**IMPORTANT**: To ensure the query engine binary is compatible with your production environment, you have to [specify the right platform for Photon.js](../core/generators/photonjs.md#specifying-the-right-platform-for-photon-js).
**IMPORTANT**: To ensure the query engine binary is compatible with your production environment, you have to [specify the right platform for Prisma Client JS](../core/generators/photonjs.md#specifying-the-right-platform-for-photon-js).

## Photon in FaaS environment (e.g. AWS Lambda, Netlify, ...)
## Prisma Client JS in FaaS environment (e.g. AWS Lambda, Netlify, ...)

### Database connection handling

Nuances around handling database connections in Lambda are not new and most of those nuances also apply to Photon.
Nuances around handling database connections in Lambda are not new and most of those nuances also apply to Prisma Client JS.

Lambda has the concept of [reusing a container](https://aws.amazon.com/blogs/compute/container-reuse-in-lambda/) which means that for subsequent invocations of
the same function it may use an already existing container that has the allocated processes, memory, file system (`/tmp` is writable in Lambda), and even DB
connection still available.

Any piece of code [outside the handler](https://docs.aws.amazon.com/lambda/latest/dg/programming-model-v2.html) remains initialized. This is a great place for
`Photon` to call "connect" or at least call `Photon` constructor so that subsequent invocations can share a connection. There are some implications though that are not directly related to Photon but any system that would require a DB connection from Lambda:
`PrismaClient` to call `connect` or at least call `PrismaClient` constructor so that subsequent invocations can share a connection. There are some implications though that are not directly related to Prisma Client JS but any system that would require a DB connection from Lambda:

| Implication | Description | Potential Solution |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Container reuse | It is not guaranteed that subsequent nearby invocations of a function will hit the same container. AWS can choose to create a new container at any time. | Code should assume the container to be stateless and create a connection only if it does not exist. Photon already implements that logic. |
| Container reuse | It is not guaranteed that subsequent nearby invocations of a function will hit the same container. AWS can choose to create a new container at any time. | Code should assume the container to be stateless and create a connection only if it does not exist. Prisma Client JS already implements that logic. |
| Zombie connections | The containers that are marked to be removed and are not being reused still keep a connection open and can stay in that state for some time (unknown and not documented from AWS), this can lead to a sub-optimal utilization of the DB connections | One potential solution is to use a lower idle connection timeout. Another solution can be to clean up the idle connections in a separate service<sup>1, 2</sup>. |
| Connection pooling issues | Concurrent requests might spin up separate containers i.e. new connections. This makes connection pooling a bit difficult to manage because if there is a pool of size N and C concurrent containers, the effective number of connections is N \* C. It is very easy to exhaust `max_connection` limits of the underlying data source | Photon does not implement connection pooling right now. This can also be handled by limiting the concurrency levels of a Lambda function. |
| Connection pooling issues | Concurrent requests might spin up separate containers i.e. new connections. This makes connection pooling a bit difficult to manage because if there is a pool of size N and C concurrent containers, the effective number of connections is N \* C. It is very easy to exhaust `max_connection` limits of the underlying data source | Prisma Client JS does not implement connection pooling right now. This can also be handled by limiting the concurrency levels of a Lambda function. |

<br />
<sup>
Expand All @@ -41,7 +41,7 @@ does not work, containers are recycled regardless.

## Examples

Here are a number of example projects demonstrating how to deploy Photon.js to various deployment providers:
Here are a number of example projects demonstrating how to deploy Prisma Client JS to various deployment providers:

- [Google Cloud Functions](https://github.com/prisma/prisma-examples/tree/prisma2/deployment-platforms/google-cloud-functions)
- [Netlify](https://github.com/prisma/prisma-examples/tree/prisma2/deployment-platforms/netlify)
Expand All @@ -53,7 +53,7 @@ Here are a number of example projects demonstrating how to deploy Photon.js to v

### AWS Lambda

In order to not exhaust the connection limits of your database, you should set the `connection_limit` parameter of your database connection string in the Prisma schema to `1` when deploying your Photon.js-based application to [AWS Lambda]().
In order to not exhaust the connection limits of your database, you should set the `connection_limit` parameter of your database connection string in the Prisma schema to `1` when deploying your Prisma-based application to [AWS Lambda]().

**PostgreSQL**

Expand Down Expand Up @@ -86,7 +86,7 @@ This means that if you're e.g. using a `m5.large` PostgreSQL instance, you need

### ZEIT Now

You can deploy your "Photon.js"-based application to [ZEIT Now](https://zeit.co/now).
You can deploy your Prisma-based application to [ZEIT Now](https://zeit.co/now).

When deploying to ZEIT Now, you must configure the following in your `now.json`:

Expand Down

0 comments on commit 2e27870

Please sign in to comment.