Upgrade an instance
Anchor is pre-1.0: read the changelog
for every version between yours and the target before upgrading. Breaking changes and manual
steps are listed there. Below, v<version> stands for the release you are moving to, such as
v0.3.0.
Back up the database first
Section titled “Back up the database first”D1 Time Travel can restore any minute of the last 30 days (Workers Paid), but take an explicit
bookmark first. Use your database’s name (anchor unless you picked another one):
pnpm exec wrangler d1 time-travel info anchorNote the bookmark it prints. To restore:
pnpm exec wrangler d1 time-travel restore anchor --bookmark=<bookmark>.
If you deployed with the button
Section titled “If you deployed with the button”Your copy is an independent repository. Pull the release into it from this one, then push:
git remote add upstream https://github.com/sotarak/anchor.git # oncegit fetch upstream --tagsgit merge v<version>git pushWorkers Builds picks up the push, applies the new migrations, and deploys. If the merge conflicts in
wrangler.jsonc, keep your own IDs (database_id, queue names, Worker name) and take everything
else from the release.
If git stops with fatal: refusing to merge unrelated histories, your copy started from a fresh
commit instead of this repository’s history. Do the first merge like this, once:
git merge --allow-unrelated-histories -X theirs v<version>git diff HEAD~1 -- wrangler.jsonc # put your own IDs and names back, then commit-X theirs takes the release’s side of every conflict, so restore your database_id, queue names
and Worker name in wrangler.jsonc before you push. Files the release deleted stay in your copy;
remove them by hand (compare with git diff --stat v<version>). Later upgrades merge normally.
If you deployed manually
Section titled “If you deployed manually”From the repository root:
git fetch --tagsgit merge v<version> # or check it out on a branch that keeps your wrangler.jsonc editspnpm install --frozen-lockfilepnpm exec wrangler d1 migrations list DB --remote # what will runpnpm deploy:worker # applies migrations, then deploysEvery migration so far only adds tables, columns, indexes and triggers, so the running version keeps working against the new schema while the deploy finishes; the changelog calls out any migration that does not.
Your wrangler.jsonc holds your own database_id. Keep that change on a local branch (or re-apply
it after each upgrade) so upgrades do not overwrite it.
0.3.0 moved the Worker config to the repository root. If you deployed manually before 0.3.0, move your
database_idfromapps/server/wrangler.jsoncinto the rootwrangler.jsonc, and moveapps/server/.dev.varsto.dev.varsat the root. Run everywranglercommand from the root from now on. The database name and binding are unchanged, so no data moves.
0.3.0 removed the setup token.
/setupno longer asks for one: the first account created there owns the instance, and an instance that already has an owner is unaffected.ANCHOR_SETUP_TOKENis no longer read; delete it withpnpm exec wrangler secret delete ANCHOR_SETUP_TOKEN(or under the Worker’s Settings → Variables and Secrets). Scripts that still sendsetupTokenkeep working.
0.4.0 adds four migrations (
0005_typed_values,0006_cli_logins,0007_service_token_no_expiry,0008_oauth). Button deploys andpnpm deployapply them; a manual deploy runspnpm exec wrangler d1 migrations apply DB --remotefrom the root first. A deploy that keeps its ownwrangler.jsoncmust also copy the newassets.run_worker_firstlist (/mcp, the/.well-known/oauth-*paths and/oauth/token,/oauth/register,/oauth/revoke), and a WAF rate-limiting rule on the login endpoints should also cover/oauth/*. No data is rewritten: existing secrets read as sensitivestringvalues. Upgrade the server before the CLI: CLI 0.4.0 logs in through the browser, which a 0.3.x server does not support (useanchor login --with-passworduntil it is upgraded). CLI 0.3.x keeps working against 0.4.0. Rolling back below 0.4.0 (for example with the Worker’s one-click rollback) is not supported once 0.4.0 has written a secret: 0.3.x cannot open versions sealed with the 0.4.0 format, so revealing them,anchor runon their folder and updating them fail with a 500 until you upgrade again. No data is lost. To run 0.3.x again, restore the bookmark from the step above, which discards every write made since.
If a release changes Worker configuration (a new binding or queue in wrangler.jsonc), the changelog
says so; create the resource before you deploy.
Check the instance
Section titled “Check the instance”Check GET /api/v1/health, sign in to the dashboard, and read one secret.
Update the CLI
Section titled “Update the CLI”Move developer machines and CI to the same release:
npm install -g @anchor-secrets/cli@<version> # npmbrew update && brew upgrade anchor # Homebrewcurl -fsSL https://sotarak.github.io/anchor/install.sh | ANCHOR_VERSION=<version> sh # install scriptIn GitHub Actions, bump the setup action to sotarak/anchor/setup-action@v<version>. The
CLI guide covers every install method.