Support first deploy database setup

[luanvdw]

Overview

Extends app deploy --db from preview-only branch databases to the first production deploy path, while keeping production guardrails around existing env vars and live deployments.

Changes

• Generalizes deploy DB setup so preview writes branch env overrides and first production setup writes production DATABASE_URL / DIRECT_URL through the same env-var APIs.
• Uses the production deploy gate to identify whether the selected production App has no live deployment before allowing setup.
• Treats existing production DATABASE_URL or DIRECT_URL as BYO DB intent and skips without overwriting.
• Updates CLI/help/product docs and adds controller tests for production bootstrap guardrails.

Why

This keeps the preview branch model and avoids managed bindings. Production setup only runs before the App has a live deployment, and any existing DB env var is treated as explicit BYO DB intent.

Validation

• pnpm --filter @prisma/cli test tests/app-branch-database.test.ts
• pnpm --filter @prisma/cli test tests/production-deploy-gate.test.ts
• pnpm --filter @prisma/cli test
• pnpm build:cli
• git diff --check

[coderabbitai]

Warning

Review limit reached

@luanvdw, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 37 minutes and 52 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e92c985e-69aa-4741-994f-982fdbc0dabc

📥 Commits

Reviewing files that changed from the base of the PR and between cdf4b67 and fffbd95.

📒 Files selected for processing (2)

• docs/product/command-spec.md
• packages/cli/tests/app-branch-database.test.ts

Walkthrough

This PR extends the app deploy --db command to handle production deployments alongside preview branches. The core change introduces a first-production-deploy gate that restricts database setup to initial production deploys only. A new environment-scoping abstraction distinguishes branch-scoped overrides (preview) from production-class env vars. The refactored setup flow detects existing production env vars as "BYO DB" intent and skips creation, gates non-interactive use with --yes requirements, and reports branch-specific next steps. Documentation and tests now cover both deployment targets with explicit production vs preview behavior rules.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Support first deploy database setup' directly and clearly summarizes the main change—extending database setup to the first production deploy while the changeset focuses on this feature addition.
Description check	✅ Passed	The description is directly related to the changeset, providing overview, changes, rationale, and validation steps that align with the modifications across docs and code.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/first-deploy-db-setup

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/first-deploy-db-setup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/product/command-spec.md`:
- Around line 642-643: Clarify the second bullet so it explicitly limits the
"DIRECT_URL-only repair" behavior to preview branches: update the sentence that
starts "when only `DIRECT_URL` exists on the branch, explicit `--db` treats it
as partial setup and repairs the pair…" to say "when only `DIRECT_URL` exists on
a preview branch" (or similar) and ensure it references preview branches rather
than "the branch" so it cannot be read as applying to production; keep the first
bullet about production treating existing `DATABASE_URL`/`DIRECT_URL` as BYO
unchanged.

In `@packages/cli/tests/app-branch-database.test.ts`:
- Around line 674-778: The existing test covers the "both keys exist" BYO case
but misses the OR logic; add two new tests in
packages/cli/tests/app-branch-database.test.ts that mirror the current "deploy
--db treats existing production database env vars as BYO DB and leaves them
unchanged" test but where listEnvironmentVariables (used by the mocked preview
provider created in createPreviewAppProvider) returns only DATABASE_URL in one
test and only DIRECT_URL in the other; in each new test assert
createBranchDatabase/createEnvironmentVariable/updateEnvironmentVariable were
not called, deployApp was called, and result.result.branchDatabase equals {
status: "skipped", reason: "production-env-exists", envVars: ["DATABASE_URL"] }
or ["DIRECT_URL"] respectively, keeping the same mocks (requireComputeAuth,
deployApp) and calling runAppDeploy with db: true so the OR-condition is
covered.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 19e8428a-557e-468c-9890-8573446b3c6c

📥 Commits

Reviewing files that changed from the base of the PR and between acb39c6 and cdf4b67.

📒 Files selected for processing (8)

• docs/product/command-spec.md
• docs/product/error-conventions.md
• docs/product/resource-model.md
• packages/cli/src/commands/app/index.ts
• packages/cli/src/controllers/app.ts
• packages/cli/src/lib/app/branch-database-deploy.ts
• packages/cli/src/lib/app/production-deploy-gate.ts
• packages/cli/tests/app-branch-database.test.ts

[AmanVarshney01]

I checked the PR with create-prisma flow and it works great