Repository navigation
0021 postgres 18
Status: accepted · Implementation: done · Date: 2026-11-18
From LibreLifts ADR 0032 and its as-built notes. Where Postgres is hosted in production gets its own record. Built 2026-11-18. The development Postgres listens on 5433 and the API on 3002, one above the usual, because LibreLifts has 5432 and 3001 on the same machine. The tests pass on both databases locally; CI runs the second in a job named api-postgres. No test counts queries on the server yet; that comes with sync.
One Postgres database is the source of truth (0014). That leaves which version, how the API talks to it, how a developer gets one, and how the tests get one. One person works on LibreBars, and a test suite that needs a database started by hand is a test suite that is not run.
- The database is Postgres 18.
-
The API talks to it through
pg, with Drizzle on top. Only the file that starts the server knows about the connection pool; the rest of the API is handed a Drizzle database. - Migrations are generated by Drizzle Kit, committed, and run by a command of their own. The API does not migrate when it starts.
-
One Postgres schema per concern:
auth,personal, later the catalog. Each has one file of table definitions. - In development, Postgres runs from a Docker Compose file in the repository, with a fixed project name.
-
The API is tested through
buildApp()andinject(), on an in-process Postgres (PGlite, through Drizzle's own PGlite driver) by default, and on a real Postgres when a variable names one. - CI runs the API's tests on both.
- Where the number of queries matters, a test counts them and fails above a limit.
-
pnpm api testworks on a fresh clone. Running the API needs Docker. - Two test databases can disagree. When they do, the real Postgres is right, and the test that showed the difference is kept.
- The in-process database has one connection. Code that waits for a second connection while holding the first would hang there, which is also a bug worth finding.
- A deploy has two steps: migrate, then start.
Generated from docs/ on dev. Edit the docs there; changes made on the wiki are overwritten.
- Development
- Workflow
-
Decisions
- 0001 Decisions are recorded
- 0002 Apache License 2.0
- 0003 Changes land on dev by fast-forward; main is the last release
- 0004 Conventional Commits, Keep a Changelog and Semantic Versioning
- 0005 docs/ is for developers and is mirrored to the wiki
- 0006 LibreBars is a free workout log for calisthenics
- 0007 The tracker is an iOS and Android app; its web build stays until the store release
- 0008 LibreBars is an app and a crowd-sourced open database
- 0009 The database is ODbL, media is CC BY-SA, and neither can be closed later
- 0010 A hosted API with a free tier is the paid product
- 0011 The workspace is app, web and api, with engine, ui, data and contracts
- 0012 The engine is small pure functions, in the style of date-fns
- 0013 Web and app share a Tailwind theme, not components
- 0014 Postgres is the source of truth for all data
- 0015 The API is Fastify, and it owns LibreBars accounts
- 0016 Every install is a guest account, made in the background
- 0017 Accounts use Better Auth
- 0018 The on-device database is SQLite with Drizzle, on every platform
- 0019 Sync is our own push and pull
- 0020 The app says it backs up, and backup can be turned off
- 0021 Postgres 18, run with Docker Compose and tested on two databases
- 0022 expo-sqlite is patched so the web build reuses one buffer
- 0023 Seed data is TypeScript modules in packages/data, with permanent ids
- 0024 The first tables
- 0025 One TanStack Start app is the website, on GitHub Pages
- 0026 The catalog reaches the app as a snapshot plus updates, and the website through the API
- 0027 The app's first components are its own