How to Migrate Experiments from Older ChaosBlade Versions to Newer Releases

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:

• 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 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 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 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:

# 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:

blade version | grep "Data file"

If you need to maintain the database in a specific location, export the environment variable:

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:

blade version

This invocation executes data.GetSource() in 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:

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:

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:

sqlite3 "$CHAOSBLADE_DATAFILE_PATH" <<SQL
PRAGMA user_version=1;
ALTER TABLE preparation ADD COLUMN pid VARCHAR DEFAULT "";
SQL

After manual execution, restart ChaosBlade to verify normal operation.

Summary

• ChaosBlade stores state in a local SQLite file (chaosblade.dat) located either beside the binary or at CHAOSBLADE_DATAFILE_PATH.
• Automatic migration triggers when running newer binaries, handled by data/preparation.go and data/experiment.go via cli/main.go.
• Key schema change: Version 1.7.5 added the pid column to the preparation table using ALTER TABLE and PRAGMA user_version tracking.
• Always backup chaosblade.dat before upgrading, and verify migration success using sqlite3 schema inspection.

Frequently Asked Questions

Will I lose my existing experiments when upgrading ChaosBlade?

No. ChaosBlade maintains backward compatibility through automatic schema migrations. The SQLite database preserves all experiment and preparation records, and the migration logic in data/preparation.go specifically handles additive changes like the pid column introduced in v1.7.5 without deleting historical data.

How do I know if the migration completed successfully?

Check the log output when running blade version or any blade command. Successful migration produces an [INFO] log entry stating the preparation table was upgraded. Additionally, query the schema using sqlite3 to confirm the pid column exists in the preparation table, or check that PRAGMA user_version returns 1.

What if the automatic migration fails?

If the automatic migration fails—typically due to file permissions, custom builds lacking the migration code, or corrupted database files—you can manually apply the schema change. Use the sqlite3 CLI to execute ALTER TABLE preparation ADD COLUMN pid VARCHAR DEFAULT "" and set PRAGMA user_version=1, then restart ChaosBlade.

Which ChaosBlade versions require database migration?

Database migrations are required when upgrading to ChaosBlade v1.7.5 or later from earlier versions. This specific release introduced the pid column in the preparation table to support process identification features. Future versions may introduce additional migrations, which the data package will handle automatically using the user_version pragma tracking system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}