For self-hosted Prefect 3.x, the best update path is usually: 1. Back up your database 2. Upgrade the Prefect version on the server host/container/image 3. Run DB migrations 4. Restart the server 5. Then upgrade workers/clients Since you’ve previously mentioned self-hosting, the main thing to protect during upgrades is the database schema. Recommended order

bash
# 1) back up your DB first
pg_dump <your-prefect-db> > prefect_backup.sql

# 2) upgrade Prefect on the server
pip install -U prefect

# 3) run migrations
prefect server database upgrade -y

# 4) restart the server
prefect server start

If you're using Docker, the equivalent is: - update the image tag - run

prefect server database upgrade -y

- then start the new container(s) If you're using Kubernetes/Helm: - update the chart/image version - ensure migrations run before or during rollout - then let the deployment roll forward Important notes - Upgrade the server first, then workers and user environments. - Prefect requires major version compatibility between client and server. So all components should remain on 3.x. - Same-major-version mismatches are usually okay temporarily, but best practice is to update workers/clients soon after the server. - If you have multiple API replicas, *don’t let all of them auto-migrate at once*; run migrations once, then start the replicas. For a bare-process/self-hosted install, I’d suggest this safer sequence:

bash
# stop server
# back up DB
pip install -U prefect
prefect server database upgrade -y
prefect server start

CLI verified -

prefect server database upgrade --help

-

prefect server start --help

Docs - Self-hosted Prefect - Database maintenance - Upgrade to Prefect 3 If you want, I can give you the best exact upgrade procedure for your setup specifically: - bare process / systemd - Docker Compose - Kubernetes / Helm

Yes — usually, yes. When upgrading from Prefect 3.6 -> 3.7, you should assume there may be database migrations and run:

bash
prefect server database upgrade -y

Whether a specific patch/minor jump actually includes new migrations depends on the release, but the safe/recommended process is always: 1. upgrade the Prefect package/image 2. run

prefect server database upgrade -y

3. restart the server If there are no pending migrations, the command is effectively a no-op. You can also preview with:

bash
prefect server database upgrade --dry-run

So the short answer is: - Yes, run the migration command when upgrading self-hosted server versions - No, that does not necessarily mean there will always be schema changes, but you should still run it If you want, I can also show you a zero-drama upgrade checklist specifically for a self-hosted Postgres-backed Prefect server.