Spacetimedb Databases

Use this skill for database module lifecycle and migration work.

Core patterns

• A module is the code and schema; a database is a published instance identified by name or identity.
• spacetime publish <DATABASE_NAME> builds, uploads, runs init if present, and starts serving the module.
• Publishing an existing database attempts an automatic migration and hot-swaps the module atomically while maintaining active client connections.
• Regenerate and ship client bindings after public schema, reducer, procedure, or view surface changes.
• Reducers run in automatic transactions; procedures open transactions manually when they need database writes.

Migration checklist

• Safe: add tables, add indexes, add or remove auto-increment annotations, make private tables public, add reducers, remove unique constraints.
• Potentially breaking: add a column at the end with a default, change or remove reducers, make a public table private, remove primary keys, remove indexes used by subscriptions.
• Forbidden by automatic migration: remove tables, remove/rename/reorder/change existing columns, add columns without defaults, add columns in the middle, change schedule-table status, add unique or primary-key constraints.
• During development, --delete-data can reset data. Do not use it for production unless permanent data loss is intended.
• For forbidden production changes, use an additive migration strategy: add new shape, dual-write/backfill, move clients, then retire old shape later.

Reference map

Guidance

• Check migration safety before changing table shape, names, indexes, constraints, or public/private visibility.
• For schema definitions, load spacetimedb-tables.
• For reducer transaction behavior, load spacetimedb-reducers.