prisma Error P3014: could not create the shadow database

TL;DR

Give Prisma a database it can create and destroy for the shadow database, by fixing permissions or by setting shadowDatabaseUrl. Prisma Migrate needs a spare empty database to compute diffs, and P3014 means the database user cannot CREATE DATABASE or the shadow URL is wrong. Grant CREATEDB to the role, or point shadowDatabaseUrl at a pre-created empty database the role owns.

Error: P3014: Could not create the shadow database.

Steps

1. Check whether the database user can create databases. In Postgres, inspect the role's CREATEDB attribute, or simply try creating and dropping a throwaway database as that user. Expected: a clear yes or no on CREATE DATABASE permission.

2. If the permission is missing and you control the role, grant it: alter role [role] createdb;. Expected: the permission check from step 1 now passes.

3. If you cannot grant it (managed Postgres, locked-down CI role), have the database owner create an empty database and set shadowDatabaseUrl in the datasource block to point at it. Expected: Prisma can connect to the shadow database URL, and that database is empty.

4. Re-run prisma migrate dev (or prisma migrate diff). Expected: no P3014, and the migration flow proceeds.

5. For CI, use a dedicated role with CREATEDB on the CI database server, and never point shadowDatabaseUrl at a database holding real data. Expected: CI migrations run cleanly on every build.

Use this when

• P3014 appears on migrate dev or migrate diff.
• The database user is restricted (managed Postgres, CI role).
• Shadow database creation fails with a permission error.
• An agent needs migrate dev working in a locked-down environment.

Not for this skill when

• The error is P3009 failed migrations (that is a history-reconciliation problem).
• Drift detection complains but no P3014 appears.
• You are on SQLite (there is no shadow database there).

Variant phrasings

• prisma P3014 shadow database
• could not create the shadow database prisma
• prisma migrate dev permission denied create database
• shadowDatabaseUrl not working

Why it happens

migrate dev creates a temporary empty database, applies your migrations to it, and diffs it against your schema to detect drift and generate the next migration. Without CREATE DATABASE permission, which is common on managed and CI Postgres with locked-down roles, that setup step fails with P3014 before any migration logic runs.

Edge cases

• Some managed providers block CREATE DATABASE entirely, even for owners. shadowDatabaseUrl pointing at a pre-created empty database is the only route there.
• Prisma wipes and recreates the shadow database's contents. Never point shadowDatabaseUrl at anything holding data you need.
• If the shadow database URL has a typo, the error can look like a permissions problem. Verify connectivity to the URL first.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_BjSI-wccga8FS861j2YbKQ