fix(shadow-database): Add standalone information on "Manually configu…

…ring the shadow database" (#4407)

Co-authored-by: Nilufar Bava <[email protected]>
Co-authored-by: Alex Ruheni <[email protected]>

cSpell.json

@@ -57,7 +57,7 @@
     "Snaplet",
     "Kysely",
     "Turso",
-    "inshellisense",
+    "autocompletions",
     "Formbricks",
     "Openform",
     "Documenso",
@@ -88,7 +88,8 @@
     "Vitess",
     "libgcc",
     "libc",
-    "Distroless"
+    "Distroless",
+    "inshellisense",
   ],
   "patterns": [
     {

content/200-concepts/100-components/03-prisma-migrate/200-shadow-database.mdx

@@ -41,7 +41,7 @@ When you run `prisma migrate dev` to create a new migration, Prisma Migrate uses
 
 To detect drift in development, Prisma Migrate:
 
-1. Creates a fresh copy of the shadow database (or performs a soft reset if the shadow database is cloud-hosted)
+1. Creates a fresh copy of the shadow database (or performs a soft reset if the shadow database is configured via [`shadowDatabaseUrl`](/reference/api-reference/prisma-schema-reference#datasource)
 1. Reruns the **current** migration history in the shadow database.
 1. **Introspects** the shadow database to generate the 'current state' of your Prisma schema.
 1. Compares the end state of the current migration history to the development database.
@@ -78,14 +78,33 @@ Assuming Prisma Migrate did not [detect schema drift](#detecting-schema-drift),
 1. Compares the end state of the existing migration history and the target schema, and generates steps to get from one to the other.
 1. Renders these steps to a SQL string and saves it in the new migration file.
 1. Applies the generated migration to the development database (assuming you have not specified the `--create-only` flag)
-1. Drops the shadow database (cloud-hosted databases cannot be dropped, but are reset at the start of the `migrate dev` command)
+1. Drops the shadow database (shadow databases configured via [`shadowDatabaseUrl`](/reference/api-reference/prisma-schema-reference#datasource) are not dropped, but are reset at the start of the `migrate dev` command)
+
+## Manually configuring the shadow database
+
+In some cases it might make sense (e.g. when [creating and dropping databases is not allowed on cloud-hosted databases](#cloud-hosted-shadow-databases-must-be-created-manually)) to manually define the connection string and name of the database that should be used as the shadow database for `migrate dev`. In such a case you can:
+
+1. Create a dedicated database that should be used as the shadow database
+2. Add the connection string of that database your environment variable `SHADOW_DATABASE_URL` (or `.env` file)
+3. Add the [`shadowDatabaseUrl`](/reference/api-reference/prisma-schema-reference#datasource) <span class="api"></span> field reading this environment variable:
+
+```prisma highlight=4;normal
+datasource db {
+  provider          = "postgresql"
+  url               = env("DATABASE_URL")
+  shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
+}
+```
+
+> **Important**: Do not use the exact same values for `url` and `shadowDatabaseUrl` as that might delete all your database in your database.
 
 ## Cloud-hosted shadow databases must be created manually
 
 Some cloud providers do not allow you to drop and create databases with SQL. Some require to create or drop the database via an online interface, and some really limit you to 1 database. If you **develop** in such a cloud-hosted environment, you must:
 
 1. Create a dedicated cloud-hosted shadow database
-2. Add the URL to the [`shadowDatabaseUrl`](/reference/api-reference/prisma-schema-reference#datasource) <span class="api"></span> field:
+2. Add the URL to your environment variable `SHADOW_DATABASE_URL`
+3. Add the [`shadowDatabaseUrl`](/reference/api-reference/prisma-schema-reference#datasource) <span class="api"></span> field reading this environment variable:
 
 ```prisma highlight=4;normal
 datasource db {
@@ -110,7 +129,7 @@ In order to create and delete the shadow database when using `migrate dev`, Pris
 
 > If you use a cloud-hosted database for development and can not use these permissions, see: [Cloud-hosted shadow databases](#cloud-hosted-shadow-databases-must-be-created-manually)
 
-> Note: The automatic creation of shadow databases is disabled on Azure SQL.
+> Note: The automatic creation of shadow databases is disabled on Azure SQL for example.
 
 Prisma Migrate throws the following error if it cannot create the shadow database with the credentials your connection URL supplied:
 
@@ -122,6 +141,7 @@ Database error: Error querying the database: db error: ERROR: permission denied
 To resolve this error:
 
 - If you are working locally, we recommend that you update the database user's privileges.
+- If you are developing against a database that does not allow creating and dropping databases (for any reason) see [Manually configuring the shadow database](#manually-configuring-the-shadow-database)
 - If you are developing against a cloud-based database (for example, on Heroku, Digital Ocean, or Vercel Postgres) see: [Cloud-hosted shadow databases](#cloud-hosted-shadow-databases-must-be-created-manually).
 - If you are developing against a cloud-based database (for example, on Heroku, Digital Ocean, or Vercel Postgres) and are currently **prototyping** such that you don't care about generated migration files and only need to apply your Prisma data model to the database schema, you can run [`prisma db push`](/reference/api-reference/command-reference#db) instead of the `prisma migrate dev` command.