From 7945599dca37216ccb26246bdabbc31085db7260 Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Tue, 14 Jul 2026 15:25:56 +0530 Subject: [PATCH 1/4] feat(prisma-compute): teach agents the CLI feedback command --- prisma-compute/SKILL.md | 1 + prisma-compute/references/troubleshooting.md | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/prisma-compute/SKILL.md b/prisma-compute/SKILL.md index 1d76cd1..3a74424 100644 --- a/prisma-compute/SKILL.md +++ b/prisma-compute/SKILL.md @@ -148,6 +148,7 @@ Use this skill for: - `deploy-json-for-agents` - Use `--json --no-interactive` for scripts and agent-readable output. - `deploy-create-project` - Use `--create-project ` only when the user wants deploy to create and link a new project; it conflicts with `--project` and `PRISMA_PROJECT_ID`. - `deploy-ops-targets` - App show/open/logs/list-deploys/promote/rollback/remove and domain commands can also accept `[app]` targets from `prisma.compute.ts`. +- `deploy-report-cli-bugs` - When a `@prisma/cli` command crashes (`UNEXPECTED_ERROR`) or fails in a way you cannot resolve, report it with `bunx @prisma/cli@latest feedback ": "`. Crash envelopes in `--json` include the exact pre-filled command in `nextActions`; run it as-is. Reports are anonymous and carry only the message plus CLI, node, and OS versions; never include secrets, URLs with credentials, or user data in the message. ### 8. SDK and API diff --git a/prisma-compute/references/troubleshooting.md b/prisma-compute/references/troubleshooting.md index de0bef0..1c9ebdc 100644 --- a/prisma-compute/references/troubleshooting.md +++ b/prisma-compute/references/troubleshooting.md @@ -423,3 +423,13 @@ bunx @prisma/cli@latest build logs --json Use `build logs` for build output keyed by a Build id from a GitHub check run, Console build page, or Management API build record. Use `app logs` for runtime logs keyed by the current app deployment or a deployment id. Summarize relevant errors. Do not paste secrets. + +## Report Unresolved CLI Issues + +When a CLI failure survives the checks above, or a command crashes with `UNEXPECTED_ERROR`, report it to the Prisma team: + +```bash +bunx @prisma/cli@latest feedback "app deploy crashed: " +``` + +Crash output points here on its own: human mode prints a `Tell us what happened:` hint, and `--json` crash envelopes carry the exact pre-filled command as a `recover` entry in `nextActions`; prefer running that command verbatim. Feedback is anonymous and attaches only the CLI version, node version, and OS platform/arch. Do not put secrets, connection URLs, or tokens in the message. From 5ac4f1a9cc2e4c789d4e41df4eb0b55f3de3669c Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Tue, 14 Jul 2026 17:12:31 +0530 Subject: [PATCH 2/4] feat(prisma-compute): cover init as the config generator; bump to 1.4.0 --- prisma-compute/SKILL.md | 3 ++- prisma-compute/references/compute-config.md | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/prisma-compute/SKILL.md b/prisma-compute/SKILL.md index 3a74424..1ef0c3c 100644 --- a/prisma-compute/SKILL.md +++ b/prisma-compute/SKILL.md @@ -4,7 +4,7 @@ description: Prisma Compute deployment and hosting guide. Use whenever the user license: MIT metadata: author: prisma - version: "1.3.1" + version: "1.4.0" --- # Prisma Compute @@ -120,6 +120,7 @@ Use this skill for: ### 5. Typed Compute Config - `config-optional-simple-app` - `prisma.compute.ts` is not required to deploy a normal single app; use flags when there is no durable config. +- `config-init-formalizer` - Generate a fresh config with `bunx @prisma/cli@latest init`: it detects the framework, pins name/framework/httpPort (plus entry for Bun/Hono), and offers the Project link. `--format json` writes a dependency-free `prisma.compute.json` instead. `init` refuses when any config already exists, never scaffolds code, and never deploys. - `config-use-prisma-compute-ts` - Put reusable deploy defaults in `prisma.compute.ts` with `defineComputeConfig`, not in `prisma.config.ts`. - `config-app-vs-apps` - Use `app` for a single deploy target and `apps` for monorepos or multi-app repos; define exactly one. - `config-monorepo-roots` - For monorepos, use `prisma.compute.ts` to declare app targets, roots, framework defaults, entrypoints, ports, and env inputs. diff --git a/prisma-compute/references/compute-config.md b/prisma-compute/references/compute-config.md index 62a533a..ad0eb9f 100644 --- a/prisma-compute/references/compute-config.md +++ b/prisma-compute/references/compute-config.md @@ -6,6 +6,12 @@ Use this reference when creating or updating `prisma.compute.ts`, especially for For monorepos or multi-app repositories, use `prisma.compute.ts`: it is the practical way to tell Compute which app target lives at which `root` and which framework/entry/env defaults belong to each target. +## Generating a Config with `init` + +Prefer `bunx @prisma/cli@latest init` over hand-writing a fresh single-app config. It detects the framework from the same registry deploy uses, pins `name`, `framework`, and `httpPort` (plus `entry` for Bun and Hono), previews every value with its source, offers the `@prisma/compute-sdk` devDependency for editor types, and offers the Project link. Useful flags: `--framework`, `--entry`, `--http-port`, `--name`, `--no-link`, `--json`. + +`--format json` writes a dependency-free static `prisma.compute.json` instead of the TypeScript config; a later explicit `init --format ts` converts it in place when the config needs to become programmatic. `init` fails with `INIT_CONFIG_EXISTS` when any compute config already exists, never scaffolds application code, and never deploys. Multi-app monorepo configs are still written by hand. + ## File Names and Discovery The canonical file is `prisma.compute.ts`. The loader also accepts: From 2a93ee0f400e25ca05e768815ab8300606e633ef Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Tue, 14 Jul 2026 17:29:45 +0530 Subject: [PATCH 3/4] fix: refresh prisma-compute and prisma-postgres against current sources Audited against prisma/prisma-cli (command spec + source), the installed @prisma/compute-sdk 0.34.0, prisma/project-compute, and prisma/pdp-control-plane. prisma-compute: - build blocks are accepted for every framework (all build types are config-backed); the 'CLI rejects build blocks for nuxt/astro/nestjs' claim was never true for these SDKs; reworded in seven places - deploy-time database setup via --db/--no-db (--db --yes in CI) replaces the stale 'do not add database setup to deploy examples' - --no-promote build-then-verify path; first production deploy auto-promotes without --prod - project rename/transfer/remove, database usage/backup list/restore, connection rotate added to the command surface - agent deploy template no longer assumes --prod - prisma.compute.json in the accepted filename list; bun.lockb in the discovery boundaries; top-level region default documented - NestJS detection includes nest-cli.json; deploy port default is framework-specific (Astro 4321) - branch wording narrowed to branch list (no create/remove commands) - SDK deploy-result fields completed; env-var scope follows branch role prisma-postgres (7.6.0 -> 7.7.0): - @prisma/cli database group added for persistent databases - Workspace->Project->Branch->Database model and branch endpoints - endpoints.direct/endpoints.pooled documented; flat connectionString deprecated; one-time-view secret behavior noted --- prisma-compute/SKILL.md | 7 ++++--- prisma-compute/references/app-deploy-cli.md | 21 +++++++++++++++---- prisma-compute/references/compute-config.md | 9 +++++--- prisma-compute/references/frameworks.md | 20 +++++++++--------- prisma-compute/references/sdk-api.md | 4 ++-- prisma-postgres/SKILL.md | 16 +++++++++++++- .../references/console-and-connections.md | 2 ++ prisma-postgres/references/management-api.md | 10 ++++++++- 8 files changed, 65 insertions(+), 24 deletions(-) diff --git a/prisma-compute/SKILL.md b/prisma-compute/SKILL.md index 1ef0c3c..6b9854a 100644 --- a/prisma-compute/SKILL.md +++ b/prisma-compute/SKILL.md @@ -42,7 +42,7 @@ Use this skill for: - Creating or updating a typed `prisma.compute.ts` deploy config - Deciding whether a framework is Compute-ready - Debugging `create-prisma --deploy`, `compute:deploy`, or `app deploy` -- Managing Compute app logs, deployments, environment variables, branches, and domains +- Managing Compute app logs, deployments, environment variables, and domains, and listing platform branches (`branch list`; there are no branch create/remove commands) - Inspecting GitHub/Console build logs and GitHub push-to-deploy status - Running non-interactive deploys with browser auth, multiple stored workspaces, or Prisma service tokens - Switching, selecting, listing, or logging out local Prisma Platform workspaces for `@prisma/cli` @@ -138,11 +138,12 @@ Use this skill for: - `env-cli-token-name` - `@prisma/cli` uses `PRISMA_SERVICE_TOKEN` for service-token auth. - `env-branch-scope` - Branch deploys, branch env vars, and branch databases must use the same branch name; pass `--branch ` explicitly when targeting a preview branch. - `env-production-vs-preview` - Use `--role production` for production env, `--role preview` for preview template env, and `--branch ` for branch-specific overrides. -- `env-db-explicit` - Keep database and env wiring explicit through database and project env commands; deploy examples should not add database setup, and deploys do not run migrations, seed data, or create one database per app automatically. +- `env-db-explicit` - Keep database and env wiring explicit: `app deploy --db` creates one branch-scoped database shared by every app on the branch and wires `DATABASE_URL`/`DIRECT_URL` (`--db --yes` in CI; `--yes` alone never creates one; `--no-db` skips). Everything else goes through database and project env commands, and deploys never run migrations, seed data, or create one database per app automatically. ### 7. Deploy Operations -- `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy. +- `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy. The first production deploy of an App auto-promotes without `--prod`; the flag gates subsequent production-branch deploys. +- `deploy-no-promote` - Use `app deploy --no-promote` for build-then-verify: it builds a candidate reachable at its own URL without touching the live deployment, promoted later with `app promote `. - `deploy-github-default-branch` - When a Compute app is connected to GitHub push-to-deploy, a merge to the default branch is the production deploy path; check deployment records or GitHub check runs instead of telling users to redeploy the merged PR branch or run a default-branch preview deploy. - `deploy-build-logs` - Use `@prisma/cli build logs ` for GitHub/Console build output. Use `app logs` for runtime deployment logs; the two ids are different. - `deploy-noninteractive-auth` - Non-interactive deploys need either the correct active stored OAuth workspace or a supported service token env var; never print the token. diff --git a/prisma-compute/references/app-deploy-cli.md b/prisma-compute/references/app-deploy-cli.md index a548c36..fe81ffc 100644 --- a/prisma-compute/references/app-deploy-cli.md +++ b/prisma-compute/references/app-deploy-cli.md @@ -156,7 +156,7 @@ bunx @prisma/cli@latest project env remove STRIPE_KEY --role preview `app deploy --env .env` loads environment variables from a file for the deployment. A config-backed deploy can instead load env through `prisma.compute.ts` `env`. Neither path is a migration command or seed command. -Database setup is not part of `prisma.compute.ts`. Keep database intent explicit with `database create` and project env commands. Do not add database setup to deploy examples. Treat any generated connection URL as a one-time secret. +Database setup is not part of `prisma.compute.ts`. Deploy-time setup goes through explicit flags: `app deploy --db` creates one branch-scoped Prisma Postgres database (shared by all apps on the branch) and wires `DATABASE_URL`/`DIRECT_URL` through project env; `--yes` alone never creates a database, so CI passes `--db --yes`; `--no-db` skips setup. `--db` and `--no-db` are mutually exclusive, and deploys still never run migrations or seed data. Outside deploy, keep database intent explicit with `database create` and project env commands. Treat any generated connection URL as a one-time secret. Database and env guardrails: @@ -179,8 +179,17 @@ bunx @prisma/cli@latest database remove db_123 --confirm db_123 bunx @prisma/cli@latest database connection list db_123 --json bunx @prisma/cli@latest database connection create db_123 --name readonly bunx @prisma/cli@latest database connection remove conn_123 --confirm conn_123 +bunx @prisma/cli@latest database connection rotate conn_123 --confirm conn_123 +bunx @prisma/cli@latest database usage db_123 --json +bunx @prisma/cli@latest database backup list db_123 --json +bunx @prisma/cli@latest database restore db_123 --backup bkp_123 --confirm db_123 +bunx @prisma/cli@latest project rename new-name --project proj_123 +bunx @prisma/cli@latest project transfer proj_123 --to-workspace wksp_456 --confirm proj_123 +bunx @prisma/cli@latest project remove proj_123 --confirm proj_123 ``` +Destructive and ownership-changing commands (`remove`, `restore`, `transfer`, `connection rotate`) require exact `--confirm `; `--yes` is not enough. + Git integration connects a Project to a GitHub repository. Console-side GitHub import can create a Compute app and trigger push-to-deploy for the connected repository, including default-branch production deploys. The CLI `git connect` command is setup, not a local deploy command; use `app deploy` for explicit CLI deploys. For GitHub-driven deploys, inspect the Console/build-runner state, deployment records, build logs, or the `Prisma Compute Deploy` GitHub check run instead of assuming local CLI output exists. The build runner can perform branch-aware database/env wiring: a preview branch with a Prisma schema and no `DATABASE_URL` can get a branch-scoped preview database, while production can wire a missing `DATABASE_URL` template from an existing ready database. GitHub check runs are the guided feedback path; do not promise Vercel-style PR comments. @@ -229,17 +238,21 @@ Deploy with prompts: bunx @prisma/cli@latest app deploy ``` -Agent/script-friendly deploy: +Agent/script-friendly deploy (do not assume production; add `--prod --yes` only when the user intends a production deploy, and note the first production deploy of an App auto-promotes without `--prod`): ```bash bunx @prisma/cli@latest app deploy \ --json \ --no-interactive \ - --prod \ - --yes \ --env .env ``` +Build-then-verify path for CI: `--no-promote` builds a candidate deployment without changing the live one; it is reachable at its own candidate URL and promoted later with `app promote `: + +```bash +bunx @prisma/cli@latest app deploy --no-promote --json --no-interactive +``` + For preview branches, omit `--prod` unless the user explicitly intends a production deploy: ```bash diff --git a/prisma-compute/references/compute-config.md b/prisma-compute/references/compute-config.md index ad0eb9f..633a603 100644 --- a/prisma-compute/references/compute-config.md +++ b/prisma-compute/references/compute-config.md @@ -21,11 +21,14 @@ prisma.compute.mts prisma.compute.js prisma.compute.mjs prisma.compute.cjs +prisma.compute.json ``` +`prisma.compute.json` is the static, dependency-free variant of the same config; it is discovered and loaded like the others. + Keep exactly one compute config file in a directory. If multiple names exist together, the CLI reports `COMPUTE_CONFIG_INVALID`. -The CLI searches from the invocation directory up to the repository or workspace boundary. Boundaries include `.git`, `pnpm-workspace.yaml`, `bun.lock`, or `package.json#workspaces`. Config-relative paths such as `root` and `env.file` resolve from the config file directory. `--env` flag paths still resolve from the invocation directory. +The CLI searches from the invocation directory up to the repository or workspace boundary. Boundaries include `.git`, `pnpm-workspace.yaml`, `bun.lock`, `bun.lockb`, or `package.json#workspaces`. Config-relative paths such as `root` and `env.file` resolve from the config file directory. `--env` flag paths still resolve from the invocation directory. When a config is discovered, its directory becomes the Compute project directory for local state: `.prisma/local.json` and `.prisma/cli/state.json` live beside that config, not necessarily inside the app root. @@ -53,7 +56,7 @@ Define exactly one of: - `app` for a single deploy target - `apps` for a monorepo or multi-app repository -Do not define both, and do not add unrelated top-level keys. +Do not define both. Besides `app`/`apps`, the only other allowed top-level key is `region`: a project-level default region applied when deploy creates new apps, overridable per app and by `--region`. ## App Fields @@ -121,7 +124,7 @@ export default defineComputeConfig({ `build.entrypoint` is relative to `build.outputDirectory` when an output directory is set. For Bun/Hono configs without an output directory, an entrypoint-backed build can supply the source entrypoint. Do not set both `entry` and `build.entrypoint` unless they describe the same file. -`build` applies to frameworks whose build settings are configurable by Compute, such as `nextjs`, `hono`, `tanstack-start`, `custom`, and `bun`. Nuxt, Astro, and NestJS use their framework strategy output and reject a config `build` block. +A config `build` block is accepted for every supported framework: the config-backed build types are `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, `custom`, and `bun` (`hono` builds through the `bun` strategy). Only `custom` requires one (`build.outputDirectory` and `build.entrypoint`); for the others it overrides inferred build settings. ## Monorepos and Multi-App Repos diff --git a/prisma-compute/references/frameworks.md b/prisma-compute/references/frameworks.md index ad767c5..10c8e79 100644 --- a/prisma-compute/references/frameworks.md +++ b/prisma-compute/references/frameworks.md @@ -25,7 +25,7 @@ Auto-detection: - Nuxt: `nuxt.config.*` or `nuxt` dependency - Astro: `astro.config.*` or `astro` dependency - Hono: `hono` dependency -- NestJS: `@nestjs/core` dependency +- NestJS: `nest-cli.json` or `@nestjs/core` dependency - TanStack Start: `@tanstack/react-start` or `@tanstack/solid-start` - Custom artifact: explicit `framework: "custom"` plus `build.outputDirectory` and `build.entrypoint` in `prisma.compute.ts` - Bun: explicit `--entry ` or `--framework bun` @@ -37,10 +37,10 @@ If detection is ambiguous, set `framework` in `prisma.compute.ts` or pass a supp | App shape | Deploy command shape | Auto-detected | Required output/entry | Notes | |-----------|----------------------|---------------|-----------------------|-------| | Next.js | `--framework nextjs` | Yes | standalone `server.js` output | Requires `output: "standalone"` | -| Nuxt | `--framework nuxt` | Yes | `.output/server/index.mjs` | CLI owns framework build output; do not add a config `build` block | -| Astro | `--framework astro` | Yes | standalone Node server artifact | CLI owns framework build output; do not add a config `build` block | +| Nuxt | `--framework nuxt` | Yes | `.output/server/index.mjs` | Framework strategy supplies build defaults; a config `build` block is optional | +| Astro | `--framework astro` | Yes | standalone Node server artifact | Framework strategy supplies build defaults; a config `build` block is optional | | Hono | `--framework hono` | Yes | Bun entry from `main`, `module`, `--entry`, or `src/index.ts` | Usually fixed port `8080` in generated config/scripts | -| NestJS | `--framework nestjs` | Yes | NestJS server artifact | Omit host or bind to `0.0.0.0`; do not add a config `build` block | +| NestJS | `--framework nestjs` | Yes | NestJS server artifact | Omit host or bind to `0.0.0.0`; a config `build` block is optional | | TanStack Start | `--framework tanstack-start` | Yes | `.output/server/index.mjs` | Requires Nitro node output | | Custom artifact | config-backed `framework: "custom"` | No | configured `build.outputDirectory` and `build.entrypoint` | Use for prebuilt/custom-built Node artifacts | | Bun / plain server | `--framework bun --entry ` | With explicit entry | server entrypoint | Use for Elysia and custom HTTP servers | @@ -52,7 +52,7 @@ If detection is ambiguous, set `framework` in `prisma.compute.ts` or pass a supp `app run --build-type` is local-dev oriented and supports `auto`, `bun`, and `nextjs`. It streams the local dev server and is not proof that the deployed app is reachable through public ingress. -`prisma.compute.ts` can set framework, entrypoint, HTTP port, env inputs, app root, region, and build settings. Config `build` blocks apply only where Compute consumes committed settings: `nextjs`, `hono`, `tanstack-start`, `custom`, and `bun`. The CLI rejects `build` blocks for `nuxt`, `astro`, and `nestjs` because their framework build paths are owned by the framework strategy. +`prisma.compute.ts` can set framework, entrypoint, HTTP port, env inputs, app root, region, and build settings. A config `build` block is accepted for every supported framework; all build types are config-backed (`nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, `custom`, `bun`; `hono` builds through the `bun` strategy). For Nuxt, Astro, and NestJS the framework strategy supplies the default build command and output, so a `build` block is optional and normally unnecessary, but it overrides those defaults when present. Only `custom` requires one. Config snippets below assume: @@ -64,7 +64,7 @@ import { defineComputeConfig } from "@prisma/compute-sdk/config"; Compute needs a server process: -- It must listen on the deployed HTTP port. `@prisma/cli app deploy` defaults to HTTP `3000` unless `--http-port` is passed. +- It must listen on the deployed HTTP port. `@prisma/cli app deploy` defaults to the framework's default HTTP port (3000 for most frameworks, 4321 for Astro) unless `--http-port` is passed. - It must bind on all interfaces. Do not hard-code `localhost` or `127.0.0.1` for a deployed server; use `0.0.0.0`, `server.host: true`, or the framework equivalent. - It must have a deployable entrypoint or recognized framework output. - It must not rely on a preview-only command such as `vite preview`. @@ -157,11 +157,11 @@ export default defineComputeConfig({ Project expectations: -- dependency detection uses `@nestjs/core`; pass `--framework nestjs` when the dependency graph is unusual +- detection uses `nest-cli.json` or the `@nestjs/core` dependency; pass `--framework nestjs` when neither signal is present - `src/main.ts` or the compiled runtime must start an HTTP server - read `process.env.PORT` and default to the same port used by `--http-port` - omit the host argument in `app.listen(port)` or pass `"0.0.0.0"`; do not pass `"localhost"` or `"127.0.0.1"` -- do not add a `build` block for NestJS in `prisma.compute.ts`; the Compute framework strategy owns the build/output path +- a `build` block is optional for NestJS; the framework strategy supplies the build/output defaults, and a committed `build` block overrides them - use `app build --build-type nestjs` for a Compute artifact check; `app run --build-type nestjs` is not supported, so use the Nest dev server locally Example runtime shape: @@ -234,7 +234,7 @@ export default defineComputeConfig({ }); ``` -Nuxt uses Nitro output at `.output/server/index.mjs`. Keep the Nitro preset compatible with a Node server runtime. Do not add a `build` block for Nuxt in `prisma.compute.ts`; the Compute framework strategy owns the build command and output. +Nuxt uses Nitro output at `.output/server/index.mjs`. Keep the Nitro preset compatible with a Node server runtime. A `build` block is optional for Nuxt: the framework strategy supplies the build command and output, and a committed `build` block overrides them. ## Astro @@ -269,7 +269,7 @@ export default defineConfig({ }) ``` -Do not add a `build` block for Astro in `prisma.compute.ts`; the Compute framework strategy owns the build command and output. +A `build` block is optional for Astro: the framework strategy supplies the build command and output, and a committed `build` block overrides them. ## Bun, Elysia, and Plain Source Servers diff --git a/prisma-compute/references/sdk-api.md b/prisma-compute/references/sdk-api.md index ebf11d8..8bc2292 100644 --- a/prisma-compute/references/sdk-api.md +++ b/prisma-compute/references/sdk-api.md @@ -66,7 +66,7 @@ if (result.isOk()) { } ``` -SDK methods return `Result`. Check `isOk()` or `isErr()` instead of assuming errors throw. Deploy results expose app/deployment vocabulary: `appId`, `appName`, `deploymentId`, `deploymentEndpointDomain`, `appEndpointDomain`, `promoted`, and `resolvedConfig`. +SDK methods return `Result`. Check `isOk()` or `isErr()` instead of assuming errors throw. Deploy results expose app/deployment vocabulary including `appId`, `appName`, `projectId`, `region`, `deploymentId`, `deploymentEndpointDomain`, `appEndpointDomain`, `promoted`, `previousDeploymentId`, `previousDeploymentAction`, and `resolvedConfig`. ## SDK Build Strategies @@ -118,7 +118,7 @@ Low-level public routes use App/Deployment names: Internal compatibility aliases may still appear in code. Prefer App/Deployment names in new docs, skills, and automation. -Environment variables are not embedded directly in the low-level deployment create payload. They resolve from the app's attached Branch. Use project/environment-variable APIs or CLI env commands to write env vars first, and keep the branch name consistent across app creation, database creation, and env writes. +Environment variables are not embedded directly in the low-level deployment create payload. The attached branch's role selects their scope: a preview branch resolves branch-scoped vars, while a production branch (or no branch) resolves project-scoped production vars. Use project/environment-variable APIs or CLI env commands to write env vars first, and keep the branch name consistent across app creation, database creation, and env writes. When using the CLI alongside SDK automation: diff --git a/prisma-postgres/SKILL.md b/prisma-postgres/SKILL.md index 86024dd..256cc4c 100644 --- a/prisma-postgres/SKILL.md +++ b/prisma-postgres/SKILL.md @@ -4,7 +4,7 @@ description: Prisma Postgres setup and operations guidance across Console, creat license: MIT metadata: author: prisma - version: "7.6.0" + version: "7.7.0" --- # Prisma Postgres @@ -67,6 +67,20 @@ For app integrations, you can also use the programmatic API (`create()` / `regio Temporary databases auto-delete after ~24 hours unless claimed. +### 2b. Persistent databases with the Platform CLI + +For databases that belong to a Project (not throwaway `create-db` databases), use `@prisma/cli`: + +```bash +npx -y @prisma/cli@latest database create main --branch main +npx -y @prisma/cli@latest database list --json +npx -y @prisma/cli@latest database connection create db_123 +npx -y @prisma/cli@latest database usage db_123 +npx -y @prisma/cli@latest database backup list db_123 +``` + +`database create` and `database connection create` print a one-time connection URL; store it immediately. Destructive commands (`remove`, `restore`) require exact `--confirm `. + ### 3. Link an existing local project Use `prisma postgres link` when the database already exists and you want to wire a local project to it: diff --git a/prisma-postgres/references/console-and-connections.md b/prisma-postgres/references/console-and-connections.md index c6e30f9..4025d12 100644 --- a/prisma-postgres/references/console-and-connections.md +++ b/prisma-postgres/references/console-and-connections.md @@ -55,6 +55,8 @@ Typical direct TCP format: DATABASE_URL="postgres://identifier:key@db.prisma.io:5432/postgres?sslmode=require" ``` +Management API connection responses expose both `endpoints.direct` (`db.prisma.io:5432`) and `endpoints.pooled` (`pooled.db.prisma.io:5432`); prefer those fields over the deprecated flat `connectionString`. Connection secrets are shown once at creation (one-time view); store them immediately. + ## Adapter choices - Standard Node.js apps: prefer `@prisma/adapter-pg` with the direct TCP URL above. diff --git a/prisma-postgres/references/management-api.md b/prisma-postgres/references/management-api.md index ff37c39..d34641b 100644 --- a/prisma-postgres/references/management-api.md +++ b/prisma-postgres/references/management-api.md @@ -42,12 +42,20 @@ Authorization: Bearer $TOKEN 3. Exchange code at `https://auth.prisma.io/token`. 4. Use returned access token in Management API requests. +## Resource model + +Workspace -> Project -> Branch -> Database. Branches are a first-class resource: databases attach to a Branch, and branch-scoped env/databases are how preview isolation works. + ## Common endpoints - `GET /workspaces` - `GET /projects` - `POST /projects` -- Database management endpoints under project/database paths +- `GET`/`POST /projects/:projectId/branches` +- `GET`/`PATCH`/`DELETE /branches/:branchId` +- Databases at both `/databases` (flat) and `/projects/:projectId/databases` +- Connection responses return structured `endpoints.direct` and `endpoints.pooled` objects; the flat top-level `connectionString` is deprecated in favor of `endpoints.direct.connectionString`/`endpoints.pooled.connectionString` +- Connection secrets are one-time view: revealed at creation, never re-readable from later GETs ## Notes From f95d5e059b3c3d7cbfccec065b1dc77c4dea615e Mon Sep 17 00:00:00 2001 From: Aman Varshney Date: Tue, 14 Jul 2026 19:01:42 +0530 Subject: [PATCH 4/4] revert: keep --db out of the skill; database setup stays explicit --- prisma-compute/SKILL.md | 2 +- prisma-compute/references/app-deploy-cli.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/prisma-compute/SKILL.md b/prisma-compute/SKILL.md index 6b9854a..84e0612 100644 --- a/prisma-compute/SKILL.md +++ b/prisma-compute/SKILL.md @@ -138,7 +138,7 @@ Use this skill for: - `env-cli-token-name` - `@prisma/cli` uses `PRISMA_SERVICE_TOKEN` for service-token auth. - `env-branch-scope` - Branch deploys, branch env vars, and branch databases must use the same branch name; pass `--branch ` explicitly when targeting a preview branch. - `env-production-vs-preview` - Use `--role production` for production env, `--role preview` for preview template env, and `--branch ` for branch-specific overrides. -- `env-db-explicit` - Keep database and env wiring explicit: `app deploy --db` creates one branch-scoped database shared by every app on the branch and wires `DATABASE_URL`/`DIRECT_URL` (`--db --yes` in CI; `--yes` alone never creates one; `--no-db` skips). Everything else goes through database and project env commands, and deploys never run migrations, seed data, or create one database per app automatically. +- `env-db-explicit` - Keep database and env wiring explicit through database and project env commands; deploy examples should not add database setup, and deploys do not run migrations, seed data, or create one database per app automatically. ### 7. Deploy Operations diff --git a/prisma-compute/references/app-deploy-cli.md b/prisma-compute/references/app-deploy-cli.md index fe81ffc..0c472e0 100644 --- a/prisma-compute/references/app-deploy-cli.md +++ b/prisma-compute/references/app-deploy-cli.md @@ -156,7 +156,7 @@ bunx @prisma/cli@latest project env remove STRIPE_KEY --role preview `app deploy --env .env` loads environment variables from a file for the deployment. A config-backed deploy can instead load env through `prisma.compute.ts` `env`. Neither path is a migration command or seed command. -Database setup is not part of `prisma.compute.ts`. Deploy-time setup goes through explicit flags: `app deploy --db` creates one branch-scoped Prisma Postgres database (shared by all apps on the branch) and wires `DATABASE_URL`/`DIRECT_URL` through project env; `--yes` alone never creates a database, so CI passes `--db --yes`; `--no-db` skips setup. `--db` and `--no-db` are mutually exclusive, and deploys still never run migrations or seed data. Outside deploy, keep database intent explicit with `database create` and project env commands. Treat any generated connection URL as a one-time secret. +Database setup is not part of `prisma.compute.ts`. Keep database intent explicit with `database create` and project env commands. Do not add database setup to deploy examples. Treat any generated connection URL as a one-time secret. Database and env guardrails: