Schema Overview

PostgreSQL schema reference for the Crawbl orchestrator. All tables live in the orchestrator schema, set via search_path on the database connection.

Entity Hierarchy

users
 +-- user_preferences    (1:1, CASCADE delete)
 +-- user_push_tokens    (1:1, CASCADE delete)
 +-- workspaces          (1:N, CASCADE delete)
      +-- agents         (1:N, CASCADE delete)
      +-- conversations  (1:N, CASCADE delete)
           +-- messages  (1:N, CASCADE delete)

Entity Relationship Diagram

Click diagram to zoom

Tables

Table	Rows per parent	Delete behavior	Description
users	—	Soft delete (deleted_at)	User accounts
user_preferences	1 per user	CASCADE	Theme, language, currency
user_push_tokens	1 per user	CASCADE	FCM push token
workspaces	N per user	CASCADE	Isolated work environments
agents	N per workspace	CASCADE	AI agents within a workspace
conversations	N per workspace	CASCADE	Chat threads (swarm or agent)
messages	N per conversation	CASCADE	Individual messages

Conventions

Convention	Detail
Primary keys	UUIDs generated in Go, not database-generated
Timestamps	All tables have created_at and updated_at (TIMESTAMPTZ)
Soft deletes	deleted_at column (only users currently)
Foreign keys	ON DELETE CASCADE by default
Agent references	ON DELETE SET NULL (conversations and messages keep the row when an agent is removed)
Schema	orchestrator, set via search_path on the connection