Local development with Prisma Postgres
Prisma Postgres is a production-grade, cloud-native database and is ideal for staging and production environments. For rapid iteration and isolated testing, you can run a local Prisma Postgres instance (powered by PGlite). This page explains how to install and launch a local Prisma Postgres database.
Local Prisma Postgres is in 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.
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:
npx prisma dev
This starts a local Prisma Postgres server that you can connect to using Prisma ORM.
The output of the command contains a DATABASE_URL and looks like this:
Great Success!
To connect to your local Prisma Postgres database via Prisma ORM, use the following connection string:
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 local Prisma Postgres server:
DATABASE_URL="prisma+postgres://localhost:51213/?api_key=__API_KEY__"
The DATABASE_URL is a connection string that Prisma uses to connect to the local Prisma Postgres server and is compatible with the Prisma Postgres extension:
import { withAccelerate } from '@prisma/extension-accelerate'
const prisma = new PrismaClient().$extends(withAccelerate())
This ensures no additional code changes are needed when switching from local Prisma Postgres to Prisma Postgres in production.
Keep the local Prisma Postgres server running in the background while you work on your application.
2. Applying migrations and seeding data
Then in a separate terminal tab, run the prisma migrate dev command to create the database and run the migrations:
npx prisma migrate dev
Make sure the local Prisma Postgres server is running before running the prisma migrate dev command.
If you must use a different port, append --port <number> (for example, npx prisma migrate dev --port 5422) and update your DATABASE_URL (or other connection settings) to match.
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.
3. Running your application locally
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.
Using different local Prisma Postgres instances
You can target a specific, local Prisma Postgres instance via the --name (-n) option of the prisma dev command, for example:
npx prisma dev --name mydb1
Whenever you pass the --name mydb1 to prisma dev, the command will return the same connection string pointing to a local instance called mydb1.
Known limitations
Caching is mocked locally
Prisma Postgres caching is simulated locally. Queries always directly interact with the local Prisma Postgres instance, bypassing cache configurations:
const users = await prisma.user.findMany({
cache: { ttl: 60 },
});
Caching works normally when you're using Prisma Postgres in staging and production.
Single connection only
The local Prisma Postgres database server accepts one connection at a time. Additional connection attempts queue until the active connection closes. This constraint is sufficient for most local development and testing scenarios.
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 for detailed information.
No HTTPS connections
The local Prisma Postgres server doesn't use HTTPS. We advise against self-hosting it.