Multi-machine sync

Upsight is a local, single-machine app. To use it on more than one machine, put the database file in a directory that Syncthing replicates, then point each machine's app at that shared file.

Setup overview

1. Install Syncthing on both machines and add them to a shared folder.
2. Put your Upsight database in the shared folder, or move it there.
3. Set the UPSIGHT_DB environment variable on each machine to point at the file in the shared folder.
4. Configure .stignore on both machines to exclude transient SQLite files (see below).

Pointing the app at the shared file

Set UPSIGHT_DB before launching Upsight:

export UPSIGHT_DB="$HOME/sync/upsight/upsight.db"

Put this in your shell profile or session environment so it applies on every launch. When set, the app always uses that path instead of the default.

One instance at a time

Run only one instance of Upsight against a given database file at a time. The app opens the database in WAL mode with a single writer, so running two instances against the same file at once corrupts it.

On a two-machine setup, close the app on machine A, wait for Syncthing to finish syncing (the tray icon shows progress), then open it on machine B.

Syncthing .stignore patterns

SQLite writes several transient sidecar files Syncthing should not sync. Add these patterns to the .stignore file for your Upsight sync folder:

upsight.db-wal
upsight.db-shm
upsight.db.lock
*.db.backup-v*
*.pre-restore
config.toml.tmp
config.toml.bak
upsight.session.tmp
*.sync-conflict-*

The same list is shown in Settings under Data, Sync.

upsight.db-wal and upsight.db-shm are the WAL journal files SQLite writes while the database is open. Syncing them to another machine while the app is running would corrupt the database there. upsight.db.lock stops Syncthing from replicating an open lock file. *.db.backup-v* and *.pre-restore exclude Upsight's own backup and pre-restore copies so they do not bloat the sync folder. config.toml.tmp and config.toml.bak are transient config writes. upsight.session.tmp is a temporary session file.

*.sync-conflict-* suppresses Syncthing's own conflict copies. If a conflict file appears (which should not happen if you follow the one-instance rule), do not open it in Upsight. Instead, inspect both copies and decide which one to keep, then delete the other.

Letting a sync settle

After closing the app on one machine, wait for Syncthing to finish syncing before opening it on another. Syncthing replicates the -wal and -shm sidecar files alongside the main database file. Opening the app mid-sync risks reading a half-transferred checkpoint.

A short wait, 10 to 30 seconds after the Syncthing indicator goes idle, is usually enough.