Skip to content

Running the Postgres tests locally ​

The row-level security, audit-log, migration and store tests need a real Postgres. They skip when DATABASE_URL and APP_DATABASE_URL are unset, and CI refuses to skip them (REQUIRE_DATABASE_TESTS). This is how to run them on a Windows machine with WSL, against a throwaway database, as CI does.

Never point these variables at the NAS database (CLAUDE.md rule 6).

1. Let WSL reach Docker Desktop (once) ​

  1. Open Docker Desktop, then Settings, then Resources, then WSL integration.
  2. Turn on "Enable integration with my default WSL distro", and the switch for your distro (for example Ubuntu).
  3. Apply and restart.
  4. In WSL, docker info should now print a Server Version. If it prints a link to docs.docker.com/go/wsl2, the integration is still off.

2. Start a throwaway Postgres like CI's ​

bash
docker run -d --rm --name gmb-test-pg \
  -e POSTGRES_USER=getmy_books \
  -e POSTGRES_PASSWORD=dev_only_not_a_real_secret \
  -e POSTGRES_DB=getmy_books_dev \
  -p 55432:5432 postgres:17-alpine
until docker exec gmb-test-pg pg_isready -U getmy_books >/dev/null 2>&1; do sleep 1; done

3. Build the schema and run the tests ​

bash
export DATABASE_URL=postgres://getmy_books:dev_only_not_a_real_secret@localhost:55432/getmy_books_dev
export APP_DATABASE_URL=postgres://app:app_dev_password@localhost:55432/getmy_books_dev
corepack pnpm db:setup
REQUIRE_DATABASE_TESTS=true corepack pnpm test

db:setup builds the schema the way production does: it makes sure the app role exists, then applies every migration, policies.sql and bootstrap.sql. Run it again after pulling a new migration.

  • It only runs against a throwaway database: the host must be local or CI's postgres service, and the database must be getmy_books_dev or end in _test or _dev (never prd or prod).
  • The app role belongs to the whole Postgres server, not one database. A missing role is created with APP_DB_PASSWORD, or app_dev_password if that is unset. If the role already exists and APP_DB_PASSWORD is set, db:setup resets the role's password to it, for every database on that server. Without APP_DB_PASSWORD an existing role is left as it is.

REQUIRE_DATABASE_TESTS=true makes the run fail rather than skip if either URL is missing, as in CI.

4. Seed a dev database (optional) ​

To run the app or the MCP server against this throwaway database, rather than only the tests, give it an owner, one company and a Xero connection. Use the Demo company and Xero's UK Demo Company, never FEAW's or any other real books (issue #73, ADR 0030). With the two URLs from step 3 still set:

bash
# The owner and one company called Demo, with access between them.
OPERATOR_EMAIL=you@example.com ENTITY_NAME=Demo \
  node --import tsx scripts/db-seed-owner.ts

# Connect Demo to Xero's UK Demo Company. The consent screen opens in the
# browser: choose "Demo Company (UK)". ENTITY_NAME picks it from the
# organisations Xero offers; TENANT_ID=<id> picks one by id instead.
OPERATOR_EMAIL=you@example.com ENTITY_NAME=Demo \
  XERO_CLIENT_ID=... XERO_CLIENT_SECRET=... XERO_TOKEN_ENCRYPTION_KEY=... \
  node --import tsx scripts/xero-connect.ts
  • ENTITY_NAME must never be FEAW. Migration 0005-access-grants.sql grants FEAW's two real people access to any company named FEAW, by name, so a dev company with that name would be shared with them. Use Demo.
  • db-seed-owner.ts runs only against a throwaway database, as db:setup does, and is safe to run twice.
  • The Xero client id and secret are a development Xero app's, connected only to the UK Demo Company. XERO_TOKEN_ENCRYPTION_KEY is any 64 hex characters made for this database (openssl rand -hex 32), never the production key. Its redirect URI is http://localhost:8734/callback unless XERO_REDIRECT_URI says otherwise.
  • Xero resets the Demo Company from time to time; run xero-connect.ts again when Xero says the organisation is gone.

5. Throw it away ​

bash
docker rm -f gmb-test-pg
unset DATABASE_URL APP_DATABASE_URL

The container was started with --rm, so nothing is left behind.