spacetimedb-tables

name	spacetimedb-tables
description	Use when defining or changing SpacetimeDB tables, columns, constraints, primary keys, unique constraints, indexes, auto-increment fields, default values, event tables, schedule tables, access permissions, file storage, or table performance. Triggers on: table, column, primary key, unique, index, btree, direct index, event table, schedule table.
license	MIT

Use this skill for module schema and table performance.

Core table patterns

TypeScript tables use table(options, columns) and must be passed to schema() as an object:

import { schema, table, t } from "spacetimedb/server";

const player = table(
  { name: "player", public: true },
  {
    id: t.u64().primaryKey().autoInc(),
    identity: t.identity().unique(),
    name: t.string().index("btree"),
  },
);

export default schema({ player });

Language-specific table declarations:

• TypeScript: { name: "player_score" } creates ctx.db.playerScore.
• C#: [SpacetimeDB.Table(Accessor = "Player", Public = true)] creates ctx.Db.Player; the type must be partial.
• Rust: #[spacetimedb::table(accessor = player, public)] creates ctx.db.player(); pub struct does not make a table public.
• C++: SPACETIMEDB_TABLE(Type, player, Public) creates ctx.db[player].

Design rules

• Organize data by access/update pattern. Split hot, frequently updated state from rarely changed profile, settings, or stats fields.
• Public tables are visible to clients through subscriptions. Keep server-only state private and expose derived subsets through views when needed.
• Primary keys and unique constraints automatically create indexes; do not add duplicate indexes for them.
• Add indexes only for frequent equality, range, subscription, or join paths. Use B-tree by default; direct indexes are for dense unsigned integer keys and are not universally supported in every language.
• New columns in existing published tables need defaults and must be appended at the end. Check database migration rules before changing existing schemas.
• Auto-increment values are generated by the database and can have gaps after failed transactions.
• Use event tables for append-only client notifications; the event flag cannot be changed after publish.
• Schedule tables need a ScheduleAt column and a linked scheduled reducer. In TypeScript, import ScheduleAt from spacetimedb, not spacetimedb/server.

Reference map

Need	Open
Table definitions and core patterns	references/tables.md
Access control	references/tables-access-permissions.md
IDs and defaults	references/tables-auto-increment.md, references/tables-default-values.md
Types and constraints	references/tables-column-types.md, references/tables-constraints.md
Index design	references/tables-indexes.md
Event and schedule tables	references/tables-event-tables.md, references/tables-schedule-tables.md
Storage and performance	references/tables-file-storage.md, references/tables-performance.md

Guidance

• Check migration implications in spacetimedb-databases before changing existing schemas.
• Favor indexed lookups for reducer paths that run often or touch large tables.
• Use event tables for append-only client notifications, especially when replacing reducer result callback patterns.