Prisma "migrate dev" Shadow Database Permission Error in CI

By Kaveh Alemi·Latchkey

Prisma migrate dev creates a temporary shadow database to detect drift and validate migrations. When the database user lacks permission to create one, Prisma stops with P3014. This is a privileges/configuration issue, not a transient failure.

What this error means

prisma migrate dev fails with P3014 saying it could not create the shadow database, often citing a permission-denied from the server. The same user/connection fails identically every run.

prisma output

Error: P3014

Prisma Migrate could not create the shadow database. Please make sure the
database user has permission to create databases. Original error:
ERROR: permission denied to create database

Common causes

Migration user cannot CREATE DATABASE

On managed Postgres/MySQL the connection user often lacks the privilege to create the throwaway shadow database that migrate dev requires.

No shadowDatabaseUrl configured for a restricted server

When you cannot grant CREATE DATABASE, Prisma needs an explicit empty shadowDatabaseUrl to use instead, and it was not set.

Using migrate dev where migrate deploy belongs

migrate dev (with its shadow DB) is a development command. CI/production should run migrate deploy, which needs no shadow database.

How to fix it

Use migrate deploy in CI

CI and production should apply committed migrations with deploy, which does not create a shadow database.

Terminal

npx prisma migrate deploy

Provide an explicit shadow database

When you must run dev-style migrate against a restricted server, point Prisma at a separate empty database you control.

schema.prisma

datasource db {
  provider          = "postgresql"
  url               = env("DATABASE_URL")
  shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}

Grant the create privilege for dev databases

On a database you fully control, grant the migration user CREATEDB (Postgres) or equivalent.
Confirm the user can create and drop the shadow database.
Prefer migrate deploy in CI regardless, to avoid needing the privilege at all.

How to prevent it

Run migrate deploy in CI/production; keep migrate dev for local work.
Set shadowDatabaseUrl when the migration user cannot create databases.
Document the required privileges for the migration role.

Frequently asked questions

What causes ""shadow database" / P3014"?

On managed Postgres/MySQL the connection user often lacks the privilege to create the throwaway shadow database that migrate dev requires.

How do I fix "shadow database" / P3014?

CI and production should apply committed migrations with deploy, which does not create a shadow database.

References

GitHub Actions documentation