Upgrades

Upgrade your instance to a new release — manually with the update script, or one-click via an update channel.

#Upgrades

New EmuView versions arrive as tagged GitHub releases — development on main never affects your instance until a release is cut. Your instance's System dashboard shows an Update available badge when a newer release exists, and this page covers the ways to act on it.

#Before you upgrade

  1. Read the release notes — the badge links straight to them; check for breaking changes
  2. Back up — export your core and pool databases (see Backups):
    npx wrangler d1 export <instance>_sveltesync --remote --output backup-core.sql
  3. Know the rollback path — code deploys can be rolled back; database migrations cannot

#Path 1 — Manual (default)

From your clone of the repository:

# 1. Move to the release
git fetch --tags
git checkout v0.4.0        # or: git pull origin main for the latest

# 2. Install any new dependencies
npm install

# 3. Update the instance — migrations, build, deploy, in one command
npm run update -- --name my-blog

The update script rediscovers your instance's resources from Cloudflare by name (no state file), applies pending D1 migrations, rebuilds, redeploys both the API worker and the dashboard, and finishes by printing the exact rollback command for that deploy.

Other useful forms:

npm run update -- --all          # update every instance on the account
npm run update -- --discover     # interactive: scan, select, update
npm run update -- --name my-blog --migrate-only

#Path 2 — One-click update channels

If your instance deploys from a GitHub fork, you can wire the dashboard's Update now button to your pipeline instead. Set the channel in Settings → System:

Channel How it deploys
Workers Builds Your fork is connected to Cloudflare Workers Builds. The button syncs the fork with upstream; the push triggers your build automatically
GitHub Actions The button dispatches the deploy.yml workflow included in the repository, with the release tag as input — deploying exactly that version

One-time setup for the GitHub Actions channel, in your fork:

  1. Repository secret CLOUDFLARE_API_TOKEN (same scopes as deployment)
  2. Repository variable INSTANCE_NAME (your instance's name); add CLOUDFLARE_ACCOUNT_ID if the token spans multiple accounts
  3. In the app: Settings → System → channel github-actions, Update Repository you/sveltesync
  4. A GITHUB_TOKEN secret on the gateway worker with write access to the fork

Nothing instance-specific is ever committed — the workflow reads everything from secrets and variables, so upstream updates always merge cleanly into your fork. The admin-facing view of all this (the version card, trigger results, permissions) is documented in Administration → Updates.

Note

The workflow file can also be dispatched by hand from your fork's Actions tab with any tag — including an older one, which is the rollback path for this channel.

#Migrations

Both paths apply migrations the same way: numbered SQL files in migrations/, applied in order, tracked in the d1_migrations table so each runs exactly once. Migrations are forward-only — this is why the backup step above is not optional.

#What you learned

  • Releases are deliberate: only tags trigger the update badge, never main
  • Manual path: check out the tag, npm run update -- --name <instance> does migrations + build + deploy
  • Channel path: the dashboard's Update button drives your fork's own pipeline
  • Migrations run once, forward-only — back up before every upgrade

#Next steps