Dev and test work uses one Homebrew Postgres server (postgresql@18) on localhost:5432. Every worktree, audit owner, and project gets its own database on that server. Docker is only for production deploys (app/docker-compose.yml).
Many Postgres servers on this Mac default to port 5432: older Homebrew versions (postgresql@14, postgresql@15), the old vn-db2 and vn-dev-pg containers, and bible-daily's container. When two of them bind 5432, localhost can reach either one. To stop them from fighting:
- Run only
postgresql@18as a Homebrew service. Leave other versions stopped (brew services list). - Link 18 so plain
psql,pg_dump, andcreatedbmatch the server:brew unlink postgresql@15; brew link --force postgresql@18. Older tools cannot read dumps from newer servers. - Do not start Postgres containers for dev. Make a new database on the shared server instead.
audit:dbchecks that the server on the port is Homebrew's. If another server answers, it names it and stops.
Idle, the server uses about 30 MB. With a dev server and its connection pool attached, it uses about 200 MB. The Docker Desktop VM used 7 GB.
From any worktree's app/ directory:
corepack pnpm audit:db -- --owner <slug>This command:
- Starts
postgresql@18withbrew servicesif nothing listens on the env file's port (it installs the formula first if it is missing). - Creates the env file's role (
postgres/postgres) if it is missing. - Creates
visual_notes_audit_<slug>and applies every migration. - Prints the commands that start the app (
pnpm devthroughaudit:harness) and run Playwright against it.
Rerun it after you pull new migrations. Reset the database with --drop, then run the command again:
corepack pnpm audit:db -- --owner <slug> --drop
corepack pnpm audit:db -- --owner <slug>Database-backed vitest files (*.db.test.ts) run when TEST_DATABASE_URL names an audit database:
TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/visual_notes_audit_<slug> corepack pnpm testServer commands, if you need them:
brew services start postgresql@18
brew services stop postgresql@18
psql -h localhost -U postgres -lThe main checkout's app/.env names a database visual-notes. It holds a copy of the old vn-db2 container's visual_notes database (22 synthetic notes, no users; real notes live in production). To start it again empty:
cd app
dropdb -h localhost -U postgres --force visual-notes
createdb -h localhost -U postgres visual-notes
pnpm prisma migrate deployTo copy a database out of an old container, start Docker Desktop, then:
docker start vn-db2
docker exec vn-db2 pg_dump -U postgres -Fc visual_notes > tmp/vn-db2.dump
docker stop vn-db2
createdb -h localhost -U postgres visual-notes
pg_restore -h localhost -U postgres -d visual-notes --no-owner tmp/vn-db2.dumpThe Postgres containers now have --restart=no, so they do not take port 5432 when Docker starts. Their volumes are intact. bible-daily's container also holds the bible database and 26 old visual_notes_audit_* databases from earlier agents.
- PGlite runs Postgres in WebAssembly in the Node process. Prisma reaches it only through a driver adapter, so the app's Prisma client and the
prisma migrateCLI would both need changes. The app would also run on a different engine in dev than in production. - embedded-postgres (npm) downloads Postgres binaries and runs one server for each process. Many worktrees would mean many servers, more memory, and more ports.
- Postgres.app works, but it is a GUI app that
audit:dbcannot install or start from a script. Homebrew was already installed. - Docker costs 7 GB or more for its VM, which is the problem this change removes.
No extension blocks a plain install. The schema needs only pg_trgm, which ships with Homebrew Postgres. Embeddings are Float[] columns, not pgvector.