From 6f2548164fc48e26450b66a087e3384943e5d633 Mon Sep 17 00:00:00 2001 From: Tasin Ishmam Date: Fri, 17 Nov 2023 21:29:52 +0600 Subject: [PATCH 1/8] Add documentation on prepared statement caching (#4648) Co-authored-by: Jan Piotrowski Co-authored-by: Nikolas --- .../200-database-connectors/03-postgresql.mdx | 60 +++++++++++++------ 1 file changed, 43 insertions(+), 17 deletions(-) diff --git a/content/200-concepts/200-database-connectors/03-postgresql.mdx b/content/200-concepts/200-database-connectors/03-postgresql.mdx index e1d6e77d08..96f2889c1e 100644 --- a/content/200-concepts/200-database-connectors/03-postgresql.mdx +++ b/content/200-concepts/200-database-connectors/03-postgresql.mdx @@ -70,23 +70,24 @@ postgresql://USER:PASSWORD@HOST:PORT/DATABASE?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE The following arguments can be used: -| Argument name | Required | Default | Description | -| :----------------- | :------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `schema` | **Yes** | `public` | Name of the [schema](https://www.postgresql.org/docs/12/ddl-schemas.html) you want to use, e.g. `myschema` | -| `connection_limit` | No | `num_cpus * 2 + 1` | Maximum size of the [connection pool](/concepts/components/prisma-client/working-with-prismaclient/connection-pool) | -| `connect_timeout` | No | `5` | Maximum number of seconds to wait for a new connection to be opened, `0` means no timeout | -| `pool_timeout` | No | `10` | Maximum number of seconds to wait for a new connection from the pool, `0` means no timeout | -| `sslmode` | No | `prefer` | Configures whether to use TLS. Possible values: `prefer`, `disable`, `require` | -| `sslcert` | No | | Path of the server certificate. Certificate paths are [resolved relative to the `./prisma folder`](/concepts/components/prisma-schema/data-sources#securing-database-connections) | -| `sslidentity` | No | | Path to the PKCS12 certificate | -| `sslpassword` | No | | Password that was used to secure the PKCS12 file | -| `sslaccept` | No | `accept_invalid_certs` | Configures whether to check for missing values in the certificate. Possible values: `accept_invalid_certs`, `strict` | -| `host` | No | | Points to a directory that contains a socket to be used for the connection | -| `socket_timeout` | No | | Maximum number of seconds to wait until a single query terminates | -| `pgbouncer` | No | `false` | Configure the Engine to [enable PgBouncer compatibility mode](/guides/performance-and-optimization/connection-management/configure-pg-bouncer) | -| `application_name` | No | | Since 3.3.0: Specifies a value for the application_name configuration parameter | -| `channel_binding` | No | `prefer` | Since 4.8.0: Specifies a value for the channel_binding configuration parameter | -| `options` | No | | Since 3.8.0: Specifies command line options to send to the server at connection start | +| Argument name | Required | Default | Description | +| :--------------------- | :------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `schema` | **Yes** | `public` | Name of the [schema](https://www.postgresql.org/docs/12/ddl-schemas.html) you want to use, e.g. `myschema` | +| `connection_limit` | No | `num_cpus * 2 + 1` | Maximum size of the [connection pool](/concepts/components/prisma-client/working-with-prismaclient/connection-pool) | +| `connect_timeout` | No | `5` | Maximum number of seconds to wait for a new connection to be opened, `0` means no timeout | +| `pool_timeout` | No | `10` | Maximum number of seconds to wait for a new connection from the pool, `0` means no timeout | +| `sslmode` | No | `prefer` | Configures whether to use TLS. Possible values: `prefer`, `disable`, `require` | +| `sslcert` | No | | Path of the server certificate. Certificate paths are [resolved relative to the `./prisma folder`](/concepts/components/prisma-schema/data-sources#securing-database-connections) | +| `sslidentity` | No | | Path to the PKCS12 certificate | +| `sslpassword` | No | | Password that was used to secure the PKCS12 file | +| `sslaccept` | No | `accept_invalid_certs` | Configures whether to check for missing values in the certificate. Possible values: `accept_invalid_certs`, `strict` | +| `host` | No | | Points to a directory that contains a socket to be used for the connection | +| `socket_timeout` | No | | Maximum number of seconds to wait until a single query terminates | +| `pgbouncer` | No | `false` | Configure the Engine to [enable PgBouncer compatibility mode](/guides/performance-and-optimization/connection-management/configure-pg-bouncer) | +| `statement_cache_size` | No | `500` | Since 2.1.0: Specifies the number of [prepared statements](#prepared-statement-caching) cached per connection | +| `application_name` | No | | Since 3.3.0: Specifies a value for the application_name configuration parameter | +| `channel_binding` | No | `prefer` | Since 4.8.0: Specifies a value for the channel_binding configuration parameter | +| `options` | No | | Since 3.8.0: Specifies command line options to send to the server at connection start | As an example, if you want to connect to a schema called `myschema`, set the connection pool size to `5` and configure a timeout for queries of `3` seconds. You can use the following arguments: @@ -214,3 +215,28 @@ model Device { data Unsupported("circle") } ``` + +## Prepared statement caching + +A [prepared statement](https://www.postgresql.org/docs/current/sql-prepare.html) is a feature that can be used to optimize performance. A prepared statement is parsed, compiled, and optimized only once and then can be executed directly multiple times without the overhead of parsing the query again. + +By caching prepared statements, Prisma Client's [query engine](https://www.prisma.io/docs/concepts/components/prisma-engines/query-engine) does not repeatedly compile the same query which reduces database CPU usage and query latency. + + +For example, here is the generated SQL for two different queries made by Prisma Client: + +```sql +SELECT * FROM user WHERE name = "John"; +SELECT * FROM user WHERE name = "Brenda"; +``` + +The two queries after parameterization will be the same, and the second query can skip the preparing step, saving database CPU and one extra roundtrip to the database. Query after parameterization: + +```sql +SELECT * FROM user WHERE name = $1 +``` + + +Every database connection maintained by Prisma has a separate cache for storing prepared statements. The size of this cache can be tweaked with the `statement_cache_size` parameter in the connection string. By default, Prisma Client caches 500 statements per connection. + +Due to the nature of pgBouncer, if the `pgbouncer` parameter is set to `true`, the prepared statement cache is automatically disabled for that connection. From 5bf9aa35f69e875914c325cda5041752e8089467 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Rudge?= Date: Fri, 17 Nov 2023 08:37:53 -0700 Subject: [PATCH 2/8] Update prisma-generator-fake-data text (#5471) --- .../100-components/01-prisma-schema/03-generators.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-concepts/100-components/01-prisma-schema/03-generators.mdx b/content/200-concepts/100-components/01-prisma-schema/03-generators.mdx index 503185a232..51a192d22f 100644 --- a/content/200-concepts/100-components/01-prisma-schema/03-generators.mdx +++ b/content/200-concepts/100-components/01-prisma-schema/03-generators.mdx @@ -95,5 +95,5 @@ The following is a list of community created generators. If you want to create y - [`prisma-generator-graphql-typedef`](https://github.com/mavvy22/prisma-generator-graphql-typedef): Generates graphql schema. - [`prisma-markdown`](https://github.com/samchon/prisma-markdown): Generates markdown document composed with ERD diagrams and their descriptions. Supports pagination of ERD diagrams through `@namespace` comment tag. - [`prisma-models-graph`](https://github.com/dangchinh25/prisma-models-graph): Generates a bi-directional models graph for schema without strict relationship defined in the schema, works via a custom schema annotation. -- [`https://github.com/luisrudge/prisma-generator-fake-data`](https://github.com/luisrudge/prisma-generator-fake-data): Generates realistic-looking fake data for your Prisma models that can be used in unit/integration tests, demos, and more. +- [`prisma-generator-fake-data`](https://github.com/luisrudge/prisma-generator-fake-data): Generates realistic-looking fake data for your Prisma models that can be used in unit/integration tests, demos, and more. From cc7fd2f3c56f909e7b338f00bb097f5cfcdf5145 Mon Sep 17 00:00:00 2001 From: Nikolas Date: Fri, 17 Nov 2023 21:21:02 +0100 Subject: [PATCH 3/8] docs: update landing page for getting started (#5468) Co-authored-by: meletj <70962362+meletj@users.noreply.github.com> --- content/100-getting-started/index.mdx | 54 ++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/content/100-getting-started/index.mdx b/content/100-getting-started/index.mdx index 899e9a1a48..62dc3d4d22 100644 --- a/content/100-getting-started/index.mdx +++ b/content/100-getting-started/index.mdx @@ -6,27 +6,29 @@ metaDescription: 'Get started' -Welcome to the Prisma getting started section! 👋 Prisma is an [open source](https://github.com/prisma/prisma) next-generation ORM. It consists of the following parts: +Welcome to the Prisma getting started section! 👋 -- [**Prisma Client**](/concepts/components/prisma-client): Auto-generated and type-safe query builder for Node.js & TypeScript -- [**Prisma Migrate**](/concepts/components/prisma-migrate): Migration tool to easily evolve your database schema from prototyping to production -- [**Prisma Studio**](/concepts/components/prisma-studio): GUI to view and edit data in your database +Explore our range of products defined to make working with data easy: -Prisma is also available on the [Prisma Data Platform](https://console.prisma.io), a cloud-based, collaborative environment for teams and organizations to develop type-safe applications. The platform focuses on developer productivity with GitHub integration for your code and schema, a visual data browser, an online query console, and an optional data proxy for handling database connections. For more information, refer to the Prisma Data Platform [documentation](/data-platform). +[**Prisma ORM**](/concepts/overview/what-is-prisma) is an [open source](https://github.com/prisma/prisma) next-generation database toolkit that helps with data modeling, data access, schema migrations and more. -For a more detailed breakdown of what problems Prisma solves and why it's **built to make you more productive**, see the [Why Prisma](/concepts/overview/why-prisma) section. +[**Prisma Accelerate**](/data-platform/accelerate/what-is-accelerate) is a global database cache with scalable connection pooling. + +[**Prisma Pulse**](/data-platform/pulse/what-is-pulse) allows you to build reactive, real-time applications in a type-safe manner. ## Which tutorial is right for me? -To get up and running with Prisma in your local environment, follow our [Quickstart guide](./quickstart). It makes no assumptions about your knowledge level and offers the **fastest** way from install to query! +### Get started with Prisma ORM + +To get up and running with Prisma in your local environment, follow our Quickstart guide It makes no assumptions about your knowledge level and offers the **fastest** way from install to query! Quickstart -If you're looking to incorporate Prisma with an **existing project**, choose whether you want to use a SQL database or MongoDB: +If you're looking to incorporate Prisma with an **existing project**, choose whether you want to use a SQL database or MongoDB. -To learn how to **create a project** with Prisma from scratch, choose between SQL and MongoDB. Both tutorials will guide you through creating a project, connecting your database, and querying your data. +To learn how to **create a new project** with Prisma from scratch, choose between SQL and MongoDB. Both tutorials will guide you through creating a project, connecting your database, and querying your data. +If you're interested in learning how Prisma integrates with your favorite library or framework, such as Next.js, Express, Apollo GraphQL, NestJS, etc, you can check out our **ready-to-run examples**. + + + Examples + + +### Get started with Prisma Accelerate + +Add **Accelerate** to your app to use connection pooling and global database caching. + + + Get started with Accelerate + + +### Get started with Prisma Pulse + +Add **Pulse** to your app to subscribe to real-time updates from your database using Prisma Client. + + + Get started with Pulse + + ## Prisma with different tooling Prisma can be used with a wide range of tooling and frameworks, the following links outline how to get started with some of them: From fde141db653bccf3365aeecc1f2b40f8f68e673f Mon Sep 17 00:00:00 2001 From: Nikolas Date: Mon, 20 Nov 2023 10:45:06 +0100 Subject: [PATCH 4/8] Update 03-supported-databases.mdx (#5474) --- .../03-supported-databases.mdx | 21 +++++++------------ 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/content/400-reference/300-database-reference/03-supported-databases.mdx b/content/400-reference/300-database-reference/03-supported-databases.mdx index a0f4284210..a1ece2fc64 100644 --- a/content/400-reference/300-database-reference/03-supported-databases.mdx +++ b/content/400-reference/300-database-reference/03-supported-databases.mdx @@ -6,7 +6,11 @@ metaDescription: 'This page lists all the databases and their versions that are -Prisma currently supports the following databases: +Prisma currently supports the following databases. + + + +## Self-hosted databases | Database | Version | | ---------------------------- | ------- | @@ -30,6 +34,8 @@ Prisma currently supports the following databases: ## Managed databases +| Database | Version | +| ---------------------------- | ------- | | PlanetScale | \* | | AWS Aurora | \* | | AWS Aurora Serverless ¹ | \* | @@ -43,18 +49,5 @@ An asterisk (\*) indicates that the version number is not relevant; either all v ¹ This does not include support for [Data API for Aurora Serverless](https://github.com/prisma/prisma/issues/1964). - - - See also: [System requirements](/reference/system-requirements) From 414a16e7e4f84b65d051f5f27cda3338c2a76508 Mon Sep 17 00:00:00 2001 From: Pavel Savchenko Date: Mon, 20 Nov 2023 09:54:00 +0000 Subject: [PATCH 5/8] docs(db-push): clarify the migration table note (#5130) --- .../100-components/03-prisma-migrate/150-db-push.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-concepts/100-components/03-prisma-migrate/150-db-push.mdx b/content/200-concepts/100-components/03-prisma-migrate/150-db-push.mdx index 6a9400bf91..020230babe 100644 --- a/content/200-concepts/100-components/03-prisma-migrate/150-db-push.mdx +++ b/content/200-concepts/100-components/03-prisma-migrate/150-db-push.mdx @@ -20,7 +20,7 @@ The Prisma CLI has a dedicated command for prototyping schemas: [`db push`](/ref > **Notes**: > -> - `db push` does not interact with or rely on migrations. The migrations table will not be updated, and no migration files will be generated. +> - `db push` does not interact with or rely on migrations. The migrations table `_prisma_migrations` will not be created or updated, and no migration files will be generated. > - When working with PlanetScale, we recommend that you use `db push` instead of `migrate`. For details refer to our Getting Started documentation, either [Start from scratch](/getting-started/setup-prisma/start-from-scratch/relational-databases-typescript-planetscale) or [Add to existing project](/getting-started/setup-prisma/add-to-existing-project/relational-databases-typescript-planetscale) depending on your situation. From 976d1c8bea722927b778d3cbe54f3df689404c14 Mon Sep 17 00:00:00 2001 From: Vaibhav Dangra Date: Mon, 20 Nov 2023 15:45:27 +0530 Subject: [PATCH 6/8] fix: broken link (#4676) From 8ff58bdca4d560ce9d52a8c8d5070dcfbac54781 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Mon, 20 Nov 2023 06:43:24 -0500 Subject: [PATCH 7/8] Offer clear field @map example (#5473) --- .../200-api-reference/100-prisma-schema-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx index 0f926bb7ec..660aab63ed 100644 --- a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx +++ b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx @@ -385,7 +385,7 @@ model User { - Typically spelled in camelCase - Must adhere to the following regular expression: `[A-Za-z][A-Za-z0-9_]*` -> **Note**: You can use the [`@map` attribute](#map) to map a field name (for example, `MyField`) to a column with a different name that does not match field naming conventions (for example, `myField`). +> **Note**: You can use the [`@map` attribute](#map) to [map a field name to a column](/concepts/components/prisma-client/working-with-prismaclient/use-custom-model-and-field-names) with a different name that does not match field naming conventions: e.g. `myField @map("my_field")`. ## model field scalar types From 781284c72fa6bd82c23f6009910ee859db2c2bb0 Mon Sep 17 00:00:00 2001 From: Olivier Lacan Date: Mon, 20 Nov 2023 06:43:56 -0500 Subject: [PATCH 8/8] Fix typo in Order of Fields section (#5472) --- .../200-api-reference/100-prisma-schema-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx index 660aab63ed..e97e3fc2bb 100644 --- a/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx +++ b/content/400-reference/200-api-reference/100-prisma-schema-reference.mdx @@ -343,7 +343,7 @@ Defines a Prisma [model](/concepts/components/prisma-schema/data-model#defining- #### Order of fields -- In version 2.3.0 and later, introspection lists model fields same order as the corresponding columns in the database. Relation fields are listed after scalar fields. +- In version 2.3.0 and later, introspection lists model fields in the same order as the corresponding columns in the database. Relation fields are listed after scalar fields. ### Examples