Upgrading

Before upgradingCopy Anchor Link

1. Read the release notes of the target version.
2. Keep a copy of the metadata database to roll back to: in the admin console, go to Settings → Backups & export → Metadata snapshots, click Back up now, then Download that snapshot and store it off the server. Alternatively, stop the service and copy <data dir>/imgyoung.db (only consistent once stopped).
3. Make sure master.key is backed up; see Configuration.

Check the running version with imgyoung -version, or under Server version in Settings → Runtime settings → Bootstrap configuration.

Upgrade commandsCopy Anchor Link

# Running as a systemd service (installed with --service): replaces the binary, rewrites the unit and restarts the service
curl -fsSL https://raw.githubusercontent.com/x-haose/imgyoung/main/install.sh | sudo sh -s -- --service

# Managing the process yourself: only replaces the binary; restart imgyoung afterwards
curl -fsSL https://raw.githubusercontent.com/x-haose/imgyoung/main/install.sh | sh

When the old process is stopped, ImgYoung first stops accepting new requests and waits up to 6 seconds for in-flight requests (cutting them off after that), then stops the background loops and in-flight replication jobs, waiting up to 2 more seconds, and finally closes the database and exits. Interrupted replication jobs are queued again by reconciliation on the next start. Docker's default 10-second stop timeout and the stop_grace_period: 15s (Compose) and TimeoutStopSec=15s (systemd) in the deploy/ examples are all enough.

Database migrationsCopy Anchor Link

Migrations are embedded in the binary and run automatically on every start, right after the database is opened:

• the migration files are first checked against their checksum list, then every migration not yet applied runs in version order; when skipping several versions, all intermediate migrations are applied in turn. Applied versions are recorded in the schema_revisions table.
• the replication subsystem's job queue tables are migrated at startup as well.
• runtime settings added by a migration are filled in with their factory defaults; existing values are untouched.
• if the database records a migration version this binary does not know (it was migrated by a newer version), startup is refused; see Rolling back below.
• if a migration fails, the process exits with an error naming the failing migration file. Roll back using your pre-upgrade snapshot (see below).

There is no separate migration command, and none is needed.

Rolling backCopy Anchor Link

Downgrades are not supported: migrations only go forward, and some of them drop columns or rebuild tables. An older binary refuses to start on a database migrated by a newer version; the error names the newest migration version in the database and the newest one the binary knows.

Rolling back therefore takes exactly one thing: the older binary plus your pre-upgrade snapshot. Without a pre-upgrade snapshot, you have to stay on the new version.

Metadata written since the upgrade is lost, with the same effects as restoring a snapshot: images uploaded in the meantime have no record in the metadata, so their objects on the channels are only counted, never deleted, but can no longer be reached through ImgYoung. See Backup & restore.