diff --git a/content/300-accelerate/200-getting-started.mdx b/content/300-accelerate/200-getting-started.mdx index fa0a24042f..5a7b36af62 100644 --- a/content/300-accelerate/200-getting-started.mdx +++ b/content/300-accelerate/200-getting-started.mdx @@ -1,7 +1,7 @@ --- title: 'Getting started' -metaTitle: 'Getting started with Accelerate' -metaDescription: 'Learn how to get up and running with Accelerate.' +metaTitle: 'Getting started with Prisma Accelerate' +metaDescription: 'Learn how to get up and running with Prisma Accelerate.' tocDepth: 3 toc: true --- @@ -14,52 +14,46 @@ toc: true To get started with Accelerate, you will need the following: -- A GitHub account. +- A [Prisma Data Platform workspace](https://console.prisma.io). - A project that uses [Prisma Client](/orm/prisma-client) `4.16.1` or higher. If your project is using interactive transactions, you need to use `5.1.1` or higher. (We always recommend using the latest version of Prisma.) - A hosted PostgreSQL, MySQL/MariaDB, PlanetScale, CockroachDB, or MongoDB database. -## 1. Enable Accelerate in a project +## 1. Enable Accelerate -In order to enable Accelerate, you can log in to [Prisma Data Platform](https://pris.ly/pdp) and create a new project. Follow the instructions in the UI to add Accelerate. +Navigate to your Prisma Data Platform project, choose an environment, and enable Accelerate by providing your database connection string and selecting the region nearest your database. -At the end of the setup process, you'll obtain a connection string that connects to Accelerate. This connection string also contains an API key that you need to use when configuring Prisma Client to use Accelerate. - -## 2. Use Accelerate in your application + -To get started using Accelerate, we recommend using the [latest version of Prisma ORM](https://github.com/prisma/prisma/releases/). +If you require IP allowlisting or firewall configurations with trusted IP addresses, enable Static IP for enhanced security -### 2.1. Update your database connection string - -After enabling Accelerate in your project and creating a new API key, you should be given an Accelerate connection string. + -To use this connection string, update the `datasource` block's `url` field in your Prisma schema: +## 2. Add Accelerate to your application -```prisma -datasource db { - provider = "postgresql" - url = env("DATABASE_URL") -} -``` +### 2.1. Update your database connection string -Most likely, as shown above, your database connection string in defined in a `.env` file rather than hard-coded into the schema file. +Once enabled, you'll be prompted to generate an API key that you'll use in your new Accelerate connection string to authenticate requests. -Update that variable to use the new Accelerate connection string: +Replace your direct database url with your new Accelerate connection string. ```env file=.env -# __API_KEY__ is a unique API key that Accelerate generates and automatically assigns to a project. +# New Accelerate connection string with generated API_KEY DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__" -# Previous connection string +# Previous (direct) database connection string # DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public" ``` -Prisma Migrate and Introspection do not work with a `prisma://` connection string. In order to continue using these features add a new variable to the `.env` file named `DIRECT_DATABASE_URL` whose value is the direct database connection string: +Your updated connection string will be used as the datasource `url` in your Prisma schema file; - - -As of Prisma version `5.2.0` you can use Prisma Studio with the Accelerate connection string. +```prisma +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} +``` - +Prisma Migrate and Introspection do not work with a `prisma://` connection string. In order to continue using these features add a new variable to the `.env` file named `DIRECT_DATABASE_URL` whose value is the direct database connection string: ```env file=.env highlight=3;add DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__" @@ -82,10 +76,16 @@ Migrations and introspections will use the `directUrl` connection string rather ### 2.2. Install the Accelerate Prisma Client extension -Run the following command to install the Accelerate extension for Prisma Client: + + +💡 Accelerate requires [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-accelerate`](https://www.npmjs.com/package/@prisma/extension-accelerate) version `1.0.0` or higher + + + +Install the latest version of Prisma Client and Accelerate Prisma Client extension ```terminal -npm install @prisma/extension-accelerate +npm install @prisma/client@latest @prisma/extension-accelerate ``` ### 2.3. Generate Prisma Client for Accelerate @@ -122,10 +122,9 @@ If your Prisma version is below `5.0.0`, generate Prisma Client with the `--data -### 2.4. Extend your Prisma Client instance to add the Accelerate extension +### 2.4. Extend your Prisma Client instance with the Accelerate extension -To use Accelerate, you must extend Prisma Client with the Accelerate extension. -Extend your Prisma Client instance to add the Accelerate extension: +Add the following to extend your existing Prisma Client instance with the Accelerate extension: ```ts import { PrismaClient } from '@prisma/client' @@ -192,3 +191,9 @@ You should now see improved performance for your cached queries. For information about which strategy best serves your application, see [Select a cache strategy](/accelerate/caching#selecting-a-cache-strategy). + + + +As of Prisma version `5.2.0` you can use Prisma Studio with the Accelerate connection string. + + diff --git a/content/300-accelerate/580-local-development.mdx b/content/300-accelerate/580-local-development.mdx index ece970a8f4..b771d2dd20 100644 --- a/content/300-accelerate/580-local-development.mdx +++ b/content/300-accelerate/580-local-development.mdx @@ -8,7 +8,7 @@ toc: true -Prisma Accelerate is designed to scale database connections efficiently in production environments. Prisma Accelerate also provides a global cache to reduce the load on your database and reduce query response time. To leverage Prisma Accelerate, it is essential to utilize a publicly accessible database. +Prisma Accelerate efficiently scales production traffic with integrated connection pooling and a global database cache. In development environments, you may want to use a local database to minimize expenses. Furthermore, you may consider extending Prisma Client with the Accelerate client extension once so that you can use a local database in development and a hosted database with Accelerate’s connection pooling and caching enabled. This eliminates the need for conditional logic to switch clients between development and production. diff --git a/content/300-accelerate/600-faq.mdx b/content/300-accelerate/600-faq.mdx index 9aa920820e..877b449176 100644 --- a/content/300-accelerate/600-faq.mdx +++ b/content/300-accelerate/600-faq.mdx @@ -8,6 +8,18 @@ toc: true Below are frequently asked questions about Accelerate. +## When should I enable static IP for Prisma Accelerate? + +A static IP address is an IPv4 or an IPv6 address that is fixed. Unlike dynamic IP addresses, which can change unpredictably, traffic from static IP addresses can be easily identified. Enable static IP for Accelerate when your security setup requires IP allowlisting or if you're implementing firewalls that only permit access from trusted IPs, ensuring controlled and secure database connections. + +![What is a static IP](./images/static-ip.png) + +For databases using IP allowlisting, enable static IP for Accelerate in your specified project environment, and add the obtained IP address to your database's allowlist to ensure authorized access from Accelerate. + +![](./images/result-of-adding-static-ip-to-accelerate.png) + +> ℹ️ To enable static IP support for Accelerate within your existing or new project environment, your workspace will need to be on our **Pro** or **Business** plans. Take a look at the [pricing page](https://www.prisma.io/pricing) for more information. + ## Why do I sometimes see unexpected cache behavior? Accelerate's cache performs best when it observes a higher load from a project. Many cache operations, such as committing data to cache and refreshing stale data, happen asynchronously. When benchmarking Accelerate, we recommend doing so with loops or a load testing approach. This will mimic higher load scenarios better and reduce outliers from low frequency operations. diff --git a/content/300-accelerate/650-troubleshoot.mdx b/content/300-accelerate/650-troubleshoot.mdx index 716fd69b47..4e4031d99f 100644 --- a/content/300-accelerate/650-troubleshoot.mdx +++ b/content/300-accelerate/650-troubleshoot.mdx @@ -110,9 +110,9 @@ This error indicates that Prisma Accelerate cannot establish a connection to you #### Database Not Publicly accessible -Prisma Accelerate currently requires the database to be publicly accessible. If your database is behind a VPC, or access is restricted to specific IP addresses, this error may occur. +If your database is behind a VPC, or access is restricted to specific IP addresses, this error may occur. -**Suggested solution:** Ensure your database is publicly accessible, if not, allow public access. Please note this is only an interim requirement, Static IPs are coming soon and will alleviate the need for complete public access if that’s not desirable. +**Suggested solution:** Enable static IP within your Accelerate configuration in your project environment. After you enable static IP, add the obtained IP address in your database firewall's IP allowlist. This will ensure that Accelerate can connect to your database. To learn more about static IP, see this [FAQ](/accelerate/faq#when-do-i-have-to-enable-static-ip-for-prisma-accelerate). #### Unreachable Database Host/Port diff --git a/content/300-accelerate/images/result-of-adding-static-ip-to-accelerate.png b/content/300-accelerate/images/result-of-adding-static-ip-to-accelerate.png new file mode 100644 index 0000000000..5c33efcc6f Binary files /dev/null and b/content/300-accelerate/images/result-of-adding-static-ip-to-accelerate.png differ diff --git a/content/300-accelerate/images/static-ip.png b/content/300-accelerate/images/static-ip.png new file mode 100644 index 0000000000..7d3259dc85 Binary files /dev/null and b/content/300-accelerate/images/static-ip.png differ diff --git a/content/400-pulse/200-getting-started.mdx b/content/400-pulse/200-getting-started.mdx index 3b44e8999b..7d52dd1971 100644 --- a/content/400-pulse/200-getting-started.mdx +++ b/content/400-pulse/200-getting-started.mdx @@ -16,7 +16,7 @@ toc: true -You'll need the following to integrate Pulse into your application: +To get started with Pulse, you will need the following: - A [Prisma Data Platform workspace](https://console.prisma.io). - [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-pulse`](https://www.npmjs.com/package/@prisma/extension-pulse) version `1.0.1` or higher.