How to fix P3014: Prisma Migrate could not create the shadow database. Please make sure the database user has permission to create databases. in Prisma

PrismaINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 189 views

This error occurs when Prisma Migrate cannot automatically create a temporary shadow database during development migrations. The shadow database is used to detect schema drift and validate migrations before applying them.

Quick fix

Fixes P3014

SELECT rolname, rolcreatedb FROM pg_roles WHERE rolname = 'your_username';
  1. Verify your database user permissions
  2. Create a manual shadow database
  3. Configure the shadow database URL
  4. Run migrations again
prisma — error
SELECT rolname, rolcreatedb FROM pg_roles WHERE rolname = 'your_username';
P3014: Prisma Migrate could not create the shadow database. Please make sure the database user has permission to create databases.

What this error means

The P3014 error indicates that Prisma Migrate attempted to create a shadow database but failed due to insufficient permissions or database constraints. The shadow database is a temporary, secondary database that Prisma creates automatically during the `prisma migrate dev` command. It's used to validate migrations, detect schema drift, and ensure that migrations can be applied cleanly before touching your actual database. This error typically occurs in cloud-hosted database environments (like Heroku, Railway, PlanetScale, or managed AWS RDS) where database users are restricted from creating new databases. It can also happen in local development if your database user lacks the necessary `CREATE DATABASE` privilege. Understanding the shadow database's role is key: it's a safety mechanism that prevents potentially destructive migrations from being applied to your development database without validation.

Typical symptoms

  • Running "prisma migrate dev" fails immediately with P3014 error
  • Error message mentions "permission denied to create database"
  • Migration commands work fine with "prisma db push" but fail with migrate
  • Issue appears only on cloud-hosted databases, not locally
  • Migration workflow is blocked in CI/CD pipelines

Common causes

  1. Database user lacks CREATE DATABASE permission (most common in cloud environments)
  2. Cloud provider restricts automatic database creation (Heroku, Railway, PlanetScale)
  3. PostgreSQL/MySQL security policies prevent non-superuser database creation
  4. Connection string points to a user account with limited privileges
  5. Database quota limits prevent additional database creation

How to fix "P3014: Prisma Migrate could not create the shadow database. Please make sure the database user has permission to create databases."

1Verify your database user permissions

First, check if your database user has permission to create databases. Connect to your database and run:

For PostgreSQL:

sql
SELECT rolname, rolcreatedb FROM pg_roles WHERE rolname = 'your_username';

For MySQL:

sql
SHOW GRANTS FOR 'your_username'@'%';

If rolcreatedb is false (PostgreSQL) or you don't see CREATE privileges (MySQL), that's the root cause.

2Create a manual shadow database

The recommended solution for cloud-hosted databases is to manually create a dedicated shadow database. Create a new database in your provider's dashboard or via SQL:

For PostgreSQL:

sql
CREATE DATABASE myapp_shadow;

For MySQL:

sql
CREATE DATABASE myapp_shadow;
GRANT ALL PRIVILEGES ON myapp_shadow.* TO 'your_username'@'%';

Make sure the shadow database uses the same structure/encoding as your main database.

3Configure the shadow database URL

Add the shadow database connection string to your environment variables. In your .env file, add:

env
DATABASE_URL="postgresql://user:pass@host:5432/myapp"
SHADOW_DATABASE_URL="postgresql://user:pass@host:5432/myapp_shadow"

For Prisma 6 and below, update your schema.prisma:

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

For Prisma 7+, the SHADOW_DATABASE_URL environment variable is automatically recognized without schema changes.

4Run migrations again

Now retry your migration command:

bash
npx prisma migrate dev --name your_migration_name

Prisma will now use your manually created shadow database instead of trying to create one automatically. The migration should proceed without the P3014 error.

5Alternative: Grant CREATE DATABASE permission (local only)

If you're working locally and have control over database permissions, you can grant the necessary privilege:

For PostgreSQL:

sql
ALTER USER your_username CREATEDB;

For MySQL (requires root/admin):

sql
GRANT CREATE ON *.* TO 'your_username'@'%';
FLUSH PRIVILEGES;

Warning: This is typically not an option on cloud-hosted databases due to security restrictions. Use the manual shadow database approach instead.

Advanced notes

Using `prisma db push` as a workaround: While prisma db push doesn't require a shadow database and can sync your schema directly, it's not a substitute for migrations in production workflows. db push doesn't generate migration history, making it unsuitable for team collaboration or production deployments. Use it only for rapid prototyping.

Shadow database naming convention: By default, Prisma creates shadow databases with a suffix like _shadow_<hash>. When creating manually, use a clear naming pattern like yourapp_shadow to avoid confusion.

Cloud provider specifics:
- Heroku Postgres: Hobby tier doesn't allow multiple databases. Upgrade to Standard tier or use db push for development.
- PlanetScale: Doesn't support shadow databases due to its branching model. Use the --skip-generate flag or switch to a different provider for development.
- Supabase: Provides full CREATE DATABASE permissions, so this error is rare unless using a custom role.

CI/CD considerations: In CI pipelines, ensure your test database user has CREATE DATABASE permissions, or set up a pre-created shadow database and pass SHADOW_DATABASE_URL in your environment variables.

Cleaning up shadow databases: If you created a manual shadow database, it will persist after migrations. You can safely drop it when not actively developing:

sql
DROP DATABASE myapp_shadow;

Recreate it when you resume migration work.

Frequently asked questions

What does "P3014" mean?
The P3014 error indicates that Prisma Migrate attempted to create a shadow database but failed due to insufficient permissions or database constraints. The shadow database is a temporary, secondary database that Prisma creates automatically during the prisma migrate dev command. It's used to validate migrations, detect schema drift, and ensure that migrations can be applied cleanly before touching your actual database.
How do I fix "P3014"?
This error occurs when Prisma Migrate cannot automatically create a temporary shadow database during development migrations. The shadow database is used to detect schema drift and validate migrations before applying them.
What causes "P3014"?
Database user lacks CREATE DATABASE permission (most common in cloud environments) Cloud provider restricts automatic database creation (Heroku, Railway, PlanetScale) PostgreSQL/MySQL security policies prevent non-superuser database creation
Is the "P3014" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading