add FAQ about connection pooling

prisma · Sep 18, 2019 · 37a0996 · 37a0996
1 parent 64644ae
commit 37a0996
Showing 1 changed file with 26 additions and 17 deletions.
diff --git a/docs/faq.md b/docs/faq.md
@@ -2,12 +2,12 @@
 
 - Photon
   - [Can I still access my database directly (e.g. using raw SQL)?](#can-i-still-access-my-database-directly-eg-using-raw-sql)
-  - [Is Photon an ORM?](#is-photon-an-orm)
-  - [Will Photon support more databases (and other data sources) in the future?](#will-photon-support-more-databases-and-other-data-sources-in-the-future)
-  - [How can I see the generated queries that Photon sends to my database?](#how-can-i-see-the-generated-queries-that-photon-sends-to-my-database)
+  - [Is Photon.js an ORM?](#is-photon-an-orm)
+  - [Will Photon.js support more databases (and other data sources) in the future?](#will-photon-support-more-databases-and-other-data-sources-in-the-future)
+  - [How can I see the generated queries that Photon.js sends to my database?](#how-can-i-see-the-generated-queries-that-photon-sends-to-my-database)
   - [How do schema migrations work with Photon?](#how-do-schema-migrations-work-with-photon)
-  - [Is Photon production-ready? Should I start using it?](#is-photon-production-ready-should-i-start-using-it)
-  - [Does Photon support GraphQL schema delegation and GraphQL binding?](#does-photon-support-graphql-schema-delegation-and-graphql-binding)
+  - [Is Photon.js production-ready? Should I start using it?](#is-photon-production-ready-should-i-start-using-it)
+  - [Does Photon.js support GraphQL schema delegation and GraphQL binding?](#does-photon-support-graphql-schema-delegation-and-graphql-binding)
 - Lift
   - [Am I locked-in when using Lift? Is it easy to migrate off it?](#am-i-locked-in-when-using-lift-is-it-easy-to-migrate-off-it)
   - [How do I see details about how Lift migrates my database schema?](#how-do-i-see-details-about-how-lift-migrates-my-database-schema)
@@ -21,42 +21,50 @@
 
 ### Can I still access my database directly (e.g. using raw SQL)?
 
-While it's currently not possible to use Photon to directly access your database, this feature has a priority on our list and is one of the first things we are working on during the Preview period. You can track the progress of this feature [here](https://github.com/prisma/photonjs/issues/10). 
+While it's currently not possible to use Photon.js to directly access your database, this feature has a priority on our list and is one of the first things we are working on during the Preview period. You can track the progress of this feature [here](https://github.com/prisma/photonjs/issues/10). 
 
-In the meanwhile, you can use Photon alongside other lightweight query builders such as [knex](https://www.github.com/tgriesser/knex).
+In the meanwhile, you can use Photon.js alongside other lightweight query builders such as [knex](https://www.github.com/tgriesser/knex).
 
-### Is Photon an ORM?
+### Is Photon.js an ORM?
 
 ORMs are typically object-oriented mapping layers that map classes to tables. A record is represented as an object that not only carries data but also implements various behaviours for storage, retrieval,
 serialization and deserialization of its own data, sometimes it also implements business/domain logic.
-Photon acts more as a _query builder_ returning plain objects with a focus on structural typing rather than rich object behavior.
+Photon.js acts more as a _query builder_ returning plain objects with a focus on structural typing rather than rich object behavior.
 
-### Will Photon support more databases (and other data sources) in the future?
+### Will Photon.js support more databases (and other data sources) in the future?
 
-Yes. Photon is based on Prisma's query engine that can connect to any data source that provides a proper connector implementation. There will be built-in connectors such as the current ones for [PostgreSQL](./core/connectors/postgresql.md), [MySQL](./core/connectors/mysql.md) and [SQLite](./core/connectors/sqlite.md). 
+Yes. Photon.js is based on Prisma's query engine that can connect to any data source that provides a proper connector implementation. There will be built-in connectors such as the current ones for [PostgreSQL](./core/connectors/postgresql.md), [MySQL](./core/connectors/mysql.md) and [SQLite](./core/connectors/sqlite.md). 
 
 However, it's also possible to build your own connectors, more documentation on that topic will follow soon.
 
-### How can I see the generated queries that Photon sends to my database?
+### How can I see the generated queries that Photon.js sends to my database?
 
-There will be rich query analytics for Photon soon. For now you can set the `debug` option to `true` when instanting your `Photon` instance. Learn more in the [docs](./photon/api.md#debugging).
+There will be rich query analytics for Photon.js soon. For now you can set the `debug` option to `true` when instanting your `Photon` instance. Learn more in the [docs](./photon/api.md#debugging).
 
 ### How do schema migrations work with Photon?
 
-Photon is not opinionated on how exactly you migrate your database schema. You can keep your existing migration system and simply re-introspect your database schema after each migration to update Photon. Learn more in the [docs](./photon/use-only-photon.md). You can also always use [Lift](https://lift.prisma.io) to perform your migrations based on Prisma's declarative [data model definition](./data-modeling.md).
+Photon.js is not opinionated on how exactly you migrate your database schema. You can keep your existing migration system and simply re-introspect your database schema after each migration to update Photon. Learn more in the [docs](./photon/use-only-photon.md). You can also always use [Lift](https://lift.prisma.io) to perform your migrations based on Prisma's declarative [data model definition](./data-modeling.md).
 
-### Is Photon production-ready? Should I start using it?
+### Is Photon.js production-ready? Should I start using it?
 
-Photon is not yet production-ready, it has a number of severe [limitations](./limitations.md) that don't make it suitable for production uses and heavy loads. You can track the progress of the release process on [isprisma2ready.com](https://www.isprisma2ready.com). While it shouldn't be used for critical applications yet, Photon is definitely in a usable state. You can help us accelerate the release process by using it and [sharing your feedback](./prisma2-feedback.md) with us.
+Photon.js is not yet production-ready, it has a number of severe [limitations](./limitations.md) that don't make it suitable for production uses and heavy loads. You can track the progress of the release process on [isprisma2ready.com](https://www.isprisma2ready.com). While it shouldn't be used for critical applications yet, Photon.js is definitely in a usable state. You can help us accelerate the release process by using it and [sharing your feedback](./prisma2-feedback.md) with us.
 
-### Does Photon support GraphQL schema delegation and GraphQL binding?
+### Does Photon.js support GraphQL schema delegation and GraphQL binding?
 
 GraphQL [schema delegation](https://www.prisma.io/blog/graphql-schema-stitching-explained-schema-delegation-4c6caf468405/) connects two GraphQL schemas by passing the [`info`](https://www.prisma.io/blog/graphql-server-basics-demystifying-the-info-argument-in-graphql-resolvers-6f26249f613a/) object from a resolver of the first GraphQL schema to a resolver of the second GraphQL schema. Schema delegation also is the foundation for [GraphQL binding](https://github.com/graphql-binding/graphql-binding).
 
 Prisma 1 officially supports both schema delegation and GraphQL binding as it exposes a GraphQL CRUD API through the [Prisma server](https://www.prisma.io/docs/prisma-server/). This API can be used to as foundation for an application-layer GraphQL API created with GraphQL binding. 
 
 With Prisma 2, Prisma's query engine doesn't expose a [spec](https://graphql.github.io/graphql-spec/June2018/)-compliant GraphQL endpoint any more, so usage of schema delegation and GraphQL binding with Prisma 2 is not officially supported. To build GraphQL servers with Prisma 2, be sure to check out [GraphQL Nexus](https://nexus.js.org/) and its [`nexus-prisma`](https://nexus.js.org/docs/database-access-with-prisma-v2) integration. GraphQL Nexus provides a code-first and type-safe way to build GraphQL servers in a scalable way. 
 
+### How does Photon.js handle connection pooling?
+
+Photon.js currently [doesn't support connection pooling](https://github.com/prisma/photonjs/issues/228). If you're intested in learning how to manage database connections in serverless environments, check out the [docs](./photon/deployment.md).
+
+As of now, the recommended workaround is to use a tool like [PgBouncer](https://pgbouncer.github.io/faq.html). We are further exploring some options, such as [enabling a "DB proxy server"](https://github.com/prisma/prisma2/issues/370) (e.g. using a specific generator that generates a Docker image to host Photon's query engine) that manages the connection pool for you (similar to the the Prisma 1 architecture).
+
+Also note that there some cloud offerings start to have solutions for connection pooling out-of-the-box, such as [AWS Aurora](https://aws.amazon.com/blogs/aws/new-data-api-for-amazon-aurora-serverless/).
+
 ## Lift
 
 ### Am I locked-in when using Lift? Is it easy to migrate off it?
@@ -91,3 +99,4 @@ There will be no new features developed for Prisma 1.
 
 Check out the [`specs`](https://github.com/prisma/specs) repo which contains the technical specifications for future Prisma 2 features. Get involved by [creating issues](https://github.com/prisma/prisma2/issues) and [sharing feedback](./prisma2-feedback)!
 
+