Skip to content
Watcher Docs

Upgrading

Watcher upgrades are ordinary code deployments. The database is the thing to be careful with, and it is designed to be forgiving.

Procedure

Section titled “Procedure”

  1. Back up the database. Cheap, and the only real safety net. See Backup and restore.

  2. Pause scheduling if you can — disable the scheduled job, or stop the service. Watches will simply be due when you resume; nothing is lost.

  3. Pull and install:

    Terminal window
    git pull
    pnpm install

  4. Run the gate:

    Terminal window
    pnpm verify

    Typecheck, lint, tests and build. If this fails, do not deploy.

  5. Check for new configuration. Compare your .env against the shipped example for variables that did not exist before. Missing optional ones degrade gracefully; missing required ones stop startup with a clear message.

  6. Deploy, then resume scheduling.

  7. Force one run and read the outcome:

    Terminal window
    pnpm run-due:force

Database compatibility

Section titled “Database compatibility”

New state fields are added as optional with safe defaults, so an older document still parses under newer code. Two consequences:

  • Rolling back is usually safe — older code ignores fields it does not know.
  • Some improvements are gradual. A watch that has never fired since an upgrade may not have the newest state populated until it next fires.

One-off migrations

Section titled “One-off migrations”

Occasionally a change ships a command rather than doing it silently. They are idempotent — running one twice is safe — and the release notes say when one is needed. For example, key-store restructuring provides:

Terminal window
pnpm keys:migrate

Run any such command after deploying the new code and before resuming the scheduler.

Verifying the upgrade

Section titled “Verifying the upgrade”
Check Expect
GET /health {"status":"ok"}
GET /config/status The same integrations as before
pnpm watches:list All your watches
A forced run A sensible outcome, no new source errors
Run history New records appearing
The panel Loads, signs in, shows history

If something is wrong

Section titled “If something is wrong”
  1. Read the error. Startup failures are explicit about the missing or invalid setting.
  2. Roll back the code. State written by the newer version is normally readable by the older one.
  3. Restore the database only if state is actually corrupt — and expect the re-alerting behaviour described in Backup and restore.