Register for Neon Developer Days 🚀Read More
Guides

Connect from Prisma to Neon

Prisma is an open-source, next-generation ORM that allows you to easily manage and interact with your database. This guide describes how to create a Neon project, connect to it from Prisma, and optionally configure a shadow database for Prisma Migrate.

To create a Neon project and connect to it from Prisma:

  1. Create a Neon project
  2. Connect to Neon from Prisma
  3. Optionally, Configure a shadow database for Prisma Migrate.

Create a Neon project

To create a Neon project:

  1. Navigate to the Projects page in the Neon Console.
  2. Click New Project.
  3. Specify a name, a PostgreSQL version, a region, and click Create Project.
  4. After creating a project, you are directed to the Neon Dashboard, where a connection string with your password is provided under Connection Details. The connection string includes your password until you navigate away from the Neon Console or refresh the browser page. Copy the connection string. It is required to connect to Neon from your Prisma app.

Connect to Neon from Prisma

To connect to Neon from Prisma:

  1. Add the following lines to prisma/schema.prisma to identify the data source and database URL:

    datasource db {
      provider = "postgresql"
      url   = env("DATABASE_URL")
    }
  2. Add a DATABASE_URL setting to your Prisma .env file and set it to the Neon connection string that you copied in the previous step.

DATABASE_URL="postgres://<user>:<password>@<endpoint_hostname>:5432/main"

note

If connection pooling is enabled for your Neon project, which is the default, append ?pgbouncer=true to the connection string, as described in the Prisma documentation.

For information about enabling and disabling connection pooling for your Neon project, see Connection pooling.

where:

  • <endpoint_hostname> the hostname of the branch endpoint, which is found on the Neon Dashboard, under Connection Settings.
  • <user> is the database user, which is found on the Neon Console Dashboard tab, under Connection Details.
  • <password> is the database user's password, which is provided to you when you create a Neon project.

Configure a shadow database for Prisma Migrate

Prisma Migrate is a migration tool that allows you to easily evolve your database schema from prototyping to production. Prisma Migrate requires a shadow database to detect schema drift. This section describes how to configure a second Neon database, which is required to run the prisma migrate dev command.

To configure a shadow database:

  1. Create a second Neon project and make sure to copy the connection string. Refer to Create a Neon project for instructions.

  2. Add the shadowDatabaseUrl setting to your prisma/schema.prisma file to identify the shadow database URL:

    datasource db {
      provider = "postgresql"
      url   = env("DATABASE_URL")
      shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
    }
  3. Add a SHADOW_DATABASE_URL setting to your Prisma .env file and set it to the Neon connection string that you copied in the previous step.

    SHADOW_DATABASE_URL="postgres://<user>:<password>@<endpoint_hostname>:5432/main"

For additional information about shadow databases, refer to About the shadow database, in the Prisma documentation.

Edit this page
Was this page helpful?