dbsync-manager: a web UI and supervisor for DB Sync (open source)
Hi all,
I would like to share a tool I have built around DB Sync over the past two months: dbsync-manager, a web UI and supervisor that runs one DB Sync daemon per Mergin Maps project, watches the results against the database, and tells you when something needs attention.
https://github.com/NicklasBlidmo/dbsync-manager (MIT)
Background, honestly told: we are an archaeology company in Sweden and have only just started syncing field projects into PostGIS with DB Sync. We began with one excavation in September and have a few running now; far from all our projects, though that may come. The need showed up as soon as there was more than one daemon: config files, logs, and no way to see from a distance whether a sync had stopped or quietly fallen behind the field. The manager is what grew out of that. It adds:
a registry of projects and one daemon per project, started, restarted and stopped gracefully between cycles (a deploy no longer kills a pull halfway);
a check every few minutes of server version, checkout, database version, row counts and row content, with a health state per project and e-mail alerts that fire once when a condition starts and once when it ends;
a web UI with an add wizard, pause/resume, re-init, verify (checkout against
basethrough geodiff), event log, live log, pull history and conflict records;hooks for your own scripts (post-init views, pre-remove dumps, a nightly
pg_dumpas a scheduled job) and a small JSON API for other tools.
A note on how it was made: I wrote this with Claude (Fable): Claude Code wrote the code slice by slice from briefs, and a second Claude session reviewed each slice, wrote the field-test plans and the review notes in docs/review-notes/. I ran every field test myself on our server and decided what went in. I say this so you know what you are looking at: the design and the decisions are mine, most of the lines are not, and the tests and the field notes are where I would start if I were judging it.§
It runs the unmodified DB Sync 2.4.0 image plus two small patches kept in the repo until, or unless, they land upstream; I have opened them as #194 (graceful stop on SIGTERM) and #196 (logging a field update that a database delete drops during rebase) and leave it to the maintainers to judge. #187, one checkout per connection, was merged into 2.4.0, thank you for that.
One thing that may be useful even if you never use the tool: we ran the concurrent-edit cases of two-way sync in the field and wrote down what happens (README, “Two-way sync”). In short, a delete wins over an update, and in a same-column conflict the database always wins, because the daemon is always the last to sync. We keep our projects one-way during field work for that reason.
It is a 1.1.0 from a small installation, and the field notes in docs/review-notes/ are open about what broke along the way. If you try it, I would like to hear what does not fit your setup; a different database, hosting or workflow than ours is exactly the feedback I cannot get on my own.
Nicklas