Upgrades & migrations

Upgrading means installing a new binary or pulling a new image and restarting. Your data stays where it is, and database changes (migrations) are applied automatically on the next start — there is nothing to run by hand. Always take a backup first so you can go back.

UpgradeCopy Anchor Link

staqly serve backup ~/staqly-backup.db

curl -fsSL https://raw.githubusercontent.com/staqly/staqly/main/scripts/install.sh | sh

curl -fsSL https://raw.githubusercontent.com/staqly/staqly/main/scripts/install.sh | STAQLY_VERSION=v0.2.0 sh

The Community Edition now needs the access tokenCopy Anchor Link

Earlier versions let agents on your computer call the local API without a key. Now every request needs the install's access token, which staqly makes on the first start after the upgrade and prints at every start. After upgrading:

• give your agents and scripts the token: export STAQLY_API_KEY=$(staqly serve token) (Docker: $(docker exec staqly server token)) and add the bearer header to their MCP configuration — see Connect an agent;
• in n8n, send the token as Authorization: Bearer — see n8n;
• sign each browser in once with the printed link or the pasted token;
• remove LOCAL_TRUSTED_PEERS, LOCAL_ALLOWED_HOSTS and LOCAL_ALLOWED_ORIGINS from your settings: they are no longer read.

docker exec -i staqly mcp-stdio and the staqly CLI next to staqly serve keep working without changes.

Roll backCopy Anchor Link

A newer version may already have migrated the database, so go back to the backup together with the older version.

How migrations workCopy Anchor Link

• Database migrations (goose) are embedded in the binary — in staqly and in the ghcr.io/staqly/staqly image alike — and run automatically at startup, each in its own transaction.
• If a start is interrupted, the next start resumes from the last fully applied migration.
• There is no separate migration command. /readyz reports migrations: pending until they are all applied — see Monitoring.
• Media files stored before workspace folders are moved once into workspaces/<id>/ of the media storage on the first start (old thumbnails are dropped and made again on use). Each file is copied before the old copy is deleted, so an interrupted start simply continues next time.
• The job queue's own tables (River, river_*) are migrated the same way, right after. Upgrading from a version before the River queue carries queued and running jobs (scheduled posts, pending retries) into it on the first start; nothing is lost and nothing needs doing.

Next stepsCopy Anchor Link