Migrations

Yoke runs SQL migrations automatically on yoke dev, yoke start, and control-plane boot.

Migration files

File	Purpose
`001_initial.sql`	Core tables: `stream_events`, `actor_instances`, `portal_instances`, `actor_queues`
`002_actor_sqlite.sql`	`actor_sqlite` BYTEA storage for per-instance SQLite
`003_queue_retries_dead_letters.sql`	Retry counts, `dead_letters` table
`004_worker_scaling.sql`	`runtime_workers` registry, heartbeats
`005_multi_tenant.sql`	`tenants`, `tenant_runtimes`, lease columns
`006_tenant_scoped.sql`	`tenant_id` on stream, instances, queues
`007_notify_rls_scheduler_events.sql`	Scheduler notifications
`008_fanout_idempotency.sql`	`fanout_delivered`, `runtime_metadata` cursor
`009_conversations.sql`	Conversation store: actors, conversations, participants, messages
`010_message_schema.sql`	`message_relations`, `blobs`, `branches`
`011_scheduled_events.sql`	Keyed schedules table
`012_actor_sqlite_stores.sql`	`store_id` column for sqliteStoreId segments
`013_queue_priority_groups.sql`	`priority`, `group_id` on `actor_queues`

Core runtime tables

stream_events           — global append-only log
tenant_stream_counters  — per-tenant seq allocator
actor_instances         — instance registry
portal_instances        — portal singletons
actor_queues            — per-instance work queues
dead_letters            — exhausted retries
actor_sqlite            — serialized SQLite (BYTEA)
fanout_delivered        — fan-out idempotency
runtime_workers         — horizontal scaling
runtime_metadata        — fan-out cursor
scheduled_events        — keyed delayed appends

Conversation tables

actors
conversations
participants
messages
message_relations
blobs
branches

All scoped by tenant_id.

Multi-tenant tables

tenants
tenant_runtimes         — lease_holder, lease_expires_at, last_activity

Applying migrations

Automatic on boot:

yoke dev ./your-package --database "$DATABASE_URL" --storage pg_sqlite

Manual migration command:

yoke migrate --database "$DATABASE_URL"

Inspect applied schema:

psql "$DATABASE_URL" -c "\dt"

Schema versioning

Migrations are sequential and idempotent where possible. The runtime tracks applied migrations in Postgres — do not modify applied migration files in production; add new numbered files.

Backup guidance

Deployment	Backup
`pg_sqlite`	Postgres dump includes actor SQLite BYTEA
`s3`	Postgres dump + S3 bucket replication
Multi-tenant	Single Postgres cluster backup; tenant isolation is row-level

Storage

actor_sqlite BYTEA detail.

Data model

Conversation schema.

Storage

Data model

On this page