Setting the file. One moment.
Subchapter 3.7
references/deploy-cli-and-ci.mdMarkdown7 KBView on GitHub
Deploy a Composer app with prisma deploy: production or a stage, from a workstation or from CI.
HIGH
deploy does not build, chooses the project by the app’s name rather than the directory link, and targets production unless told otherwise. Getting any of these wrong ships stale code, deploys into the wrong project, or changes production by accident.
npx prisma deploy module.ts --help
npx prisma dev module.ts --help| You want to | Run |
|---|---|
| Run the app locally, no credentials | npm run build && npx prisma dev module.ts |
| Deploy a preview | npm run build && npx prisma deploy module.ts --stage <name> |
| Deploy production | npm run build && npx prisma deploy module.ts |
| Deploy under another app name | npx prisma deploy module.ts --name <name> |
| Write the outcome as JSON | npx prisma deploy module.ts --report deploy-report.json |
<entry> is the file whose default export is the root module, usually module.ts.
deploy and dev package what the build already produced.npx prisma dev module.ts and request each local URL it prints. It runs the same pipeline against local emulators, with a real local Postgres, and needs no account. Ctrl-C leaves local data in place.npx prisma auth whoami --json. If no one is signed in, ask the user to run npx prisma auth login; it opens a browser and cannot be done by an agent.prismaCloud({ region }) in prisma.config.ts or PRISMA_REGION.--stage changes production.--stage: production. In platform terms the app is a project named after the root module, and production is its default branch.--stage <name>: a complete, isolated copy of the app as a preview branch of the same project, with its own services, databases, and configuration. Only the code is shared. The name must be a valid Git ref name; an invalid one fails the deploy.provision() from the module deletes that resource on the next deploy. A deploy never deletes the last service, the project, or a branch.The deploy finds the project in the workspace by the root module name (or --name) and creates it if none exists. It does not read or write .prisma/local.json, and it has no --project flag.
--name <unique-name> or rename the module.npx prisma project link <app-name>. Otherwise pass --project <app-name> to service, git, and project env commands.| Where | How |
|---|---|
| Workstation | npx prisma auth login once; later commands, including an agent’s, reuse the stored session |
| CI or headless | PRISMA_SERVICE_TOKEN (a workspace service token from Console settings) and PRISMA_WORKSPACE_ID |
| GitHub Actions on a connected repository | OIDC through prisma/cloud-deploy-action; no stored secret. See deploy-on-push.md |
A non-empty PRISMA_SERVICE_TOKEN takes priority over stored sessions. A set-but-empty value is an error. Never print the token; check presence with test -n "${PRISMA_SERVICE_TOKEN:-}".
Input fields bound with envParam/envSecret are stored per stage. A fresh stage starts with none, so CI must export those values; the first deploy copies missing names from the shell to the stage.
A deploy prints each step and ends with the app tree: every authored name, the platform resource it became, and public URLs.
my-app
├─ db postgres-database db_def456
└─ api compute-service cps_abc123
https://xyz.ewr.prisma.buildWith --json, the final envelope’s result.summary.nodes[].entities[] lists what was deployed, each with kind, id, and url for services. --report <path> (or PRISMA_COMPOSER_REPORT_FILE) writes the outcome as JSON, including failure.code when the deploy fails. Request each service URL after the deploy:
curl -i https://xyz.ewr.prisma.buildAny CI runs the same commands with the two credential variables as secrets:
npm ci
npm run build
npx prisma deploy module.ts --stage "pr-$PR_NUMBER" --json --report deploy-report.json--build-id <id> joins a build record your CI already created through POST /v1/builds.
The CLI has no destroy command, and branch has no delete.
destroy from @prisma/composer/control with an explicit target. It needs PRISMA_SERVICE_TOKEN and PRISMA_WORKSPACE_ID in the environment and the app already built:// destroy-stage.ts
import { destroy } from "@prisma/composer/control";
import prismaConfig from "./prisma.config.ts";
const result = await destroy({
entry: "module.ts",
config: { value: prismaConfig.composer, file: "prisma.config.ts" },
target: { kind: "stage", stage: "pr-42" },
});
if (!result.ok) throw new Error(`${result.failure.code}: ${result.failure.message}`);config is required in @prisma/composer 0.28.0: the composer section and the path of the file that declares it. Pass name when the app was deployed with --name. target is { kind: "stage", stage } or { kind: "production" } and has no default. Destroying a stage removes its resources, branch, and data; destroying production removes its resources and deletes the project once it is empty. Get the user’s confirmation first. The deploy action’s mode: destroy does not work against the current CLI.
npx prisma deploy module.tsRun without a build, this deploys whatever stale output is on disk, and without --stage it targets production.
npm run build
npx prisma dev module.ts # verify locally, then Ctrl-C
npx prisma auth whoami --json
npx prisma deploy module.ts --stage feat-search --json --report deploy-report.json
npx prisma project link my-app
npx prisma service list --branch feat-search --json