Migrations and Upgrades

This guide covers upgrading an existing Hot project and database between Hot releases.

Updating Hot

Update to the latest published Hot release:

hot update

If your installed hot supports pinned updates, install a specific Hot version:

hot update --version 2.3.0

For older hot binaries that do not support hot update --version, use the hosted installer script instead.

macOS / Linux:

curl -fsSL https://get.hot.dev/install.sh | sh -s -- --version 2.3.0

Windows PowerShell:

$env:HOT_VERSION = "2.3.0"; irm https://get.hot.dev/install.ps1 | iex

Pinned installs are useful when you need to finish database migrations with an older release line before moving to a newer major version.

Upgrading to Hot 2.6

Hot 2.6 completes the move to one error idiom and removes the legacy flow-result-modifier syntax:

• ::hot::lang/try and ::hot::lang/try-call are removed. Expected failures are Result.Err values — branch with is-err / if-err; use OnErr.Preserve for fan-out isolation and a task boundary (::hot::task/start + await) to supervise untrusted work. See Error Handling.
• The |map, |vec, and |one flow result modifiers are removed — annotate the binding or return type instead. All<Map> / All<Vec> collect all results (x: All<Map> cond { ... }); any other type on a collect-all flow takes the single final value (x: Int parallel { ... }). See Flows.

Upgrading to Hot 2.3

Hot 2.3 includes a breaking cleanup to the public Failure and Cancellation payload fields. Replace direct field access as follows:

• failure.$msg → failure.msg
• failure.$err → failure.err
• cancellation.$msg → cancellation.msg
• cancellation.$data → cancellation.data

Upgrading to Hot 2.2

No code changes were required for 2.2 itself. The idioms it introduced are now the standard forms — and, as of Hot 2.6, the only forms: the legacy syntax that 2.2 still tolerated (|map/|vec/|one modifiers, try-call) is removed, see Upgrading to Hot 2.6. The version bump invalidates bytecode and AST cache entries from older versions; they rebuild automatically on first run.

2.2 added:

• All<Vec> / All<Map> annotations for flow result shape — see Flows.
• OnErr.Force / OnErr.Preserve disposition for map-shaped higher-order functions — see Error Handling.

Upgrading from Hot 1.x to Hot 2

Hot 2 ships a clean baseline schema and does not migrate a Hot 1.x database in place. The public upgrade path covers local SQLite projects; Hot Cloud's v1→v2 data backfill lives in the private cloud repository.

Before you upgrade

Back up your database before changing major versions. hot db port-v1-to-v2 writes its own backup of the v1 SQLite file alongside the original, but a separate copy is still good practice.

Check the installed version before each phase:

hot version

SQLite (local development)

If you do not need to preserve your local data, the simplest path is to delete the SQLite file and let Hot 2 create a fresh one:

rm .hot/db/hot.sqlite.db
hot db migrate

To preserve your data, run the SQLite porter:

hot update
hot db port-v1-to-v2

hot db port-v1-to-v2 writes a backup of your v1 file alongside it (named hot.sqlite.db.v1.bak.<utc-timestamp>), applies the Hot 2 baseline migrations to a fresh file at the original path, and copies your user-data rows from the backup using SQLite's ATTACH DATABASE. The resulting v2 file's schema is byte-identical to a fresh hot init. Tables Hot 2 pre-populates with seed rows (statuses, roles, alert channels, scheduler state) are not copied; v1-only tables (subscription_plan, subscription, store) have no Hot 2 destination and are reported as dropped. The v1 backup file is preserved; remove it manually when you no longer need it.