@cedarjs/pg 0.2.0-beta.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Worktree-isolated local Postgres for Vite+, Nx, and CedarJS. The host is [autopg](https://github.com/automagik-dev/autopg) (embedded PostgreSQL 18). cedar-pg creates one database and role per git worktree so parallel checkouts do not share a DB.
 
-Published as `@cedarjs/pg`. CLI: `cedarpg`. Beta (`0.2.0-beta.0`, `beta` dist-tag). Public APIs may still change.
+Published as `@cedarjs/pg`. CLI: `cedarpg`. Pre-1.0 (`0.x`, `latest` dist-tag). Public APIs may still change between minor versions.
 
 | Layer    | Owns                                                                              |
 | -------- | --------------------------------------------------------------------------------- |
@@ -14,13 +14,15 @@ Published as `@cedarjs/pg`. CLI: `cedarpg`. Beta (`0.2.0-beta.0`, `beta` dist-ta
 Node `>=24`.
 
 ```bash
-npm install -D @cedarjs/pg@beta
-# pnpm add -D @cedarjs/pg@beta
-# yarn add -D @cedarjs/pg@beta
+npm install -D @cedarjs/pg
+# pnpm add -D @cedarjs/pg
+# yarn add -D @cedarjs/pg
 ```
 
 `postinstall` installs the pinned autopg binary when it is missing. The pin is `scripts/autopg-version`. To bump autopg, change that file.
 
+An autopg that is already installed is never upgraded for you, because upgrading restarts the host every worktree shares. When it is older than the pin, `postinstall` and the first host attach of each process (`acquire`, `cedarpg run`, test setup) print a warning with the upgrade commands. It never fails. `cedarpg run --attach` and skipped acquires (external URL, `CEDAR_PG=0`) do not check. To upgrade, run the install command below, then `autopg update` (autopg's own migrations; on its own it does not download a new binary). `scripts/ci-install-autopg.sh` and the GitHub Action replace any binary that is not exactly the pinned version, since CI hosts are ephemeral.
+
 To install the host by hand (local, non-CI; upstream `install.sh` may use pm2):
 
 ```bash
@@ -45,6 +47,12 @@ vp pack
 # or install the tarball vp pack writes (name includes the version in package.json)
 ```
 
+Every push to `main` and every PR also builds a preview on [pkg.pr.new](https://pkg.pr.new) (not the npm registry):
+
+```bash
+pnpm add -D https://pkg.pr.new/@cedarjs/pg@<commit-sha-or-pr-number>
+```
+
 ## Acquire a database
 
 `dev` databases persist across restarts. `test` databases drop on `dispose`.
@@ -62,8 +70,9 @@ Worktree state lives in `.cedarpg`. Import `STATE_DIRNAME` instead of hardcoding
 ```bash
 cedarpg acquire --mode=dev
 cedarpg acquire --mode=test --print-env
-cedarpg run --mode=dev -- yarn tsx scripts/apiServer/dev.ts
+cedarpg run --mode=dev -- prisma migrate deploy
 cedarpg run --mode=test -- vitest run
+cedarpg run --attach --mode=dev -- node dist/server.js   # existing lease only, no DDL
 cedarpg dispose --mode=test
 cedarpg print-url --mode=dev
 cedarpg status --mode=dev
@@ -73,9 +82,11 @@ cedarpg gc                         # drop DBs whose worktree root is gone
 
 `status` and `studio` are read-only. They do not acquire. `studio` walks from cwd up to the worktree.
 
-`cedarpg run` acquires or attaches the lease, then execs the command. The child always gets `DATABASE_URL` from the lease. In test mode it also gets `TEST_DATABASE_URL`. `--force` only sets `CEDAR_PG_FORCE=1`, so nested adapters do not treat an ambient URL as an escape hatch.
+`cedarpg run` acquires (idempotent role and database DDL), then execs the command. The child always gets `DATABASE_URL` from the lease. In test mode it also gets `TEST_DATABASE_URL`. `--force` only sets `CEDAR_PG_FORCE=1`, so nested adapters do not treat an ambient URL as an escape hatch.
+
+`cedarpg run --attach` skips the acquire. It reads the lease a prior `acquire` / `run` wrote, sets the same child env, and execs. It never runs DDL and never starts or revives the host. It fails (nonzero, before the child starts) when there is no lease or nothing is listening on the leased port.
 
-If two targets run `cedarpg acquire` or `cedarpg run` on the same worktree, role and database DDL can race. Use one acquire, then `run` wrappers.
+If two targets run `cedarpg acquire` or plain `cedarpg run` on the same worktree, role and database DDL can race. Acquire once, then wrap children with `run --attach`. Any number of those can run concurrently.
 
 ## Vite+
 
@@ -95,15 +106,17 @@ export default defineConfig({
         env: ["DATABASE_URL", "TEST_DATABASE_URL"],
       },
       dev: {
-        command: "vp dev",
+        command: "cedarpg run --attach --mode=dev -- vp dev",
         dependsOn: ["db:acquire"],
-        env: ["DATABASE_URL"],
+        cache: false,
       },
     },
   },
 });
 ```
 
+Like Nx `dependsOn`, Vite+ `dependsOn` does not forward env, and task `env` only fingerprints and passes through variables already set in the `vp` process. So `dev` acquires once via `db:acquire`, then `cedarpg run --attach` hands the lease `DATABASE_URL` to `vp dev`. `test` needs no wrapper: the stock Vitest setup acquires and sets the URL itself.
+
 `cedarPgDev()` does not acquire. Keep `dependsOn: ["db:acquire"]`. On listen it prints a status panel (TTY, non-CI). Vite CLI shortcuts (`key` then Enter; also listed under `h`):
 
 | Key | Action                                                                 |
@@ -117,58 +130,84 @@ Shortcuts bind on Vite 8 and vite-plus. Vite 7 and Cedar print the listen panel
 
 ## Nx
 
-Nx `dependsOn` does not forward env from an acquire task into dependents. Vite+ `env: [...]` does. Canonical shape:
-
-1. One `db:ready` (or `createAcquireTask`) that acquires and migrates.
-2. Wrap API, dev, and e2e children with `cedarpg run --mode=dev --force -- <cmd>`.
-
-Pointing Nx `envFile` at `.cedarpg/<mode>.env` after acquire still loses to an ambient `.env` unless you also force or overwrite.
-
-```ts
-import { cedarPgNxTargets, cedarPgRunCommand, relativeEnvFile } from "@cedarjs/pg/nx";
-
-cedarPgNxTargets();
-// { "db:acquire": { command: "cedarpg acquire --mode=dev", cache: false }, ... }
+Nx `dependsOn` does not forward env from one target to the next, so the setup has two parts:
 
-cedarPgRunCommand("dev", "yarn tsx scripts/apiServer/dev.ts");
-// "cedarpg run --mode=dev -- yarn tsx scripts/apiServer/dev.ts"
+1. **One `db:ready` target** acquires the worktree database and migrates it. It is the only target that runs role/database DDL.
+2. **Children** (`dev`, `serve`, workers, e2e) depend on `db:ready` and pick up the lease URL in one of two ways. They never acquire again: two acquires on the same worktree race DDL.
 
-relativeEnvFile("dev"); // ".cedarpg/dev.env"
-```
-
-```json
+```jsonc
+// project.json (workspace root)
 {
   "targets": {
-    "db:ready": { "command": "tsx tools/db-ready.ts", "cache": false },
-    "dev": {
-      "dependsOn": ["db:ready"],
-      "command": "cedarpg run --mode=dev --force -- yarn tsx scripts/apiServer/dev.ts"
+    "db:ready": {
+      "command": "cedarpg run --mode=dev -- prisma migrate deploy",
+      "cache": false,
     },
-    "serve": {
-      "dependsOn": ["db:ready"],
-      "command": "cedarpg run --mode=dev --force -- node dist/server.js"
-    }
-  }
+    "db:status": { "command": "cedarpg status --mode=dev", "cache": false },
+    "db:url": { "command": "cedarpg print-url --mode=dev", "cache": false },
+    "db:studio": { "command": "cedarpg studio --mode=dev", "cache": false },
+  },
 }
 ```
 
-Migrate hook (same compose shape as Jest `createGlobalSetup`):
+Swap in your migrate command (`drizzle-kit migrate`, …). Add `--force` (`cedarpg run --mode=dev --force -- …`) when a shell or `.env` `DATABASE_URL` would otherwise trip the [external-URL escape hatch](#environment-variables). For a migrate step written in TypeScript, call `createAcquireTask` from a script instead:
 
 ```ts
-// tools/db-ready.ts
+// tools/db-ready.ts → "command": "tsx tools/db-ready.ts"
 import { createAcquireTask } from "@cedarjs/pg";
 
 await createAcquireTask({
   mode: "dev",
-  // Need this when .env already has DATABASE_URL
   force: true,
   afterAcquire: async ({ databaseUrl }) => {
-    // prisma migrate deploy, drizzle push, ...
+    // run your migrations against databaseUrl
   },
 })();
 ```
 
-If you cannot wrap with `run`, use `loadDevEnv({ overwrite: true })` or `import "@cedarjs/pg/dev-env"`. Absolute path helper: `envFilePath(root, mode)`.
+`db:status`, `db:url`, and `db:studio` are optional local helpers. They read the lease and never acquire. `studio` opens Prisma Studio or Drizzle Kit Studio, whichever it finds.
+
+### Children: preload or attach
+
+Pick one per target. Both give the child the `DATABASE_URL` that `db:ready` leased, overriding a `DATABASE_URL` from `.env`.
+
+```jsonc
+{
+  "targets": {
+    // Preload: Node loads .cedarpg/dev.env with overwrite before your code runs.
+    "serve": {
+      "dependsOn": ["db:ready"],
+      "command": "node --require @cedarjs/pg/dev-env dist/server.js",
+    },
+    "dev": {
+      "dependsOn": ["db:ready"],
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsx watch src/server.ts",
+        "env": { "NODE_OPTIONS": "--require @cedarjs/pg/dev-env" },
+      },
+    },
+    // Attach: cedarpg sets the env, then execs any command (Node or not).
+    "worker": {
+      "dependsOn": ["db:ready"],
+      "command": "cedarpg run --attach --mode=dev -- node dist/worker.js",
+    },
+  },
+}
+```
+
+- **Preload** (`@cedarjs/pg/dev-env`, or `loadDevEnv({ overwrite: true })` at the top of your entry) costs nothing extra but only works for Node processes. With no lease it is a no-op, and the process keeps its ambient URL.
+- **Attach** (`cedarpg run --attach --mode=dev -- <cmd>`) works for any command. It reads the lease and checks the port, and fails before the child starts when either is missing. It never runs DDL and never starts the host, so any number of attached children can start at once.
+
+Avoid Nx `envFile: ".cedarpg/dev.env"`. An ambient `.env` `DATABASE_URL` wins over it.
+
+### Tests
+
+Tests do not go through `db:ready`. The Jest TEMPLATE adapter acquires its own `test` lease, migrates once, clones per worker, and drops everything in teardown. Point Jest at it (see [TEMPLATE clones → Jest](#jest)) and make the Nx `test` target a plain runner command:
+
+```jsonc
+{ "targets": { "test": { "command": "jest --config jest.config.cjs" } } }
+```
 
 ## Vitest and Jest
 
@@ -228,6 +267,14 @@ Migrate stays app-owned via `createGlobalSetup({ migrate })`. The adapter then m
 
 Point `globalSetup` at a local module that calls `createGlobalSetup`. String-resolving the package entry without a migrate hook throws.
 
+Each setup starts clean. Before migrate, `createGlobalSetup` drops every database owned by this worktree's test role: a TEMPLATE and worker clones left behind by a crashed or killed run, even if its lease file is gone. `migrate` therefore always runs against an empty database, and you do not need your own pre-cleanup. Only this worktree's `cpg_*_test_*` role is touched, never other databases on the shared host. Core API: `acquire({ mode: "test", fresh: true })`.
+
+`cloneWorkerDatabase()` gives each worker one clone, `<template>_c_<JEST_WORKER_ID | VITEST_POOL_ID | pid>`, shared by every test file that worker runs. The first file creates it. Later files find it in Postgres and reuse it. Nothing is cached in memory, so this holds under Jest's per-file `globalThis` and module registry. If the clone name exists but belongs to a different role, the call fails with a clear error rather than reusing it.
+
+Each file then starts from empty tables. By default `cloneWorkerDatabase()` runs one `TRUNCATE ... RESTART IDENTITY` over every user table in the clone, so rows from earlier files in the worker are gone and `serial` / identity IDs restart at 1. Tests that expect a first row with `id = 1` behave the same whichever file a worker runs first. It truncates on every call, the first file included, so rows that `migrate` seeded into the TEMPLATE (including bookkeeping tables such as `_prisma_migrations`) are cleared too. It skips system schemas, temp tables, and tables an extension owns (for example PostGIS `spatial_ref_sys`). If skip policy uses an external URL or `CEDAR_PG=0` is set, nothing is cloned and nothing is truncated.
+
+To keep the clone as the previous file left it and reset on your own, pass `cloneWorkerDatabase({ reset: "none" })`. Resets between tests inside one file stay app-owned.
+
 ### Jest
 
 ```js
@@ -247,7 +294,8 @@ process.env.CEDAR_PG_FORCE = "1";
 module.exports = {
   globalSetup: "<rootDir>/jest.cedar-global.cjs",
   globalTeardown: require.resolve("@cedarjs/pg/jest-teardown"),
-  // Prefer setupFilesAfterEnv so you can use beforeAll (Jest globals).
+  // Runs once per test file; every file in a worker reuses that worker's clone,
+  // truncated with RESTART IDENTITY first.
   setupFilesAfterEnv: ["<rootDir>/jest.cedar-worker.cjs"],
 };
 
@@ -256,8 +304,6 @@ const { cloneWorkerDatabase } = require("@cedarjs/pg/jest/template");
 beforeAll(() => cloneWorkerDatabase());
 ```
 
-`cloneWorkerDatabase` memos on `globalThis`, so Jest `setupFiles` (module reload per file) still shares one clone per worker.
-
 ### Vitest
 
 ```ts
@@ -304,7 +350,9 @@ await dispose({ root: acquired.root, mode: "test" }); // TEMPLATE + all clones +
 
 `acquire` returns `adminUrl` for migrate hooks and privileged DDL. `markTemplate` and `cloneFromTemplate` accept it, or rediscover the host when it is omitted. `cloneFromTemplate` uses the admin connection (`CREATE DATABASE ... TEMPLATE`). Test roles stay `LOGIN`-only.
 
-`setEnv` defaults to false on `cloneFromTemplate`. It defaults to true on `cloneFromTemplateIfNeeded` (same as `acquireIfNeeded`). Worker adapters call `cloneFromTemplateIfNeeded` via `cloneWorkerDatabase`.
+`setEnv` defaults to false on `cloneFromTemplate`. It defaults to true on `cloneFromTemplateIfNeeded` (same as `acquireIfNeeded`). Worker adapters call `cloneFromTemplateIfNeeded` via `cloneWorkerDatabase`, with `reuse: true`.
+
+An explicit `name` that already exists fails with `database already exists` unless you pass `reuse: true`. Then a clone owned by the lease role is kept as is.
 
 `dispose` is role-scoped suite teardown, not `dropClone`. It unsets `IS_TEMPLATE` and drops every database owned by the lease role.
 
@@ -312,7 +360,7 @@ await dispose({ root: acquired.root, mode: "test" }); // TEMPLATE + all clones +
 
 `acquire` attaches when TCP accepts on the port from `autopg status --json`. Registration is not liveness. An installed-but-stopped host still reports a port.
 
-When nothing is listening, cedar-pg brings up the registered local host. It runs `autopg restart`, then `autopg install` if the host was never registered. It attaches once TCP accepts. Same port, same `~/.autopg/data`. It does not start a second local Postgres. If neither verb produces a listener, `acquire` fails with what it tried.
+When nothing is listening, cedar-pg brings up the registered local host. It runs `autopg restart`, then (if still dark) detached `autopg postmaster` on the registered port and `~/.autopg/data`. `autopg restart` (autopg ≥ v3.2) drives pm2 only and exits 0 once ready; without pm2, or under systemd-user / launchd, it exits 1 and cedar-pg moves on. Either way TCP accept is the gate. It does not run `autopg install` on an already-registered host (that path wants pm2). `install` is only for a never-registered machine. Same port, same data dir — not a second Postgres. The data dir and socket dir come from `autopg status --json`. They are never guessed: if autopg reports no `dataDir`, revive is skipped. If a live `postmaster.pid` already owns the data dir (pm2 still recovering, or a concurrent acquire), cedar-pg waits for that postmaster instead of starting a competitor. The revived postmaster has no supervisor and lives until reboot or crash. Its output is appended to `cedarpg-postmaster.log` in autopg's `logsDir` (`~/.autopg/logs`). If revive still produces no listener, `acquire` fails with what it tried.
 
 Callers use `acquire` (and `adminUrl`). There is no public host-options object. Ephemeral behavior is env-driven.
 
@@ -323,12 +371,12 @@ import { acquire } from "@cedarjs/pg";
 const { databaseUrl } = await acquire({ mode: "test" });
 ```
 
-| Signal                      | Effect (attach always wins when something is listening)                       |
-| --------------------------- | ----------------------------------------------------------------------------- |
-| `CEDAR_PG_EPHEMERAL_HOST=1` | Ephemeral owned postmaster on 55432                                           |
-| `CEDAR_PG_EPHEMERAL_HOST=0` | Never own a postmaster (even when `CI=true`). Local autopg host only, or fail |
-| unset and `CI=true`         | Ephemeral                                                                     |
-| unset                       | Local: `autopg restart`, then `autopg install`, then fail                     |
+| Signal                      | Effect (attach always wins when something is listening)                                      |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `CEDAR_PG_EPHEMERAL_HOST=1` | Ephemeral owned postmaster on 55432                                                          |
+| `CEDAR_PG_EPHEMERAL_HOST=0` | Never start the ephemeral 55432 postmaster (even in CI). Local registered host only, or fail |
+| unset and `CI=true`         | Ephemeral                                                                                    |
+| unset                       | Local: `autopg restart`, then registered `postmaster` if still dark, then fail               |
 
 Ephemeral recipe (not configurable via cedar-pg):
 
@@ -337,7 +385,7 @@ Ephemeral recipe (not configurable via cedar-pg):
 - Linux when `/dev/shm` exists: also `--ram` and `DIR=/dev/shm/cedar-pg-<uid>`
 - Otherwise: disk `DIR` under the OS temp dir
 - Ready when TCP accepts on the recipe port
-- Before cold-start, if the recipe port is not live, cedar-pg prunes leftover `/dev/shm/cedar-pg-*`, `pgserve-*`, and `PostgreSQL.*` (OOM-killed runs filling tmpfs). Safe on isolated CI VMs. On shared self-hosted runners another job's leftovers could match those globs.
+- Before cold-start, if the recipe port is not live, cedar-pg removes its own leftover data dir (`/dev/shm/cedar-pg-<uid>`, or `$TMPDIR/cedar-pg-host` without `--ram`) from an OOM-killed run. It never touches other `/dev/shm` entries: `PostgreSQL.*` segments belong to every running Postgres, the registered host included.
 
 If TCP already accepts on the discovered autopg port, or in ephemeral mode on 55432, cedar-pg attaches and does not start another. The CI job owns ephemeral postmaster lifetime (runner teardown, `/dev/shm`). There is no cedar-pg host dispose API.
 
@@ -378,7 +426,7 @@ Yarn Berry or ignore-scripts, when you cannot use the Action. Requires a real `n
 | `AUTOPG_PG_USER`, `AUTOPG_PG_PASSWORD` | Autopg superuser for admin URL (default user `postgres`, password `postgres`)                                                                                                                        |
 | `CEDAR_PG=0`                           | Disable auto-acquire in adapters                                                                                                                                                                     |
 | `TEST_DATABASE_URL`                    | Default escape hatch for `acquireIfNeeded`. Skip acquire for a real external DB (not `cpg_*`, `file:`, or `{...}` or `<...>` placeholders). Callers may pass `url` (`DATABASE_URL` is common in dev) |
-| `CEDAR_PG_FORCE=1`                     | Ignore the external-URL escape hatch (adapters, `cedarpg acquire --force`, `cedarpg run --force`)                                                                                                    |
+| `CEDAR_PG_FORCE=1`                     | Ignore the external-URL escape hatch (adapters, `cedarpg run --force`)                                                                                                                               |
 | `CEDAR_PG_EPHEMERAL_HOST`              | `1` owned postmaster. `0` never own one (even in CI). Unset and `CI=true` means ephemeral                                                                                                            |
 | `CEDAR_PG_REGISTRY_DIR`                | Override the global lease registry (for `gc`)                                                                                                                                                        |
 | `CEDAR_PG_SKIP_POSTINSTALL=1`          | Skip the autopg install hook                                                                                                                                                                         |
@@ -414,12 +462,13 @@ vp run smoke:pg    # pack, then Vitest and Jest adapters against real ephemeral
 
 ## Troubleshooting
 
-| Symptom                                                                                 | Fix                                                                                                                                                                                                                                                                                                |
-| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ECONNREFUSED 127.0.0.1:25432` on `cedarpg acquire`                                     | autopg is registered but not listening. cedar-pg runs `autopg restart` (then `install`) and attaches once TCP accepts. `restart` exiting 0 is not proof. When pm2 is missing it still prints "respawned daemon". If both verbs fail, install pm2 or fix the supervisor (`pm2 logs autopg-server`). |
-| `database already exists: ..._c_<workerId>` in Jest                                     | Use current `@cedarjs/pg` (`cloneWorkerDatabase` memos on `globalThis`). Prefer `setupFilesAfterEnv` + `beforeAll`. Avoid passing bare `JEST_WORKER_ID` as an explicit `name`.                                                                                                                     |
-| Acquire skipped. Tests hit shared or stale Postgres                                     | A real `.env` `TEST_DATABASE_URL` (or a `url` the caller passed) trips the escape hatch. Set `CEDAR_PG_FORCE=1` once in `jest.config.js`, or `force: true`, or `cedarpg run --force`.                                                                                                              |
-| `Disk quota exceeded` / `No space left on device` / Postgres `53100` on ephemeral start | Enlarge `/dev/shm` (`sudo mount -o remount,size=6G /dev/shm`). On isolated runners only: `rm -rf /dev/shm/cedar-pg-* /dev/shm/pgserve-* /dev/shm/PostgreSQL.*`. Cold-start also prunes these when the recipe port is dead.                                                                         |
-| `autopg: command not found` in CI with Yarn `YARN_ENABLE_SCRIPTS=false`                 | `CEDAR_PG_INSTALL_AUTOPG=1` is not enough when lifecycle scripts are off. With `nodeLinker: node-modules`, run `bash node_modules/@cedarjs/pg/scripts/ci-install-autopg.sh` and put `~/.local/bin` on `PATH` (or use `setup-autopg`). PnP: resolve the script path via Yarn, or prefer the Action. |
-| Nx child still uses `.env` `DATABASE_URL`                                               | `dependsOn` does not forward acquire env. Wrap with `cedarpg run --mode=dev --force -- <cmd>`, or `loadDevEnv({ overwrite: true })`.                                                                                                                                                               |
-| Role or DB errors under parallel Nx targets                                             | Do not run concurrent `acquire` or `run` on the same worktree. One `db:ready`, then `run` wrappers.                                                                                                                                                                                                |
+| Symptom                                                                                 | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ECONNREFUSED 127.0.0.1:25432` on `cedarpg acquire`                                     | autopg is registered but not listening. cedar-pg attaches only after TCP accepts. It runs `autopg restart`, then detached `autopg postmaster` on the registered port/data if still dark — including when pm2 is missing and `restart` exits 1. A revived postmaster logs to `~/.autopg/logs/cedarpg-postmaster.log`. `status=stopped` with `runtime.live=true` is healthy once TCP accepts; cedar-pg will not `install` pm2. If revive fails, the error lists what was tried. |
+| `database already exists: ..._c_<workerId>` in Jest                                     | Upgrade `@cedarjs/pg`. Older releases cached the clone on `globalThis`, which Jest resets for every test file. `cloneWorkerDatabase` now reuses the worker's clone from Postgres (`reuse: true`), and template setup drops crashed-run leftovers first. If the error says `owned by <other role>`, a database outside this worktree's lease has that name: drop it or pass another `name`.                                                                                    |
+| Acquire skipped. Tests hit shared or stale Postgres                                     | A real `.env` `TEST_DATABASE_URL` (or a `url` the caller passed) trips the escape hatch. Set `CEDAR_PG_FORCE=1` once in `jest.config.js`, or `force: true`, or `cedarpg run --force`.                                                                                                                                                                                                                                                                                         |
+| `Disk quota exceeded` / `No space left on device` / Postgres `53100` on ephemeral start | Enlarge `/dev/shm` (`sudo mount -o remount,size=6G /dev/shm`). Cold-start already removes cedar-pg's own leftover `/dev/shm/cedar-pg-<uid>` when the recipe port is dead. Do not `rm /dev/shm/PostgreSQL.*`: a live Postgres (your registered host included) then fails every new connection with `58P01 could not open shared memory segment`, and only a restart of that host recovers it.                                                                                  |
+| `autopg: command not found` in CI with Yarn `YARN_ENABLE_SCRIPTS=false`                 | `CEDAR_PG_INSTALL_AUTOPG=1` is not enough when lifecycle scripts are off. With `nodeLinker: node-modules`, run `bash node_modules/@cedarjs/pg/scripts/ci-install-autopg.sh` and put `~/.local/bin` on `PATH` (or use `setup-autopg`). PnP: resolve the script path via Yarn, or prefer the Action.                                                                                                                                                                            |
+| Nx child still uses `.env` `DATABASE_URL`                                               | `dependsOn` does not forward acquire env. Preload `@cedarjs/pg/dev-env` (`node --require` / `NODE_OPTIONS`), or wrap with `cedarpg run --attach --mode=dev -- <cmd>`. Not Nx `envFile`.                                                                                                                                                                                                                                                                                       |
+| Role or DB errors under parallel Nx targets                                             | Children are running plain `cedarpg run` (or `acquire`), so each one runs DDL. Keep the acquire in one `db:ready`, and switch the children to `cedarpg run --attach`.                                                                                                                                                                                                                                                                                                         |
+| `no dev lease ...; attach never acquires` from `cedarpg run --attach`                   | Nothing has acquired this worktree yet. Make the target `dependsOn` your `db:ready` (or run `cedarpg acquire --mode=dev`). On `nothing is listening`, re-run `db:ready` / `acquire` to bring the host back; attach never starts it.                                                                                                                                                                                                                                           |

package/dist/cli.cjs

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-const require_lifecycle = require("./lifecycle-BbrvFQvg.cjs");
+const require_lifecycle = require("./lifecycle-BCeM96tI.cjs");
 const require_lease = require("./lease-WlmOnNDi.cjs");
-const require_status = require("./status-4Uz6A3LB.cjs");
-const require_studio = require("./studio-oJE30_PO.cjs");
+const require_status = require("./status-Z_BYdxzI.cjs");
+const require_studio = require("./studio-CdWIdnxr.cjs");
 //#region src/cli.ts
 function printHelp() {
 	process.stdout.write(`${require_lease.CLI_NAME}: worktree-isolated local Postgres (via autopg)
 
 Usage:
-  ${require_lease.CLI_NAME} acquire --mode=dev|test [--root <path>] [--force] [--json] [--print-env]
-  ${require_lease.CLI_NAME} run --mode=dev|test [--root <path>] [--force] -- <cmd…>
+  ${require_lease.CLI_NAME} acquire --mode=dev|test [--root <path>] [--json] [--print-env]
+  ${require_lease.CLI_NAME} run --mode=dev|test [--root <path>] [--force] [--attach] -- <cmd…>
   ${require_lease.CLI_NAME} dispose [--mode=dev|test] [--root <path>]
   ${require_lease.CLI_NAME} gc [--json]
   ${require_lease.CLI_NAME} print-url [--mode=dev|test] [--root <path>]
@@ -24,6 +24,9 @@ Modes:
 run:
   Acquire, set DATABASE_URL (+ TEST_DATABASE_URL in test) on the child, exec <cmd…>.
   --force sets CEDAR_PG_FORCE (escape hatch); child env overwrite is always on.
+  --attach reads the existing lease instead: no acquire, no role/DB DDL, fails
+  when there is no lease or the host is not listening. Use it for children that
+  run after one db:ready (safe to run concurrently).
 
 status / studio:
   Read-only lease inspection (no acquire). studio runs Prisma or Drizzle Kit Studio
@@ -56,6 +59,7 @@ function parseArgs(argv) {
 		else if (a === "--json") out.json = true;
 		else if (a === "--print-env") out.printEnv = true;
 		else if (a === "--force") out.force = true;
+		else if (a === "--attach") out.attach = true;
 		else if (a === "--prisma") out.prisma = true;
 		else if (a === "--drizzle") out.drizzle = true;
 		else if (a.startsWith("--mode=")) out.mode = parseMode(a.slice(7));
@@ -141,7 +145,6 @@ async function main() {
 	}
 	try {
 		if (args.cmd === "acquire") {
-			if (args.force) process.env.CEDAR_PG_FORCE = "1";
 			const mode = args.mode ?? "dev";
 			const result = await require_lifecycle.acquire({
 				root: args.root,
@@ -173,16 +176,19 @@ async function main() {
 		if (args.cmd === "run") {
 			if (args.force) process.env.CEDAR_PG_FORCE = "1";
 			const mode = args.mode ?? "dev";
-			const result = await require_lifecycle.acquire({
+			const { databaseUrl } = args.attach ? await require_lifecycle.attach({
+				root: args.root,
+				mode
+			}) : await require_lifecycle.acquire({
 				root: args.root,
 				mode,
 				setEnv: true
 			});
 			const childEnv = {
 				...process.env,
-				DATABASE_URL: result.databaseUrl
+				DATABASE_URL: databaseUrl
 			};
-			if (mode === "test") childEnv.TEST_DATABASE_URL = result.databaseUrl;
+			if (mode === "test") childEnv.TEST_DATABASE_URL = databaseUrl;
 			return await runChild(args.child ?? [], childEnv);
 		}
 		if (args.cmd === "dispose") {

package/dist/cli.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.cjs","names":["CLI_NAME","runAttached","resolveDevStatus","formatDevStatus","detectStudio","runStudio","acquire","dispose","gc"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { CLI_NAME } from \"./core/constants.ts\";\nimport { acquire, dispose, gc } from \"./core/lifecycle.ts\";\nimport { resolveDevStatus } from \"./core/status.ts\";\nimport type { DbMode } from \"./core/naming.ts\";\nimport { runAttached } from \"./adapters/child.ts\";\nimport { formatDevStatus } from \"./adapters/status-format.ts\";\nimport { detectStudio, runStudio, type StudioKind } from \"./adapters/studio.ts\";\n\nfunction printHelp(): void {\n  process.stdout.write(`${CLI_NAME}: worktree-isolated local Postgres (via autopg)\n\nUsage:\n  ${CLI_NAME} acquire --mode=dev|test [--root <path>] [--force] [--json] [--print-env]\n  ${CLI_NAME} run --mode=dev|test [--root <path>] [--force] -- <cmd…>\n  ${CLI_NAME} dispose [--mode=dev|test] [--root <path>]\n  ${CLI_NAME} gc [--json]\n  ${CLI_NAME} print-url [--mode=dev|test] [--root <path>]\n  ${CLI_NAME} status [--mode=dev|test] [--root <path>] [--json]\n  ${CLI_NAME} studio [--mode=dev|test] [--root <path>] [--prisma|--drizzle]\n  ${CLI_NAME} --help\n\nModes:\n  dev   Keep DB across restarts (default when --mode omitted)\n  test  Drop DB on dispose / test teardown\n\nrun:\n  Acquire, set DATABASE_URL (+ TEST_DATABASE_URL in test) on the child, exec <cmd…>.\n  --force sets CEDAR_PG_FORCE (escape hatch); child env overwrite is always on.\n\nstatus / studio:\n  Read-only lease inspection (no acquire). studio runs Prisma or Drizzle Kit Studio\n  attached (stdio + exit code) with DATABASE_URL from the lease. Detects from cwd\n  up to the worktree (auto; --prisma / --drizzle to force).\n\nEnv:\n  AUTOPG_BIN       Path to autopg binary\n  CEDAR_PG=0       Disable adapters that auto-acquire\n  CEDAR_PG_FORCE=1 Ignore external-URL escape hatch (same as --force)\n`);\n}\n\nfunction parseMode(value: string | undefined): DbMode {\n  if (value === \"dev\" || value === \"test\") return value;\n  throw new Error(\"--mode must be dev or test\");\n}\n\ntype ParsedArgs = {\n  cmd?: string;\n  mode?: DbMode;\n  root?: string;\n  json?: boolean;\n  printEnv?: boolean;\n  force?: boolean;\n  help?: boolean;\n  prisma?: boolean;\n  drizzle?: boolean;\n  child?: string[];\n};\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const out: ParsedArgs = {};\n  const rest = [...argv];\n  out.cmd = rest.shift();\n\n  const dash = rest.indexOf(\"--\");\n  let flagArgs = rest;\n  if (dash >= 0) {\n    flagArgs = rest.slice(0, dash);\n    out.child = rest.slice(dash + 1);\n  }\n\n  for (let i = 0; i < flagArgs.length; i++) {\n    const a = flagArgs[i]!;\n    if (a === \"--help\" || a === \"-h\") out.help = true;\n    else if (a === \"--json\") out.json = true;\n    else if (a === \"--print-env\") out.printEnv = true;\n    else if (a === \"--force\") out.force = true;\n    else if (a === \"--prisma\") out.prisma = true;\n    else if (a === \"--drizzle\") out.drizzle = true;\n    else if (a.startsWith(\"--mode=\")) out.mode = parseMode(a.slice(7));\n    else if (a === \"--mode\") out.mode = parseMode(flagArgs[++i]);\n    else if (a.startsWith(\"--root=\")) out.root = a.slice(7);\n    else if (a === \"--root\") out.root = flagArgs[++i];\n    else throw new Error(`unknown argument: ${a}`);\n  }\n  return out;\n}\n\nfunction studioPrefer(args: ParsedArgs): StudioKind | undefined {\n  if (args.prisma && args.drizzle) {\n    throw new Error(\"pass only one of --prisma or --drizzle\");\n  }\n  if (args.prisma) return \"prisma\";\n  if (args.drizzle) return \"drizzle\";\n  return undefined;\n}\n\nfunction writeLines(stream: NodeJS.WriteStream, lines: string[]): void {\n  for (const line of lines) stream.write(`${line}\\n`);\n}\n\nfunction runChild(command: string[], env: NodeJS.ProcessEnv): Promise<number> {\n  const [file, ...args] = command;\n  if (!file) {\n    throw new Error(\n      `run requires a command after -- (e.g. ${CLI_NAME} run --mode=dev -- yarn dev)`,\n    );\n  }\n  return runAttached(file, args, { env });\n}\n\nfunction cmdPrintUrl(args: ParsedArgs): number {\n  const status = resolveDevStatus({ root: args.root, mode: args.mode });\n  if (!status.ok) {\n    writeLines(process.stderr, formatDevStatus(status));\n    return 2;\n  }\n  process.stdout.write(`${status.databaseUrl}\\n`);\n  return 0;\n}\n\nfunction cmdStatus(args: ParsedArgs): number {\n  const status = resolveDevStatus({ root: args.root, mode: args.mode });\n  if (args.json) {\n    process.stdout.write(`${JSON.stringify(status, null, 2)}\\n`);\n    return status.ok ? 0 : 2;\n  }\n  writeLines(process.stdout, formatDevStatus(status));\n  return status.ok ? 0 : 2;\n}\n\nasync function cmdStudio(args: ParsedArgs): Promise<number> {\n  const prefer = studioPrefer(args);\n  const status = resolveDevStatus({ root: args.root, mode: args.mode });\n  if (!status.ok) {\n    writeLines(process.stderr, formatDevStatus(status));\n    return 2;\n  }\n  const studio = detectStudio({ root: status.root, cwd: process.cwd(), prefer });\n  if (!studio) {\n    process.stderr.write(\n      `${CLI_NAME}: no Prisma or Drizzle Studio found (install prisma or drizzle-kit)\\n`,\n    );\n    return 1;\n  }\n  process.stdout.write(\n    `${CLI_NAME}: opening ${studio.kind} studio (${studio.command} ${studio.args.join(\" \")})\\n`,\n  );\n  return runStudio({ databaseUrl: status.databaseUrl, studio });\n}\n\nasync function main(): Promise<number> {\n  const argv = process.argv.slice(2);\n  if (argv.length === 0 || argv[0] === \"help\" || argv[0] === \"--help\" || argv[0] === \"-h\") {\n    printHelp();\n    return 0;\n  }\n  const args = parseArgs(argv);\n  if (args.help) {\n    printHelp();\n    return 0;\n  }\n\n  try {\n    if (args.cmd === \"acquire\") {\n      if (args.force) process.env.CEDAR_PG_FORCE = \"1\";\n      const mode = args.mode ?? \"dev\";\n      const result = await acquire({\n        root: args.root,\n        mode,\n        setEnv: true,\n      });\n      if (args.printEnv) {\n        process.stdout.write(`DATABASE_URL=${result.databaseUrl}\\n`);\n        if (mode === \"test\") {\n          process.stdout.write(`TEST_DATABASE_URL=${result.databaseUrl}\\n`);\n        }\n      }\n      if (args.json) {\n        process.stdout.write(\n          `${JSON.stringify(\n            {\n              databaseUrl: result.databaseUrl,\n              adminUrl: result.adminUrl,\n              databaseName: result.databaseName,\n              roleName: result.roleName,\n              repoSlug: result.repoSlug,\n              worktreeSlug: result.worktreeSlug,\n              pathHash: result.pathHash,\n              mode: result.mode,\n              port: result.port,\n              root: result.root,\n            },\n            null,\n            2,\n          )}\\n`,\n        );\n      } else if (!args.printEnv) {\n        process.stdout.write(\n          `${CLI_NAME}: ${result.databaseName} (${result.repoSlug}/${result.worktreeSlug} ${result.mode})\\n`,\n        );\n        process.stdout.write(`${result.databaseUrl}\\n`);\n      }\n      return 0;\n    }\n\n    if (args.cmd === \"run\") {\n      if (args.force) process.env.CEDAR_PG_FORCE = \"1\";\n      const mode = args.mode ?? \"dev\";\n      const result = await acquire({\n        root: args.root,\n        mode,\n        setEnv: true,\n      });\n      const childEnv: NodeJS.ProcessEnv = {\n        ...process.env,\n        DATABASE_URL: result.databaseUrl,\n      };\n      if (mode === \"test\") childEnv.TEST_DATABASE_URL = result.databaseUrl;\n      return await runChild(args.child ?? [], childEnv);\n    }\n\n    if (args.cmd === \"dispose\") {\n      const mode = args.mode ?? \"test\";\n      const result = await dispose({ root: args.root, mode });\n      if (result.dropped) {\n        process.stdout.write(`${CLI_NAME}: disposed ${mode} (${result.databaseName})\\n`);\n        return 0;\n      }\n      if (result.reason === \"no-lease\") {\n        process.stdout.write(`${CLI_NAME}: nothing to dispose for ${mode} (no lease)\\n`);\n        return 0;\n      }\n      process.stderr.write(\n        `${CLI_NAME}: could not dispose ${mode}: autopg host unavailable (lease kept for retry)\\n`,\n      );\n      return 1;\n    }\n\n    if (args.cmd === \"gc\") {\n      const result = await gc();\n      if (args.json) {\n        process.stdout.write(`${JSON.stringify(result)}\\n`);\n      } else {\n        process.stdout.write(`${CLI_NAME} gc: dropped ${result.dropped.length} database(s)\\n`);\n        for (const name of result.dropped) process.stdout.write(`  ${name}\\n`);\n      }\n      return 0;\n    }\n\n    if (args.cmd === \"print-url\") {\n      return cmdPrintUrl(args);\n    }\n\n    if (args.cmd === \"status\") {\n      return cmdStatus(args);\n    }\n\n    if (args.cmd === \"studio\") {\n      return await cmdStudio(args);\n    }\n\n    process.stderr.write(`${CLI_NAME}: unknown command ${args.cmd}\\n`);\n    printHelp();\n    return 64;\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err);\n    process.stderr.write(`${CLI_NAME}: ${message}\\n`);\n    return 1;\n  }\n}\n\nmain()\n  .then((code) => {\n    process.exit(code);\n  })\n  .catch((err: unknown) => {\n    const message = err instanceof Error ? err.message : String(err);\n    process.stderr.write(`${CLI_NAME}: ${message}\\n`);\n    process.exit(1);\n  });\n"],"mappings":"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"}
+{"version":3,"file":"cli.cjs","names":["CLI_NAME","runAttached","resolveDevStatus","formatDevStatus","detectStudio","runStudio","acquire","attach","dispose","gc"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { CLI_NAME } from \"./core/constants.ts\";\nimport { acquire, attach, dispose, gc } from \"./core/lifecycle.ts\";\nimport { resolveDevStatus } from \"./core/status.ts\";\nimport type { DbMode } from \"./core/naming.ts\";\nimport { runAttached } from \"./adapters/child.ts\";\nimport { formatDevStatus } from \"./adapters/status-format.ts\";\nimport { detectStudio, runStudio, type StudioKind } from \"./adapters/studio.ts\";\n\nfunction printHelp(): void {\n  process.stdout.write(`${CLI_NAME}: worktree-isolated local Postgres (via autopg)\n\nUsage:\n  ${CLI_NAME} acquire --mode=dev|test [--root <path>] [--json] [--print-env]\n  ${CLI_NAME} run --mode=dev|test [--root <path>] [--force] [--attach] -- <cmd…>\n  ${CLI_NAME} dispose [--mode=dev|test] [--root <path>]\n  ${CLI_NAME} gc [--json]\n  ${CLI_NAME} print-url [--mode=dev|test] [--root <path>]\n  ${CLI_NAME} status [--mode=dev|test] [--root <path>] [--json]\n  ${CLI_NAME} studio [--mode=dev|test] [--root <path>] [--prisma|--drizzle]\n  ${CLI_NAME} --help\n\nModes:\n  dev   Keep DB across restarts (default when --mode omitted)\n  test  Drop DB on dispose / test teardown\n\nrun:\n  Acquire, set DATABASE_URL (+ TEST_DATABASE_URL in test) on the child, exec <cmd…>.\n  --force sets CEDAR_PG_FORCE (escape hatch); child env overwrite is always on.\n  --attach reads the existing lease instead: no acquire, no role/DB DDL, fails\n  when there is no lease or the host is not listening. Use it for children that\n  run after one db:ready (safe to run concurrently).\n\nstatus / studio:\n  Read-only lease inspection (no acquire). studio runs Prisma or Drizzle Kit Studio\n  attached (stdio + exit code) with DATABASE_URL from the lease. Detects from cwd\n  up to the worktree (auto; --prisma / --drizzle to force).\n\nEnv:\n  AUTOPG_BIN       Path to autopg binary\n  CEDAR_PG=0       Disable adapters that auto-acquire\n  CEDAR_PG_FORCE=1 Ignore external-URL escape hatch (same as --force)\n`);\n}\n\nfunction parseMode(value: string | undefined): DbMode {\n  if (value === \"dev\" || value === \"test\") return value;\n  throw new Error(\"--mode must be dev or test\");\n}\n\ntype ParsedArgs = {\n  cmd?: string;\n  mode?: DbMode;\n  root?: string;\n  json?: boolean;\n  printEnv?: boolean;\n  force?: boolean;\n  attach?: boolean;\n  help?: boolean;\n  prisma?: boolean;\n  drizzle?: boolean;\n  child?: string[];\n};\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const out: ParsedArgs = {};\n  const rest = [...argv];\n  out.cmd = rest.shift();\n\n  const dash = rest.indexOf(\"--\");\n  let flagArgs = rest;\n  if (dash >= 0) {\n    flagArgs = rest.slice(0, dash);\n    out.child = rest.slice(dash + 1);\n  }\n\n  for (let i = 0; i < flagArgs.length; i++) {\n    const a = flagArgs[i]!;\n    if (a === \"--help\" || a === \"-h\") out.help = true;\n    else if (a === \"--json\") out.json = true;\n    else if (a === \"--print-env\") out.printEnv = true;\n    else if (a === \"--force\") out.force = true;\n    else if (a === \"--attach\") out.attach = true;\n    else if (a === \"--prisma\") out.prisma = true;\n    else if (a === \"--drizzle\") out.drizzle = true;\n    else if (a.startsWith(\"--mode=\")) out.mode = parseMode(a.slice(7));\n    else if (a === \"--mode\") out.mode = parseMode(flagArgs[++i]);\n    else if (a.startsWith(\"--root=\")) out.root = a.slice(7);\n    else if (a === \"--root\") out.root = flagArgs[++i];\n    else throw new Error(`unknown argument: ${a}`);\n  }\n  return out;\n}\n\nfunction studioPrefer(args: ParsedArgs): StudioKind | undefined {\n  if (args.prisma && args.drizzle) {\n    throw new Error(\"pass only one of --prisma or --drizzle\");\n  }\n  if (args.prisma) return \"prisma\";\n  if (args.drizzle) return \"drizzle\";\n  return undefined;\n}\n\nfunction writeLines(stream: NodeJS.WriteStream, lines: string[]): void {\n  for (const line of lines) stream.write(`${line}\\n`);\n}\n\nfunction runChild(command: string[], env: NodeJS.ProcessEnv): Promise<number> {\n  const [file, ...args] = command;\n  if (!file) {\n    throw new Error(\n      `run requires a command after -- (e.g. ${CLI_NAME} run --mode=dev -- yarn dev)`,\n    );\n  }\n  return runAttached(file, args, { env });\n}\n\nfunction cmdPrintUrl(args: ParsedArgs): number {\n  const status = resolveDevStatus({ root: args.root, mode: args.mode });\n  if (!status.ok) {\n    writeLines(process.stderr, formatDevStatus(status));\n    return 2;\n  }\n  process.stdout.write(`${status.databaseUrl}\\n`);\n  return 0;\n}\n\nfunction cmdStatus(args: ParsedArgs): number {\n  const status = resolveDevStatus({ root: args.root, mode: args.mode });\n  if (args.json) {\n    process.stdout.write(`${JSON.stringify(status, null, 2)}\\n`);\n    return status.ok ? 0 : 2;\n  }\n  writeLines(process.stdout, formatDevStatus(status));\n  return status.ok ? 0 : 2;\n}\n\nasync function cmdStudio(args: ParsedArgs): Promise<number> {\n  const prefer = studioPrefer(args);\n  const status = resolveDevStatus({ root: args.root, mode: args.mode });\n  if (!status.ok) {\n    writeLines(process.stderr, formatDevStatus(status));\n    return 2;\n  }\n  const studio = detectStudio({ root: status.root, cwd: process.cwd(), prefer });\n  if (!studio) {\n    process.stderr.write(\n      `${CLI_NAME}: no Prisma or Drizzle Studio found (install prisma or drizzle-kit)\\n`,\n    );\n    return 1;\n  }\n  process.stdout.write(\n    `${CLI_NAME}: opening ${studio.kind} studio (${studio.command} ${studio.args.join(\" \")})\\n`,\n  );\n  return runStudio({ databaseUrl: status.databaseUrl, studio });\n}\n\nasync function main(): Promise<number> {\n  const argv = process.argv.slice(2);\n  if (argv.length === 0 || argv[0] === \"help\" || argv[0] === \"--help\" || argv[0] === \"-h\") {\n    printHelp();\n    return 0;\n  }\n  const args = parseArgs(argv);\n  if (args.help) {\n    printHelp();\n    return 0;\n  }\n\n  try {\n    if (args.cmd === \"acquire\") {\n      const mode = args.mode ?? \"dev\";\n      const result = await acquire({\n        root: args.root,\n        mode,\n        setEnv: true,\n      });\n      if (args.printEnv) {\n        process.stdout.write(`DATABASE_URL=${result.databaseUrl}\\n`);\n        if (mode === \"test\") {\n          process.stdout.write(`TEST_DATABASE_URL=${result.databaseUrl}\\n`);\n        }\n      }\n      if (args.json) {\n        process.stdout.write(\n          `${JSON.stringify(\n            {\n              databaseUrl: result.databaseUrl,\n              adminUrl: result.adminUrl,\n              databaseName: result.databaseName,\n              roleName: result.roleName,\n              repoSlug: result.repoSlug,\n              worktreeSlug: result.worktreeSlug,\n              pathHash: result.pathHash,\n              mode: result.mode,\n              port: result.port,\n              root: result.root,\n            },\n            null,\n            2,\n          )}\\n`,\n        );\n      } else if (!args.printEnv) {\n        process.stdout.write(\n          `${CLI_NAME}: ${result.databaseName} (${result.repoSlug}/${result.worktreeSlug} ${result.mode})\\n`,\n        );\n        process.stdout.write(`${result.databaseUrl}\\n`);\n      }\n      return 0;\n    }\n\n    if (args.cmd === \"run\") {\n      if (args.force) process.env.CEDAR_PG_FORCE = \"1\";\n      const mode = args.mode ?? \"dev\";\n      const { databaseUrl } = args.attach\n        ? await attach({ root: args.root, mode })\n        : await acquire({ root: args.root, mode, setEnv: true });\n      const childEnv: NodeJS.ProcessEnv = {\n        ...process.env,\n        DATABASE_URL: databaseUrl,\n      };\n      if (mode === \"test\") childEnv.TEST_DATABASE_URL = databaseUrl;\n      return await runChild(args.child ?? [], childEnv);\n    }\n\n    if (args.cmd === \"dispose\") {\n      const mode = args.mode ?? \"test\";\n      const result = await dispose({ root: args.root, mode });\n      if (result.dropped) {\n        process.stdout.write(`${CLI_NAME}: disposed ${mode} (${result.databaseName})\\n`);\n        return 0;\n      }\n      if (result.reason === \"no-lease\") {\n        process.stdout.write(`${CLI_NAME}: nothing to dispose for ${mode} (no lease)\\n`);\n        return 0;\n      }\n      process.stderr.write(\n        `${CLI_NAME}: could not dispose ${mode}: autopg host unavailable (lease kept for retry)\\n`,\n      );\n      return 1;\n    }\n\n    if (args.cmd === \"gc\") {\n      const result = await gc();\n      if (args.json) {\n        process.stdout.write(`${JSON.stringify(result)}\\n`);\n      } else {\n        process.stdout.write(`${CLI_NAME} gc: dropped ${result.dropped.length} database(s)\\n`);\n        for (const name of result.dropped) process.stdout.write(`  ${name}\\n`);\n      }\n      return 0;\n    }\n\n    if (args.cmd === \"print-url\") {\n      return cmdPrintUrl(args);\n    }\n\n    if (args.cmd === \"status\") {\n      return cmdStatus(args);\n    }\n\n    if (args.cmd === \"studio\") {\n      return await cmdStudio(args);\n    }\n\n    process.stderr.write(`${CLI_NAME}: unknown command ${args.cmd}\\n`);\n    printHelp();\n    return 64;\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err);\n    process.stderr.write(`${CLI_NAME}: ${message}\\n`);\n    return 1;\n  }\n}\n\nmain()\n  .then((code) => {\n    process.exit(code);\n  })\n  .catch((err: unknown) => {\n    const message = err instanceof Error ? err.message : String(err);\n    process.stderr.write(`${CLI_NAME}: ${message}\\n`);\n    process.exit(1);\n  });\n"],"mappings":"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"}

package/dist/cli.mjs

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
-import { i as gc, r as dispose, t as acquire } from "./lifecycle-BvIx0xqq.mjs";
 import { p as CLI_NAME } from "./lease-DS1SX8U_.mjs";
-import { t as resolveDevStatus } from "./status-Dcnpgnlz.mjs";
-import { a as formatDevStatus, o as runAttached, r as runStudio, t as detectStudio } from "./studio-DIFw1qWC.mjs";
+import { a as gc, i as dispose, r as attach, t as acquire } from "./lifecycle-2BZgSVz2.mjs";
+import { t as resolveDevStatus } from "./status-B68SGSKx.mjs";
+import { a as formatDevStatus, r as runStudio, t as detectStudio, u as runAttached } from "./studio-Bi6SU9jE.mjs";
 //#region src/cli.ts
 function printHelp() {
 	process.stdout.write(`${CLI_NAME}: worktree-isolated local Postgres (via autopg)
 
 Usage:
-  ${CLI_NAME} acquire --mode=dev|test [--root <path>] [--force] [--json] [--print-env]
-  ${CLI_NAME} run --mode=dev|test [--root <path>] [--force] -- <cmd…>
+  ${CLI_NAME} acquire --mode=dev|test [--root <path>] [--json] [--print-env]
+  ${CLI_NAME} run --mode=dev|test [--root <path>] [--force] [--attach] -- <cmd…>
   ${CLI_NAME} dispose [--mode=dev|test] [--root <path>]
   ${CLI_NAME} gc [--json]
   ${CLI_NAME} print-url [--mode=dev|test] [--root <path>]
@@ -24,6 +24,9 @@ Modes:
 run:
   Acquire, set DATABASE_URL (+ TEST_DATABASE_URL in test) on the child, exec <cmd…>.
   --force sets CEDAR_PG_FORCE (escape hatch); child env overwrite is always on.
+  --attach reads the existing lease instead: no acquire, no role/DB DDL, fails
+  when there is no lease or the host is not listening. Use it for children that
+  run after one db:ready (safe to run concurrently).
 
 status / studio:
   Read-only lease inspection (no acquire). studio runs Prisma or Drizzle Kit Studio
@@ -56,6 +59,7 @@ function parseArgs(argv) {
 		else if (a === "--json") out.json = true;
 		else if (a === "--print-env") out.printEnv = true;
 		else if (a === "--force") out.force = true;
+		else if (a === "--attach") out.attach = true;
 		else if (a === "--prisma") out.prisma = true;
 		else if (a === "--drizzle") out.drizzle = true;
 		else if (a.startsWith("--mode=")) out.mode = parseMode(a.slice(7));
@@ -141,7 +145,6 @@ async function main() {
 	}
 	try {
 		if (args.cmd === "acquire") {
-			if (args.force) process.env.CEDAR_PG_FORCE = "1";
 			const mode = args.mode ?? "dev";
 			const result = await acquire({
 				root: args.root,
@@ -173,16 +176,19 @@ async function main() {
 		if (args.cmd === "run") {
 			if (args.force) process.env.CEDAR_PG_FORCE = "1";
 			const mode = args.mode ?? "dev";
-			const result = await acquire({
+			const { databaseUrl } = args.attach ? await attach({
+				root: args.root,
+				mode
+			}) : await acquire({
 				root: args.root,
 				mode,
 				setEnv: true
 			});
 			const childEnv = {
 				...process.env,
-				DATABASE_URL: result.databaseUrl
+				DATABASE_URL: databaseUrl
 			};
-			if (mode === "test") childEnv.TEST_DATABASE_URL = result.databaseUrl;
+			if (mode === "test") childEnv.TEST_DATABASE_URL = databaseUrl;
 			return await runChild(args.child ?? [], childEnv);
 		}
 		if (args.cmd === "dispose") {