# How to Migrate Experiments from Older ChaosBlade Versions to Newer Releases > Easily migrate ChaosBlade experiments to newer releases. Learn how automatic schema detection and incremental updates simplify your upgrade process. Upgrade ChaosBlade confidently. - Repository: [ChaosBlade/chaosblade](https://github.com/chaosblade-io/chaosblade) - Tags: migration-guide - Published: 2026-02-27 --- **ChaosBlade automatically migrates your existing experiments when upgrading by detecting schema changes in the local SQLite database and applying incremental updates to the `experiment` and `preparation` tables.** When you upgrade the chaosblade-io/chaosblade tool, your historic experiment definitions and preparation records persist in a local SQLite file named `chaosblade.dat`. The migration framework in the `data` package handles schema evolution automatically—most notably adding the `pid` column to the preparation table in version 1.7.5—ensuring backward compatibility without manual intervention. ## Understanding the ChaosBlade Data Storage Model ChaosBlade maintains state in a SQLite database rather than external services. This design allows offline operation and simplifies deployment, but requires careful handling when the schema changes between releases. ### Default Database Location The binary determines the database path through the `GetDataFilePath()` function in [`data/source.go`](https://github.com/chaosblade-io/chaosblade/blob/main/data/source.go): - **Default**: `$(program-path)/chaosblade.dat` (the directory containing the `blade` binary) - **Custom**: Set the `CHAOSBLADE_DATAFILE_PATH` environment variable to a directory or full file path If `CHAOSBLADE_DATAFILE_PATH` points to a directory, ChaosBlade creates `chaosblade.dat` inside that directory. If it points to a specific file path, that file is used directly. ## Automatic Migration Process in Newer Versions When you execute the new binary, [`cli/main.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/main.go) invokes `data.GetSource()`, which triggers `Source.init()`. This initialization sequence automatically detects and applies required schema migrations. ### Experiment Table Migration The `CheckAndInitExperimentTable()` function in [`data/experiment.go`](https://github.com/chaosblade-io/chaosblade/blob/main/data/experiment.go) verifies that the `experiment` table exists. As of the latest releases, no schema changes have been introduced to this table after version 1.7.5, so the function primarily ensures table presence rather than structural updates. ### Preparation Table Migration The `CheckAndInitPreTable()` function in [`data/preparation.go`](https://github.com/chaosblade-io/chaosblade/blob/main/data/preparation.go) handles the critical schema evolution for preparation records: 1. **Version Detection**: Reads `PRAGMA user_version` via `GetUserVersion()` to determine current schema state 2. **Column Check**: Uses `ColumnExists()` to verify whether the `pid` column already exists in the `preparation` table 3. **Schema Update**: If the column is missing, executes `ALTER TABLE preparation ADD COLUMN pid VARCHAR DEFAULT ""` 4. **Version Bump**: Updates `PRAGMA user_version` to the constant `UserVersion = 1` via `UpdateUserVersion()` This migration was introduced specifically in ChaosBlade v1.7.5 to support process identification in preparation records. ## Step-by-Step Migration Guide Follow these steps to safely migrate your ChaosBlade experiments when upgrading from older versions. ### 1. Backup Your SQLite Database Before upgrading, create a backup of your existing data file: ```bash # If using default location cp "$(blade version | grep 'Data file' | awk '{print $NF}')" chaosblade.dat.bak # If using custom path cp "$CHAOSBLADE_DATAFILE_PATH" chaosblade.dat.bak ``` ### 2. Locate the Data File Verify the current database location to ensure you know which file the new binary will access: ```bash blade version | grep "Data file" ``` If you need to maintain the database in a specific location, export the environment variable: ```bash export CHAOSBLADE_DATAFILE_PATH=/opt/chaosblade/data/chaosblade.dat ``` ### 3. Run the New ChaosBlade Binary Replace the old binary with the new version and execute any command to trigger initialization: ```bash blade version ``` This invocation executes `data.GetSource()` in [`cli/main.go`](https://github.com/chaosblade-io/chaosblade/blob/main/cli/main.go), which automatically runs `CheckAndInitExperimentTable()` and `CheckAndInitPreTable()`. Successful migration produces log output similar to: ``` [INFO] migration: preparation table upgraded, added pid column ``` ### 4. Verify the Migration Confirm the schema update using the SQLite command-line tool: ```bash sqlite3 "$(blade version | grep Data | awk '{print $NF}')" \ "SELECT sql FROM sqlite_master WHERE type='table' AND name='preparation';" ``` The output should include the `pid` column definition: ```sql CREATE TABLE IF NOT EXISTS preparation ( id INTEGER PRIMARY KEY AUTOINCREMENT, uid VARCHAR(32) UNIQUE, program_type VARCHAR NOT NULL, process VARCHAR, port VARCHAR, status VARCHAR, error VARCHAR, create_time VARCHAR, update_time VARCHAR, pid VARCHAR ) ``` ### 5. Manual Migration (If Automatic Fails) If the automatic migration does not execute—perhaps due to a custom build or permission issues—apply the schema change manually: ```bash sqlite3 "$CHAOSBLADE_DATAFILE_PATH" <