Appearance
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)
- Open Docker Desktop, then Settings, then Resources, then WSL integration.
- Turn on "Enable integration with my default WSL distro", and the switch for your distro (for example Ubuntu).
- Apply and restart.
- In WSL,
docker infoshould 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; done3. 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 testdb: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
postgresservice, and the database must begetmy_books_devor end in_testor_dev(neverprdorprod). - The
approle belongs to the whole Postgres server, not one database. A missing role is created withAPP_DB_PASSWORD, orapp_dev_passwordif that is unset. If the role already exists andAPP_DB_PASSWORDis set,db:setupresets the role's password to it, for every database on that server. WithoutAPP_DB_PASSWORDan 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.tsENTITY_NAMEmust never beFEAW. Migration0005-access-grants.sqlgrants FEAW's two real people access to any company namedFEAW, by name, so a dev company with that name would be shared with them. UseDemo.db-seed-owner.tsruns only against a throwaway database, asdb:setupdoes, 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_KEYis any 64 hex characters made for this database (openssl rand -hex 32), never the production key. Its redirect URI ishttp://localhost:8734/callbackunlessXERO_REDIRECT_URIsays otherwise. - Xero resets the Demo Company from time to time; run
xero-connect.tsagain when Xero says the organisation is gone.
5. Throw it away
bash
docker rm -f gmb-test-pg
unset DATABASE_URL APP_DATABASE_URLThe container was started with --rm, so nothing is left behind.