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](references/tables.md) |
| Access control | [references/tables-access-permissions.md](references/tables-access-permissions.md) |
| IDs and defaults | [references/tables-auto-increment.md](references/tables-auto-increment.md), [references/tables-default-values.md](references/tables-default-values.md) |
| Types and constraints | [references/tables-column-types.md](references/tables-column-types.md), [references/tables-constraints.md](references/tables-constraints.md) |
| Index design | [references/tables-indexes.md](references/tables-indexes.md) |
| Event and schedule tables | [references/tables-event-tables.md](references/tables-event-tables.md), [references/tables-schedule-tables.md](references/tables-schedule-tables.md) |
| Storage and performance | [references/tables-file-storage.md](references/tables-file-storage.md), [references/tables-performance.md](references/tables-performance.md) |
## 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.