Bring your towel and join one of the fastest growing data communities. Welcome to our second-generation open source orchestration platform, a completely rethought approach to dataflow automation.

Prefect Community

<@ULVA73B9P> some prefect2 -&gt; prefect3 upgrade questions:
do i get to keep old-runs and everything runs smoothly on (self-hosted) server? do i need to migrate the inner prefect-db or something?

:white_check_mark: thought for 109.9 seconds

Yes — *you should keep your old runs/history* when upgrading a self-hosted Prefect 2 server to Prefect 3, *but you do need to migrate the Prefect database schema*.

*Short version:*
- *Old flow/task runs, logs, artifacts, etc. are preserved*
- *You should run a DB migration*
- *Server upgrade is generally smooth*, but *workers/agents/deployments may need changes*
- *Take a DB backup first*

The main command is:

```bash
prefect server database upgrade -y
```

I verified that command exists. You can also inspect it with:

```bash
prefect server database upgrade --help
```

A few important details:

*What happens to old runs?*
- Existing historical runs should remain in the database and stay visible after upgrade
- Logs, states, artifacts, and most server-side metadata are intended to be preserved
- Prefect 3 upgrades the schema/data rather than replacing the DB

*Do you need to migrate the inner Prefect DB?*
- *Yes*
- If you're using the same self-hosted Postgres/SQLite database, run the DB upgrade after installing Prefect 3
- For production/self-hosted Postgres, definitely *backup first*

Typical upgrade flow:

```bash
# stop old server / API processes first

pip install -U prefect

prefect server database upgrade -y

# then start Prefect 3 server
prefect server start
```

*Big caveat:* server data may migrate cleanly, but *execution infrastructure may not be plug-and-play*.

In particular for Prefect 3:
- *agents -&gt; workers* is the big conceptual shift
- old deployment patterns from Prefect 2 often need updating
- do *not* use removed 2.x patterns like `Deployment.build_from_flow()` or `prefect deployment build`
- use `flow.from_source(...).deploy(...)` or `prefect deploy` instead

So I’d separate the upgrade into two questions:

1. *Server/database/history*: usually yes, migrate and keep historical data
2. *How flows are deployed/run going forward*: may require changes

A few cautions:
- *Backup the DB first*
- test in staging if the database is important
- if you have a *large database*, migrations may take a while
- if you run *multiple API/server instances*, disable auto-migrate on startup and run migration once before bringing them all up

Useful docs:
- <https://docs.prefect.io/v3/how-to-guides/self-hosted/server-cli|Prefect server CLI>
- <https://docs.prefect.io/v3/how-to-guides/deployments|Prefect 3 deployments>
- <https://docs.prefect.io/v3/resources/upgrade-to-prefect-3|Upgrade to Prefect 3>

If you want, I can also give you a *Prefect 2 -&gt; 3 self-hosted upgrade checklist* for either:
- *docker-compose server*
- *kubernetes*
- or *bare-metal / venv install*