How to fix P3020: The automatic creation of shadow databases is disabled on Azure SQL in Prisma

PrismaINTERMEDIATEHIGHUpdated Dec 22, 2025· 112 views

Azure SQL and some cloud databases don't allow automatic shadow database creation. Prisma Migrate needs a shadow database for development to detect schema drift. Configure a manual shadow database URL in your datasource to resolve this error.

Quick fix

Fixes P3020

DATABASE_URL="sqlserver://server.database.windows.net:1433;database=myapp;user=username;password=password;encrypt=true;trustServerCertificate=false;connectionTimeout=30;"
SHADOW_DATABASE_URL="sqlserver://server.database.windows.net:1433;database=myapp-shadow;user=username;password=password;encrypt=true;trustServerCertificate=false;connectionTimeout=30;"
  1. Create a dedicated shadow database on Azure SQL
  2. Add SHADOW_DATABASE_URL to your .env file
  3. Update your Prisma schema datasource block
  4. Run prisma migrate dev
prisma — error
DATABASE_URL="sqlserver://server.database.windows.net:1433;database=myapp;user=username;password=password;encrypt=true;trustServerCertificate=false;connectionTimeout=30;"
SHADOW_DATABASE_URL="sqlserver://server.database.windows.net:1433;database=myapp-shadow;user=username;password=password;encrypt=true;trustServerCertificate=false;connectionTimeout=30;"
P3020: The automatic creation of shadow databases is disabled on Azure SQL

What this error means

The P3020 error occurs when using Prisma Migrate with Azure SQL or other cloud-hosted databases that restrict database creation permissions. Prisma Migrate requires a shadow database during `prisma migrate dev` to detect potential issues like schema drift and data loss without affecting your production database. Since Azure SQL disables automatic database creation, you must manually configure a separate database to serve as the shadow database.

Typical symptoms

  • prisma migrate dev command fails with P3020 error
  • Unable to run database migrations in development environment
  • Error message mentions "shadowDatabaseUrl datasource attribute"
  • Migrations work in production but fail locally with Azure SQL

Common causes

  1. Shadow database URL not configured in your Prisma schema datasource
  2. Using Azure SQL or Heroku with Prisma Migrate without shadowDatabaseUrl setup
  3. Database user lacks permissions to create databases automatically
  4. Missing or incorrectly formatted SHADOW_DATABASE_URL environment variable

How to fix "P3020: The automatic creation of shadow databases is disabled on Azure SQL"

1Create a dedicated shadow database on Azure SQL

In the Azure Portal, create a new empty database on the same SQL Server as your primary database. Name it something like myapp-shadow or myapp-dev-shadow. Note the full connection string for this new database. This database will be automatically managed by Prisma Migrate.

2Add SHADOW_DATABASE_URL to your .env file

Create or update your .env.local file with the shadow database connection string:

bash
DATABASE_URL="sqlserver://server.database.windows.net:1433;database=myapp;user=username;password=password;encrypt=true;trustServerCertificate=false;connectionTimeout=30;"
SHADOW_DATABASE_URL="sqlserver://server.database.windows.net:1433;database=myapp-shadow;user=username;password=password;encrypt=true;trustServerCertificate=false;connectionTimeout=30;"

Make sure the shadow database name in the connection string matches the database you created.

3Update your Prisma schema datasource block

Open prisma/schema.prisma and add the shadowDatabaseUrl parameter to your datasource:

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

This tells Prisma to use the shadow database during migrations.

4Run prisma migrate dev

Now you can run migrations normally:

bash
npx prisma migrate dev --name your_migration_name

Prisma will create and delete the shadow database automatically as needed. The shadow database is only used for development and will be recreated fresh each time you run prisma migrate dev.

5Verify with prisma migrate deploy in production

For production deployments, use prisma migrate deploy instead of prisma migrate dev. This command executes existing migrations without requiring a shadow database:

bash
npx prisma migrate deploy

The shadow database is only needed during development with prisma migrate dev.

Advanced notes

Important considerations:

Shadow database cleanup: Prisma automatically creates and destroys the shadow database during each migration. Ensure your database user has permissions to create and drop databases, or manually clean up if migrations fail.

Different credentials: The shadow database can use a different user account than your primary database, but both must be on the same server. You can create a separate SQL user with minimal permissions (just CREATE/DROP database) for shadow database operations.

Connection pool settings: Azure SQL may apply connection pooling or firewall rules. If you see timeout errors, increase the connectionTimeout parameter in your connection strings to 30+ seconds.

Alternative: Use prisma migrate deploy: If you cannot create a shadow database, use only prisma migrate deploy and manage migrations manually through other tools. This is not recommended for team development but works for CI/CD pipelines.

Heroku PostgreSQL: If using Heroku with PostgreSQL instead of Azure SQL, you may need a similar workaround since Heroku also restricts database creation permissions.

Frequently asked questions

What does "P3020" mean?
The P3020 error occurs when using Prisma Migrate with Azure SQL or other cloud-hosted databases that restrict database creation permissions. Prisma Migrate requires a shadow database during prisma migrate dev to detect potential issues like schema drift and data loss without affecting your production database. Since Azure SQL disables automatic database creation, you must manually configure a separate database to serve as the shadow database.
How do I fix "P3020"?
Azure SQL and some cloud databases don't allow automatic shadow database creation. Prisma Migrate needs a shadow database for development to detect schema drift. Configure a manual shadow database URL in your datasource to resolve this error.
What causes "P3020"?
Shadow database URL not configured in your Prisma schema datasource Using Azure SQL or Heroku with Prisma Migrate without shadowDatabaseUrl setup Database user lacks permissions to create databases automatically
Is the "P3020" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading