:question: [Question]: stac-db migration failed, what to do?

[tlvu]

Questions

Updated a staging server from birdhouse-deploy 1.42.2 to latest 2.20.1, got the following error:

$ docker logs stac-db 2>&1 | tail -5

PostgreSQL Database directory appears to contain a database; Skipping initialization

2025-12-19 05:47:10.627 UTC [1] FATAL:  database files are incompatible with server
2025-12-19 05:47:10.627 UTC [1] DETAIL:  The data directory was initialized by PostgreSQL version 13, which is not compatible with this version 17.5 (Debian 17.5-1.pgdg110+1).

Any manual migration possible or the only option is to wipe the old DB file and start fresh?

[mishaschwartz]

Yes, you should make a representative backup of the stac data before you migrate, then wipe the database when you update the version and reload the data from the representative backup.

See discussions here:

• STAC DB migration for 0.6.10->0.6.13 [WIP post 0.7.x] #534
• 💡 [Feature] Backup *representative* data functionality #536
• backup restore without snapshot for STAC migration #561
• Add option to backup "representative" application data #548

[tlvu]

make a representative backup of the stac data

I am coming from 1.42.2, the "representative backup" feature did not exist yet at that version.

before you migrate

Too late, already migrated :(

So I conclude wiping the old DB file is the only option?

[tlvu]

By the way, it's fine if I have to wipe the old DB file. I think we don't have any production data in the Stac catalog yet.

I was just curious if there was a possible upgrade path.

[mishaschwartz]

I am coming from 1.42.2

Often when you need to do a big jump in versions, you need to upgrade incrementally. You can't just do it all at once.

So I conclude wiping the old DB file is the only option?

If it's already empty then yes that is a fine option

I was just curious if there was a possible upgrade path.

• Upgrade to 2.16.8 (the version before the db update change), backup data, update the rest of the way, repopulate the db from backup

OR

• pin STAC_DB_VERSION=0.6.10 in your local environment file, update to the latest version, backup data, unpin STAC_DB_VERSION, repopulate the db from backup