diff --git a/apps/docs/content/docs/accelerate/index.mdx b/apps/docs/content/docs/accelerate/index.mdx index bb23c0de9a..af7031590c 100644 --- a/apps/docs/content/docs/accelerate/index.mdx +++ b/apps/docs/content/docs/accelerate/index.mdx @@ -6,15 +6,19 @@ metaTitle: Prisma Accelerate metaDescription: Prisma Accelerate is a global database cache with built-in connection pooling that helps improve database performance in Serverless and Edge applications. --- -[Prisma Accelerate](https://www.prisma.io/accelerate) is a fully managed global connection pool and caching layer for your existing database, enabling query-level cache policies directly from the Prisma ORM. +[Prisma Accelerate](https://www.prisma.io/accelerate) is a managed connection pool and global cache for your database. It works with Prisma ORM and supports PostgreSQL, MySQL, MongoDB, and more. -With 15+ global regions, the connection pool scales your app for a global audience, particularly for serverless deployments that risk connection timeouts during peak times. +Prisma ORM supports connection pooling and query caching through Accelerate — you don't need a separate pooler or caching layer. Accelerate is included with [Prisma Postgres](/postgres) and also available as a standalone add-on for external databases. -Accelerate's global cache, hosted in 300+ locations, ensures a fast experience for users, regardless of your database's location. +**Connection pooling.** Accelerate manages a global connection pool across 15+ regions. This matters most in serverless and edge environments, where connection exhaustion is a real failure mode. Prisma ORM routes through the pool automatically once you swap in the Accelerate connection string. -You can configure query-level caching strategies directly in your code with Prisma ORM, making setup and tuning easy. +**Query caching.** Add a `cacheStrategy` to any Prisma ORM query to cache results at the edge using TTL or stale-while-revalidate. Results are served from 300+ cache locations. No Redis, no Memcached, no separate service. -Together, the connection pool and cache allow you to scale effortlessly and handle traffic spikes without infrastructure concerns. +```typescript title="src/lib/posts.ts" +const posts = await prisma.post.findMany({ + cacheStrategy: { ttl: 60, swr: 10 }, // cache for 60s, revalidate after 10s +}) +``` ## Supported databases diff --git a/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx b/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx index a386f5a8d6..9f5fa435d4 100644 --- a/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx +++ b/apps/docs/content/docs/guides/deployment/cloudflare-workers.mdx @@ -1,17 +1,24 @@ --- title: Cloudflare Workers -description: Learn how to use Prisma ORM in a Cloudflare Workers project +description: Learn how to use Prisma ORM and Prisma Postgres in a Cloudflare Workers project image: /img/guides/prisma-cloudflare-workers-cover.png url: /guides/deployment/cloudflare-workers metaTitle: How to use Prisma ORM and Prisma Postgres with Cloudflare Workers -metaDescription: Learn how to use Prisma ORM in a Cloudflare Workers project +metaDescription: Prisma Postgres works on Cloudflare Workers. Standard PostgreSQL clients use TCP which Cloudflare Workers doesn't support, but Prisma Postgres solves this via Node.js compatibility mode. This guide shows how to set it up. --- ## Introduction -Prisma ORM provides type-safe database access, and [Cloudflare Workers](https://workers.cloudflare.com/) enables you to deploy serverless code at the edge. Together with [Prisma Postgres](https://www.prisma.io/postgres), you get a globally distributed backend with low-latency database access. +**Yes, Prisma Postgres works on Cloudflare Workers.** -In this guide, you'll learn to integrate Prisma ORM with a Prisma Postgres database in a Cloudflare Workers project. You can find a complete example of this guide on [GitHub](https://github.com/prisma/prisma-examples/tree/latest/orm/cloudflare-workers). +Standard PostgreSQL clients (like `pg` or `postgres.js`) use TCP connections, and Cloudflare Workers doesn't support TCP by default. That's why most Postgres databases can't be accessed directly from Workers. There are two ways around it with Prisma Postgres: + +1. **Node.js compatibility mode** — add the `nodejs_compat` flag to your `wrangler.jsonc` and Prisma ORM can use TCP via Cloudflare's Node.js TCP API. That's what this guide does. +2. **Serverless HTTP driver** — the [`@prisma/ppg` driver](/postgres/database/serverless-driver) connects over HTTP instead of TCP. No compatibility flag needed. + +This guide uses the `nodejs_compat` approach. Prisma Postgres handles connection pooling, so you don't have to worry about Workers spinning up a new connection per request. + +You can find a complete example on [GitHub](https://github.com/prisma/prisma-examples/tree/latest/orm/cloudflare-workers). ## Prerequisites @@ -399,10 +406,6 @@ Once deployed, Cloudflare will provide you with a URL where your Worker is live Visit the URL in your browser, and you'll see your Worker creating users in production! -## Summary - -You've successfully created a Cloudflare Workers application with Prisma ORM connected to a Prisma Postgres database. Your Worker is now running at the edge with low-latency database access. - ## Next steps Now that you have a working Cloudflare Workers app connected to a Prisma Postgres database, you can: @@ -411,9 +414,7 @@ Now that you have a working Cloudflare Workers app connected to a Prisma Postgre - Extend your Prisma schema with more models and relationships - Implement authentication and authorization - Use [Hono](https://hono.dev/) for a more robust routing framework with Cloudflare Workers (see our [Hono guide](/guides/frameworks/hono)) - -### More info - -- [Prisma Documentation](/orm) -- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/) -- [Deploy to Cloudflare](/orm/prisma-client/deployment/edge/deploy-to-cloudflare) +- Use the [`@prisma/ppg` serverless driver](/postgres/database/serverless-driver) to connect over HTTP instead of TCP — no `nodejs_compat` flag needed +- [Deploy to Cloudflare](/orm/prisma-client/deployment/edge/deploy-to-cloudflare) — deeper reference on edge deployment options +- [Cloudflare Workers documentation](https://developers.cloudflare.com/workers/) +- [Prisma ORM documentation](/orm) diff --git a/apps/docs/content/docs/guides/postgres/meta.json b/apps/docs/content/docs/guides/postgres/meta.json index e9ee10f36d..2278dec3d2 100644 --- a/apps/docs/content/docs/guides/postgres/meta.json +++ b/apps/docs/content/docs/guides/postgres/meta.json @@ -1,4 +1,4 @@ { "title": "Postgres", - "pages": ["vercel", "netlify", "flyio", "vscode", "idx", "viewing-data"] + "pages": ["vercel", "nextjs-vercel", "netlify", "flyio", "vscode", "idx", "viewing-data"] } diff --git a/apps/docs/content/docs/guides/postgres/nextjs-vercel.mdx b/apps/docs/content/docs/guides/postgres/nextjs-vercel.mdx new file mode 100644 index 0000000000..528e8b03c6 --- /dev/null +++ b/apps/docs/content/docs/guides/postgres/nextjs-vercel.mdx @@ -0,0 +1,254 @@ +--- +title: Next.js on Vercel +description: Add Prisma Postgres to a Next.js project and deploy it to Vercel with no pgBouncer setup or connection string juggling. +url: /guides/postgres/nextjs-vercel +metaTitle: How to use Prisma Postgres with Next.js on Vercel +metaDescription: Learn how to add Prisma Postgres to a Next.js app and deploy it to Vercel. Prisma Postgres includes built-in connection pooling — no pgBouncer setup, no cold-start connection issues. +--- + +## Introduction + +This guide walks you through adding Prisma Postgres to a Next.js app and deploying it to Vercel. + +The main reason Prisma Postgres works well here: it includes connection pooling out of the box. Vercel scales your serverless functions automatically, and each new function instance opens a database connection. With a traditional Postgres setup, that's how you hit connection limits in production. Prisma Postgres handles the pooling for you, so you don't need to configure pgBouncer or maintain a separate pooler. + +You get a single `DATABASE_URL` that works in local dev, in preview deployments, and in production. + +If you'd rather not manage the connection string at all, the [Vercel Marketplace integration](/guides/postgres/vercel) sets `DATABASE_URL` automatically across all your environments. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19+, v22.12+, or v24.0+ +- A [Vercel](https://vercel.com) account + +## 1. Create a Next.js app + +Run `create-next-app` to scaffold a new project: + +```npm +npx create-next-app@latest my-app +``` + +When prompted, select the defaults (TypeScript, ESLint, Tailwind CSS, App Router, Turbopack). Then navigate into the project: + +```bash +cd my-app +``` + +## 2. Add Prisma Postgres + +### Option A: Quickstart with a template + +The fastest way to get started is to scaffold a new project with Prisma ORM and Prisma Postgres already wired up: + +```npm +npm create prisma@latest -- --template next +``` + +This sets up your schema, generates the client, and creates a Prisma Postgres database in one command. Skip to [step 5](#5-query-from-a-server-component) if you use this path. + +### Option B: Add to an existing project + +Install the Prisma CLI and client: + +```npm +npm install prisma tsx --save-dev +``` + +```npm +npm install @prisma/client @prisma/adapter-pg dotenv pg +``` + +Initialize Prisma: + +```npm +npx prisma init --output ../app/generated/prisma +``` + +This creates a `prisma/schema.prisma` file, a `prisma.config.ts` file, and a `.env` file with a placeholder `DATABASE_URL`. + +Now create a Prisma Postgres database and replace the `DATABASE_URL` in your `.env` file with the connection string from the output: + +```npm +npx create-db +``` + +:::info + +The `DATABASE_URL` from Prisma Postgres already includes connection pooling. You do not need to add a separate pooler URL or configure pgBouncer. + +::: + +## 3. Define your Prisma schema + +Open `prisma/schema.prisma` and add a `User` model: + +```prisma title="prisma/schema.prisma" +generator client { + provider = "prisma-client" + output = "../app/generated/prisma" +} + +datasource db { + provider = "postgresql" +} + +model User { // [!code ++] + id Int @id @default(autoincrement()) // [!code ++] + email String @unique // [!code ++] + name String? // [!code ++] +} // [!code ++] +``` + +## 4. Run migrations and generate Prisma Client + +### 4.1. Configure `prisma.config.ts` + +Update `prisma.config.ts` to load your `.env` file: + +```typescript title="prisma.config.ts" +import "dotenv/config"; // [!code ++] +import { defineConfig, env } from "prisma/config"; + +export default defineConfig({ + schema: "prisma/schema.prisma", + migrations: { + path: "prisma/migrations", + }, + datasource: { + url: env("DATABASE_URL"), + }, +}); +``` + +### 4.2. Run migrations + +Create the database tables: + +```npm +npx prisma migrate dev --name init +``` + +### 4.3. Generate Prisma Client + +```npm +npx prisma generate +``` + +## 5. Query from a Server Component + +### 5.1. Create a shared Prisma Client instance + +Create `lib/prisma.ts` with the global singleton pattern to prevent multiple client instances during Next.js hot reloads: + +```typescript title="lib/prisma.ts" +import { PrismaClient } from "../app/generated/prisma/client"; +import { PrismaPg } from "@prisma/adapter-pg"; + +const globalForPrisma = global as unknown as { prisma: PrismaClient }; + +const adapter = new PrismaPg({ + connectionString: process.env.DATABASE_URL!, +}); + +const prisma = + globalForPrisma.prisma || new PrismaClient({ adapter }); + +if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma; + +export default prisma; +``` + +### 5.2. Use it in a Server Component + +Replace the contents of `app/page.tsx`: + +```tsx title="app/page.tsx" +import prisma from "@/lib/prisma"; + +export default async function Home() { + const users = await prisma.user.findMany(); + + return ( +
+

Users

+ +
+ ); +} +``` + +You can query from a Route Handler in the same way: + +```typescript title="app/api/users/route.ts" +import { NextResponse } from "next/server"; +import prisma from "@/lib/prisma"; + +export async function GET() { + const users = await prisma.user.findMany(); + return NextResponse.json(users); +} +``` + +## 6. Deploy to Vercel + +### 6.1. Add a `postinstall` script + +Vercel runs `npm install` (or the equivalent) on every deploy. Add a `postinstall` script to ensure Prisma Client is generated after dependencies are installed: + +```json title="package.json" +{ + "scripts": { + "dev": "next dev --turbopack", + "build": "next build", + "postinstall": "prisma generate", // [!code ++] + "start": "next start", + "lint": "next lint" + } +} +``` + +### 6.2. Deploy + +Install the Vercel CLI and log in: + +```npm +npm install -g vercel +``` + +```bash +vercel login +``` + +Then deploy: + +```bash +vercel --prod +``` + +### 6.3. Set the `DATABASE_URL` environment variable + +After deploying, add your `DATABASE_URL` to the Vercel project's environment variables: + +1. Open your project in the [Vercel dashboard](https://vercel.com/dashboard) +2. Go to **Settings → Environment Variables** +3. Add `DATABASE_URL` with your Prisma Postgres connection string + +Redeploy after saving for the variable to take effect. + +:::info + +If you use the [Vercel Marketplace integration for Prisma Postgres](/guides/postgres/vercel), the `DATABASE_URL` is set automatically for all environments — no manual copy-paste required. + +::: + +## Next steps + +- [Vercel Marketplace integration](/guides/postgres/vercel) — create and connect Prisma Postgres databases without leaving the Vercel dashboard +- [Connection pooling](/postgres/database/connection-pooling) — learn how Prisma Postgres handles pooling internally +- [Prisma Studio](/studio) — inspect and edit your data visually +- [Next.js guide](/guides/frameworks/nextjs) — covers seeding, detail pages, forms, and more diff --git a/apps/docs/content/docs/postgres/index.mdx b/apps/docs/content/docs/postgres/index.mdx index dbfdbb4397..49bd09ec32 100644 --- a/apps/docs/content/docs/postgres/index.mdx +++ b/apps/docs/content/docs/postgres/index.mdx @@ -6,9 +6,18 @@ metaTitle: Overview | Prisma Postgres metaDescription: Learn everything you need to know about Prisma Postgres. --- -[Prisma Postgres](https://www.prisma.io/postgres?utm_source=docs) is a managed PostgreSQL service built for modern app development. +[Prisma Postgres](https://www.prisma.io/postgres?utm_source=docs) is a managed PostgreSQL database with built-in connection pooling, query caching, and edge runtime support. Use this page to choose a connection path and get started quickly. +## What's included + +Everything below is included with every Prisma Postgres database. No extra services to configure. + +- **Connection pooling** — A dedicated PgBouncer instance runs alongside your database. You don't need to set one up or manage it. Works automatically for serverless and edge deployments. See [Connection pooling](/postgres/database/connection-pooling). +- **Query caching** — Add a `cacheStrategy` to any Prisma ORM query to cache results at the edge, using TTL or stale-while-revalidate. See [Caching](/accelerate/caching). +- **Edge and serverless support** — Connect from Cloudflare Workers, Vercel Edge Functions, and other edge runtimes via the [serverless driver](/postgres/database/serverless-driver), which uses HTTP instead of TCP. +- **Automated backups** — Daily backups with point-in-time recovery. See [Backups](/postgres/database/backups). + ## Getting started ### Create a database