clockworklabs/SpacetimeDB · error

Manual database migrations are not yet implemented

Error message

Manual database migrations are not yet implemented

What it means

During publish, the engine classifies the schema diff into an auto or manual migration plan. The manual branch, manual_migrate_database (crates/engine/src/update.rs:191), is still unimplemented!(), so any plan that is not auto-migratable panics with this message instead of applying.

Source

Thrown at crates/engine/src/update.rs:191

            .ok_or_else(|| anyhow::anyhow!("table {} not found in old_module_def", table.table_name))?;

        table.check_compatible(owning_def, old_def)?;
    }

    match plan {
        MigratePlan::Manual(plan) => manual_migrate_database(stdb, tx, plan, logger),
        MigratePlan::Auto(plan) => auto_migrate_database(stdb, tx, auth_ctx, plan, logger),
    }
}

/// Manually migrate a database.
fn manual_migrate_database(
    _stdb: &RelationalDB,
    _tx: &mut MutTxId,
    _plan: ManualMigratePlan,
    _logger: &dyn UpdateLogger,
) -> anyhow::Result<UpdateResult> {
    unimplemented!("Manual database migrations are not yet implemented")
}

/// Logs with `info` level to `$logger` as well as via the `log` crate.
macro_rules! log {
    ($logger:expr, $($tokens:tt)*) => {
        $logger.info(&format!($($tokens)*));
        log::info!($($tokens)*);
    };
}

/// Automatically migrate a database.
fn auto_migrate_database(
    stdb: &RelationalDB,
    tx: &mut MutTxId,
    auth_ctx: AuthCtx,
    plan: AutoMigratePlan,
    logger: &dyn UpdateLogger,
) -> anyhow::Result<UpdateResult> {

View on GitHub (pinned to 524b4487d9)

Solutions

1. Restructure into auto-migratable steps: add a new column/table, backfill with a reducer, then remove the old one in a later publish
2. For throwaway/dev databases, publish with --wipe-data (or delete and republish the database) to skip migration entirely
3. Read the auto-migration report emitted before the failure to identify exactly which change forced the manual plan, and revert that change
4. Track SpacetimeDB release notes — manual migrations remain on the roadmap

Example fix

// before (single publish, type change -> manual plan -> panic)
#[col] pub count: String -> #[col] pub count: u64

// after (two publishes, both auto-migratable)
// 1) add #[col] count_v2: u64, backfill via reducer
// 2) remove old count column

# Before publishing a risky diff, preview the plan:
spacetime migrate diff  # or the plan/report subcommand your CLI version offers
# If the report lists non-auto-migratable changes, restructure BEFORE publish

# In deploy scripts:
if ! spacetime publish my-module; then
  # inspect output; if it reports a manual-migration panic, fall back to
  # the additive two-step publish or (dev only) --wipe-data
  spacetime publish --wipe-data my-module  # DEV DATABASES ONLY
fi

When it happens

Trigger: Publishing a module update whose diff cannot be auto-migrated (e.g. an in-place column type change with no coercion) and landing on MigratePlan::Manual; explicitly requesting a manual migration flow.

Common situations: Changing a column's type in place, deleting/renaming columns in ways auto-migration rejects, or following older docs/roadmap material that describes manual migrations that are not shipped yet.

Related errors

• Publishing aborted by user
• database `{addr}` not yet initialized
• never types are not yet supported in C# output
• Unknown constraint type
• Unknown index algorithm {:?}

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/56735a11162f56cb. Report an issue: GitHub.