pi_mcps/.roo/skills-bigmind/bigmind-migration/SKILL.md

name, description

name	description
bigmind-migration	Scaffolds a new BigMind database schema migration (v_n to v_{n+1}), including the migration function, SCHEMA_VERSION bump, and test stubs. Use this skill when adding new tables or columns to the BigMind SQLite database.

BigMind Migration

When to use

• Adding a new table to BigMind
• Adding columns to an existing table
• Creating a new FTS5 virtual table

When NOT to use

• Non-schema changes (just code, no DB structure changes)
• Dropping or renaming columns (requires extra deprecation care — discuss first)

Inputs required

• Current schema version — check SCHEMA_VERSION in db.py
• New version — current + 1
• Changes — what tables/columns are being added

Workflow

Step 1 — Read current schema

grep -n "SCHEMA_VERSION" ~/.mcp/bigmind/bigmind/db.py
grep -n "_migrate_v" ~/.mcp/bigmind/bigmind/db.py

Know what version you're migrating FROM.

Step 2 — Write migration function in db.py

Add after the last existing migration function:

def _migrate_v{N}_to_v{N+1}(conn):
    """Add {description of change}."""
    cursor = conn.cursor()
    
    # Example: new table
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS {table_name} (
            id TEXT PRIMARY KEY,
            user_id TEXT NOT NULL,
            created_at TEXT NOT NULL DEFAULT (datetime('now')),
            -- other columns
            FOREIGN KEY (user_id) REFERENCES users(id)
        )
    """)
    
    # Example: FTS5 virtual table
    cursor.execute("""
        CREATE VIRTUAL TABLE IF NOT EXISTS {table_name}_fts
        USING fts5(content, tokenize='porter')
    """)
    
    conn.commit()

Step 3 — Wire into init_db()

In the migration chain inside init_db():

SCHEMA_VERSION = {N+1}  # bump this

# In the migration section:
if current_version < {N+1}:
    _migrate_v{N}_to_v{N+1}(conn)
    current_version = {N+1}

Step 4 — Write tests

In tests/test_memory_store.py (or a new test file):

class TestMigration_v{N}_to_v{N+1}:
    def test_fresh_db_has_new_table(self, tmp_path):
        db_path = tmp_path / "test.db"
        conn = get_connection(str(db_path))
        init_db(conn)
        # Assert new table exists
        cursor = conn.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='{table_name}'")
        assert cursor.fetchone() is not None

    def test_existing_db_migrates_cleanly(self, tmp_path):
        # Create a v{N} db, then run init_db() and check migration ran
        ...

Step 5 — Run full test suite

cd ~/.mcp/bigmind
uv run pytest tests/ -v

All tests must pass.

Step 6 — Store migration fact

memory_store_fact("codebase", "BigMind schema migrated v{N}→v{N+1}: added {description}. Migration function: _migrate_v{N}_to_v{N+1}.")

Troubleshooting

• IF NOT EXISTS is your friend: Always use it so the migration is idempotent
• FTS5 table ordering: Create the base table before the FTS5 virtual table that references it
• Migration not running: Check the if current_version < X: guard — verify current_version is read correctly from PRAGMA user_version
• Test DB state: Use tmp_path fixture for isolated test databases — never test against the real memory.db