@prisma/cli 3.0.0-dev.70.1 → 3.0.0-dev.73.1

package/dist/commands/app/index.js

@@ -65,7 +65,7 @@ function createDeployCommand(runtime) {
 		"hono",
 		"tanstack-start",
 		"bun"
-	])).addOption(new Option("--entry <path>", "Entrypoint path for Bun deploys")).addOption(new Option("--http-port <port>", "HTTP port override for the deployed app")).addOption(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("--prod", "Confirm intent to deploy to production"));
+	])).addOption(new Option("--entry <path>", "Entrypoint path for Bun deploys")).addOption(new Option("--http-port <port>", "HTTP port override for the deployed app")).addOption(new Option("--env <name=value|file>", "Environment variable assignment or dotenv file").argParser(collectRepeatableValues)).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);
 	command.action(async (options) => {
 		const appName = options.app;
@@ -80,7 +80,7 @@ function createDeployCommand(runtime) {
 		const db = options.db;
 		const hasDbConflict = hasFlag(runtime.argv, "--db") && hasFlag(runtime.argv, "--no-db");
 		await runCommand(runtime, "app.deploy", options, (context) => {
-			if (hasDbConflict) throw usageError("app deploy accepts either --db or --no-db", "--db requests branch database setup, while --no-db disables it.", "Pass exactly one database setup flag.", ["prisma-cli app deploy --db", "prisma-cli app deploy --no-db"], "app");
+			if (hasDbConflict) throw usageError("app deploy accepts either --db or --no-db", "--db requests database setup, while --no-db disables it.", "Pass exactly one database setup flag.", ["prisma-cli app deploy --db", "prisma-cli app deploy --no-db"], "app");
 			return runAppDeploy(context, appName, {
 				projectRef,
 				createProjectName,

package/dist/controllers/app.js

@@ -31,6 +31,7 @@ import { listRealWorkspaceProjects } from "./project.js";
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import open from "open";
+import { Result, matchError } from "better-result";
 //#region src/controllers/app.ts
 const DEPLOY_FRAMEWORKS = [
 	"nextjs",
@@ -112,9 +113,9 @@ async function runAppDeploy(context, appName, options) {
 		createProjectName: options?.createProjectName,
 		envProjectId
 	});
-	const skipLocalPin = Boolean(envProjectId || options?.projectRef || options?.createProjectName);
-	const localPin = skipLocalPin ? { kind: "missing" } : await readLocalResolutionPin(context.runtime.cwd, context.runtime.signal);
-	if (!skipLocalPin && localPin.kind === "invalid") throw localResolutionPinStaleError();
+	const localPinReadResult = Boolean(envProjectId || options?.projectRef || options?.createProjectName) ? Result.ok({ kind: "missing" }) : await readLocalResolutionPin(context.runtime.cwd, context.runtime.signal);
+	if (localPinReadResult.isErr()) throw localPinReadErrorToDeployError(localPinReadResult.error);
+	const localPin = localPinReadResult.value;
 	const branch = await resolveDeployBranch(context, options?.branchName);
 	if (options?.httpPort) parseDeployHttpPort(options.httpPort);
 	assertSupportedEntrypointForRequestedDeployShape({
@@ -162,7 +163,7 @@ async function runAppDeploy(context, appName, options) {
 	});
 	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,
@@ -180,7 +181,8 @@ async function runAppDeploy(context, appName, options) {
 	const portMapping = parseDeployPortMapping(String(runtime.port));
 	const branchDatabaseSetup = await maybeSetupBranchDatabase(context, provider, projectId, toBranchDatabaseDeployBranch(target.branch), {
 		db: options?.db,
-		providedEnvVars: envVars
+		providedEnvVars: envVars,
+		firstProductionDeploy: productionDeployGate.firstProductionDeploy
 	});
 	const progressState = createPreviewDeployProgressState();
 	const deployStartedAt = Date.now();
@@ -1975,6 +1977,18 @@ function localResolutionPinStaleError() {
 		]
 	});
 }
+function localPinReadErrorToDeployError(error) {
+	return matchError(error, {
+		LocalResolutionPinInvalidJsonError: () => localResolutionPinStaleError(),
+		LocalResolutionPinInvalidShapeError: () => localResolutionPinStaleError(),
+		LocalResolutionPinReadAbortedError: (error) => {
+			throw error;
+		},
+		UnhandledException: (error) => {
+			throw error;
+		}
+	});
+}
 function readDeployEnvOverride(context, name) {
 	const value = context.runtime.env[name]?.trim();
 	return value ? value : void 0;

package/dist/controllers/project.js

@@ -13,6 +13,7 @@ import { requireAuthenticatedAuthState } from "./auth.js";
 import { parseGitHubRepositoryUrl, readGitOriginRemote } from "../adapters/git.js";
 import { createProjectUseCases } from "../use-cases/project.js";
 import open from "open";
+import { matchError } from "better-result";
 //#region src/controllers/project.ts
 const GITHUB_INSTALL_POLL_INTERVAL_MS = 2e3;
 const GITHUB_INSTALL_POLL_TIMEOUT_MS = 12e4;
@@ -20,11 +21,24 @@ function isRealMode(context) {
 	return !context.runtime.fixturePath && !context.runtime.env.PRISMA_CLI_MOCK_FIXTURE_PATH;
 }
 async function readProjectListLocalBinding(cwd, workspace, projects, signal) {
-	const pin = await readLocalResolutionPin(cwd, signal);
+	const pinResult = await readLocalResolutionPin(cwd, signal);
+	if (pinResult.isErr()) return localPinReadErrorToInvalidLocalBinding(pinResult.error);
+	const pin = pinResult.value;
 	if (pin.kind === "present") return pin.pin.workspaceId === workspace.id && projects.some((project) => project.id === pin.pin.projectId) ? { status: "linked" } : { status: "invalid" };
-	if (pin.kind === "invalid") return { status: "invalid" };
 	return { status: "not-linked" };
 }
+function localPinReadErrorToInvalidLocalBinding(error) {
+	return matchError(error, {
+		LocalResolutionPinInvalidJsonError: () => ({ status: "invalid" }),
+		LocalResolutionPinInvalidShapeError: () => ({ status: "invalid" }),
+		LocalResolutionPinReadAbortedError: (error) => {
+			throw error;
+		},
+		UnhandledException: (error) => {
+			throw error;
+		}
+	});
+}
 async function runProjectList(context) {
 	const authState = await requireAuthenticatedAuthState(context);
 	const workspace = authState.workspace;

package/dist/lib/app/branch-database-deploy.js

@@ -3,71 +3,72 @@ import { renderSummaryLine } from "../../shell/ui.js";
 import { canPrompt } from "../../shell/runtime.js";
 import { confirmPrompt } from "../../shell/prompt.js";
 import { formatCommandArgument } from "../../shell/command-arguments.js";
+import "../project/setup.js";
 import { hasBranchDatabaseSignal, inspectBranchDatabaseSignal, runBranchDatabaseSchemaSetup } from "./branch-database.js";
 import path from "node:path";
 //#region src/lib/app/branch-database-deploy.ts
 async function maybeSetupBranchDatabase(context, provider, projectId, branch, options) {
 	if (options.db === false) return emptyBranchDatabaseSetupOutcome();
 	if (hasProvidedDatabaseEnvVars(options.providedEnvVars)) {
-		if (options.db === true) throw usageError("Branch database setup cannot be combined with provided database env vars", "The deploy command received --db and a DATABASE_URL or DIRECT_URL value from --env.", "Remove the --env database value to let --db create a branch override, or remove --db to deploy with the provided value.", ["prisma-cli app deploy --db", "prisma-cli app deploy --env DATABASE_URL=postgresql://example"], "app");
+		if (options.db === true) throw usageError("Database setup cannot be combined with provided database env vars", "The deploy command received --db and a DATABASE_URL or DIRECT_URL value from --env.", "Remove the --env database value to let --db create and wire a database, or remove --db to deploy with the provided value.", ["prisma-cli app deploy --db", "prisma-cli app deploy --env DATABASE_URL=postgresql://example"], "app");
 		return emptyBranchDatabaseSetupOutcome();
 	}
-	if (branch.kind === "production") {
-		if (options.db === true) throw usageError("Branch database setup is only available for preview branches", "Production database wiring is a durable environment decision and is not created implicitly by app deploy.", "Use project env commands to manage production DATABASE_URL, or deploy a preview branch with --db.", ["prisma-cli project env add DATABASE_URL=<value> --role production", "prisma-cli app deploy --branch feature/db --db"], "app");
+	if (branch.kind === "production" && !options.firstProductionDeploy) {
+		if (options.db === true) throw productionDatabaseSetupAfterFirstDeployError();
 		return emptyBranchDatabaseSetupOutcome();
 	}
-	const localSignal = await inspectBranchDatabaseSignal(context.runtime.cwd, context.runtime.signal);
-	const envState = await inspectBranchDatabaseEnv(provider, projectId, branch.id, context.runtime.signal);
-	const branchEnvVars = [envState.branchDatabaseUrl, envState.branchDirectUrl].filter((variable) => Boolean(variable)).map((variable) => variable.key).sort();
-	if (envState.branchDatabaseUrl) {
-		const warning = options.db === true ? `Branch "${branch.name}" already has DATABASE_URL. Leaving branch database env vars unchanged.` : null;
+	const envState = await inspectBranchDatabaseEnv(provider, projectId, branch, context.runtime.signal);
+	const targetEnvVars = getTargetDatabaseEnvVarKeys(envState);
+	if (hasExistingDatabaseEnvForTarget(branch, envState)) {
+		const warning = options.db === true ? existingDatabaseEnvWarning(branch, targetEnvVars) : null;
 		if (warning) emitBranchDatabaseWarning(context, warning);
 		return {
 			result: options.db === true ? {
 				status: "skipped",
-				reason: "branch-env-exists",
-				envVars: branchEnvVars,
+				reason: existingDatabaseEnvReason(branch),
+				envVars: targetEnvVars,
 				schema: null
 			} : void 0,
 			warnings: warning ? [warning] : []
 		};
 	}
+	const localSignal = await inspectBranchDatabaseSignal(context.runtime.cwd, context.runtime.signal);
 	if (localSignal.unsupportedSchema) {
-		if (options.db === true) throw unsupportedBranchDatabaseSchemaError(localSignal.unsupportedSchema, branch.name, context);
+		if (options.db === true) throw unsupportedBranchDatabaseSchemaError(localSignal.unsupportedSchema, branch, context);
 		return emptyBranchDatabaseSetupOutcome();
 	}
-	const hasSignal = hasBranchDatabaseSignal(localSignal) || Boolean(envState.previewDatabaseUrl);
+	const hasSignal = hasBranchDatabaseSignal(localSignal) || Boolean(envState.inheritedPreviewDatabaseUrl);
 	if (options.db !== true) {
 		if (!hasSignal) return emptyBranchDatabaseSetupOutcome();
 		if (!canPrompt(context) || context.flags.yes) {
-			const warning = "This app appears to use DATABASE_URL. Run prisma-cli app deploy --db to create an isolated database for this preview branch.";
+			const warning = databasePromptSuppressedWarning(branch);
 			emitBranchDatabaseWarning(context, warning);
 			return {
 				result: void 0,
 				warnings: [warning]
 			};
 		}
-		maybeRenderBranchDatabaseSignal(context, branch.name, localSignal, envState);
+		maybeRenderBranchDatabaseSignal(context, branch, localSignal, envState);
 		if (!await confirmPrompt({
 			input: context.runtime.stdin,
 			output: context.output.stderr,
-			message: `Create an isolated database for branch "${branch.name}"?`,
+			message: databasePromptMessage(branch),
 			initialValue: false
 		})) return emptyBranchDatabaseSetupOutcome();
-	}
+	} else if (!canPrompt(context) && !context.flags.yes) throw nonInteractiveDatabaseSetupRequiresYesError(branch);
 	return setupBranchDatabase(context, provider, projectId, branch, localSignal, envState);
 }
 async function setupBranchDatabase(context, provider, projectId, branch, signal, envState) {
-	emitBranchDatabaseProgress(context, "pending", "Creating branch database");
+	emitBranchDatabaseProgress(context, "pending", "Creating database");
 	const database = await provider.createBranchDatabase({
 		projectId,
 		branchId: branch.id,
 		branchName: branch.name,
 		signal: context.runtime.signal
 	}).catch((error) => {
-		throw branchDatabaseSetupFailedError("Failed to create branch database", error, branch.name);
+		throw branchDatabaseSetupFailedError("Failed to create database", error, branch);
 	});
-	emitBranchDatabaseProgress(context, "success", "Created branch database");
+	emitBranchDatabaseProgress(context, "success", "Created database");
 	try {
 		let schemaSetup = null;
 		const warnings = [];
@@ -80,12 +81,12 @@ async function setupBranchDatabase(context, provider, projectId, branch, signal,
 				databaseUrl: database.databaseUrl,
 				directUrl: database.directUrl
 			}).catch((error) => {
-				throw schemaSetupFailedError(error, signal.schema, branch.name, context.runtime.cwd);
+				throw schemaSetupFailedError(error, signal.schema, branch, context.runtime.cwd);
 			});
 			emitBranchDatabaseProgress(context, "success", "Applied database schema");
-		} else skippedSchemaWarning = "No supported Prisma schema source was found. Branch database env vars were created, but schema setup was skipped.";
+		} else skippedSchemaWarning = "No supported Prisma schema source was found. Database env vars were created, but schema setup was skipped.";
 		const envVars = await upsertBranchDatabaseEnvVars(context, provider, projectId, branch, database, envState);
-		emitBranchDatabaseProgress(context, "success", `Added branch env override${envVars.length === 1 ? "" : "s"} ${envVars.join(", ")}`);
+		emitBranchDatabaseProgress(context, "success", `Added ${envScopeLabel(branch)} env var${envVars.length === 1 ? "" : "s"} ${envVars.join(", ")}`);
 		if (skippedSchemaWarning) {
 			emitBranchDatabaseWarning(context, skippedSchemaWarning);
 			warnings.push(skippedSchemaWarning);
@@ -107,37 +108,36 @@ async function setupBranchDatabase(context, provider, projectId, branch, signal,
 			warnings
 		};
 	} catch (error) {
-		throw await cleanupCreatedBranchDatabaseAfterFailure(context, provider, database, branch.name, error);
+		throw await cleanupCreatedBranchDatabaseAfterFailure(context, provider, database, branch, error);
 	}
 }
 async function upsertBranchDatabaseEnvVars(context, provider, projectId, branch, database, envState) {
+	const scope = envScopeForBranch(branch);
 	const written = [];
 	await upsertBranchDatabaseEnvVar(context, provider, {
 		projectId,
-		branchId: branch.id,
-		className: "preview",
+		...scope,
 		key: "DATABASE_URL",
 		value: database.databaseUrl,
-		existing: envState.branchDatabaseUrl,
-		branchName: branch.name
+		existing: envState.targetDatabaseUrl,
+		branch
 	});
 	written.push("DATABASE_URL");
 	if (database.directUrl) {
 		await upsertBranchDatabaseEnvVar(context, provider, {
 			projectId,
-			branchId: branch.id,
-			className: "preview",
+			...scope,
 			key: "DIRECT_URL",
 			value: database.directUrl,
-			existing: envState.branchDirectUrl,
-			branchName: branch.name
+			existing: envState.targetDirectUrl,
+			branch
 		});
 		written.push("DIRECT_URL");
-	} else if (envState.branchDirectUrl) await provider.deleteEnvironmentVariable({
-		envVarId: envState.branchDirectUrl.id,
+	} else if (branch.kind === "preview" && envState.targetDirectUrl) await provider.deleteEnvironmentVariable({
+		envVarId: envState.targetDirectUrl.id,
 		signal: context.runtime.signal
 	}).catch((error) => {
-		throw branchDatabaseSetupFailedError("Failed to remove stale DIRECT_URL", error, branch.name);
+		throw branchDatabaseSetupFailedError("Failed to remove stale DIRECT_URL", error, branch);
 	});
 	return written;
 }
@@ -148,37 +148,39 @@ async function upsertBranchDatabaseEnvVar(context, provider, options) {
 			value: options.value,
 			signal: context.runtime.signal
 		}).catch((error) => {
-			throw branchDatabaseSetupFailedError(`Failed to update ${options.key}`, error, options.branchName);
+			throw branchDatabaseSetupFailedError(`Failed to update ${options.key}`, error, options.branch);
 		});
 		return;
 	}
 	await provider.createEnvironmentVariable({
 		projectId: options.projectId,
-		branchId: options.branchId,
 		className: options.className,
 		key: options.key,
 		value: options.value,
+		...options.branchId ? { branchId: options.branchId } : {},
 		signal: context.runtime.signal
 	}).catch((error) => {
-		throw branchDatabaseSetupFailedError(`Failed to write ${options.key}`, error, options.branchName);
+		throw branchDatabaseSetupFailedError(`Failed to write ${options.key}`, error, options.branch);
 	});
 }
-async function inspectBranchDatabaseEnv(provider, projectId, branchId, signal) {
+async function inspectBranchDatabaseEnv(provider, projectId, branch, signal) {
+	const scope = envScopeForBranch(branch);
 	const [databaseUrlRows, directUrlRows] = await Promise.all([provider.listEnvironmentVariables({
 		projectId,
-		className: "preview",
+		className: scope.className,
 		key: "DATABASE_URL",
 		signal
 	}), provider.listEnvironmentVariables({
 		projectId,
-		className: "preview",
+		className: scope.className,
 		key: "DIRECT_URL",
 		signal
 	})]);
+	const targetBranchId = branch.kind === "preview" ? branch.id : null;
 	return {
-		branchDatabaseUrl: findEnvVar(databaseUrlRows, { branchId }),
-		branchDirectUrl: findEnvVar(directUrlRows, { branchId }),
-		previewDatabaseUrl: findEnvVar(databaseUrlRows, { branchId: null })
+		targetDatabaseUrl: findEnvVar(databaseUrlRows, { branchId: targetBranchId }),
+		targetDirectUrl: findEnvVar(directUrlRows, { branchId: targetBranchId }),
+		inheritedPreviewDatabaseUrl: branch.kind === "preview" ? findEnvVar(databaseUrlRows, { branchId: null }) : null
 	};
 }
 function findEnvVar(rows, options) {
@@ -187,14 +189,47 @@ function findEnvVar(rows, options) {
 function hasProvidedDatabaseEnvVars(envVars) {
 	return Boolean(envVars && ("DATABASE_URL" in envVars || "DIRECT_URL" in envVars));
 }
-function maybeRenderBranchDatabaseSignal(context, branchName, signal, envState) {
+function envScopeForBranch(branch) {
+	return branch.kind === "production" ? { className: "production" } : {
+		className: "preview",
+		branchId: branch.id
+	};
+}
+function envScopeLabel(branch) {
+	return branch.kind === "production" ? "production" : "branch";
+}
+function getTargetDatabaseEnvVarKeys(envState) {
+	return [envState.targetDatabaseUrl, envState.targetDirectUrl].filter((variable) => Boolean(variable)).map((variable) => variable.key).sort();
+}
+function hasExistingDatabaseEnvForTarget(branch, envState) {
+	if (branch.kind === "production") return Boolean(envState.targetDatabaseUrl || envState.targetDirectUrl);
+	return Boolean(envState.targetDatabaseUrl);
+}
+function existingDatabaseEnvReason(branch) {
+	return branch.kind === "production" ? "production-env-exists" : "branch-env-exists";
+}
+function existingDatabaseEnvWarning(branch, envVars) {
+	if (branch.kind === "production") return `Production already has ${envVars.join(" and ")}. Treating it as BYO database configuration and leaving env vars unchanged.`;
+	return `Branch "${branch.name}" already has DATABASE_URL. Leaving branch database env vars unchanged.`;
+}
+function databasePromptSuppressedWarning(branch) {
+	if (branch.kind === "production") return "This app appears to use DATABASE_URL. Run prisma-cli app deploy --db --yes to create and wire a Prisma Postgres database for this first production deploy.";
+	return "This app appears to use DATABASE_URL. Run prisma-cli app deploy --db to create an isolated database for this preview branch.";
+}
+function databasePromptMessage(branch) {
+	return branch.kind === "production" ? "Create a Prisma Postgres database for production?" : `Create an isolated database for branch "${branch.name}"?`;
+}
+function maybeRenderBranchDatabaseSignal(context, branch, signal, envState) {
 	if (context.flags.json || context.flags.quiet) return;
 	const rows = [
 		signal.schema ? `  Schema  ${path.relative(context.runtime.cwd, signal.schema.path) || defaultSchemaSourcePath(signal.schema)}` : null,
 		signal.databaseUrlReferences.length > 0 ? `  Code    ${signal.databaseUrlReferences.slice(0, 3).join(", ")}` : null,
-		envState.previewDatabaseUrl ? "  Env     preview DATABASE_URL is inherited by this branch" : null
+		envState.inheritedPreviewDatabaseUrl ? "  Env     preview DATABASE_URL is inherited by this branch" : null
 	].filter((row) => Boolean(row));
-	context.output.stderr.write(`Database signal found for branch "${branchName}"\n${rows.join("\n")}\n\n`);
+	context.output.stderr.write(`Database signal found for ${databaseTargetLabel(branch)}\n${rows.join("\n")}\n\n`);
+}
+function databaseTargetLabel(branch) {
+	return branch.kind === "production" ? `production branch "${branch.name}"` : `branch "${branch.name}"`;
 }
 function emitBranchDatabaseProgress(context, status, message) {
 	if (context.flags.json || context.flags.quiet) return;
@@ -211,6 +246,12 @@ function emptyBranchDatabaseSetupOutcome() {
 		warnings: []
 	};
 }
+function productionDatabaseSetupAfterFirstDeployError() {
+	return usageError("Database setup is only available during the first production deploy", "The selected production app already has a live deployment.", "Use project env commands to manage production DATABASE_URL, or deploy a preview branch with --db.", ["prisma-cli project env add DATABASE_URL=<value> --role production", "prisma-cli app deploy --branch feature/db --db"], "app");
+}
+function nonInteractiveDatabaseSetupRequiresYesError(branch) {
+	return usageError("Database setup requires --yes in non-interactive mode", "The deploy command received --db, but prompts are not available and --yes was not passed.", "Pass --yes together with --db to confirm non-interactive database creation.", [branch.kind === "production" ? "prisma-cli app deploy --prod --db --yes" : `prisma-cli app deploy --branch ${formatCommandArgument(branch.name)} --db --yes`], "app");
+}
 function formatSchemaSetupCommand(command) {
 	switch (command) {
 		case "migrate-deploy": return "prisma migrate deploy";
@@ -218,46 +259,46 @@ function formatSchemaSetupCommand(command) {
 		case "prisma-next-db-init": return "prisma-next db init";
 	}
 }
-function branchDatabaseSetupFailedError(summary, error, branchName) {
+function branchDatabaseSetupFailedError(summary, error, branch) {
 	return new CliError({
 		code: "BRANCH_DATABASE_SETUP_FAILED",
 		domain: "app",
 		summary,
 		why: error instanceof Error ? error.message : String(error),
-		fix: "Retry the command, or create the branch database and env vars manually with project env commands.",
+		fix: "Retry the command, or create the database and env vars manually with project env commands.",
 		debug: formatDebugDetails(error),
-		meta: { branch: branchName },
+		meta: { branch: branch.name },
 		exitCode: 1,
-		nextSteps: [`prisma-cli app deploy --branch ${formatCommandArgument(branchName)} --db`, `prisma-cli project env list --branch ${formatCommandArgument(branchName)}`]
+		nextSteps: [formatAppDeployWithDbNextStep(branch), formatProjectEnvListNextStep(branch)]
 	});
 }
-async function cleanupCreatedBranchDatabaseAfterFailure(context, provider, database, branchName, error) {
-	const setupError = error instanceof CliError ? error : branchDatabaseSetupFailedError("Branch database setup failed", error, branchName);
-	emitBranchDatabaseProgress(context, "pending", "Removing branch database after setup failed");
+async function cleanupCreatedBranchDatabaseAfterFailure(context, provider, database, branch, error) {
+	const setupError = error instanceof CliError ? error : branchDatabaseSetupFailedError("Database setup failed", error, branch);
+	emitBranchDatabaseProgress(context, "pending", "Removing database after setup failed");
 	try {
 		await provider.deleteBranchDatabase({
 			databaseId: database.id,
 			signal: context.runtime.signal
 		});
-		emitBranchDatabaseProgress(context, "success", "Removed branch database after setup failed");
+		emitBranchDatabaseProgress(context, "success", "Removed database after setup failed");
 	} catch (cleanupError) {
-		return branchDatabaseCleanupFailedError(setupError, cleanupError, database, branchName);
+		return branchDatabaseCleanupFailedError(setupError, cleanupError, database, branch);
 	}
 	return setupError;
 }
-function branchDatabaseCleanupFailedError(setupError, cleanupError, database, branchName) {
+function branchDatabaseCleanupFailedError(setupError, cleanupError, database, branch) {
 	const cleanupWhy = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
-	const setupWhy = setupError.why ?? "Branch database setup failed.";
+	const setupWhy = setupError.why ?? "Database setup failed.";
 	return new CliError({
 		code: setupError.code,
 		domain: setupError.domain,
 		summary: setupError.summary,
 		why: `${setupWhy} Prisma could not delete the created database "${database.name}" (${database.id}): ${cleanupWhy}`,
-		fix: "Delete the created branch database from Console or contact Prisma support, then rerun deploy with --db.",
+		fix: "Delete the created database from Console or contact Prisma support, then rerun deploy with --db.",
 		debug: formatCombinedDebugDetails(setupError, cleanupError),
 		meta: {
 			...setupError.meta,
-			branch: branchName,
+			branch: branch.name,
 			databaseId: database.id,
 			databaseName: database.name,
 			cleanupFailed: true
@@ -266,7 +307,7 @@ function branchDatabaseCleanupFailedError(setupError, cleanupError, database, br
 		nextSteps: []
 	});
 }
-function schemaSetupFailedError(error, schema, branchName, cwd) {
+function schemaSetupFailedError(error, schema, branch, cwd) {
 	return new CliError({
 		code: "SCHEMA_SETUP_FAILED",
 		domain: "app",
@@ -275,17 +316,26 @@ function schemaSetupFailedError(error, schema, branchName, cwd) {
 		fix: "Fix the Prisma schema or migrations, then rerun deploy with --db.",
 		debug: formatDebugDetails(error),
 		meta: {
-			branch: branchName,
+			branch: branch.name,
 			schemaPath: schema.path,
 			source: schema.kind,
 			command: schema.command
 		},
 		exitCode: 1,
-		nextSteps: [...formatSchemaSetupNextSteps(schema, cwd), `prisma-cli app deploy --branch ${formatCommandArgument(branchName)} --db`]
+		nextSteps: [...formatSchemaSetupNextSteps(schema, cwd), formatAppDeployWithDbNextStep(branch)]
 	});
 }
-function unsupportedBranchDatabaseSchemaError(schema, branchName, context) {
-	return usageError("Branch database setup is not available for this Prisma schema", `${path.relative(context.runtime.cwd, schema.path) || defaultUnsupportedSchemaSourcePath(schema)} targets ${formatUnsupportedSchemaTarget(schema.target)}, but --db creates Prisma Postgres databases.`, "Use project env commands to provide a database URL for this branch, or switch the Prisma schema source to PostgreSQL before using --db.", [`prisma-cli project env add DATABASE_URL=<value> --branch ${formatCommandArgument(branchName)}`, `prisma-cli app deploy --branch ${formatCommandArgument(branchName)}`], "app");
+function unsupportedBranchDatabaseSchemaError(schema, branch, context) {
+	return usageError("Database setup is not available for this Prisma schema", `${path.relative(context.runtime.cwd, schema.path) || defaultUnsupportedSchemaSourcePath(schema)} targets ${formatUnsupportedSchemaTarget(schema.target)}, but --db creates Prisma Postgres databases.`, "Use project env commands to provide a database URL, or switch the Prisma schema source to PostgreSQL before using --db.", [formatProjectEnvAddNextStep(branch), `prisma-cli app deploy --branch ${formatCommandArgument(branch.name)}`], "app");
+}
+function formatAppDeployWithDbNextStep(branch) {
+	return `prisma-cli app deploy --branch ${formatCommandArgument(branch.name)} --db`;
+}
+function formatProjectEnvListNextStep(branch) {
+	return branch.kind === "production" ? "prisma-cli project env list --role production" : `prisma-cli project env list --branch ${formatCommandArgument(branch.name)}`;
+}
+function formatProjectEnvAddNextStep(branch) {
+	return branch.kind === "production" ? "prisma-cli project env add DATABASE_URL=<value> --role production" : `prisma-cli project env add DATABASE_URL=<value> --branch ${formatCommandArgument(branch.name)}`;
 }
 function formatSchemaSetupNextSteps(schema, cwd) {
 	const sourcePath = path.relative(cwd, schema.path) || defaultSchemaSourcePath(schema);

package/dist/lib/app/production-deploy-gate.js

@@ -3,22 +3,22 @@ import { canPrompt } from "../../shell/runtime.js";
 import { confirmPrompt } from "../../shell/prompt.js";
 //#region src/lib/app/production-deploy-gate.ts
 async function enforceProductionDeployGate(context, provider, options) {
-	if (options.branchKind !== "production") return;
+	if (options.branchKind !== "production") return { firstProductionDeploy: false };
 	if (!options.appId) {
 		renderFirstProductionDeployLine(context, options.appName);
-		return;
+		return { firstProductionDeploy: true };
 	}
 	const currentLiveDeployment = resolveCurrentProductionDeployment(await provider.listDeployments(options.appId).catch((error) => {
 		throw productionDeployInspectionFailedError(error);
 	}));
 	if (!currentLiveDeployment) {
 		renderFirstProductionDeployLine(context, options.appName);
-		return;
+		return { firstProductionDeploy: true };
 	}
 	if (!options.prod) throw productionDeployRequiresFlagError();
 	if (context.flags.yes) {
 		renderProductionDeployYesLine(context);
-		return;
+		return { firstProductionDeploy: false };
 	}
 	if (!canPrompt(context)) throw productionDeployConfirmationRequiredError(options.appName);
 	renderProductionDeployConfirmation(context, currentLiveDeployment);
@@ -28,6 +28,7 @@ async function enforceProductionDeployGate(context, provider, options) {
 		message: "Deploy to production?",
 		initialValue: false
 	})) throw productionDeployCancelledError();
+	return { firstProductionDeploy: false };
 }
 function resolveCurrentProductionDeployment(result) {
 	if (result.deployments.length === 0) return null;

package/dist/lib/project/local-pin.js

@@ -1,25 +1,75 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { Result, TaggedError, UnhandledException } from "better-result";
 //#region src/lib/project/local-pin.ts
 const LOCAL_RESOLUTION_PIN_RELATIVE_PATH = ".prisma/local.json";
-async function readLocalResolutionPin(cwd, signal) {
-	signal?.throwIfAborted();
-	try {
-		const raw = await readFile(path.join(cwd, LOCAL_RESOLUTION_PIN_RELATIVE_PATH), {
-			encoding: "utf8",
-			signal
+var LocalResolutionPinInvalidJsonError = class extends TaggedError("LocalResolutionPinInvalidJsonError")() {
+	constructor(cause) {
+		super({
+			message: `${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} contains invalid JSON.`,
+			cause,
+			pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH
+		});
+	}
+};
+var LocalResolutionPinInvalidShapeError = class extends TaggedError("LocalResolutionPinInvalidShapeError")() {
+	constructor() {
+		super({
+			message: `${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} must contain workspaceId and projectId string fields only.`,
+			pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH
+		});
+	}
+};
+var LocalResolutionPinReadAbortedError = class extends TaggedError("LocalResolutionPinReadAbortedError")() {
+	constructor(cause) {
+		super({
+			message: `Reading ${LOCAL_RESOLUTION_PIN_RELATIVE_PATH} was aborted.`,
+			cause,
+			pinPath: LOCAL_RESOLUTION_PIN_RELATIVE_PATH
 		});
-		const parsed = JSON.parse(raw);
-		if (!isLocalResolutionPin(parsed)) return { kind: "invalid" };
-		return {
+	}
+};
+async function readLocalResolutionPin(cwd, signal) {
+	return Result.gen(async function* () {
+		yield* ensureLocalResolutionPinReadNotAborted(signal);
+		const file = yield* Result.await(readLocalResolutionPinFile(cwd, signal));
+		if (file.kind === "missing") return Result.ok({ kind: "missing" });
+		const parsed = yield* parseLocalResolutionPin(file.raw);
+		if (!isLocalResolutionPin(parsed)) return Result.err(new LocalResolutionPinInvalidShapeError());
+		return Result.ok({
 			kind: "present",
 			pin: parsed
-		};
-	} catch (error) {
-		if (error.code === "ENOENT") return { kind: "missing" };
-		if (error instanceof SyntaxError) return { kind: "invalid" };
-		throw error;
+		});
+	});
+}
+function ensureLocalResolutionPinReadNotAborted(signal) {
+	return Result.try({
+		try: () => signal?.throwIfAborted(),
+		catch: (cause) => new LocalResolutionPinReadAbortedError(cause)
+	});
+}
+async function readLocalResolutionPinFile(cwd, signal) {
+	const readResult = await Result.tryPromise({
+		try: () => readFile(path.join(cwd, LOCAL_RESOLUTION_PIN_RELATIVE_PATH), {
+			encoding: "utf8",
+			signal
+		}),
+		catch: (cause) => signal?.aborted ? new LocalResolutionPinReadAbortedError(cause) : new UnhandledException({ cause })
+	});
+	if (readResult.isErr()) {
+		if (readResult.error instanceof UnhandledException && readResult.error.cause.code === "ENOENT") return Result.ok({ kind: "missing" });
+		return Result.err(readResult.error);
 	}
+	return Result.ok({
+		kind: "present",
+		raw: readResult.value
+	});
+}
+function parseLocalResolutionPin(raw) {
+	return Result.try({
+		try: () => JSON.parse(raw),
+		catch: (cause) => cause instanceof SyntaxError ? new LocalResolutionPinInvalidJsonError(cause) : new UnhandledException({ cause })
+	});
 }
 async function writeLocalResolutionPin(cwd, pin, signal) {
 	const prismaDir = path.join(cwd, ".prisma");

package/dist/lib/project/resolution.js

@@ -3,6 +3,7 @@ import { formatCommandArgument } from "../../shell/command-arguments.js";
 import { LOCAL_RESOLUTION_PIN_RELATIVE_PATH, readLocalResolutionPin } from "./local-pin.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { matchError } from "better-result";
 //#region src/lib/project/resolution.ts
 async function resolveProjectTarget(options) {
 	const localPin = await readImplicitLocalPin(options, { allowEnvProjectId: true });
@@ -224,7 +225,6 @@ async function resolveBoundProjectTarget(options, projects, settings) {
 	}
 	const localPin = settings.localPin;
 	if (!localPin) return null;
-	if (localPin.kind === "invalid") throw localStateStaleError();
 	if (localPin.kind === "present") {
 		if (localPin.pin.workspaceId !== options.workspace.id) throw localProjectWorkspaceMismatchError({
 			pinnedWorkspaceId: localPin.pin.workspaceId,
@@ -247,7 +247,9 @@ async function resolveBoundProjectTarget(options, projects, settings) {
 }
 async function readImplicitLocalPin(options, settings) {
 	if (options.explicitProject || settings.allowEnvProjectId && options.envProjectId) return null;
-	const localPin = await readLocalResolutionPin(options.context.runtime.cwd, options.context.runtime.signal);
+	const localPinResult = await readLocalResolutionPin(options.context.runtime.cwd, options.context.runtime.signal);
+	if (localPinResult.isErr()) throw localPinReadErrorToProjectError(localPinResult.error);
+	const localPin = localPinResult.value;
 	if (localPin.kind === "present" && localPin.pin.workspaceId !== options.workspace.id) throw localProjectWorkspaceMismatchError({
 		pinnedWorkspaceId: localPin.pin.workspaceId,
 		pinnedProjectId: localPin.pin.projectId,
@@ -255,6 +257,18 @@ async function readImplicitLocalPin(options, settings) {
 	});
 	return localPin;
 }
+function localPinReadErrorToProjectError(error) {
+	return matchError(error, {
+		LocalResolutionPinInvalidJsonError: () => localStateStaleError(),
+		LocalResolutionPinInvalidShapeError: () => localStateStaleError(),
+		LocalResolutionPinReadAbortedError: (error) => {
+			throw error;
+		},
+		UnhandledException: (error) => {
+			throw error;
+		}
+	});
+}
 function resolvedTarget(workspace, project, projectSource, resolutionDetails) {
 	return {
 		workspace,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma/cli",
-  "version": "3.0.0-dev.70.1",
+  "version": "3.0.0-dev.73.1",
   "description": "Command-line interface for the Prisma Developer Platform.",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
     "@prisma/compute-sdk": "^0.22.0",
     "@prisma/credentials-store": "^7.8.0",
     "@prisma/management-api-sdk": "^1.37.0",
+    "better-result": "^2.9.2",
     "c12": "4.0.0-beta.5",
     "colorette": "^2.0.20",
     "commander": "^14.0.3",