Repository navigation
0018 on device database
Status: accepted · Implementation: done · Date: 2026-11-18
From LibreLifts ADR 0026 and its as-built notes. PGlite had no React Native package on 2026-11-17. Built 2026-11-18 and seen running on a brand-new install in both places: in Chromium, where the page is cross-origin isolated and a second tab is told the app is open elsewhere, and on the iOS simulator (iPhone 17 Pro, iOS 26.5). Android has not been run.
The app writes to a database on the device first (0014). Two other ideas were weighed in LibreLifts and turned down. Using the database each platform is born with, SQLite on phones and IndexedDB in browsers, needs a layer that hides the difference, and the one mature library that does this charges for it. Postgres everywhere, through PGlite, would let the device and the server share one schema, but PGlite does not run on iOS or Android.
-
The on-device database is SQLite, through
expo-sqlite, on iOS, Android and the web build. - Drizzle defines the tables, runs the migrations and types the queries. Migrations are generated, committed, bundled with the app and run when it starts.
- Every step of starting the database is in one function, and that function is tested on an empty database. Running the migrations is awaited.
-
The device's tables mirror the server's for the data that syncs. The two schemas are
written separately, one for SQLite and one for Postgres, and a test compares each with the
shapes in
packages/contracts. - Code that reads or writes the database is tested on Node's own SQLite, against the real migrations, so tests need no phone and no browser.
-
In the browser build:
- whatever serves the page sends
Cross-Origin-Embedder-Policy: credentiallessandCross-Origin-Opener-Policy: same-origin, in development too, because the synchronous calls Drizzle uses need a cross-origin isolated page; - the app takes a Web Lock before opening the database, and a second tab shows a message saying the app is open elsewhere.
- whatever serves the page sends
- One storage layer, one schema and one set of tests for every place the app runs.
- A change to synced data is made in three places: the device's schema, the server's and the contract.
- The app does not share the server's dialect of SQL. For rows that are only stored and synced, that costs little.
- A brand-new install is the case no developer's device is in. The start-up test is what stands in for it.
- In the browser one answer from the database is limited to about one megabyte, so long lists are read in pages, and the build carries a patch (0022).
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