Migrations

Database migrations for the orchestrator schema.

Current Migration Files

migrations/orchestrator/
  000001_create_all.up.sql          — users, user_preferences, user_push_tokens, workspaces
  000002_create_chat_tables.up.sql  — agents, conversations, messages

Running Migrations

Local (Docker Compose)

./crawbl dev start                  # Start the full local stack (also runs migrations)
./crawbl dev start --database-only  # Start only Postgres + run migrations
./crawbl dev migrate                # Run migrations only

Direct (Repo-Local Binary)

./crawbl platform orchestrator migrate

Against Remote Database

kubectl port-forward -n backend svc/backend-postgresql 5432:5432
# In another terminal:
./crawbl platform orchestrator migrate

Creating a New Migration

1

Step 1

Create the file

Add the next sequence number under migrations/orchestrator/.

touch migrations/orchestrator/000003_<description>.up.sql

2

Step 2

Write idempotent SQL

Use IF NOT EXISTS and IF EXISTS where the database allows it.

3

Step 3

Test locally

Run the stack from scratch, then run the unit tests.

./crawbl dev start --clean  # Runs all migrations from scratch
./crawbl test unit          # Verify nothing breaks

Conventions

Convention	Detail
Naming	NNNNNN_<description>.up.sql (zero-padded 6-digit sequence)
Direction	Up-only migrations (no .down.sql files)
Schema	All DDL targets the orchestrator schema
Idempotency	Use IF NOT EXISTS / IF EXISTS guards
IDs	UUIDs generated in application code, not DEFAULT gen_random_uuid()
Timestamps	Always TIMESTAMPTZ, never TIMESTAMP