diff --git a/content/100-getting-started/03-prisma-postgres/100-quickstart/50-prisma-orm.mdx b/content/100-getting-started/03-prisma-postgres/100-quickstart/50-prisma-orm.mdx index 6e370e4f93..bf86530d32 100644 --- a/content/100-getting-started/03-prisma-postgres/100-quickstart/50-prisma-orm.mdx +++ b/content/100-getting-started/03-prisma-postgres/100-quickstart/50-prisma-orm.mdx @@ -257,4 +257,4 @@ You should see the created user and all users printed to the console! - [Prisma Postgres documentation](/postgres) - [Prisma Config reference](/orm/reference/prisma-config-reference) - [Database connection management](/orm/prisma-client/setup-and-configuration/databases-connections) -- [Cache your queries](/postgres/database/caching#setting-up-caching-in-prisma-postgres) \ No newline at end of file +- [Cache your queries](/postgres/database/caching#setting-up-caching-in-prisma-postgres) diff --git a/content/100-getting-started/index.mdx b/content/100-getting-started/index.mdx index 5006fc70e0..a93d27b908 100644 --- a/content/100-getting-started/index.mdx +++ b/content/100-getting-started/index.mdx @@ -127,11 +127,26 @@ You can also use Prisma Postgres with different tools or ORMs. Pick one of the o image={'/img/technologies/drizzle.svg'} tech="Drizzle" /> + {/* */} + + +
+
+ +### Add Prisma to your favorite framework? + +Working with **Next.js**, **Remix**, or another framework? You can easily add Prisma to your setup in just a few steps and start using it right away. + + :@db.prisma.io:5432/postgres β”‚ β—† Claim your database β†’ -β”‚ -β”‚ Want to keep your database? Claim for free: +β”‚ Keep your database for free: β”‚ https://create-db.prisma.io?projectID=proj_... β”” ``` -Once you have the output, take the **Prisma ORM-optimized connection string** (`prisma+postgres://...`) and add it to your `.env` file as `DATABASE_URL`: +Once you have the output, take the connection string and add it to your `.env` file as `DATABASE_URL`: ```env -DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=..." +DATABASE_URL="postgresql://:@db.prisma.io:5432/postgres" ``` You can now follow the [Prisma Postgres quickstart guide](/getting-started/prisma-orm/quickstart/prisma-postgres) to connect your Prisma project to this database. @@ -163,12 +156,12 @@ When you claim a database: Here are the CLI flags for the `npx create-db` command: -| Flag | Shorthand | Description | -|---------------|-----------|----------------------------------------------------------------------------------------------| -| `--region` | `-r` | Specify a region.
**Available regions:** `ap-southeast-1`, `ap-northeast-1`, `eu-central-1`, `eu-west-3`, `us-east-1`, `us-west-1` | -| `--interactive` | `-i` | Run in interactive mode (select region from a list). | -| `--json` | `-j` | Output machine-readable JSON and exit. | -| `--help` | `-h` | Show this help message. | +| Flag | Shorthand | Description | +|-----------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------| +| `--region` | `-r` | Specify a region.
**Available regions:** `ap-southeast-1`, `ap-northeast-1`, `eu-central-1`, `eu-west-3`, `us-east-1`, `us-west-1` | +| `--interactive` | `-i` | Run in interactive mode (select region from a list). | +| `--json` | `-j` | Output machine-readable JSON and exit. | +| `--help` | `-h` | Show this help message. | To view all CLI options use the `--help` or `-h` flag: diff --git a/content/250-postgres/100-introduction/250-overview.mdx b/content/250-postgres/100-introduction/250-overview.mdx index 8b5300dc91..a5bffb88ca 100644 --- a/content/250-postgres/100-introduction/250-overview.mdx +++ b/content/250-postgres/100-introduction/250-overview.mdx @@ -12,7 +12,7 @@ toc: true It supports the following workflows: - Schema migrations and queries (via [Prisma ORM](https://www.prisma.io/orm) or any other ORM/database library) -- Connection pooling and caching (via [Prisma Accelerate](https://www.prisma.io/accelerate)) +- Connection pooling and caching - Local database workflows via [`prisma dev`](/postgres/database/local-development) ## Usage metrics @@ -63,22 +63,6 @@ When changing your subscription from Free to Starter/Pro/Business or from Starte This is temporary. In the future, there won't be any downtime when up- or downgrading a plan. ::: -## Bundling with Prisma Accelerate - -Prisma Postgres comes bundled with [Prisma Accelerate](/accelerate). - -### Using the Client extension for Prisma Accelerate (required) - -Because all traffic to Prisma Postgres is routed through Accelerate's connection pool, your project must have the [`@prisma/extension-accelerate`](https://www.npmjs.com/package/@prisma/extension-accelerate) npm package installed. The extension then needs to be applied to the `PrismaClient` instance you use to interact with your database: - -```ts -import { PrismaClient } from '@prisma/client' -import { withAccelerate } from '@prisma/extension-accelerate' - -const prisma = new PrismaClient() - .$extends(withAccelerate()) -``` - ## Technical details ### PostgreSQL version diff --git a/content/250-postgres/1200-more/1000-faq.mdx b/content/250-postgres/1200-more/1000-faq.mdx index bca6c2d8c4..262b477d00 100644 --- a/content/250-postgres/1200-more/1000-faq.mdx +++ b/content/250-postgres/1200-more/1000-faq.mdx @@ -29,11 +29,8 @@ If you previously signed up using GitHub and want to switch to email and passwor 3. Test Your Login - Log out and try logging in with your email and the password you just created. -:::note - If you encounter any issues, please contact our support team for help linking your accounts. -::: ### VS Code does not recognize the `$extends` method diff --git a/content/250-postgres/1200-more/900-troubleshooting.mdx b/content/250-postgres/1200-more/900-troubleshooting.mdx index 13fb26186d..ff7113630d 100644 --- a/content/250-postgres/1200-more/900-troubleshooting.mdx +++ b/content/250-postgres/1200-more/900-troubleshooting.mdx @@ -33,28 +33,6 @@ npx prisma@latest init --db This ensures that you're using the most up-to-date CLI, preventing issues with outdated command syntax. -## Warning: In production, we recommend using `prisma generate --no-engine` - -### Problem - -You're seeing the following error in your logs: - -``` -prisma:warn: In production, we recommend using 'prisma generate --no-engine' -``` - -### Cause - -Prisma ORM by default uses a [query engine](/orm/overview/) binary that's deployed as part of the `@prisma/client` package. However, with Prisma Postgres, this is not needed. - -### Solution - -To remove this warning and generate Prisma Client without the query engine, you can run the following command: - -``` -npx prisma generate --no-engine -``` - ## Workspace plan limit reached when running `prisma init --db` ### Problem diff --git a/content/250-postgres/300-database/400-connection-pooling.mdx b/content/250-postgres/300-database/400-connection-pooling.mdx index 83f92d3e5e..874a5dec90 100644 --- a/content/250-postgres/300-database/400-connection-pooling.mdx +++ b/content/250-postgres/300-database/400-connection-pooling.mdx @@ -6,48 +6,25 @@ tocDepth: 3 toc: true --- -Prisma Postgres provides built-in [connection pooling](https://www.prisma.io/dataguide/database-tools/connection-pooling) by default, enabled by [Prisma Accelerate](/accelerate/). By using Prisma Postgres, you get the benefits of connection pooling without having to configure anything. The efficient management of database connections allows the database to process more queries without exhausting the available database connections, making your application more scalable. - -In some cases, however, it may be beneficial to further configure connection pooling in order to optimize the performance of your application. - -:::note - -This document focuses on the connection pooling features of Prisma Postgres. For more information about the internal connection pool of Prisma ORM specifically, see our [ORM connection pooling documentation](/orm/prisma-client/setup-and-configuration/databases-connections/connection-pool). - -::: +Prisma Postgres provides built-in [connection pooling](https://www.prisma.io/dataguide/database-tools/connection-pooling) without you having to configure anything. The efficient management of database connections allows the database to process more queries without exhausting the available database connections, making your application more scalable. ### Connection pooling in Prisma Postgres -Currently, Prisma Postgres allows a maximum of 10 concurrent database connections per Prisma Schema. This limit is typically sufficient due to Prisma Postgres's efficient unikernel-based architecture, which minimizes the need for large connection pools. - -:::note -If you're using **your own database** with Prisma Accelerate, the connection limits differ: +For Prisma Postgres, the connection limit depends on the plan you have signed up for. -- **Free plan**: Maximum of `10` connections. -- **Starter plan**: Maximum of `10` connections. This is often sufficient for most workloads, but if you're expecting high traffic or intensive compute operations, you may want to [increase this limit](#configuring-the-connection-pool-size). -- **Pro plan**: Supports up to `100` concurrent connections. -- **Business plan**: Supports up to `1000` concurrent connections. +| | Free | Starter | Pro | Business | +|---------------------------|------|---------|-----|----------| +| Connection Limit (Pooled) | 10 | 100 | 500 | 1000 | You can compare plans on the [Prisma pricing page](https://www.prisma.io/pricing). -::: - - -### Configuring the connection pool size - -If you're **not using Prisma Postgres**, you can configure the connection pool size for Prisma ORM by specifying it [in the connection string](/orm/prisma-client/setup-and-configuration/databases-connections/connection-pool#setting-the-connection-pool-size). - -For Prisma Postgres, the connection limit is currently **fixed at `10`** and cannot be changed. - -If you're using Prisma Accelerate with your own database, you can configure the connection pool size through the `Connection limit` setting in your project on the [Accelerate setup page](/accelerate/getting-started). -### Configuring the connection pool timeout +### Connection pool timeout The connection pool timeout is the maximum number of seconds that a query will block while waiting for a connection from Prisma Postgres's internal connection pool. This occurs if the number of concurrent requests exceeds the connection limit, resulting in queueing of additional requests until a free connection becomes available. An exception is thrown if a free connection does not become available within the pool timeout. The connection pool timeout can be disabled by setting the value to 0. -Similar to the connection pool size, you may also configure the connection pool timeout via the _database connection string_. To adjust this value, you may add the `pool_timeout` parameter to the database connection string. For example: diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index e74f746867..c3a1f5d5ed 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -10,21 +10,13 @@ sidebar_class_name: preview-badge [Prisma Postgres](/postgres) is a production-grade, cloud-native database and is ideal for staging and production environments. For rapid iteration and isolated testing, you can run a _local_ Prisma Postgres instance (powered by [PGlite](https://pglite.dev)) via the `prisma dev` command. This page explains how to install and launch a local Prisma Postgres database. -:::note - Local Prisma Postgres is in [Preview](/orm/more/releases#preview) and is being actively developed. -::: - ## Setting up local development for Prisma Postgres Follow these steps to set up local Prisma Postgres for development. -:::note - -Please ensure you're running Node.js 20 or later, as it's required for local Prisma Postgres. - -::: +Node.js v20 or later is required for local Prisma Postgres ### 1. Launching local Prisma Postgres @@ -58,16 +50,6 @@ If you want to connect via Prisma ORM, hit h on your keyboard, copy t DATABASE_URL="prisma+postgres://localhost:51213/?api_key=__API_KEY__" ``` -The `DATABASE_URL` is a connection string that Prisma uses to connect to the local Prisma Postgres server and is compatible with the [Prisma Postgres extension](https://www.npmjs.com/package/@prisma/extension-accelerate): - -```ts -import { withAccelerate } from '@prisma/extension-accelerate' - -const prisma = new PrismaClient().$extends(withAccelerate()) -``` - -This ensures no additional code changes are needed when switching from local Prisma Postgres to Prisma Postgres in production. - Keep the local Prisma Postgres server running in the background while you work on your application. ### 2. Applying migrations and seeding data diff --git a/content/250-postgres/300-database/650-direct-connections.mdx b/content/250-postgres/300-database/650-direct-connections.mdx index b63e7f4687..bc258e2ac7 100644 --- a/content/250-postgres/300-database/650-direct-connections.mdx +++ b/content/250-postgres/300-database/650-direct-connections.mdx @@ -8,7 +8,7 @@ toc: true ## Overview -Prisma Postgres is the perfect choice for your applications, whether you connect to it via [Prisma ORM](/orm) or any other ORM, database library / tool of your choice. If you use it with Prisma ORM, Prisma Postgres comes with built-in connection pooling and an integrated caching layer (powered by [Prisma Accelerate](/accelerate/)). +Prisma Postgres is the perfect choice for your applications, whether you connect to it via [Prisma ORM](/orm) or any other ORM, database library / tool of your choice. If you use it with Prisma ORM, Prisma Postgres comes with built-in connection pooling, and an integrated caching layer (powered by [Prisma Accelerate](/accelerate/)). If you connect to it via another tool, you can do so with a [direct connection string](#connection-string) following the conventional PostgreSQL format. @@ -18,10 +18,12 @@ In order to get a direct connection string, you need to: 1. Open a project in your [Prisma Console](https://console.prisma.io) account (or create a new one) 1. Navigate to your active Prisma Postgres instance. -1. Click the **API Keys** tab in the project's sidenav. -1. Click the **Create API key** button. -1. In the popup, provide a **Name** for the API key and click **Create**. -1. Copy the connection string starting with `postgres://`, this is your direct connection string. +1. Click the **Connect to your database** button in your dashboard. +1. Click the **Generate new connection string** button. +1. If enabling connection pooling, click the toggle button +1. Copy the connection string that is generated below. + +![](/img/postgres/connection-string.png) ## Connection string @@ -45,7 +47,7 @@ SSL mode is required when connecting to Prisma Postgres via direct TCP, so you n ## Billing -When using direct TCP to connect to a Prisma Postgres instance, every SQL query is counted as a [billable operation](/postgres/introduction/overview#usage-based-pricing). Learn more on our [pricing page](https://www.prisma.io/pricing). +When using direct TCP to connect to a Prisma Postgres instance, every request is counted as a [billable operation](/postgres/introduction/overview#usage-based-pricing). Learn more on our [pricing page](https://www.prisma.io/pricing). ## Temporary limitations @@ -55,16 +57,12 @@ Prisma Postgres closes idle connections after an extended period of time. If tha ### Connection limit -While direct connections are in Early Access, the following connection limits apply: - | | Free | Starter | Pro | Business | | ------------------------------------ | ---------------- | ---------------- | ---------------- | ---------------- | | **Connection limit** | Max 10 | Max 10 | Max 50 | Max 100 | ### Query and transaction timeouts -While direct connections are in Early Access, the following timeouts apply: - | | Free | Starter | Pro | Business | | ------------------------------------ | ---------------- | ---------------- | ---------------- | ---------------- | | **Query timeout** | Up to 10 seconds | Up to 10 seconds | Up to 10 seconds | Up to 10 seconds | @@ -190,4 +188,4 @@ When using the TCP tunnel, keep the following in mind: - The tunnel does not support schema management (i.e., DDL queries outside of Prisma Migrate). - The tunnel should not be exposed to untrusted networks. - Always store API keys securely and avoid hardcoding them. -- Ensure that only necessary users have direct access to the Prisma Postgres database. \ No newline at end of file +- Ensure that only necessary users have direct access to the Prisma Postgres database. diff --git a/content/250-postgres/300-database/800-api-reference/100-caching-api.mdx b/content/250-postgres/300-database/800-api-reference/100-caching-api.mdx deleted file mode 100644 index eb1c6ebde4..0000000000 --- a/content/250-postgres/300-database/800-api-reference/100-caching-api.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Cache API" -metaTitle: "Prisma Postgres: Cache API Reference" -metaDescription: "Cache API reference documentation for Prisma Postgres." ---- - -## Overview - -The Prisma Postgres API reference documentation is based on the following schema: - -```prisma -model User { - id Int @id @default(autoincrement()) - name String? - email String @unique -} -``` - -All example are based on the `User` model. - -## `cacheStrategy` - -With [the Prisma client extension for Prisma Postgres](https://www.npmjs.com/package/@prisma/extension-accelerate), you can use the `cacheStrategy` parameter for model queries and use the [`ttl`](/postgres/database/caching#time-to-live-ttl) and [`swr`](/postgres/database/caching#stale-while-revalidate-swr) parameters to define a cache strategy for your Prisma Postgres queries. The client extension requires that you install Prisma Client version `4.10.0`. - -### Options - -The `cacheStrategy` parameter takes an option with the following keys: - -| Option | Example | Type | Required | Description | -| ------ | ---------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `swr` | `60` | `Int` | No | The stale-while-revalidate time in seconds. | -| `ttl` | `60` | `Int` | No | The time-to-live time in seconds. | -| `tags` | `["user"]` | `String[]` | No | The `tag` array can control the [invalidation](/accelerate/api-reference#accelerateinvalidate) of cached query results. Each tag can only contain alphanumeric characters and underscores with a maximum length of 64 characters. | - -| - -### Examples - -Add a caching strategy to the query, defining a 60-second stale-while-revalidate (SWR) value, a 60-second time-to-live (TTL) value, and a cache tag of `"emails_with_alice"`: - -```ts -await prisma.user.findMany({ - where: { - email: { - contains: "alice@prisma.io", - }, - }, - // highlight-start - cacheStrategy: { - swr: 60, - ttl: 60, - tags: ["emails_with_alice"], - }, - // highlight-end -}); -``` - -### Supported Prisma Client operations - -The following is a list of all read query operations that support `cacheStrategy`: - -- [`findUnique()`](/orm/reference/prisma-client-reference#findunique) -- [`findUniqueOrThrow()`](/orm/reference/prisma-client-reference#finduniqueorthrow) -- [`findFirst()`](/orm/reference/prisma-client-reference#findfirst) -- [`findFirstOrThrow()`](/orm/reference/prisma-client-reference#findfirstorthrow) -- [`findMany()`](/orm/reference/prisma-client-reference#findmany) -- [`count()`](/orm/reference/prisma-client-reference#count) -- [`aggregate()`](/orm/reference/prisma-client-reference#aggregate) -- [`groupBy()`](/orm/reference/prisma-client-reference#groupby) - - - -The `cacheStrategy` parameter is not supported on any write operations, such as `create()`. - - - -## `withAccelerateInfo` - -Any query that supports the `cacheStrategy` can append `withAccelerateInfo()` to wrap the response data and include additional information about the cached response. - -To retrieve the status of the response, use: - -```ts -const { data, info } = await prisma.user - .count({ - cacheStrategy: { ttl: 60, swr: 600 }, - where: { myField: "value" }, - }) - .withAccelerateInfo(); - -console.dir(info); -``` - -:::info -Notice the `info` property of the response object. This is where the request information is stored. -::: - -### Return type - -The `info` object is of type `AccelerateInfo` and follows the interface below: - -```ts -interface AccelerateInfo { - cacheStatus: "ttl" | "swr" | "miss" | "none"; - lastModified: Date; - region: string; - requestId: string; - signature: string; -} -``` - -| Property | Type | Description | -| -------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `cacheStatus` | `"ttl" \| "swr" \| "miss" \| "none" ` | The cache status of the response.
  • `ttl` indicates a cache hit within the `ttl` duration and no database query was executed
  • `swr` indicates a cache hit within the `swr` duration and the data is being refreshed by Prisma Postgres in the background
  • `miss` indicates that both `ttl` and `swr` have expired and the database query was executed by the request
  • `none` indicates that no cache strategy was specified and the database query was executed by the request
| -| `lastModified` | `Date` | The date the response was last refreshed. | -| `region` | `String` | The data center region that received the request. | -| `requestId` | `String` | Unique identifier of the request. Useful for troubleshooting. | -| `signature` | `String` | The unique signature of the Prisma operation. | - -## `$accelerate.invalidate` - -You can invalidate the cache using the [`$accelerate.invalidate` API](/accelerate/). - -:::note - -To invalidate cached query results on-demand, a paid plan is required. Each plan has specific limits on the number of cache tag-based invalidations allowed per day, though there are no limits on calling the `$accelerate.invalidate` API itself. See our [pricing for more details](https://www.prisma.io/pricing#accelerate). - -::: - -### Example - -To invalidate the query below: - -```ts -await prisma.user.findMany({ - where: { - email: { - contains: "alice@prisma.io", - }, - }, - cacheStrategy: { - swr: 60, - ttl: 60, - // highlight-start - tags: ["emails_with_alice"], - // highlight-end - }, -}); -``` - -You need to provide the cache tag in the `$accelerate.invalidate` API: - -```ts -try { - // highlight-start - await prisma.$accelerate.invalidate({ - tags: ["emails_with_alice"], - }); - // highlight-end -} catch (e) { - if (e instanceof Prisma.PrismaClientKnownRequestError) { - // The .code property can be accessed in a type-safe manner - if (e.code === "P6003") { - console.log("The cache invalidation rate limit has been reached. Please try again later."); - } - } - throw e; -} -``` - -:::note -You can invalidate up to 5 tags per call. -::: - -## `$accelerate.invalidateAll` - -You can invalidate the entire cache using the `$accelerate.invalidateAll` API. - -### Example - -To invalidate the query below: - -```ts -await prisma.user.findMany({ - where: { - email: { - contains: "alice@prisma.io", - }, - }, - cacheStrategy: { - swr: 60, - ttl: 60, - // highlight-start - tags: ["emails_with_alice"], - // highlight-end - }, -}); -``` - -Just call the `$accelerate.invalidateAll` API: - -```ts -try { - // highlight-start - await prisma.$accelerate.invalidateAll(); - // highlight-end -} catch (e) { - if (e instanceof Prisma.PrismaClientKnownRequestError) { - if (e.code === "P6003") { - console.log("The cache invalidation rate limit has been reached. Please try again later."); - } - } - throw e; -} -``` - -### Why use `$accelerate.invalidateAll`? - -This method offers better editor support (e.g. IntelliSense) than alternatives like `invalidate("all")`. - -:::warning - -This clears cache for the entire environmentβ€”use with care. - -::: - -## Errors - -Prisma Postgres-related errors start with `P6xxx`. - -You can find the full error code reference for Prisma Postgres [here](/postgres/database/api-reference/error-reference). diff --git a/content/250-postgres/300-database/800-api-reference/200-error-reference.mdx b/content/250-postgres/300-database/800-api-reference/200-error-reference.mdx index 0b5e253e56..bf55117094 100644 --- a/content/250-postgres/300-database/800-api-reference/200-error-reference.mdx +++ b/content/250-postgres/300-database/800-api-reference/200-error-reference.mdx @@ -88,13 +88,13 @@ This error indicates that Prisma ORM cannot establish a connection to your Prism If the database's server address (hostname) and port are incorrect or unreachable then you may encounter this error. -**Suggested solution:** Verify the hostname/port of the database connection string that was provided while creating the Prisma Accelerate project. Additionally, attempt to connect to the database using a Database GUI tool (e.g., [Prisma Studio](https://www.prisma.io/studio), [TablePlus](https://tableplus.com/), or [DataGrip](https://www.jetbrains.com/datagrip/)) for further investigation. +**Suggested solution:** Verify the hostname/port of the database connection string that was provided while creating the project. Additionally, attempt to connect to the database using a Database GUI tool (e.g., [Prisma Studio](https://www.prisma.io/studio), [TablePlus](https://tableplus.com/), or [DataGrip](https://www.jetbrains.com/datagrip/)) for further investigation. #### Incorrect username/password/database name This error can happen when the wrong credentials are provided, preventing it from establishing a connection to your database. -**Suggested solution:** Verify the correctness of your database's username, password, and name in the connection string provided to Prisma Accelerate. Ensure that these credentials match those required by your database. Testing the connection using a direct database GUI tool can also help in confirming if the provided credentials are correct. +**Suggested solution:** Verify the correctness of your database's username, password, and name in the connection string provided to Prisma Postgres. Ensure that these credentials match those required by your database. Testing the connection using a direct database GUI tool can also help in confirming if the provided credentials are correct. ## [`P5011`](/orm/reference/error-reference#p5011-too-many-requests) (`TooManyRequests`) @@ -109,14 +109,12 @@ If your application retries queries immediately or with minimal delay, especiall **Suggested solution:** - Implement an exponential backoff strategy. Rather than retrying immediately or with a fixed delay, gradually increase the delay period after each failed attempt. -- This allows the system time to recover and reduces the likelihood of overwhelming Prisma Accelerate and your database. #### Sudden traffic spikes Unpredicted traffic surges (for example, during product launches, flash sales, or viral growth events) can cause the threshold to be met and result into `P5011`. **Suggested solution:** -- Consider proactive scaling strategies for both Prisma Accelerate and your database. - Monitor traffic and resource usage. If you anticipate a surge, please contact [support](/platform/support) for capacity planning and potential configuration adjustments. #### Prolonged or planned high workloads diff --git a/content/250-postgres/350-integrations/100-netlify.mdx b/content/250-postgres/350-integrations/100-netlify.mdx index 06a1353719..2fe03aec24 100644 --- a/content/250-postgres/350-integrations/100-netlify.mdx +++ b/content/250-postgres/350-integrations/100-netlify.mdx @@ -47,18 +47,18 @@ Perform the following steps _for every Netlify site_ in which you want to use Pr ### Ensure your project uses the `DATABASE_URL` environment variable -Ensure that the data source in your `schema.prisma` file is configured to use the `DATABASE_URL` environment variable: - -```prisma -// schema.prisma -generator client { - provider = "prisma-client-js" -} - -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} +Ensure that the data source in your `prisma.config.ts` file is configured to use the `DATABASE_URL` environment variable: + +```typescript +// prisma.config.ts +import 'dotenv/config'; +import { defineConfig, env } from '@prisma/config'; +export default defineConfig({ + datasource: { + url: env('DATABASE_URL'), + }, + schema: './prisma/schema.prisma', +}); ``` ### Generate Prisma Client in a `postinstall` script in `package.json` @@ -71,13 +71,12 @@ To ensure the generated Prisma Client library is available on your deployed Netl "scripts": { // ... // add-next-line - "postinstall": "prisma generate --no-engine" + "postinstall": "prisma generate" } // } ``` -The `--no-engine` flag ensures that the query engine binary is kept out of the generated Prisma Client library. It's not needed when using Prisma Postgres. ## Example: Deploy a Next.js template with Prisma Postgres @@ -100,12 +99,13 @@ Once you're done with this, you'll be able to access the deployed version of thi Next, set up a Prisma Postgres instance: -1. Log in to [Prisma Data Platform](https://console.prisma.io/) and open the Console. +1. Log in to [Prisma Platform](https://console.prisma.io/) and open the Console. 1. In a [workspace](/platform/about#workspace) of your choice, click the **New project** button. 1. Type a name for your project in the **Name** field, e.g. **hello-ppg**. 1. In the **Prisma Postgres** section, click the **Get started** button. 1. In the **Region** dropdown, select the region that's closest to your current location, e.g. **US East (N. Virginia)**. 1. Click the **Create project** button. +1. Click the **Connect to your Database** button 1. Save the `DATABASE_URL` environment variable, you'll need it in the next section. ### 3. Locally add Prisma Postgres to the project @@ -130,12 +130,12 @@ In this section, you are going to add Prisma Postgres to the starter project _on 1. Open the newly created `schema.prisma` file and add the following model to it: ```prisma file=schema.prisma generator client { - provider = "prisma-client-js" + provider = "prisma-client" + output = "../src/generated/prisma" } datasource db { provider = "postgresql" - url = env("DATABASE_URL") } // add-start @@ -160,10 +160,14 @@ In this section, you are going to add Prisma Postgres to the starter project _on Open the `app/page.jsx` file and replace the entire contents with this code: -```js file=app/page.jsx -import { PrismaClient } from '@prisma/client' - -const prisma = new PrismaClient(); +```tsx file=app/page.jsx +import 'dotenv/config'; +import { PrismaClient } from '../path/to/generated/prisma/client'; +import { withAccelerate } from '@prisam/extension-accelerate'; +const databaseUrl = process.env.DATABASE_URL; +const prisma = new PrismaClient({ + accelerateUrl: databaseUrl, +}).$extends(withAccelerate()); export default async function Page() { const users = await prisma.user.findMany(); @@ -173,11 +177,17 @@ export default async function Page() {

Users

    {users.length > 0 ? ( - users.map(user => ( + users.map((user) => (
  • -

    ID: {user.id}

    -

    Name: {user.name || 'N/A'}

    -

    Email: {user.email}

    +

    + ID: {user.id} +

    +

    + Name: {user.name || 'N/A'} +

    +

    + Email: {user.email} +

    • )) ) : ( @@ -212,11 +222,11 @@ As mentioned [above](#generate-prisma-client-in-a-postinstall-script-in-packagej "start": "next start", "lint": "next lint", // add-next-line - "postinstall": "prisma generate --no-engine" + "postinstall": "prisma generate" }, "dependencies": { "@netlify/blobs": "^8.1.0", - "@prisma/client": "^6.3.0", + "@prisma/client": "^7.0.0", "@prisma/extension-accelerate": "^1.2.1", "blobshape": "^1.0.0", "bright": "^0.8.5", @@ -232,7 +242,7 @@ As mentioned [above](#generate-prisma-client-in-a-postinstall-script-in-packagej "eslint": "8.57.1", "eslint-config-next": "15.1.6", "postcss": "^8.4.36", - "prisma": "^6.3.0", + "prisma": "^7.0.0", "tailwindcss": "^3.4.1" } } @@ -246,4 +256,4 @@ After having completed these steps, find the **Trigger deploy** button and selec ### 5. Validate the deployment -Open the deployed site by clicking the **Open production deploy** button. You should now see the same UI as you did at the end of step 3 when you were running the app locally. +Open the deployed site by clicking the **Open production deploy** button. You should now see the same UI as you did at the end of step 3 when you were running the app locally. \ No newline at end of file diff --git a/content/250-postgres/350-integrations/200-vercel.mdx b/content/250-postgres/350-integrations/200-vercel.mdx index 106e5264c2..ba1b4962ba 100644 --- a/content/250-postgres/350-integrations/200-vercel.mdx +++ b/content/250-postgres/350-integrations/200-vercel.mdx @@ -6,11 +6,9 @@ tocDepth: 3 toc: true --- -The [Vercel Marketplace integration for Prisma Postgres](https://www.vercel.com/marketplace/prisma) connects your Vercel projects with Prisma Postgres instances. Once connected, the integration will automatically set the following environment variables on your deployed Vercel app: +The [Vercel Marketplace integration for Prisma Postgres](https://www.vercel.com/marketplace/prisma) connects your Vercel projects with Prisma Postgres instances. Once connected, the integration will automatically set the following environment variable on your deployed Vercel app: -`POSTGRES_URL`: The [direct TCP connection URL](/postgres/database/direct-connections) starting with `postgres://...` -`PRISMA_DATABASE_URL`: The connection URL used by Prisma ORM starting with `prisma+postgres://accelerate.prisma-data.net/?api_key=ey...` -`DATABASE_URL`: The [direct TCP connection URL](/postgres/database/direct-connections) starting with `postgres://...` +- `DATABASE_URL`: The [direct TCP connection URL](/postgres/database/direct-connections) starting with `postgres://...` These enable you to connect to the Prisma Postgres instances via any ORM or database library you want to use (Prisma ORM, Drizzle, Kysely, ...). @@ -68,18 +66,17 @@ npx prisma studio ### Ensure your project uses the correct environment variable -Ensure that the data source in your `schema.prisma` file is configured to use the `DATABASE_URL` or `PRISMA_DATABASE_URL` environment variable (depending on which one is being exported in the **Settings** of your Vercel project): - -```prisma -// schema.prisma -generator client { - provider = "prisma-client-js" -} - -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} +Ensure that the data source in your `prisma.config.ts` file is configured to use the `DATABASE_URL` environment variable: + +```ts +import 'dotenv/config'; +import { defineConfig, env } from '@prisma/config'; +export default defineConfig({ + datasource: { + url: env('DATABASE_URL'), + }, + schema: './prisma/schema.prisma', +}); ``` ### Generate Prisma Client in a `postinstall` script in `package.json` @@ -92,10 +89,8 @@ To ensure the generated Prisma Client library is available on your deployed Verc "scripts": { // ... // add-next-line - "postinstall": "prisma generate --no-engine" + "postinstall": "prisma generate" } // } ``` - -The `--no-engine` flag ensures that the query engine binary is kept out of the generated Prisma Client library. It's not needed when using Prisma Postgres. diff --git a/content/250-postgres/400-query-optimization/100-setup.mdx b/content/250-postgres/400-query-optimization/100-setup.mdx index a7a19dd194..314495e553 100644 --- a/content/250-postgres/400-query-optimization/100-setup.mdx +++ b/content/250-postgres/400-query-optimization/100-setup.mdx @@ -39,20 +39,6 @@ Run the following command in your terminal to install the necessary dependencies npm install @prisma/extension-optimize ``` -
    -Enabling tracing in older versions of Prisma ORM - -For versions of Prisma ORM between `4.2.0` and `6.1.0`, you need to enable the `tracing` preview feature in your Prisma schema file. - -```prisma -generator client { - provider = "prisma-client-js" - previewFeatures = ["tracing"] -} -``` - -
    - ### 2.2. Add the Optimize API Key to your `.env` file Copy the Prisma Optimize API key and add it to your `.env` file: @@ -66,8 +52,7 @@ OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY" Extend your existing Prisma Client instance with the Optimize extension: ```ts -import { PrismaClient } from "@prisma/client"; -import { withAccelerate } from "@prisma/extension-optimize"; +import { PrismaClient } from '../path/to/generated/prisma/client'; import { withOptimize } from "@prisma/extension-optimize"; const prisma = new PrismaClient().$extends( diff --git a/content/250-postgres/400-query-optimization/300-recommendations/400-repeated-query.mdx b/content/250-postgres/400-query-optimization/300-recommendations/400-repeated-query.mdx index 2da4c4d17e..ec2f37b1f0 100644 --- a/content/250-postgres/400-query-optimization/300-recommendations/400-repeated-query.mdx +++ b/content/250-postgres/400-query-optimization/300-recommendations/400-repeated-query.mdx @@ -25,10 +25,4 @@ When the same query is executed multiple times with the same parameters within a - **Time waste:** A new connection may be established between the application and database, the query and its parameters are sent to the database, the database processes the query, and the results are sent back to the application. - **Increased resource usage:** Query execution increases CPU and memory usage, as well as disk I/O, putting strain on your database's system resources. -- **Higher costs:** In serverless database pricing models, higher resource usage can result in increased costs. - -:::info - -To learn more about avoiding repeated queries with caching in Prisma Postgres, refer to the [caching documentation](/postgres/database/caching). - -::: \ No newline at end of file +- **Higher costs:** In serverless database pricing models, higher resource usage can result in increased costs. \ No newline at end of file diff --git a/content/250-postgres/50-getting-started/index.mdx b/content/250-postgres/50-getting-started/index.mdx index 9a63cf6c87..797fb2f2b3 100644 --- a/content/250-postgres/50-getting-started/index.mdx +++ b/content/250-postgres/50-getting-started/index.mdx @@ -16,7 +16,6 @@ npx prisma init --db After running this command, the terminal will guide you with next steps. Follow [this page](/getting-started/prisma-postgres/from-the-cli) to complete the setup for your first Prisma Postgres project. -:::note If you need a database quickly for testing, or want to try out Prisma Postgres, you can run the following command to spin up a temporary 24-hour database: ```terminal @@ -24,7 +23,6 @@ npx create-db@latest ``` You can learn more about `npx create-db` in [the dedicated documentation](/postgres/introduction/npx-create-db). -::: ## Prisma ORM @@ -40,16 +38,7 @@ If you are looking to explore Prisma Postgres in a fullstack project, check out ## Connect via any database library / tool -You can access Prisma Postgres with any ORM or database tool of your choice via [direct TCP connections](/postgres/database/direct-connections). - -In order to get a direct TCP connection string, you need to: -1. Navigate to your active Prisma Postgres instance. -1. Click the **API Keys** tab in the project's sidenav. -1. Click the **Create API key** button. -1. In the popup, provide a **Name** for the API key and click **Create**. -1. Copy the connection string starting with `postgres://`, this is your direct connection string. - -Once you have the connection string, you can follow the setup docs for PostgreSQL of any ORM or database tool: +You can access Prisma Postgres with any ORM or database tool of your choice. Once you have the connection string, you can follow the setup docs for PostgreSQL of any ORM or database tool: - [Drizzle ORM](https://orm.drizzle.team/docs/get-started/postgresql-new) - [Kysely](https://kysely.dev/docs/getting-started) diff --git a/static/img/postgres/connection-string.png b/static/img/postgres/connection-string.png new file mode 100644 index 0000000000..19e872cb5c Binary files /dev/null and b/static/img/postgres/connection-string.png differ