# Spacetimedb Tables

> 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.

- Skill: `danmossa/spacetimedb-tables` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add danmossa/spacetimedb-tables`
- Raw SKILL.md: https://api.skillmd.com/api/skills/danmossa/spacetimedb-tables/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: danmossa (https://skillmd.com/u/danmossa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/danmossa/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:

```typescript
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.