Skip to main content

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​

ConventionDetail
NamingNNNNNN_<description>.up.sql (zero-padded 6-digit sequence)
DirectionUp-only migrations (no .down.sql files)
SchemaAll DDL targets the orchestrator schema
IdempotencyUse IF NOT EXISTS / IF EXISTS guards
IDsUUIDs generated in application code, not DEFAULT gen_random_uuid()
TimestampsAlways TIMESTAMPTZ, never TIMESTAMP