[wmadden-electric]

Linked issue

n/a. Part of the local-dev work that adds prisma dev url, prisma dev stop and prisma emulator list (plan in .drive/projects/emulator-commands/).

Summary

Two checkouts of the same app now get separate local databases and buckets, and stopping prisma dev now stops its Postgres servers too:

~/work/shop   $ prisma dev module.ts   # writes a row to the catalog database
~/work/shop-2 $ prisma dev module.ts   # its catalog database is empty, and its uploads bucket has nothing from ~/work/shop
^C                                     # catalog's Postgres server stops, and its port closes
~/work/shop   $ prisma dev module.ts   # catalog is back on the same port, with the row

Decisions:

1. The local Postgres and bucket emulators no longer know what an app, a database name or a directory is, as feat(dev): checkouts of one app get their own local services, and a service keeps its port #354 did for the emulator that runs services.
2. A directory keeps local data for every app run there. Running a different app stops the previous one and keeps its data.
3. When prisma dev ends, it stops the app's Postgres servers as well as its service processes. Data stays.

ADR-0052 is extended to cover all three emulators.

Background

prisma dev runs your app against local stand-ins for Prisma Cloud, called emulators. They are long-lived processes shared by everything on the machine:

• the Compute emulator runs service processes;
• the Postgres emulator hosts one local Postgres server per database;
• the bucket emulator serves the S3 protocol over plain files.

#354 changed the Compute emulator to run instances under ids it generates, with Composer recording in each directory (.prisma-composer/dev/emulator-instances.json) which instance runs which service. The Postgres and bucket emulators were still keyed by app name, so two checkouts of one app shared a database and a bucket, and a --fresh in either wiped both.

Databases and buckets become instances

• A database gets an id (db_<hex>) and its own Postgres server named after that id. New operations: stop closes the server and keeps its data and port; start brings it back on the same port with the same rows; delete removes the server and its data. A stopped database keeps its port for the same reason a stopped service does: its connection URL is in other services' environments, and a warm start doesn't redeploy.
• A bucket gets an id (bkt-<hex>; S3 bucket names can't contain _), and that id is its name on the S3 wire. Access keys are registered per bucket. Objects stay as plain files in the project, now under .prisma-composer/dev/buckets/<app>/<bucket>/.

As with services, Composer's names reach these emulators only as labels they store but never read.

The record holds every app run from a directory

{ current: "shop",
  apps: { shop: { nodes: { quotes:  { kind: "service",  id: "svc_…", port: 3000 },
                           catalog: { kind: "database", id: "db_…",  port: 51300 },
                           uploads: { kind: "bucket",   id: "bkt-…" } } } } }

Each entry under nodes is keyed by its address, the node's dotted name in the app.

#354 deleted the previous app's services when a directory ran a different app. With databases involved, that would delete data whenever someone renamed the root module or passed a different --name. So now:

• Switching apps stops the previous app's services and databases and keeps them.
• Switching back resumes them, with their data and ports.
• --fresh deletes only the current app's instances.

A record written by #354 is read as a single app.

Starting and stopping

• Starting: before deploying, prisma dev makes sure every node of the app has its instance. It reuses recorded instances, re-creates missing ones on their remembered ports, and starts stopped databases. That last part fixes an existing gap. After the Postgres emulator restarted, for example after a reboot, a warm prisma dev never started its databases again, because the deploy engine saw nothing to change.
• Re-created databases are migrated. A re-created database comes back empty on the same URL, so the deploy engine would skip its migration. The local migration step now checks the database's migration marker on every start, at the cost of one connection per database.
• Stopping: when prisma dev ends, or a start fails partway, the app's databases are stopped along with its services.

Old state

Data from before the upgrade is discarded, as with every local-state change:

• The Postgres emulator deletes the old app-named servers. It skips any server another live process is still serving, and tries again later.
• The bucket emulator drops its old state file.

Testing performed

Against real Compute, Postgres and bucket emulators in temporary emulators directories (skipped on Windows):

• Two directories running one app each see only their own rows and their own bucket objects.
• When the app stops, its database server stops and its port closes. The next start has the data on the same port.
• Switching apps A, then B, then A brings A's data and ports back.
• A lost database is re-created on its port and migrated. --fresh removes only the current app.
• The Postgres emulator:
  • Stop and start keep data. Delete frees the port.
  • Delete still works after the Postgres library copy used at creation is removed.
  • Old-data cleanup leaves a server another process is serving alone.
• By hand, on examples/orm-demo: write a row, Ctrl-C, warm start with the row intact; delete the database through the emulator, then start, and it is re-created and migrated.

Also pnpm build, typecheck, lint, lint:deps, lint:casts, the docs checks, and the local-dev integration scripts, each run on its own.

Checklist

• All commits are signed off (git commit -s) per the DCO. The DCO status check will block merge if any commit is missing a Signed-off-by: trailer.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• The PR title is a conventional commit (feat, fix, chore, docs, refactor, test, build) — PR titles drive the auto-generated release notes.
• Tests are updated (or n/a if the change is doc-only / refactor with no behavioural delta).

Notes for the reviewer

• Stacked on feat(dev): checkouts of one app get their own local services, and a service keeps its port #354. It retargets to main when feat(dev): checkouts of one app get their own local services, and a service keeps its port #354 merges.
• Renamed: the method prisma dev calls on exit is now stopApp instead of stopServices, since it also stops databases.
• Deferred, in .drive/projects/emulator-commands/deferred.md: the dev directory's env.json and secrets.json are still shared by every app run there, and --fresh wipes them. This was already the case before this PR.

Alternatives considered

• Delete the previous app's instances when a directory switches apps, as feat(dev): checkouts of one app get their own local services, and a service keeps its port #354 did. That loses database data whenever a root module is renamed.
• Keep bucket objects at buckets/<bucket>/. Two apps in one directory would share a bucket's files.
• Only re-run migrations when the deploy engine redeploys. A re-created database is empty on an unchanged URL, so the engine never redeploys it.

Agent: attila-51

🤖 Generated with Claude Code

[prisma-gizmo]

✅ Gizmo reviewed 9ea57c1 — posted 0 inline comment(s) this pass.

Open findings: none

Change walkthrough

prisma dev now gives each project directory its own local Postgres databases and S3 buckets, keeps every app run from that directory recorded with stable ids and ports, and shuts the app's Postgres servers down when the dev session ends (Ctrl-C, SIGTERM, or failure) — data and ports survive restarts and app switches.

Emulator instances (dev-emulators). The Postgres emulator gains stop/start/delete: stopping closes a @prisma/dev server but keeps its data directory and reserved port, so a warm redeploy brings it back on the same URL. The bucket emulator switches to per-bucket ids (bkt-…, no _ for S3-name legality), per-bucket credential checks, and app-scoped object paths under .prisma-composer/dev/buckets/<app>/<bucket>/ so two apps in one directory can't share or wipe each other's files. Old state files are discarded, with legacy Postgres servers cleaned up only when no other live process is serving them.

Dev record and hook (local-target). The per-directory record now keys every node of every app (service/database/bucket kinds with instance ids and ports); a #354-shaped record is read with compute mapped to service. The emulators hook ensures each node in dependency order before Alchemy runs — reusing instances, re-creating missing ones on remembered ports, and starting stopped databases, which fixes the pre-existing gap where a restarted emulator left warm-start databases down. --fresh deletes only the current app's instances, and a partially failed hook stops what it already started. stopServices is renamed stopApp on the target-agnostic local-target interface.

Migration re-run. Because a re-created database is empty on an unchanged URL (Alchemy sees nothing to diff), the local OrmMigration provider reads the migration marker on each start and requests an update when it isn't at target, costing one connection per postgres() database per start.

Compute emulator concurrency. A start whose child process has already exited is no longer joined by a concurrent resume or identical PUT; those start the service again instead of waiting on a doomed start. The poll interval is exposed as --ready-poll-ms (tests only; the CLI never passes it), with readiness tests moved onto a file-private port range.

Docs and skills. ADR-0052 now covers all three emulators, the local-dev design doc records the new concurrency rule, and the skill documents platform logicalId addressing (branchless deploys omit it; local providers pass null) along with the 0.30.0 / alchemy beta.83 bumps.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 3005caa2-8ffe-4e95-b8ad-24d985998b64

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@356

npm i https://pkg.pr.new/@prisma/composer-cli@356

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@356

commit: b68f53a

[prisma-gizmo]

New findings: 🟡 2 minor · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No critical or major Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

New findings: none · trace

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.

[prisma-gizmo]

No Gizmo finding is open and the head commit has been reviewed. Approving.