Fly.io Upgrade & Migration

Overview

Guide for Fly.io platform migrations: Apps v1 (Nomad) to v2 (Machines), flyctl CLI upgrades, Postgres major version upgrades, and region migrations.

Prerequisites

Current platform documentation and an inventory of applications, machines, regions, volumes, databases, identities, and dependent consumers.
A staging environment, synthetic traffic/data, tested backup/restore, rollback owner, and explicit acceptance/reconciliation criteria.

Output

Produce a migration receipt with versions reviewed, affected resources, staging/canary results, backup/restore evidence, reconciliation outcome, approver, and rollback state. Keep tokens, connection strings, and user data out of the receipt.

Error Handling

Stop promotion on health, schema, region, permission, or reconciliation mismatches and restore the prior configuration.
Quarantine failed migrations by opaque resource ID; do not bulk replay stateful workloads to diagnose failures.
Escalate potential data loss or credential exposure and retain only approved incident evidence.

Examples

Migrate a disposable staging app using synthetic traffic, exercise a backup/restore of fictional data, and simulate a failed health check. Verify rollback returns routing and data access to the known-good release before considering a production canary.

Instructions

Apps v1 to v2 Migration

# Check current platform version
fly status -a my-app  # Look for "Platform: machines" vs "nomad"

# Migrate to Apps v2 (Machines)
fly migrate-to-v2 -a my-app

# Verify
fly status -a my-app
fly machine list -a my-app

flyctl CLI Upgrade

# Check current version
fly version

# Upgrade
fly version update

# Or reinstall
curl -L https://fly.io/install.sh | sh

Postgres Major Version Upgrade

# Check current version
fly postgres connect -a my-db -c "SELECT version();"

# Create new cluster with target version
fly postgres create --name my-db-v16 --region iad --image-ref flyio/postgres-flex:16

# Migrate data
fly postgres import pg_dump_url -a my-db-v16

# Update app to point to new cluster
fly postgres detach my-db -a my-app
fly postgres attach my-db-v16 -a my-app
fly deploy -a my-app  # Picks up new DATABASE_URL

Region Migration

# Add machines in new region
fly scale count 1 --region fra -a my-app

# Verify new region is healthy
fly status -a my-app

# Remove machines from old region
fly scale count 0 --region iad -a my-app

# For volumes: create new volume, migrate data, destroy old
fly volumes create data --size 10 --region fra -a my-app

Migration Checklist

Current state documented (fly status, fly scale show)
Database backed up before migration
Tested migration in staging app first
DNS/certificates transferred if changing domains
Monitoring confirms healthy after cutover
Old resources cleaned up

Resources

Next Steps

For CI integration, see flyio-ci-integration.