From 9aa602de86b7886d1f99dbaff823e759638cf682 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Fri, 9 May 2025 15:32:29 +0600 Subject: [PATCH 01/26] [6.8]feat: docs release --- .../005-introduction.mdx | 11 - .../301-edge/550-deploy-to-deno-deploy.mdx | 24 +- .../200-prisma-cli-reference.mdx | 36 +++ .../050-client-preview-features.mdx | 3 +- .../350-ai-tools/400-github-copilot.mdx | 225 ++++++++++++++++++ .../200-editor-setup.mdx | 7 + .../1100-integrations/400-mcp-server.mdx | 7 + .../1100-integrations/500-vscode-agent.mdx | 57 +++++ .../300-database/550-local-development.mdx | 125 ++++++++++ 9 files changed, 471 insertions(+), 24 deletions(-) create mode 100644 content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx create mode 100644 content/250-postgres/1100-integrations/500-vscode-agent.mdx create mode 100644 content/250-postgres/300-database/550-local-development.mdx diff --git a/content/200-orm/200-prisma-client/000-setup-and-configuration/005-introduction.mdx b/content/200-orm/200-prisma-client/000-setup-and-configuration/005-introduction.mdx index 061779c21d..e7520935fd 100644 --- a/content/200-orm/200-prisma-client/000-setup-and-configuration/005-introduction.mdx +++ b/content/200-orm/200-prisma-client/000-setup-and-configuration/005-introduction.mdx @@ -138,17 +138,6 @@ const prisma = new PrismaClient() > **Note**: If you're using [driver adapters](/orm/overview/databases/database-drivers#driver-adapters), you can import from the location spefified in your generator's `output` path directly, e.g. `./src/generated/prisma`. No need to import from `./src/generated/prisma/edge`. -For Deno, you can import Prisma Client as follows: - -```ts file=lib/prisma.ts -import { PrismaClient } from './generated/prisma/deno/edge.ts' - -const prisma = new PrismaClient() -// use `prisma` in your application to read and write data in your DB -``` - -The import path will depend on the custom `output` specified in Prisma Client's [`generator`](/orm/reference/prisma-schema-reference#generator) block in your Prisma schema. - ### 4. Use Prisma Client to send queries to your database Once you have instantiated `PrismaClient`, you can start sending queries in your code: diff --git a/content/200-orm/200-prisma-client/500-deployment/301-edge/550-deploy-to-deno-deploy.mdx b/content/200-orm/200-prisma-client/500-deployment/301-edge/550-deploy-to-deno-deploy.mdx index f2c1ab874b..0ad4f8d407 100644 --- a/content/200-orm/200-prisma-client/500-deployment/301-edge/550-deploy-to-deno-deploy.mdx +++ b/content/200-orm/200-prisma-client/500-deployment/301-edge/550-deploy-to-deno-deploy.mdx @@ -47,14 +47,17 @@ This command: - Creates a `prisma` directory containing a `schema.prisma` file for your database models. - Creates a `.env` file with your `DATABASE_URL` (e.g., for Prisma Postgres it should have something similar to `DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."`). -Edit the `prisma/schema.prisma` file to define a `Log` model, add a custom `output` path and enable the `deno` preview feature flag: +Edit the `prisma/schema.prisma` file to define a `Log` model, add a custom `output` path and [the `prisma-client` generator](/orm/prisma-schema/overview/generators#prisma-client-early-access) with `deno` as the `runtime`: ```prisma file=schema.prisma highlight=3-4,12-23;add showLineNumbers generator client { + // delete-start provider = "prisma-client-js" + // delete-end //add-start - previewFeatures = ["deno"] - output = "../generated/client" + provider = "prisma-client" + output = "../generated/prisma" + runtime = "deno" //add-end } @@ -79,13 +82,11 @@ enum Level { //add-end ``` -:::note +Then, install Prisma Client: -To use Deno, you need to add the preview feature flag `deno` to the `generator` block of your `schema.prisma` file. - -Deno also requires you to generate Prisma Client in a custom location. You can enable this with the `output` parameter in the `generator` block. - -::: +```terminal +deno install npm:@prisma/client +``` Then, install [the Client extension](https://www.npmjs.com/package/@prisma/extension-accelerate) required to use Prisma Postgres: @@ -121,7 +122,7 @@ You can now create a local Deno application. Create `index.ts` in the root folde ```ts file=index.ts import { serve } from "https://deno.land/std@0.140.0/http/server.ts"; import { withAccelerate } from "npm:@prisma/extension-accelerate"; -import { PrismaClient } from "./generated/client/deno/edge.ts"; +import { PrismaClient } from "./generated/prisma/client.ts"; const prisma = new PrismaClient().$extends(withAccelerate()); @@ -208,6 +209,7 @@ Use the GitHub repository to add your application to Deno Deploy: 1. Go to [https://dash.deno.com/](https://dash.deno.com/). 1. Select a GitHub organization or user and then select a repository. 1. Select a production branch and select **Fresh (Automatic)** mode so that Deno Deploy can deploy every time you push a change to the repository. +1. In the **Build Step** add `deno run -A npm:prisma generate` to generate the Prisma Client. 1. Select `index.ts` as the entry point to your project. 1. Click `Create & Deploy`. @@ -227,7 +229,7 @@ Add the following code in your `index.ts` file: ```ts file=index.ts import { serve } from "https://deno.land/std@0.140.0/http/server.ts"; import { withAccelerate } from "npm:@prisma/extension-accelerate"; -import { PrismaClient } from "./generated/client/deno/edge.ts"; +import { PrismaClient } from "./generated/prisma/client.ts"; const prisma = new PrismaClient().$extends(withAccelerate()); diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index 31112e07cc..37bbd6e3df 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -328,6 +328,42 @@ A file to define environment variables for your project: DATABASE_URL="mysql://user:password@localhost:3306/mydb" ``` +### `dev` + +The `dev` command starts a local [PGlite server](https://pglite.dev/) that you can run Prisma ORM commands against. It is useful for development and testing purposes and also allows you to switch to [Prisma Postgres](/postgres) easily. You can learn more about the PGlite server [in this section](/postgres/database/local-development). + +#### Examples + +**Run `prisma dev`** + + + + + +```terminal +prisma dev +``` + + + + + +```code no-copy wrap +Starting Prisma Dev... + + +Great Success! + +To connect to your local Prisma Postgres database via Prisma ORM, use the following connection string: + + DATABASE_URL="prisma+postgres://localhost:5433/?dbname=default&dbport=5432&dbuser=postgres" + +``` + + + + + ### `generate` The `generate` command generates assets like Prisma Client based on the [`generator`](/orm/prisma-schema/overview/generators) and [`data model`](/orm/prisma-schema/data-model/models) blocks defined in your `prisma/schema.prisma` file. diff --git a/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx b/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx index 861056000a..fb720d6b28 100644 --- a/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx +++ b/content/200-orm/500-reference/500-preview-features/050-client-preview-features.mdx @@ -21,7 +21,6 @@ The following [Preview](/orm/more/releases#preview) feature flags are available | [`metrics`](/orm/prisma-client/observability-and-logging/metrics) | [3.15.0](https://github.com/prisma/prisma/releases/tag/3.15.0) | [Submit feedback](https://github.com/prisma/prisma/issues/13579) | | [`multiSchema`](https://github.com/prisma/prisma/issues/1122#issuecomment-1231773471) | [4.3.0](https://github.com/prisma/prisma/releases/tag/4.3.0) | [Submit feedback](https://github.com/prisma/prisma/issues/15077) | | [`postgresqlExtensions`](/orm/prisma-schema/postgresql-extensions) | [4.5.0](https://github.com/prisma/prisma/releases/tag/4.5.0) | [Submit feedback](https://github.com/prisma/prisma/issues/15835) | -| [`deno`](/orm/prisma-client/deployment/edge/deploy-to-deno-deploy) | [4.5.0](https://github.com/prisma/prisma/releases/tag/4.5.0) | [Submit feedback](https://github.com/prisma/prisma/issues/15844) | | [`views`](/orm/prisma-schema/data-model/views) | [4.9.0](https://github.com/prisma/prisma/releases/tag/4.9.0) | [Submit feedback](https://github.com/prisma/prisma/issues/17335) | | `driverAdapters` | [5.4.0](https://github.com/prisma/prisma/releases/tag/5.4.0) | [Submit feedback](https://github.com/prisma/prisma/issues/3108) | | `relationJoins` | [5.7.0](https://github.com/prisma/prisma/releases/tag/5.7.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/22288) | @@ -30,7 +29,7 @@ The following [Preview](/orm/more/releases#preview) feature flags are available | `strictUndefinedChecks` | [5.20.0](https://github.com/prisma/prisma/releases/tag/5.20.0) | [Submit feedback](https://github.com/prisma/prisma/discussions/25271) | | [`fullTextSearchPostgres`](/orm/prisma-client/queries/full-text-search) | [6.0.0](https://github.com/prisma/prisma/releases/tag/6.0.0) | [Submit feedback](https://github.com/prisma/prisma/issues/25773) | | [`prisma-client`](/orm/prisma-schema/overview/generators#prisma-client-early-access) | [6.6.0](https://pris.ly/release/6.6.0) | [Submit feedback](https://github.com/prisma/prisma/issues/25773) | -| `queryCompiler` | [6.7.0](https://pris.ly/release/6.7.0) | [Submit feedback](https://github.com/prisma/prisma/issues/tbd) | +| `queryCompiler` | [6.7.0](https://pris.ly/release/6.7.0) | [Submit feedback](https://github.com/prisma/prisma/issues/) | To enable a Preview feature, [add the feature flag to the `generator` block](#enabling-a-prisma-client-preview-feature) in your `schema.prisma` file. [Share your feedback on all Preview features on GitHub](https://github.com/prisma/prisma/issues/3108). diff --git a/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx b/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx new file mode 100644 index 0000000000..81e3f834dc --- /dev/null +++ b/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx @@ -0,0 +1,225 @@ +--- +title: 'GitHub Copilot' +metaTitle: 'Prisma ORM with GitHub Copilot' +metaDescription: 'Learn about the features available with GitHub Copilot and Prisma ORM, plus best practices and tips.' +tocDepth: 3 +toc: true +--- + +GitHub Copilot is an AI coding assistant that speeds up your Prisma ORM workflows, so you spend less time on boilerplate and more on data modeling, querying, and collaboration. With the GitHub Copilot extension for Prisma in VS Code, you can: + +- Get Prisma-aware code suggestions as you edit your schema or invoke the client. +- Chat with Copilot about modeling patterns, troubleshoot queries, or explore migration strategies. +- Run common Prisma CLI commands (e.g. `prisma migrate dev`, `prisma db push`) via Copilot's command-palette interface. +- Scaffold Prisma schema models and generate Prisma Client code and run migrations directly from the Copilot chat interface. + +GitHub Copilot allows you to query the official docs and also perform automated [actions in VS Code Agent mode](/postgres/integrations/vscode-agent), such as scaffolding a Prisma schema, running seeds scripts, and creating a production-ready Prisma Postgres database. + +## Query Prisma docs with the Prisma for Copilot extension + +The Prisma for Copilot extension lets you fetch Prisma documentation directly in GitHub Copilot Chat. You can look up schema syntax, client methods, migration commands, and more from your editor. + +### How to enable the extension + +1. Install the **Prisma for Copilot** from the GitHub Marketplace. +2. Ensure [GitHub Copilot Chat is installed](https://docs.github.com/en/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide) and active in your code editor. +3. Open a file in your workspace and launch Copilot Chat. +4. In chat, prefix your question with the `@prisma-for-copilot` keyword: + +```bash +@prisma-for-copilot How do I define a one-to-many relation? +``` + +## Use GitHub Copilot's agent features + +GitHub Copilot Chat offers an **Agent** mode in VS Code that can run Prisma commands. You can use the agent chat to: + +- Run and inspect migrations. +- Generate Prisma Client code. +- Create a new Prisma Postgres database and update your `.env` file. + +You can type `Create a database named test-db and add its connection string to the .env file.` in the Copilot chat, and it will automatically create a new database named `test-db` and add the connection string to your `.env` file. To learn more about this, visit our [VS Code agent mode documentation](/postgres/integrations/vscode-agent). + +## Customize GitHub Copilot with `copilot-instructions.md` + +You can tailor Copilot Chat's behavior in your repository by [adding a `.github/copilot-instructions.md` file](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot). This file injects your guidelines into every Copilot Chat session. + +
+Example `.github/copilot-instructions.md` for Prisma + +```text +# GitHub Copilot Instructions for Prisma Workspace + +## General Guidelines + +1. **Language**: English only. +2. **Types**: Declare explicit types; avoid `any`. +3. **Comments**: Use JSDoc for public methods and classes. +4. **Exports**: One export per file. +5. **Naming**: + + * **Classes/interfaces** → `PascalCase` + * **Variables/functions** → `camelCase` + * **Files/directories** → `kebab-case` + * **Constants** → `UPPERCASE` + * **Boolean flags** → verb-based (e.g., `isLoading`) + +--- + +## Prisma-Specific Guidelines + +### 1. Data Modeling + +* **Domain-driven model names**: keep them singular (e.g. `User`, `OrderItem`). +* **Field naming**: use `camelCase` for fields (e.g. `createdAt`, `deletedAt`). +* **IDs & keys**: + + ```prisma + model Post { + id Int @id @default(autoincrement()) + uuid String @unique @default(uuid()) + } + /``` +* **Composite keys & uniques**: + + ```prisma + @@id([userId, role]) + @@unique([email, tenantId]) + /``` +* **Enums & constrained values**: leverage `enum` for fixed domains. +* **Soft deletes & audit**: + + ```prisma + model Base { + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + deletedAt DateTime? + } + /``` + +### 2. Indexing & Constraints + +* **Single-column indexes** for frequent lookups: + + ```prisma + @@index([email]) + /``` +* **Compound indexes** for multi-field filters/sorts: + + ```prisma + @@index([status, createdAt]) + /``` +* **Full-text search** (Postgres-only): + + ```prisma + @@index([title, content], type: Brin) // or Gin for JSONB + /``` + +### 3. Migrations + +* **Descriptive names**: `npx prisma migrate dev --name add-order-totals` +* **Idempotent steps**: avoid imperative SQL in migrations. +* **Shadow database**: enable in CI to catch drift. +* **Never edit** migration SQL after it’s applied to any environment. + +### 4. Client Instantiation & Connection Management + +* **Singleton pattern** + + ```ts + // prisma.ts + import { PrismaClient } from '@prisma/client'; + export const prisma = global.prisma || new PrismaClient(); + if (process.env.NODE_ENV !== 'production') global.prisma = prisma; + /``` + +### 5. Transactions & Batch Operations + +* **Multi-step atomicity**: + + ```ts + const result = await prisma.$transaction([ + prisma.user.create({ data: { /*…*/ } }), + prisma.order.create({ data: { /*…*/ } }), + ]); + /``` +* **Interactive transactions** for long-running flows. +* **Bulk writes**: chunk large inserts/updates to avoid timeouts. + +### 6. Precise Queries & Performance + +* **Select only needed fields**: + + ```ts + await prisma.user.findUnique({ + where: { id }, + select: { id: true, email: true }, + }); + /``` +* **Avoid N+1**: use `include` or batch `findMany` with `where: { id: { in: [...] } }` or use database joins in prisma. +* Use **Cursor-based pagination** + +### 7. Raw Queries & Client Extensions + +* **Raw SQL** when necessary, safely: + + ```ts + const users = await prisma.$queryRaw`SELECT * FROM "User" WHERE email = ${email}`; + /``` +* **Sanitize inputs** with `Prisma.sql` for complex interpolations. +* **Client extensions**: use preview feature `clientExtensions` to add common helper methods. + +### 8. Error Handling + +* **Catch specific errors**: + + ```ts + try { + // … + } catch (e) { + if (e instanceof Prisma.PrismaClientKnownRequestError) { + // P2002: Unique constraint + } + } + /``` +* **Wrap in service-level errors** to add context before bubbling up. + +### 9. Testing + +* **In-memory DB** (SQLite) or **Testcontainers** for integration tests. +* **Mock Prisma Client** for pure unit tests via `jest.mock()` or similar. + +### 10. Logging, Monitoring & Metrics + +* **Enable query logging** in dev: + + ```ts + new PrismaClient({ log: ['query', 'warn', 'error'] }); + /``` +* **APM integration** (Datadog, Sentry) – capture latency, errors. +* **Client extensions** for metrics: create extensions that wrap calls to emit timing and telemetry instead of middleware. + +### 11. Security & Best Practices + +* **Never expose** raw Prisma client in HTTP controllers—wrap in a service layer. +* **Validate inputs** (e.g. with Zod) before any DB operation. +* **Least privilege** DB users: use separate roles for migrations vs. runtime. +* **Rotate credentials** and load from secure vault (AWS Secrets Manager, etc.). + +### 12. Environment & Configuration + +* **Centralize `DATABASE_URL`** and connection settings in `.env`. +* **Pin preview features** in `schema.prisma`: + + ```prisma + generator client { + previewFeatures = ["clientExtensions", "interactiveTransactions"] + } + /``` +* **Version pinning**: match CLI and client versions in `package.json`. + +``` + +
+ +Place this file at the root of your repository under `.github/`. Copilot Chat automatically applies these rules to every conversation in your project. diff --git a/content/200-orm/800-more/500-development-environment/200-editor-setup.mdx b/content/200-orm/800-more/500-development-environment/200-editor-setup.mdx index d17879d216..eeeccb8c70 100644 --- a/content/200-orm/800-more/500-development-environment/200-editor-setup.mdx +++ b/content/200-orm/800-more/500-development-environment/200-editor-setup.mdx @@ -17,6 +17,13 @@ If you don't see your editor here, please [open a feature request](https://githu You can install the official [Prisma VS Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma). Once installed, make sure to select the appropriate language model to use it within VS Code. +:::tip + +If you're using VS Code, you can use [VS Code agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) to enter prompts such as “create Postgres database” or “apply schema migration” directly in the chat. The VS code agent handles all underlying Prisma CLI invocations and API calls automatically. See our [VS Code Agent documentation](/postgres/integrations/vscode-agent) for more details. + +::: + + ## Community projects > **Note**: Community projects are not maintained or officially supported by Prisma and some features may by out of sync. Use at your own discretion. diff --git a/content/250-postgres/1100-integrations/400-mcp-server.mdx b/content/250-postgres/1100-integrations/400-mcp-server.mdx index 67cfde24cd..f1ecb6a0f8 100644 --- a/content/250-postgres/1100-integrations/400-mcp-server.mdx +++ b/content/250-postgres/1100-integrations/400-mcp-server.mdx @@ -14,6 +14,13 @@ The Prisma MCP server is available via the Prisma CLI command `prisma platform m ::: +:::tip + +If you're using VS Code, you can use [VS Code agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) to enter prompts such as “create Postgres database” or “apply schema migration” directly in the chat. The VS code agent handles all underlying Prisma CLI invocations and API calls automatically. See our [VS Code Agent documentation](/postgres/integrations/vscode-agent) for more details. + +::: + + ## Usage The Prisma MCP server follows the standard JSON-based configuration for MCP servers. Here's what it looks like: diff --git a/content/250-postgres/1100-integrations/500-vscode-agent.mdx b/content/250-postgres/1100-integrations/500-vscode-agent.mdx new file mode 100644 index 0000000000..15104d11cc --- /dev/null +++ b/content/250-postgres/1100-integrations/500-vscode-agent.mdx @@ -0,0 +1,57 @@ +--- +title: 'VS Code Agent' +description: 'Streamline Prisma ORM workflows, manage migrations, and create databases directly in Visual Studio Code using the Prisma Agent.' +metaTitle: 'Visual Studio Code Agent' +metaDescription: 'Manage Prisma ORM migrations and provision Prisma databases efficiently within Visual Studio Code using the Prisma Agent.' +tocDepth: 3 +toc: true +--- + +## Overview + +[Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) includes an **agent** mode (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. + +## Capabilities + +The [Prisma Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) enables the agent to perform the following tasks using our Model Context Protocol (MCP) server: + +- Manage Prisma Data Platform projects. +- Provision new databases. +- Run migrations and generate the Prisma Client. +- Generate Prisma schemas and client code. +- Execute Prisma commands directly in the terminal. + +This integration removes the need to manually run MCP commands, significantly speeding your database-related workflows. + +## How to enable and use the VS Code agent + +The [latest version of the Prisma VS Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) fully supports agent mode. Since extensions update automatically, no manual action is required to enable it. + +:::note + +We recommend you to use the latest version of Prisma ORM. + +::: + +To use the agent mode: + +1. Open [GitHub Copilot Chat in VS Code and switch to **Agent** mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_use-agent-mode). +2. With GitHub Copilot Chat open and the Prisma extension updated, you can simply type a request such as: "Create a new database for me and add the connection string to the .env file". +3. The agent will request permission to make changes in your workspace. +4. It automatically handles login to your Prisma Data Platform account before proceeding. +5. Upon approval, the agent creates the new database and adds the connection string to your `.env` file. +6. You can also use agent mode to run migrations, generate the Prisma Client, and perform other tasks. + +:::note +Currently, the agent mode uses your default workspace in the Prisma Data Platform. +::: + +## Querying Prisma docs from VS Code using GitHub Copilot + +Complementing the agent, the Prisma Copilot extension allows you to query Prisma documentation directly within VS Code. + +You need to install the [Prisma for Copilot extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) from the GitHub marketplace. + +Then, [switch to **Ask** mode in VS Code](https://code.visualstudio.com/docs/copilot/chat/chat-ask-mode) and type your question using the `@prisma` namespace. + +For more details, refer to our [GitHub Copilot documentation](/orm/more/ai-tools/github-copilot). \ No newline at end of file diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx new file mode 100644 index 0000000000..5e7841d70d --- /dev/null +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -0,0 +1,125 @@ +--- +title: 'Local development' +metaTitle: 'Using Prisma Postgres in a development environment' +metaDescription: 'Guide to setting up local development using Prisma Postgres with PGlite' +tocDepth: 3 +toc: true +--- + +[Prisma Postgres](/postgres) is our production-grade cloud offering, and it is recommended for production and staging setups. + +To simplify your development workflow and make transitioning to production effortless, we've created a local database server compatible with Prisma Postgres, [powered by PGlite](https://pglite.dev/). + +PGlite is a lightweight, in-memory PostgreSQL compatible database packaged as a TypeScript/JavaScript library using WebAssembly ([WASM](https://webassembly.org/)). Learn more in the [PGlite documentation](https://pglite.dev/). + +This guide provides instructions for setting up and running your local Prisma Postgres development environment using the PGlite server. + +## Setting up local development with PGlite + +Follow these steps to integrate PGlite into your local development workflow. + +### 1. Launching the local PGlite server + +Navigate into your project and start the PGlite server using the following command: + +```terminal +npx prisma@latest dev +``` + +This starts a local PGlite server that you can connect to using Prisma Client. The server will run in the background and will be available at `localhost:5433` by default. + +This should give you an output with `DATABASE_URL` that looks like this: + +```bash +Starting Prisma Dev... + + +Great Success! + +To connect to your local Prisma Postgres database via Prisma ORM, use the following connection string: + + DATABASE_URL="prisma+postgres://localhost:5433/?dbname=default&dbport=5432&dbuser=postgres" + +``` + +Copy the `DATABASE_URL` and store it in your `.env` file. This will be used to connect to the PGlite server: + +```bash file=.env +DATABASE_URL="prisma+postgres://localhost:5433/?dbname=default&dbport=5432&dbuser=postgres" +``` + +The `DATABASE_URL` is a connection string that Prisma uses to connect to the PGlite 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 PGlite to Prisma Postgres in production. + +### 2. Applying migrations and seed data + +Then run the `prisma migrate dev` command to create the database and run the migrations: + +```bash +npx prisma migrate dev +``` + +This will create the database and run the migrations. + +If you have a seeder script to seed the database, you should also run it in this step. + +:::note + +Currently, our PGlite server does not persist data. This means that if you stop the server, all data will be lost. Hence have to run the migrations and seeds every time you start the PGlite server by using the npx prisma@latest dev command. See the [limitation section below](#no-data-persistence-between-restarts). + +::: + +### 3. Running your application locally + +Start your application's development server. You can now perform queries against the local PGlite database using Prisma ORM. + +To transition to production, you only need to update the database URL in the `.env` file with a Prisma Postgres connection url without additional application logic changes. + +## Known limitations + +### No data persistence between restarts + +Currently in the local PGlite server, data does not persist after server restart the server. Each time you restart the server (`npx prisma@latest dev`), reapply migrations and seeds: + +```terminal +npx prisma migrate dev +npm run seed +``` + +Persistent storage will be supported in the future. + +### Caching is mocked locally + +[Prisma Postgres caching](/postgres/database/caching) is simulated locally. Queries always directly interact with the PGlite database, bypassing cache configurations: + +```typescript +const users = await prisma.user.findMany({ + cache: { ttl: 60 }, +}); +``` + +Caching works normally in staging and production when you're using Prisma Postgres. + +### Cache invalidation not supported locally + +[Cache invalidation (`$accelerate.invalidate()`)](/postgres/database/api-reference#accelerateinvalidate) is unsupported locally and throws an error. To safely handle this you can use a `try-catch` block: + +```typescript +try { + await prisma.$accelerate.invalidate(); +} catch (e) { + console.error(e); +} +``` + +### Prisma Postgres limitations apply locally + +All Prisma Postgres limitations also apply to local development with PGlite. Refer to the [Prisma Postgres limitations documentation](/postgres/more/known-limitations) for detailed information. + From c991321b38dec5a308f86ba410b9e48e2332a2b1 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:23:27 +0600 Subject: [PATCH 02/26] Update content/250-postgres/1100-integrations/500-vscode-agent.mdx Co-authored-by: Nikolas --- content/250-postgres/1100-integrations/500-vscode-agent.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/content/250-postgres/1100-integrations/500-vscode-agent.mdx b/content/250-postgres/1100-integrations/500-vscode-agent.mdx index 15104d11cc..454ae386f6 100644 --- a/content/250-postgres/1100-integrations/500-vscode-agent.mdx +++ b/content/250-postgres/1100-integrations/500-vscode-agent.mdx @@ -15,7 +15,6 @@ toc: true The [Prisma Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) enables the agent to perform the following tasks using our Model Context Protocol (MCP) server: -- Manage Prisma Data Platform projects. - Provision new databases. - Run migrations and generate the Prisma Client. - Generate Prisma schemas and client code. From dd57944727dc72a5b7bdef84309cf3707ca146c3 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:24:11 +0600 Subject: [PATCH 03/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 5e7841d70d..b545fdbc31 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -1,6 +1,6 @@ --- title: 'Local development' -metaTitle: 'Using Prisma Postgres in a development environment' +metaTitle: 'Local development with Prisma Postgres' metaDescription: 'Guide to setting up local development using Prisma Postgres with PGlite' tocDepth: 3 toc: true From 9ff560b7f84f08e527dc8f2aa239f5874e3352f6 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:24:23 +0600 Subject: [PATCH 04/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index b545fdbc31..a2d839fe87 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -90,7 +90,7 @@ Currently in the local PGlite server, data does not persist after server restart ```terminal npx prisma migrate dev -npm run seed +npx prisma db seed ``` Persistent storage will be supported in the future. From d1f8564f76c8bf9440b54b2cf8f22c4affc36505 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:24:36 +0600 Subject: [PATCH 05/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index a2d839fe87..e3f68cd176 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -93,7 +93,7 @@ npx prisma migrate dev npx prisma db seed ``` -Persistent storage will be supported in the future. +Persistent storage will be supported soon. ### Caching is mocked locally From b82768d42106a9ceac009502300fdc0a24f9d1b9 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:25:12 +0600 Subject: [PATCH 06/26] Update content/250-postgres/1100-integrations/500-vscode-agent.mdx Co-authored-by: Nikolas --- content/250-postgres/1100-integrations/500-vscode-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/1100-integrations/500-vscode-agent.mdx b/content/250-postgres/1100-integrations/500-vscode-agent.mdx index 454ae386f6..1d0ae9d7a2 100644 --- a/content/250-postgres/1100-integrations/500-vscode-agent.mdx +++ b/content/250-postgres/1100-integrations/500-vscode-agent.mdx @@ -9,7 +9,7 @@ toc: true ## Overview -[Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) includes an **agent** mode (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. +Visual Studio Code includes an [agent mode](](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)) (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. ## Capabilities From 2db0cf35b4537466467970ab9298a9caa72a8d9b Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:25:22 +0600 Subject: [PATCH 07/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index e3f68cd176..5973843512 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -14,7 +14,7 @@ PGlite is a lightweight, in-memory PostgreSQL compatible database packaged as a This guide provides instructions for setting up and running your local Prisma Postgres development environment using the PGlite server. -## Setting up local development with PGlite +## Setting up local development with Prisma Postgres Follow these steps to integrate PGlite into your local development workflow. From 449cc1a1e2b78b1c8fae763a8e4dbec8c6ec10f9 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:25:55 +0600 Subject: [PATCH 08/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 5973843512..d862e1f77d 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -30,7 +30,7 @@ This starts a local PGlite server that you can connect to using Prisma Client. T This should give you an output with `DATABASE_URL` that looks like this: -```bash +``` Starting Prisma Dev... From ada2e39e6f51b69d4e8216157f11636e1a3456fb Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:27:05 +0600 Subject: [PATCH 09/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index d862e1f77d..120809fabc 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -1,7 +1,7 @@ --- title: 'Local development' metaTitle: 'Local development with Prisma Postgres' -metaDescription: 'Guide to setting up local development using Prisma Postgres with PGlite' +metaDescription: 'Guide to setting up local development using Prisma Postgres' tocDepth: 3 toc: true --- From 41c3a077ab6fbff2a7524e4ce5e0a8193d5bd4f8 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 14:28:29 +0600 Subject: [PATCH 10/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 120809fabc..f33ae790a0 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -16,7 +16,7 @@ This guide provides instructions for setting up and running your local Prisma Po ## Setting up local development with Prisma Postgres -Follow these steps to integrate PGlite into your local development workflow. +Follow these steps to locally set up Prisma Postgres for development. ### 1. Launching the local PGlite server From 78d18ce3f6f1f6e656587e466276b1f29da06533 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 15:57:37 +0600 Subject: [PATCH 11/26] feat: remove pglite docs --- .../350-ai-tools/400-github-copilot.mdx | 17 ++++-- .../1100-integrations/500-vscode-agent.mdx | 32 ++++++---- .../300-database/550-local-development.mdx | 58 +++++++++---------- 3 files changed, 62 insertions(+), 45 deletions(-) diff --git a/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx b/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx index 81e3f834dc..b22cf52746 100644 --- a/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx +++ b/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx @@ -6,18 +6,18 @@ tocDepth: 3 toc: true --- -GitHub Copilot is an AI coding assistant that speeds up your Prisma ORM workflows, so you spend less time on boilerplate and more on data modeling, querying, and collaboration. With the GitHub Copilot extension for Prisma in VS Code, you can: +GitHub Copilot is an AI coding assistant that speeds up your Prisma ORM workflows, so you spend less time on boilerplate and more on data modeling, querying, and collaboration. With the GitHub Copilot extension in your editor, you can: - Get Prisma-aware code suggestions as you edit your schema or invoke the client. - Chat with Copilot about modeling patterns, troubleshoot queries, or explore migration strategies. - Run common Prisma CLI commands (e.g. `prisma migrate dev`, `prisma db push`) via Copilot's command-palette interface. - Scaffold Prisma schema models and generate Prisma Client code and run migrations directly from the Copilot chat interface. -GitHub Copilot allows you to query the official docs and also perform automated [actions in VS Code Agent mode](/postgres/integrations/vscode-agent), such as scaffolding a Prisma schema, running seeds scripts, and creating a production-ready Prisma Postgres database. +GitHub Copilot allows you to query the official docs via the [**Prisma for GitHub Copilot** extension](https://github.com/apps/prisma-for-github-copilot) and also perform automated [actions in VS Code Agent mode](/postgres/integrations/vscode-agent), such as scaffolding a Prisma schema, running seeds scripts, and creating a production-ready Prisma Postgres database. -## Query Prisma docs with the Prisma for Copilot extension +## Query Prisma docs with the Prisma for GitHub Copilot extension -The Prisma for Copilot extension lets you fetch Prisma documentation directly in GitHub Copilot Chat. You can look up schema syntax, client methods, migration commands, and more from your editor. +The [Prisma for GitHub Copilot extension](https://github.com/apps/prisma-for-github-copilot) lets you fetch Prisma documentation directly in GitHub Copilot Chat. You can look up schema syntax, client methods, migration commands, and more from your editor. ### How to enable the extension @@ -30,6 +30,15 @@ The Prisma for Copilot extension lets you fetch Prisma documentation directly in @prisma-for-copilot How do I define a one-to-many relation? ``` +1. Install the [Prisma for GitHub Copilot](https://github.com/apps/prisma-for-github-copilot) extension. +2. Open your IDE. +3. Install the [GitHub Copilot Chat extension](https://docs.github.com/en/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment). +4. Open Copilot Chat and switch to [**Ask** mode](https://code.visualstudio.com/docs/copilot/chat/chat-ask-mode). +5. Ask: "`@prisma-for-github-copilot` How do I define a one-to-many relation?" (If the `@prisma-for-github-copilot` namespace doesn't show up after a few seconds, reload the chat.) +6. When prompted, authorize the Prisma app in your browser, then return to the chat. +7. After returning to the chat, resend the question. +8. Copilot returns the answer pulled straight from the Prisma docs. + ## Use GitHub Copilot's agent features GitHub Copilot Chat offers an **Agent** mode in VS Code that can run Prisma commands. You can use the agent chat to: diff --git a/content/250-postgres/1100-integrations/500-vscode-agent.mdx b/content/250-postgres/1100-integrations/500-vscode-agent.mdx index 1d0ae9d7a2..fd2078d412 100644 --- a/content/250-postgres/1100-integrations/500-vscode-agent.mdx +++ b/content/250-postgres/1100-integrations/500-vscode-agent.mdx @@ -1,26 +1,34 @@ --- title: 'VS Code Agent' -description: 'Streamline Prisma ORM workflows, manage migrations, and create databases directly in Visual Studio Code using the Prisma Agent.' -metaTitle: 'Visual Studio Code Agent' -metaDescription: 'Manage Prisma ORM migrations and provision Prisma databases efficiently within Visual Studio Code using the Prisma Agent.' +description: 'Simplify Prisma ORM workflows, manage migrations, and create databases using VS Code agent mode.' +metaTitle: 'VS Code Agent Mode' +metaDescription: 'Manage Prisma ORM migrations and provision Prisma databases efficiently using VS Code agent mode.' tocDepth: 3 toc: true --- ## Overview -Visual Studio Code includes an [agent mode](](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)) (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. +VS Code includes an [agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. ## Capabilities -The [Prisma Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) enables the agent to perform the following tasks using our Model Context Protocol (MCP) server: +The [Prisma VS Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) enables support for VS Code agent mode. -- Provision new databases. -- Run migrations and generate the Prisma Client. -- Generate Prisma schemas and client code. -- Execute Prisma commands directly in the terminal. +VS Code agent mode can perform the following tasks: + +- Check migration status (e.g. Flag unapplied migrations) +- Create and apply schema migrations automatically +- Sign in to the Prisma Data Platform +- Provision Prisma Postgres instances, letting you start coding right away + + +:::note + +Although you can connect your editor to [the MCP server](/postgres/integrations/mcp-server), this integration eliminates the need for you to interact with our MCP server in VS Code. + +::: -This integration removes the need to manually run MCP commands, significantly speeding your database-related workflows. ## How to enable and use the VS Code agent @@ -49,8 +57,8 @@ Currently, the agent mode uses your default workspace in the Prisma Data Platfor Complementing the agent, the Prisma Copilot extension allows you to query Prisma documentation directly within VS Code. -You need to install the [Prisma for Copilot extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) from the GitHub marketplace. +You need to install the [Prisma for Copilot extension](https://github.com/apps/prisma-for-github-copilot) from the GitHub marketplace. -Then, [switch to **Ask** mode in VS Code](https://code.visualstudio.com/docs/copilot/chat/chat-ask-mode) and type your question using the `@prisma` namespace. +Then, [switch to **Ask** mode in GitHub Copilot Chat](https://code.visualstudio.com/docs/copilot/chat/chat-ask-mode) and type your question using the `@prisma-for-github-copilot` namespace. For more details, refer to our [GitHub Copilot documentation](/orm/more/ai-tools/github-copilot). \ No newline at end of file diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index f33ae790a0..7ce67dddd5 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -1,54 +1,46 @@ --- title: 'Local development' -metaTitle: 'Local development with Prisma Postgres' +metaTitle: 'Local development for Prisma Postgres' metaDescription: 'Guide to setting up local development using Prisma Postgres' tocDepth: 3 toc: true --- -[Prisma Postgres](/postgres) is our production-grade cloud offering, and it is recommended for production and staging setups. -To simplify your development workflow and make transitioning to production effortless, we've created a local database server compatible with Prisma Postgres, [powered by PGlite](https://pglite.dev/). +[Prisma Postgres](/postgres) is our 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 [PG Lite](https://pglite.dev). This guide shows you how to install and launch a local Prisma Postgres database. -PGlite is a lightweight, in-memory PostgreSQL compatible database packaged as a TypeScript/JavaScript library using WebAssembly ([WASM](https://webassembly.org/)). Learn more in the [PGlite documentation](https://pglite.dev/). -This guide provides instructions for setting up and running your local Prisma Postgres development environment using the PGlite server. +## Setting up local development for Prisma Postgres -## Setting up local development with Prisma Postgres +Follow these steps to set up local Prisma Postgres for development. -Follow these steps to locally set up Prisma Postgres for development. +### 1. Launching local Prisma Postgres -### 1. Launching the local PGlite server - -Navigate into your project and start the PGlite server using the following command: +Navigate into your project and start the local Prisma Postgres server using the following command: ```terminal -npx prisma@latest dev +npx prisma dev ``` -This starts a local PGlite server that you can connect to using Prisma Client. The server will run in the background and will be available at `localhost:5433` by default. +This starts a local Prisma Postgres server that you can connect to using Prisma Client. The server will run in the background and will be available at `localhost:51213` by default and will also contain an auto-generated API key. This should give you an output with `DATABASE_URL` that looks like this: ``` -Starting Prisma Dev... - - Great Success! To connect to your local Prisma Postgres database via Prisma ORM, use the following connection string: - - DATABASE_URL="prisma+postgres://localhost:5433/?dbname=default&dbport=5432&dbuser=postgres" - + + DATABASE_URL="prisma+postgres://localhost:51213/?api_key=__API_KEY__" ``` -Copy the `DATABASE_URL` and store it in your `.env` file. This will be used to connect to the PGlite server: +Copy the `DATABASE_URL` and store it in your `.env` file. This will be used to connect to the local Prisma Postgres server: ```bash file=.env -DATABASE_URL="prisma+postgres://localhost:5433/?dbname=default&dbport=5432&dbuser=postgres" +DATABASE_URL="prisma+postgres://localhost:51213/?api_key=__API_KEY__" ``` -The `DATABASE_URL` is a connection string that Prisma uses to connect to the PGlite server and is compatible with the [Prisma Postgres extension](https://www.npmjs.com/package/@prisma/extension-accelerate): +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' @@ -56,29 +48,37 @@ import { withAccelerate } from '@prisma/extension-accelerate' const prisma = new PrismaClient().$extends(withAccelerate()) ``` -This ensures no additional code changes are needed when switching from PGlite to Prisma Postgres in production. +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 seed data -Then run the `prisma migrate dev` command to create the database and run the migrations: +Then in a separate terminal tab, run the `prisma migrate dev` command to create the database and run the migrations: ```bash npx prisma migrate dev ``` +:::note + +Make sure the local Prisma Postgres server is running before running the `prisma migrate dev` command. + +::: + This will create the database and run the migrations. If you have a seeder script to seed the database, you should also run it in this step. :::note -Currently, our PGlite server does not persist data. This means that if you stop the server, all data will be lost. Hence have to run the migrations and seeds every time you start the PGlite server by using the npx prisma@latest dev command. See the [limitation section below](#no-data-persistence-between-restarts). +Currently, our local Prisma Postgres server does not persist data. This means that if you stop the server, all data will be lost. Hence have to run the migrations and seeds every time you start the server by using the `npx prisma dev` command. See the [limitation section below](#no-data-persistence-between-restarts). ::: ### 3. Running your application locally -Start your application's development server. You can now perform queries against the local PGlite database using Prisma ORM. +Start your application's development server. You can now perform queries against the local Prisma Postgres instance using Prisma ORM. To transition to production, you only need to update the database URL in the `.env` file with a Prisma Postgres connection url without additional application logic changes. @@ -86,7 +86,7 @@ To transition to production, you only need to update the database URL in the `.e ### No data persistence between restarts -Currently in the local PGlite server, data does not persist after server restart the server. Each time you restart the server (`npx prisma@latest dev`), reapply migrations and seeds: +Currently in the local Prisma Postgres server, data does not persist after server restart the server. Each time you restart the server (`npx prisma dev`), reapply migrations and seeds: ```terminal npx prisma migrate dev @@ -97,7 +97,7 @@ Persistent storage will be supported soon. ### Caching is mocked locally -[Prisma Postgres caching](/postgres/database/caching) is simulated locally. Queries always directly interact with the PGlite database, bypassing cache configurations: +[Prisma Postgres caching](/postgres/database/caching) is simulated locally. Queries always directly interact with the local Prisma Postgres instance, bypassing cache configurations: ```typescript const users = await prisma.user.findMany({ @@ -105,7 +105,7 @@ const users = await prisma.user.findMany({ }); ``` -Caching works normally in staging and production when you're using Prisma Postgres. +Caching works normally when you're using Prisma Postgres in staging and production. ### Cache invalidation not supported locally @@ -121,5 +121,5 @@ try { ### Prisma Postgres limitations apply locally -All Prisma Postgres limitations also apply to local development with PGlite. Refer to the [Prisma Postgres limitations documentation](/postgres/more/known-limitations) for detailed information. +All Prisma Postgres limitations also apply to local development for Prisma Postgres. Refer to the [Prisma Postgres limitations documentation](/postgres/more/known-limitations) for detailed information. From a4c4052ca3229a5c32a65f4537ab66a2f02da856 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 16:01:11 +0600 Subject: [PATCH 12/26] fix: clean up docs --- .../250-postgres/1100-integrations/500-vscode-agent.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/content/250-postgres/1100-integrations/500-vscode-agent.mdx b/content/250-postgres/1100-integrations/500-vscode-agent.mdx index fd2078d412..d4cfbec8b1 100644 --- a/content/250-postgres/1100-integrations/500-vscode-agent.mdx +++ b/content/250-postgres/1100-integrations/500-vscode-agent.mdx @@ -22,14 +22,6 @@ VS Code agent mode can perform the following tasks: - Sign in to the Prisma Data Platform - Provision Prisma Postgres instances, letting you start coding right away - -:::note - -Although you can connect your editor to [the MCP server](/postgres/integrations/mcp-server), this integration eliminates the need for you to interact with our MCP server in VS Code. - -::: - - ## How to enable and use the VS Code agent The [latest version of the Prisma VS Code extension](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma) fully supports agent mode. Since extensions update automatically, no manual action is required to enable it. From f41fac977add2705d5c6088078cbd65daa27ad5a Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 16:04:40 +0600 Subject: [PATCH 13/26] Update content/250-postgres/300-database/550-local-development.mdx --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 7ce67dddd5..cc94bb7049 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -119,7 +119,7 @@ try { } ``` -### Prisma Postgres limitations apply locally +### Prisma Postgres limitations apply to the local Prisma Postgres database All Prisma Postgres limitations also apply to local development for Prisma Postgres. Refer to the [Prisma Postgres limitations documentation](/postgres/more/known-limitations) for detailed information. From 6ccb06bd861ecb0058f82ed147c59389c842afaa Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 16:06:20 +0600 Subject: [PATCH 14/26] fix: correct word --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index cc94bb7049..7234c2d067 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -72,7 +72,7 @@ If you have a seeder script to seed the database, you should also run it in this :::note -Currently, our local Prisma Postgres server does not persist data. This means that if you stop the server, all data will be lost. Hence have to run the migrations and seeds every time you start the server by using the `npx prisma dev` command. See the [limitation section below](#no-data-persistence-between-restarts). +Currently, the local Prisma Postgres server does not persist data. This means that if you stop the server, all data will be lost. Hence have to run the migrations and seeds every time you start the server by using the `npx prisma dev` command. See the [limitation section below](#no-data-persistence-between-restarts). ::: From 4b4c82c53de5eac78f7abb089b12f00b12dd3c58 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 13 May 2025 19:09:09 +0600 Subject: [PATCH 15/26] Update content/200-orm/500-reference/200-prisma-cli-reference.mdx --- content/200-orm/500-reference/200-prisma-cli-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index 37bbd6e3df..1e40e4653c 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -330,7 +330,7 @@ DATABASE_URL="mysql://user:password@localhost:3306/mydb" ### `dev` -The `dev` command starts a local [PGlite server](https://pglite.dev/) that you can run Prisma ORM commands against. It is useful for development and testing purposes and also allows you to switch to [Prisma Postgres](/postgres) easily. You can learn more about the PGlite server [in this section](/postgres/database/local-development). +The `dev` command starts a local Prisma Postgres database that you can run Prisma ORM commands against. It is useful for development and testing purposes and also allows you to switch to [Prisma Postgres](/postgres) in production easily. You can learn more about the local Prisma Postgres database [in this section](/postgres/database/local-development). #### Examples From 37c0d6db9ea6b221cf08abdd8f6a11e1919ff826 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 13:59:59 +0600 Subject: [PATCH 16/26] Update content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx Co-authored-by: Nikolas --- content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx b/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx index b22cf52746..62c796e63d 100644 --- a/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx +++ b/content/200-orm/800-more/350-ai-tools/400-github-copilot.mdx @@ -26,7 +26,7 @@ The [Prisma for GitHub Copilot extension](https://github.com/apps/prisma-for-git 3. Open a file in your workspace and launch Copilot Chat. 4. In chat, prefix your question with the `@prisma-for-copilot` keyword: -```bash +``` @prisma-for-copilot How do I define a one-to-many relation? ``` From 82d3d7c3fd8090359ceef41de3f620225fa814ab Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 14:00:10 +0600 Subject: [PATCH 17/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 7234c2d067..3de57f23d4 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -1,6 +1,6 @@ --- title: 'Local development' -metaTitle: 'Local development for Prisma Postgres' +metaTitle: 'Local development with Prisma Postgres' metaDescription: 'Guide to setting up local development using Prisma Postgres' tocDepth: 3 toc: true From 104f7cf2f2e040fd1b70e44d2aa4014d86b23e32 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 14:00:29 +0600 Subject: [PATCH 18/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 3de57f23d4..256e371893 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -7,7 +7,7 @@ toc: true --- -[Prisma Postgres](/postgres) is our 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 [PG Lite](https://pglite.dev). This guide shows you how to install and launch a local Prisma Postgres database. +[Prisma Postgres](/postgres) is our 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 [PG Lite](https://pglite.dev)). This guide shows you how to install and launch a local Prisma Postgres database. ## Setting up local development for Prisma Postgres From f840bf553ecb99380a402e8b53ce070e834ecedc Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 14:01:01 +0600 Subject: [PATCH 19/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 256e371893..039d12a688 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -56,7 +56,7 @@ Keep the local Prisma Postgres server running in the background while you work o Then in a separate terminal tab, run the `prisma migrate dev` command to create the database and run the migrations: -```bash +```terminal npx prisma migrate dev ``` From 13fb33e4257ed71ef01176de1466bf96fccfbddf Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 16:31:25 +0600 Subject: [PATCH 20/26] Update content/250-postgres/1100-integrations/500-vscode-agent.mdx --- content/250-postgres/1100-integrations/500-vscode-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/1100-integrations/500-vscode-agent.mdx b/content/250-postgres/1100-integrations/500-vscode-agent.mdx index d4cfbec8b1..c20afede54 100644 --- a/content/250-postgres/1100-integrations/500-vscode-agent.mdx +++ b/content/250-postgres/1100-integrations/500-vscode-agent.mdx @@ -9,7 +9,7 @@ toc: true ## Overview -VS Code includes an [agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. +VS Code includes an [agent mode](https://pris.ly/vs-code-docs) (powered by GitHub Copilot) that automatically performs code changes and executes Prisma CLI commands based on your prompts. ## Capabilities From da76e68cbecd9ff3f6b3c49f7c7d5783380d2fd6 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 16:31:34 +0600 Subject: [PATCH 21/26] Update content/200-orm/500-reference/200-prisma-cli-reference.mdx --- content/200-orm/500-reference/200-prisma-cli-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index 1e40e4653c..8e346d6005 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -356,7 +356,7 @@ Great Success! To connect to your local Prisma Postgres database via Prisma ORM, use the following connection string: - DATABASE_URL="prisma+postgres://localhost:5433/?dbname=default&dbport=5432&dbuser=postgres" + DATABASE_URL="prisma+postgres://localhost:51213/?api_key=__API_KEY__" ``` From 7f9fbae72e38d9272f850249c58ada6c8a281066 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 16:45:24 +0600 Subject: [PATCH 22/26] feat: add arguments --- .../200-orm/500-reference/200-prisma-cli-reference.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index 8e346d6005..ff16524135 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -332,6 +332,14 @@ DATABASE_URL="mysql://user:password@localhost:3306/mydb" The `dev` command starts a local Prisma Postgres database that you can run Prisma ORM commands against. It is useful for development and testing purposes and also allows you to switch to [Prisma Postgres](/postgres) in production easily. You can learn more about the local Prisma Postgres database [in this section](/postgres/database/local-development). +#### Arguments + +| Argument | Required | Description | Default | +| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------- | +| `--port` (or `-p`) | No | Specifies the port on HTTP server starts. | `51213` | +| `--db-port` (or `-P`) | No | Specifies the port on which the local Prisma Postgres TCP server listens, allowing TCP and HTTP ports to be configured separately. | `51215` | + + #### Examples **Run `prisma dev`** From 9d0225eb203b1d776f04625470b59c5041b6c382 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 17:37:18 +0600 Subject: [PATCH 23/26] fix: add more arguments --- content/200-orm/500-reference/200-prisma-cli-reference.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/200-orm/500-reference/200-prisma-cli-reference.mdx b/content/200-orm/500-reference/200-prisma-cli-reference.mdx index ff16524135..6cd2bbbb1d 100644 --- a/content/200-orm/500-reference/200-prisma-cli-reference.mdx +++ b/content/200-orm/500-reference/200-prisma-cli-reference.mdx @@ -336,8 +336,11 @@ The `dev` command starts a local Prisma Postgres database that you can run Prism | Argument | Required | Description | Default | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------- | -| `--port` (or `-p`) | No | Specifies the port on HTTP server starts. | `51213` | -| `--db-port` (or `-P`) | No | Specifies the port on which the local Prisma Postgres TCP server listens, allowing TCP and HTTP ports to be configured separately. | `51215` | +| `--port` (or `-p`) | No | Main port number the local Prisma Postgres HTTP server will listen on. | `51213` | +| `--db-port` (or `-P`) | No | Port number the local Prisma Postgres database server will listen on. | `51214` | +| `--shadow-db-port` | No | Port number the shadow database server will listen on. | `51215` | +| `--debug` | No | Enable debug logging. | `false` | + #### Examples From 6e2db1f35e0bf928b77520af430b4ed11200f7cf Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 18:13:48 +0600 Subject: [PATCH 24/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index 039d12a688..b7d9de86ac 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -52,7 +52,7 @@ This ensures no additional code changes are needed when switching from local Pri Keep the local Prisma Postgres server running in the background while you work on your application. -### 2. Applying migrations and seed data +### 2. Applying migrations and seeding data Then in a separate terminal tab, run the `prisma migrate dev` command to create the database and run the migrations: From 24bff6c48cd17e06fdec744db424f32a3cd98ff6 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Wed, 14 May 2025 18:14:43 +0600 Subject: [PATCH 25/26] Update content/250-postgres/300-database/550-local-development.mdx Co-authored-by: Nikolas --- content/250-postgres/300-database/550-local-development.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index b7d9de86ac..fce9dfbcb5 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -22,9 +22,9 @@ Navigate into your project and start the local Prisma Postgres server using the npx prisma dev ``` -This starts a local Prisma Postgres server that you can connect to using Prisma Client. The server will run in the background and will be available at `localhost:51213` by default and will also contain an auto-generated API key. +This starts a local Prisma Postgres server that you can connect to using Prisma ORM. -This should give you an output with `DATABASE_URL` that looks like this: +The output of the command contains a `DATABASE_URL` and looks like this: ``` Great Success! From 275fdd7980d3c0bf9624f1346429ecf9809cdbc2 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Thu, 15 May 2025 12:43:11 +0600 Subject: [PATCH 26/26] feat: early access --- .../300-database/550-local-development.mdx | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/content/250-postgres/300-database/550-local-development.mdx b/content/250-postgres/300-database/550-local-development.mdx index fce9dfbcb5..3e0a0f4ac1 100644 --- a/content/250-postgres/300-database/550-local-development.mdx +++ b/content/250-postgres/300-database/550-local-development.mdx @@ -1,19 +1,31 @@ --- title: 'Local development' -metaTitle: 'Local development with Prisma Postgres' -metaDescription: 'Guide to setting up local development using Prisma Postgres' +metaTitle: 'Local development with Prisma Postgres (Early Access)' +metaDescription: 'Guide to setting up local development using Prisma Postgres (Early Access)' tocDepth: 3 toc: true +sidebar_class_name: early-access-badge --- [Prisma Postgres](/postgres) is our 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 [PG Lite](https://pglite.dev)). This guide shows you how to install and launch a local Prisma Postgres database. +:::note + +Local Prisma Postgres is in [Early Access](/orm/more/releases#early-access) 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. + +::: + ### 1. Launching local Prisma Postgres Navigate into your project and start the local Prisma Postgres server using the following command: @@ -93,7 +105,7 @@ npx prisma migrate dev npx prisma db seed ``` -Persistent storage will be supported soon. +Persistent storage will be supported when local Prisma Postgres is [Generally Available](/orm/more/releases#generally-available-ga). ### Caching is mocked locally