Great question. I can tailor precise steps if you share: - Are you on Prefect 2.x or 3.x today? - How do you run OSS Prefect in prod (Docker Compose, Kubernetes/Helm, or VMs)? - Which database (Postgres version) and do you have HA/multiple replicas? Below is a production-safe playbook you can follow. It assumes Prefect 3.x OSS; I add 2.x→3.x notes at the end. Production upgrade playbook (Prefect OSS 3.x) 1) Plan and pin versions - Read the release notes and identify any breaking changes or required settings. - Latest notes: Prefect releases (see your target version) - Example latest from our tooling: 3.4.23 changelog - Pin everything (server image tag, worker/flow image tags, Python package versions) in config/infra-as-code. Avoid “latest” tags in prod. - Prefer upgrading the server first, then clients/workers. Older clients are generally compatible with newer servers, but newer clients may not be compatible with older servers. See Server concepts and compatibility. 2) Stage and rehearse - Rehearse the exact upgrade in a staging environment with a snapshot of your prod database. - Validate: - API/health checks and UI load - Scheduling and task submissions - A few representative flows end-to-end 3) Database migrations (important) - Prefect 3.x runs DB migrations automatically on startup by default. You can control this via: - Env var:

PREFECT_SERVER_DATABASE_MIGRATE_ON_START=true|false

- Config:

server.database.migrate_on_start

- Docs: Settings reference - Recommended: - Take a database backup/snapshot before upgrading. - For zero-ish downtime: run a one-off migration job or start a single new server instance to perform the migration, then roll the rest of the replicas. If you disable auto-migration, ensure you run the migration once before flipping traffic. 4) Upgrade the server - Docker Compose: - Update the image tag(s) for your Prefect server services in your compose file to the target version. - Pull and roll out:

docker compose pull
    docker compose up -d

- Consider blue/green: bring up a parallel stack (different project name/network), verify, then cut over by swapping DNS/ingress or port bindings. - Reference: Docker Compose (self-hosted) guide - Kubernetes: - If using a Helm chart for Prefect Server, perform a rolling upgrade:

helm repo update
    helm upgrade <release-name> <chart> -f values.yaml --install --wait --timeout 10m

- Ensure your values set

PREFECT_SERVER_DATABASE_MIGRATE_ON_START

appropriately, and that a single pod (or a pre-upgrade job) applies migrations before others roll. - If you are not on a Helm chart, use a Deployment with rolling updates and pre/post hooks to manage migrations and readiness. - Worker on K8s (separate but related): Deploy a worker using Helm - Validate post-upgrade: - UI reachable, API healthy, flow run creation working - Schedules are generating runs 5) Upgrade workers and flow environments - Upgrade the Prefect library in the environments that actually execute your flows. For containers, update the image tag; for VMs, pin and upgrade the Python package:

pip install --upgrade "prefect==<your_target_version>"

- Confirm the CLI/client versions:

prefect version

- Rebuild and redeploy worker images or restart worker pods/VMs so they pick up the new library. 6) Post-upgrade checks - Run canary flows. Watch logs and the UI for failed runs, mismatched schemas, or 422/4xx errors indicating client–server incompatibilities.

- Keep the previous server and worker images available until you confirm stability. 7) Rollback plan - Keep your previous Helm values/Compose file and image tags. - If a rollback is needed and DB migrations were applied: - Attempt a standard rollback first (previous image/values). If the server fails due to schema mismatch and migrations are not backward-compatible, restore the DB snapshot you took pre-upgrade and then roll back images. - For clients/workers, just revert the image or pip version pin and redeploy. Notes for 2.x → 3.x upgrades - Plan this as a project, not an in-place patch: - Workers replace agents in 3.x. Migration notes: Upgrade agents to workers - CLI and deployment changes: use

prefect deploy

and `flow.from_source(...).deploy(...)`; do not use deprecated 2.x commands like

prefect deployment build

or

Deployment.build_from_flow()

. - Expect some API and settings differences; test flows end-to-end in staging. - General guidance and launch post: Prefect 3 GA announcement Useful links - Server concepts and compatibility: Prefect Server (OSS) concepts - Self-hosted via Docker Compose: Docker Compose guide - Settings reference (incl. DB migrate on start): Settings reference - K8s worker Helm example: Worker on Kubernetes with Helm If you can share your current version (2.x or 3.x), deployment method (Compose/Helm/VMs), and whether you have multiple server replicas/HA DB, I’ll adapt this into exact commands and a rollback runbook for your setup.