idb-migrations

IDB Storage Migrations

Overview

Suite uses IndexedDB for persistent storage. When the data schema changes between versions, a migration transforms old data to match the new shape. Migrations live in packages/suite/src/storage/migrations/versions/.

Creating a Migration

Step 1: Scaffold

# Auto-detect version (recommended)
yarn workspace @trezor/suite make:migration

# Specific version
yarn workspace @trezor/suite make:migration 26.5.0

# Revision within a version
yarn workspace @trezor/suite make:migration 26.5.0.1

This creates the migration file and updates the auto-generated index at packages/suite/src/storage/migrations/versions/index.ts.

Step 2: Implement

Every migration file uses createMigration from @suite/idb-migration-utils and default-exports the result.

Minimal (schema-only) migration

Use when creating/deleting object stores — no data transformation needed:

import { createMigration } from '@suite/idb-migration-utils';
import { type SuiteDBSchema } from 'src/storage/definitions';

export default createMigration<SuiteDBSchema>('26.5.0', db => {
    db.createObjectStore('newStore');
});

Data transformation migration

Use updateAll from ../utils to iterate and transform all records in a store. The callback receives each record and must return:

• the updated record to update it
• null to delete it
• undefined/void to leave it untouched

import { createMigration } from '@suite/idb-migration-utils';
import { type SuiteDBSchema } from 'src/storage/definitions';
import { updateAll } from '../utils';

export default createMigration<SuiteDBSchema>('26.5.0', async (_, tx) => {
    await updateAll(tx, 'devices', device => {
        // Add a new field with a default value
        if (!device.newField) {
            device.newField = 'default';
        }
        return device;
    });
});

Accessing multiple stores

The migration callback receives (db, tx) where db is the database and tx is the versionchange transaction. You can access any store via tx.objectStore('storeName'):

export default createMigration<SuiteDBSchema>('26.5.0', async (db, tx) => {
    // Read from a store directly
    const store = tx.objectStore('suiteSettings');
    const settings = await store.get('suite');

    // Modify and write back
    if (settings) {
        settings.someField = 'newValue';
        await store.put(settings, 'suite');
    }

    // Also transform another store
    await updateAll(tx, 'devices', device => {
        device.field = 'value';
        return device;
    });
});

Accessing deleted stores

When a store was removed from SuiteDBSchema, use @ts-expect-error to access it:

// @ts-expect-error storeName no longer exists
if (db.objectStoreNames.contains('oldStore')) {
    // @ts-expect-error storeName no longer exists
    const store = tx.objectStore('oldStore');
    const data = await store.get('key');
    // ... migrate data to new location
    // @ts-expect-error storeName no longer exists
    db.deleteObjectStore('oldStore');
}

Step 3: Update the CHANGELOG

For base migrations (revision 0), a ## x.y.z header is auto-added to packages/suite/src/storage/CHANGELOG.md. Add a description of what the migration does under it.

Key Stores

Full schema: packages/suite/src/storage/definitions.ts (SuiteDBSchema)

Version Encoding

IndexedDB version is a 32-bit integer encoding SemVer: (major << 24) | (minor << 16) | (patch << 8) | revision. Each component is 0-255. See suite/idb-migration-utils/MIGRATION.md for details.

Important Notes

• Migration files must default-export the createMigration result
• The versions/index.ts file is auto-generated — use the scaffold command, don't edit manually
• Use @ts-expect-error for accessing stores/fields that no longer exist in the current schema
• Always guard with if checks before accessing potentially missing data
• The updateAll utility handles cursor iteration — just provide the transform function