Copy page

Self-Hosting

Database Migrations

Database Migrations

OmniStream memakai sqlx::migrate! untuk menerapkan migrasi PostgreSQL secara otomatis saat service pertama kali start. Tidak ada perintah migrasi manual; cukup letakkan file SQL baru di folder migrations/, build ulang image, dan restart service — migrasi akan berjalan urut sesuai urutan nama file.

Cara kerja

Migrator di-embed ke binary saat build (sqlx::migrate! adalah macro yang membaca folder saat compile-time). Saat api-gateway — dan service lain yang memakai omni_common::db::postgres::create_pg_pool — start, ia:

1. Membuat tabel _sqlx_migrations jika belum ada.
2. Membaca semua file .sql di migrations/ (yang sudah di-embed).
3. Menjalankan hanya file yang belum ter-record di _sqlx_migrations.
4. Mencatat versi + checksum di _sqlx_migrations untuk mencegah eksekusi ulang.

Konvensi penamaan file

YYYYMMDDHHMMSS_nama_deskriptif.sql — timestamp di depan menentukan urutan eksekusi.

Contoh dari repo:

Code
20260218000001_initial_schema.sql
20260219000002_quick_replies_and_notes.sql
20260220000003_add_email_and_expired_status.sql
...
20260403000040_add_messenger_channel.sql

Daftar migrasi v1

Sebanyak 41 file migrasi di folder migrations/. Daftar pengelompokan kasar:

Blok	File	Isi
Skema awal	20260218000001_initial_schema.sql	agents, contacts, conversations, messages legacy
Quick replies + catatan	20260219000002_quick_replies_and_notes.sql	tabel quick_replies + conversation_notes
Email channel	20260220000003, 20260220000004	status expired + tabel email
Campaign	20260221000005, 20260226000010, 20260227000011	campaigns + recipients + scheduler
Integrations	20260222000006	tabel integrations dengan config JSONB
WA Templates	20260223000007	header media URL
Activity logs	20260224000008	activity_logs + indeks
Divisions + manajemen	20260225000009	divisions, agent_divisions, can_broadcast
Routing + tag	20260228000012, 20260301000013	conversation_tags, routing
Reply v2	20260302000014	canned responses v2
Preview + metrik	20260303000015, 20260304000016, 20260305000017	last_message_preview, metrik waktu, last_seen
Transfer	20260306000018	conversation_transfers
Scheduled	20260306000019	scheduled_messages
CSAT	20260306000020	csat_surveys
SLA	20260306000021	sla_policies, sla_breach_logs
Outgoing webhooks	20260306000022	outgoing_webhooks, webhook_deliveries
Automation	20260307000023 ... 20260307000029, 20260307000031	rules + alert + snooze + schedule + rollout
Integration accounts	20260307000030	akun integrasi multi
WA Flows	20260307000032, 20260307000033, 20260307000034	flows + campaign flow support + encryption
Chat expiration	20260308000032	chat_expiration_rules
Campaign integration	20260308000033, 20260309000035, 20260309000036	integration account ref + conversation ref + window expires_at
Crypto	20260309000037	enable pgcrypto (UUID + gen_random_uuid)
Status simplify	20260326000039_simplify_conversation_statuses.sql	disederhanakan ke open/resolved
Messenger channel	20260403000040_add_messenger_channel.sql	dukungan channel Messenger

Jumlah persisnya bisa anda verifikasi dengan ls migrations/ | wc -l.

Menambahkan migrasi baru

1. Buat file migrations/YYYYMMDDHHMMSS_deskripsi.sql dengan timestamp lebih besar dari semua file yang sudah ada.
2. Tulis SQL DDL/DML yang idempotent bila memungkinkan (IF NOT EXISTS).
3. Rebuild image yang memakai sqlx::migrate! — biasanya api-gateway — supaya macro meng-embed file baru: docker compose build api-gateway.
4. Restart container: docker compose up -d api-gateway.
5. Log akan menampilkan applied migration <version> untuk tiap file.

Debug migrasi gagal

Kalau service crash saat start dengan error migrasi:

• Baca log api-gateway — error menyebutkan versi migrasi problematis.

• Cek tabel _sqlx_migrations di DB untuk melihat versi terakhir yang sukses diterapkan:

  Code
  SELECT version, description, success, execution_time FROM _sqlx_migrations ORDER BY version;

• Untuk dev lokal, reset cepat: docker compose down -v lalu up -d (menghancurkan data — jangan di produksi).