| name | db-sync |
| description | Use to set up and operate device-agnostic, collision-safe sync of a local SQLite/libSQL database across two or more machines, so the same database is shared everywhere — for running Claude Code (or any app) on more than one machine with one shared database. Built on a Turso embedded replica: one cloud primary as the single source of truth, a fast local replica on each machine. Deterministic and repeatable. Trigger on: set up database sync, sync my database across machines, share a database between two computers, db sync now, db sync status, onboard this machine to the database. |
| trigger | /db-sync |
/db-sync
Deterministic, system-agnostic sync of a local SQLite/libSQL database across two or more
machines. The point: you run Claude Code (or any application) on more than one computer and
want them to share one database that stays in step and cannot corrupt or collide — even
when both machines are used at the same time.
It uses a Turso libSQL embedded replica: one cloud primary is the single source of
truth; each machine keeps a fast local replica. Reads are local; writes go to the primary;
each machine pulls the others' changes on sync.
This skill works for ANY SQLite-class database. You tell it which database (a path) and what to
call the primary; it has no hard-coded project, owner, or machine. British English. No emojis.
Free tier only. Never commit credentials. The local replica must live outside any cloud
file-sync folder (Drive / Dropbox / iCloud), because file-sync corrupts live databases.
Usage
/db-sync setup # ONE-TIME, on the machine that holds the canonical database.
# Seeds the cloud primary from the existing database file, swaps the
# connection to an embedded replica, adds unique IDs + a flock guard +
# a sync cadence, installs `db-sync now`, the timer, and (opt-in) a button.
/db-sync onboard # On EACH OTHER machine: turn it into a replica of the same primary.
/db-sync now # Flush sync now: push local writes up, pull the other machines' down.
/db-sync status # Last-sync time, replica health, credentials present, file-sync check.
/db-sync doctor # Diagnose: creds, libsql install, replica path, file-sync-folder check, locks.
/db-sync --help # Print this Usage block and stop.
If invoked with --help/-h and nothing else: print the Usage block above verbatim and stop.
How the two copies sit together
- There is one logical database. Physically: one primary in Turso Cloud, and one local
replica file per machine.
- Machine A and Machine B never talk to each other — each syncs only with the primary.
- A write on A goes to the primary; B pulls it down on its next sync. Both machines converge to
the primary's exact state. That is how two local copies behave as one shared database.
Locked design decisions (these make it deterministic and collision-safe — do not change)
- Online-write embedded replicas only. Every write routes to the single cloud primary,
which serialises them into one total order. So two machines writing at once is safe: the
primary is the one referee, and every replica converges to the same state.
- Never enable Turso offline-writes / Sync mode. Its last-push-wins conflict resolution can
silently drop a write — that breaks determinism.
- Globally-unique IDs (ULID or UUIDv7), generated on the client, for any append table that
relies on autoincrement/rowid — so two machines can never mint the same key without coordinating.
- Per-machine flock around the sync+write critical section, so two local processes on the
same machine never open the replica mid-sync (the one documented corruption risk).
- Sync cadence: on start, after every write, and a background interval — plus an optional
timer for when the app is idle.
- Free tier. Credentials in an env file (
~/.config/db-sync/db-sync.env), never committed.
Replica file lives outside any cloud file-sync folder.
Rationale and trade-offs are in references/setup.md.
What you must do when invoked
setup (one-time, on the machine holding the canonical database)
Real work on a live database — do it carefully, verifying each step. Read references/setup.md
and execute it. In short:
- Identify the database file to share and the single place the app opens its
sqlite3 connection.
- Install the Turso CLI; sign up (free).
- Seed the cloud primary from the existing file:
turso db create <db-name> --from-file <path>.
- Capture creds into
~/.config/db-sync/db-sync.env (TURSO_DATABASE_URL, TURSO_AUTH_TOKEN,
DB_REPLICA_PATH). Never commit them.
- Swap the connection to a libSQL embedded replica using
references/connection-template.py;
add the flock guard and the in-process sync cadence.
- Audit the schema for autoincrement reliance; move to ULID/UUIDv7 IDs where needed.
bash scripts/install.sh to install the skill, the db-sync command, and (opt-in) the timer.- Prove it: (a) round-trip — write a sentinel row,
/db-sync now, confirm it is in the primary;
(b) concurrency — two simultaneous writers, confirm both land with zero loss and no key collision.
onboard (on each other machine)
- Install the same app/database client; copy
~/.config/db-sync/db-sync.env (same URL + token;
pick a local DB_REPLICA_PATH outside any cloud file-sync folder).
bash scripts/install.sh. The first /db-sync now seeds a fresh local replica from the primary.
now
Run python3 scripts/db_sync.py. Self-contained (reads creds from env or
~/.config/db-sync/db-sync.env), flock-guarded, prints a one-line status. Exit codes:
0 ok, 2 misconfig, 3 sync failed, 4 another sync already running.
status / doctor
Run python3 scripts/db_sync.py --status. Report last-sync age, replica path + size, whether
creds are present, whether the replica is (wrongly) inside a cloud file-sync folder, and the
timer state (launchctl list | grep com.dbsync.db-sync).
Safety rules
- Free tier only; never spend without asking.
- Never commit
db-sync.env / tokens. Keep the replica out of cloud file-sync folders.
- Do not enable offline-writes mode. Do not change the database's logical schema.
- If the connection layer is spread across more than one place, STOP and report before refactoring.
