Railbase
GPTClaude

Updating

Update plugins and Railbase itself in one click, and how version compatibility is enforced.

Updated

Video guide —watch on YouTube ↗

Railbase updates two things independently: the plugins you've installed and the core binary itself. Both are driven from the Marketplace in your admin: when something newer is available, an "Updates available" banner appears there with one-click actions. Both respect a version-compatibility gate.

Updating a plugin

When a newer version of an installed plugin is published, the Marketplace flags it (a badge on the plugin, plus the banner up top). A plugin is data-resident (an encrypted JS+schema row in your Vault), so updating isn't "stop one process, start another" — it re-lands the new signed bundle and remounts the runtime:

  1. fetches the new build and verifies it's authentic and unmodified (the same check as a fresh install — see How plugins work),
  2. replaces the encrypted _plugins row and reloads the runtime — reusing your existing license, so there's no second checkout.

The update re-runs the same install gates, so it can be refused: if the new version's min_core is newer than your core it's blocked until you update the core (below), and on a licensed (pinned) build the plugin's license must still be valid and the Core EULA accepted, or the update is denied.

Updating Railbase

Railbase can update itself in place — from the Settings → System update screen (/_/settings/system-update), which shows your running vs the latest version and a progress checklist, or from the Marketplace banner's Update Railbase button. This isn't a blind "download and restart"; a small in-binary supervisor runs a safety pipeline:

  1. download + verify the new build (authenticity check),
  2. take an automatic vault backup,
  3. run a migration dry-run against the new binary,
  4. stage it beside the current binary and swap it in,
  5. health-gate the new worker — and automatically roll back to the previous binary if it fails to come up.

So a bad upgrade self-recovers. You can also update the manual way described in Installation: download the latest build and restart. Either way, your data is forward-compatible and schema migrations apply on the next boot.

Tip

The self-update already snapshots for you, but a manual snapshot is cheap insurance. Note ./railbase backup needs the server stopped (it takes the vault lock) — or snapshot from the admin console, which runs in-process. See Backups & restore.

Note

The API-compatibility default is strict. Railbase serves the PocketBase-compatible shapes at /api/* (the v1 ship target). The native surface lives under a separate /v1 prefix, and is only mounted when compat.mode is native (/v1 only) or both (/api and /v1) — it is not served under /api/*. If you need the native shapes, opt in explicitly: railbase config set compat.mode '"both"' (or RAILBASE_COMPAT_MODE=both). An instance that already saved a compat.mode setting keeps it across updates. See REST API → URL compatibility.

Compatibility

Every plugin declares a minimum core version (min_core). The core enforces it:

  • A plugin whose min_core is newer than your core won't install or run — the Marketplace tells you to update the core first.
  • The Marketplace also flags when a core update is available (comparing your running version to the catalogue), so the banner tells you when it's worthwhile.

This is why you occasionally update the core before a plugin: the plugin needs a capability the older core doesn't have.

  1. Snapshot — ./railbase backup.
  2. Update Railbase if a plugin needs it (or to pick up fixes), then let it restart.
  3. Update plugins — they pick up the newer core's capabilities.

Because licenses are reused across updates, none of this re-charges you — updates are purely fetch, verify, and install.

Was this page helpful?Thanks for your feedback!
← PreviousManaging billingNext →The documentation assistant