15 - Migration and Model Conventions

Dokumen ini menjelaskan standar migration dan model untuk central/tenant context.

Migration Placement Rules

Central Migration

Taruh di database/migrations/central jika:

data global platform

auth identity global

tenant registry/metadata global

billing source-of-truth global

audit/security global

Tenant Migration

Taruh di database/migrations/tenant jika:

data operasional tenant

data master lokal tenant

role/permission tenant-scoped

audit tenant-scoped

Tenant Migration (PostgreSQL + RLS) Rules

Untuk migration tenant di proyek ini, pattern default adalah PostgreSQL + RLS.

Wajib untuk tabel tenant-scoped

Gunakan trait:

use InteractsWithPostgresRls;

Simpan kolom tenant context:

tenant_id (UUID, indexed).

Aktifkan RLS:

$this->enableRls('<table>');

Buat minimal satu isolation policy tenant:

tenant_isolation_policy atau policy setara.

Pada down(), drop policy sebelum drop table.

Sangat direkomendasikan

Tambah partial index untuk query path aktif (misal is_active = true).

Tambah policy tambahan sesuai business role (misal owner visibility).

Gunakan helper trait untuk expression SQL agar konsisten:

tenantIsolationUsing()

partialIndex()

createPolicy()

Referensi implementasi aktual

database/migrations/tenant/2026_02_14_032023_create_tenant_user_table.php

database/migrations/tenant/2026_02_25_000039_create_taxonomies_table.php

app/Support/Database/Concerns/InteractsWithPostgresRls.php

Naming Conventions

file: {timestamp}_create_{table}_table.php

alter: {timestamp}_add_{column}_to_{table}_table.php

gunakan nama singular/plural konsisten dengan existing schema

Migration Template Guidelines

Checklist kolom:

primary key UUID/ULID sesuai standar proyek

timestamps

softDeletes jika perlu

index untuk query frequent path

foreign key eksplisit jika relasi intra-context

Untuk tenant table:

jika model akan diakses via tenant context + trait, jangan hardcode koneksi di migration logic selain kebutuhan khusus.

wajib follow helper/project convention untuk RLS:

enableRls()

createPolicy()

dropPolicy()

tenantIsolationUsing()

partialIndex()

Model Placement Rules

central model: app/Models/Central/{Domain}/*

tenant model: app/Models/Tenant/{Domain}/*

user/auth model global: app/Models/User/*

Tenant Model Rule

Gunakan HasTenantClusterConnection bila model:

harus resolve koneksi cluster tenant otomatis berdasarkan TenantContext.

Contoh use case:

tenant master data

tenant identity mirror

tenant RBAC

Cross-Context Rules

central controller/service tidak boleh query model tenant tanpa boundary resolver/context yang benar.

tenant runtime tidak boleh bergantung langsung pada mutable central domain data tanpa kontrak yang jelas.

Seeder and Migration Order

Gunakan command orchestration proyek:

Urutan inti:

migration central

seed cluster registry minimal

migration tenant clusters

seed data central

Anti-Patterns

menaruh migration tenant di folder central karena cepat.

menaruh model tenant di namespace central.

membuat logic tenant connection resolve manual berulang di banyak service.

merubah payload API tanpa update docs dan FE contract.

membuat table tenant tanpa tenant_id + policy RLS.

membuat index hanya index biasa untuk query aktif padahal butuh partial index.

15 - Migration and Model Conventions

Migration Placement Rules#

Central Migration#

Tenant Migration#

Tenant Migration (PostgreSQL + RLS) Rules#

Wajib untuk tabel tenant-scoped#

Sangat direkomendasikan#

Referensi implementasi aktual#

Naming Conventions#

Migration Template Guidelines#

Model Placement Rules#

Tenant Model Rule#

Cross-Context Rules#

Seeder and Migration Order#

Anti-Patterns#