spacetimedb-tables

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

Guidance

• Check migration implications in [spacetimedb-databases](../spacetimedb-databases/SKILL.md) 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.