Support first deploy database setup

docs/product/command-spec.md

@@ -631,15 +631,18 @@ Behavior:
 - deploy progress uses short stage copy (`Building locally...`, `Built <size>`, `Uploading...`, `Uploaded`, `Deploying...`, `Deployed`) and never prints `Status: running` or `Deployment is running at ...`
 - success human output prints `Live in <duration>`, the URL on its own line, and `Logs   prisma-cli app logs`
 - accepts repeated `--env NAME=VALUE` flags and dotenv file paths such as `--env .env`
-- supports `--db` for preview Branches to create a new empty Prisma Postgres database, apply a supported local Prisma schema source when one exists, and write branch-scoped `DATABASE_URL` and `DIRECT_URL` overrides through the existing `project env` storage
+- supports `--db` to create a new empty Prisma Postgres database, apply a supported local Prisma schema source when one exists, and write `DATABASE_URL` and `DIRECT_URL` through the existing `project env` storage
 - supports `--no-db` to suppress automatic database prompting for the deploy
 - `--db` and `--no-db` are mutually exclusive; passing both is rejected
 - `--yes` alone never creates a database; CI must pass `--db --yes` to create and wire one
-- branch database setup only runs for preview Branches; production database env vars are managed with `project env`
-- branch database setup never overwrites an existing branch-scoped `DATABASE_URL`; when the branch already has `DATABASE_URL`, `--db` leaves branch database env vars unchanged and continues
-- when only `DIRECT_URL` exists on the branch, explicit `--db` treats it as partial setup and repairs the pair by writing fresh branch database env values
-- if schema setup or branch env-var wiring fails after database creation, the CLI deletes the newly created database before returning the error
-- branch database setup does not clone or infer schema from another database; it only creates an empty database and optionally applies schema from local code
+- preview Branch setup writes branch-scoped env-var overrides
+- production setup writes production env vars only during the first production deploy, before the selected App has a live deployment
+- later production deploys do not prompt for database setup; explicit `--db` is rejected once the selected production App has a live deployment
+- database setup never overwrites an existing branch-scoped `DATABASE_URL`; when the branch already has `DATABASE_URL`, `--db` leaves branch database env vars unchanged and continues
+- production setup treats existing production `DATABASE_URL` or `DIRECT_URL` as BYO DB intent; it does not prompt, and explicit `--db` leaves production env vars unchanged and continues with a warning
+- when only `DIRECT_URL` exists on a preview branch, explicit `--db` treats it as partial setup and repairs the pair by writing fresh branch database env values
+- if schema setup or env-var wiring fails after database creation, the CLI deletes the newly created database before returning the error
+- database setup does not clone or infer schema from another database; it only creates an empty database and optionally applies schema from local code
 - Prisma Next config (`prisma-next.config.*`) is preferred over `schema.prisma`; setup runs `prisma-next contract emit` and then `prisma-next db init`
 - for Prisma ORM `schema.prisma`, setup runs `prisma migrate deploy` when `prisma/migrations` exists next to the schema, otherwise it runs `prisma db push`
 - when no supported Prisma schema source is found, `--db` still creates the database and env overrides but skips schema setup

docs/product/error-conventions.md

@@ -239,8 +239,8 @@ Recommended meanings:
 - `REPO_ALREADY_CONNECTED`: a project already has a different GitHub repository connected
 - `REPO_CONNECTION_FAILED`: the Management API repository connection operation failed
 - `BUILD_FAILED`: build failed before a healthy deployment existed
-- `BRANCH_DATABASE_SETUP_FAILED`: preview Branch database creation or branch env-var wiring failed before deployment started
-- `SCHEMA_SETUP_FAILED`: local Prisma schema source setup against a newly created Branch database failed before deployment started
+- `BRANCH_DATABASE_SETUP_FAILED`: database creation or env-var wiring failed before deployment started
+- `SCHEMA_SETUP_FAILED`: local Prisma schema source setup against a newly created database failed before deployment started
 - `RUN_FAILED`: local framework run command could not be started or exited unsuccessfully
 - `DEPLOY_FAILED`: deployment or post-build health failed
 - `VERSION_UNAVAILABLE`: CLI could not read its own bundled package metadata to report a version (defensive; not expected in normal installs)

docs/product/resource-model.md

@@ -154,19 +154,20 @@ resource.
 
 The beta package does not expose a standalone database command group yet. The
 current database surface is limited to `app deploy --db`, which can create an
-empty Prisma Postgres database for a preview Branch, apply a supported local
-Prisma schema source when available, and write normal branch-scoped environment
-variable overrides.
+empty Prisma Postgres database, apply a supported local Prisma schema source
+when available, and write normal environment variables for the deploy target.
 
 Rules:
 
 - database wiring uses the existing environment-variable model
-- `DATABASE_URL` is written as a preview Branch override, not a separate app binding
-- branch database setup never overwrites an existing branch-scoped `DATABASE_URL`
+- preview Branch setup writes branch-scoped `DATABASE_URL` and `DIRECT_URL` overrides, not separate app bindings
+- first production deploy setup writes production `DATABASE_URL` and `DIRECT_URL` env vars before the App has a live deployment
+- database setup never overwrites an existing branch-scoped `DATABASE_URL`
+- production setup treats existing production `DATABASE_URL` or `DIRECT_URL` as BYO DB intent and leaves env vars unchanged
 - schema setup is sourced only from local code; the CLI does not clone or infer schema from another database
 - Prisma Next config (`prisma-next.config.*`) is preferred over `schema.prisma`
 - known non-Postgres Prisma sources are treated as unsupported for automatic Prisma Postgres setup
-- production database configuration is managed through explicit environment-variable commands
+- later production database configuration is managed through explicit environment-variable commands
 
 ## Relationships
 

packages/cli/src/commands/app/index.ts

@@ -183,8 +183,8 @@ function createDeployCommand(runtime: CliRuntime): Command {
       new Option("--env <name=value|file>", "Environment variable assignment or dotenv file")
         .argParser(collectRepeatableValues),
     )
-    .addOption(new Option("--db", "Create and wire an isolated database for the preview Branch"))
-    .addOption(new Option("--no-db", "Skip branch database setup"))
+    .addOption(new Option("--db", "Create and wire a Prisma Postgres database for this deploy target"))
+    .addOption(new Option("--no-db", "Skip database setup"))
     .addOption(new Option("--prod", "Confirm intent to deploy to production"));
   addGlobalFlags(command);
 
@@ -209,7 +209,7 @@ function createDeployCommand(runtime: CliRuntime): Command {
         if (hasDbConflict) {
           throw usageError(
             "app deploy accepts either --db or --no-db",
-            "--db requests branch database setup, while --no-db disables it.",
+            "--db requests database setup, while --no-db disables it.",
             "Pass exactly one database setup flag.",
             [
               "prisma-cli app deploy --db",

packages/cli/src/controllers/app.ts

@@ -310,7 +310,7 @@ export async function runAppDeploy(
   framework = customized.framework;
   runtime = customized.runtime;
 
-  await enforceProductionDeployGate(context, provider, {
+  const productionDeployGate = await enforceProductionDeployGate(context, provider, {
     appId: selectedApp.appId,
     appName: selectedApp.displayName,
     branchKind: target.branch.kind,
@@ -326,6 +326,7 @@ export async function runAppDeploy(
   const branchDatabaseSetup = await maybeSetupBranchDatabase(context, provider, projectId, toBranchDatabaseDeployBranch(target.branch), {
     db: options?.db,
     providedEnvVars: envVars,
+    firstProductionDeploy: productionDeployGate.firstProductionDeploy,
   });
 
   const progressState = createPreviewDeployProgressState();