Migrate to 0.1.0

Backup Your Data

Before proceeding with the migration, ensure you have a complete backup of your Stump database. This is crucial in case anything goes wrong during the migration process.

Create a separate Stump instance

I absolutely do not recommend updating your existing Stump instance in place. Please do not do that. This process should be in total isolation from your existing instance to avoid any potential data loss. We will bring over your existing configs and database in the next steps.

You could do something like the following:

/stump-old/      # Your existing Stump instance
	├── docker-compose.yml
	└── config/
	    └── stump.db
/stump-new/      # Your new Stump instance
	├── docker-compose.yml
	└── config/ # Empty, first start will create what you need

The important part here is to ensure you have an upgraded instance running to get the new database created and migrated, which happens automatically after the first start.

A few suggestions:

• If your existing setup uses latest alias for the Docker image, pin it to 0.0.12 instead to avoid accidental upgrades
• Make sure to fully stop your existing Stump instance before starting the new one (even though they are isolated)

Start the new Stump instance

Start the new Stump instance to allow it to create all the fresh configs and database files. Once you see the startup messages in the logs, fully stop the instance.

Be sure your old Stump instance is fully stopped as well. At this point, you can copy over your old instance's stump.db file into the new instance's config directory as stump-legacy.db (or any other name you prefer, just not stump.db). You may also mount is separately if preferred.

Download the backfill.sql Script

Download the backfill.sql script from the release page for 0.1.0.

If you continue with this guide, you will not need to make any edits to this script file. The migration tool will handle executing the sql for you.

If you would prefer to attempt to run the migration manually, please carefully review the script instructions. The important part is that you will need to replace the placeholders at the top of the script with your actual database paths.

Migrate Your Database

The updated Stump instance includes a CLI tool to help with the migration process. Before continuing, please ensure the following:

• The new Stump instance has been started at least once, has not been configured, and is fully stopped. There should be a new database created with no data in any of the tables
• The old Stump instance is fully stopped
• The old Stump database is accessible (if running Docker, ensure both database files are mounted properly or you copied it over accordingly)

To migrate your database using the CLI tool, run the following:

# If using Docker, exec into the NEW stump container
./stump system sea-orm-migration

The tool will prompt you for the necessary information to pull data from the old database and insert it into the new one. Follow the prompts carefully. A loose outline of the prompts is as follows:

• Confirm you want to proceed with the migration
• Enter the path to the legacy database file (with the data you want to migrate)
• Confirm the path to the new database file (this should be pre-filled with the correct path)
• Monitor the migration progress (should be very quick)