Data Model¶

The map of the Starbase Postgres schema. This page holds no DDL — every table lives on the page that owns its concern (the RBAC-page pattern); this is the entity graph and the index. All IDs are UUIDs (§20.2 encodes them into HTTPRoute names). (Design record: specs/2026-07-11-database-schema-design.md.)

The entity graph¶

erDiagram
  workspaces ||--o{ projects : ""
  projects ||--o{ environments : ""
  projects ||--o{ services : "definitions"
  services ||--o{ service_environments : "instantiation"
  environments ||--o{ service_environments : ""
  environments ||--o{ databases : ""
  service_environments ||--o{ deployments : ""
  builds ||--o{ deployments : "released as"
  services ||--o{ builds : ""
  clusters ||--o{ service_environments : "placement"
  regions ||--o{ clusters : ""

Where every table lives¶

Tables	Home
`users` · `workspaces` · `workspace_members` · `projects` · `project_members` · `environments`	RBAC §15.7
`services` · `service_environments`	Services & Environments
`databases`	Managed Databases
`sessions` · `sso_identities`	Auth & Sessions
`var_groups` · `var_group_entries` · `service_var_groups`	Var Groups §38.2
`builds` · `deployments`	Starforge › Build Lifecycle
`github_installations` · `webhook_deliveries`	Starforge › Git & Webhooks
`billing_snapshots` · `usage_totals` · `usage_events`	Billing
`jobs`	Worker Binary
`regions`	Region Onboarding
`clusters` · `cluster_tokens`	Region Onboarding

Cross-cutting design notes¶

Soft deletes are the tombstone protocol (§25.1/§25.4): a deleted placed entity keeps its row (deleted_at set) and keeps appearing in payloads as deleted: true until Shuttle confirms (deletion_confirmed_at); hard cleanup follows confirmation (+ the 7-day offline-cluster backstop).
Desired state is never stored — it is computed query-and-serialize per §32; the only persisted piece is the per-cluster desired_state_sequence (clusters table).
Not in the schema: buckets (post-MVP, §39.3 #16) · Mass Relay / ClickHouse-audit tables (post-MVP, §39.3 #43/#71).

Cross-references

The payload these tables serialize into → §25.1 / §32 · the REST surface over them → Dashboard API · tenant key → §24.1. Canonical map: Canonical Sources.