Elixir untuk Technical Leader — Bab 4 dari 10

Ecto — The Database Layer

Ecto bukan ORM. Ecto itu toolkit — 4 alat terpisah yang masing-masing punya tugas jelas. Ini fondasi semua data di LabaBersih.

Ecto Bukan ORM — Ini Penting

Kalau kamu pernah dengar istilah ORM (Object-Relational Mapping), lupakan sebentar. ORM tradisional seperti ActiveRecord (Ruby) atau Prisma (JavaScript) punya filosofi: "sembunyikan database, anggap aja semua object."

Ecto kebalikannya: "database itu penting, kamu harus tau apa yang terjadi."

Ecto terdiri dari 4 komponen terpisah yang bisa dipakai sendiri-sendiri:

Perbandingan: Ecto vs Prisma vs Raw SQL

Schema — Blueprint Data

Schema = cara bilang ke Ecto: "tabel orders punya field apa aja, tipenya apa, dan relasinya ke tabel mana."

Ini schema Order yang benar-benar dipakai di LabaBersih v2:

defmodule Lababersih.Orders.Order do
  use Ecto.Schema
  import Ecto.Changeset

  # Primary key = string ("PS2603-00001"), bukan auto-increment angka
  @primary_key {:id, :string, autogenerate: false}

  schema "orders" do          # ← nama tabel di PostgreSQL
    field :nomor_pesanan, :string
    field :customer_name, :string
    field :customer_phone, :string
    field :platform, :string        # "tiktok", "shopee", "mengantar"
    field :order_status, :string, default: "dibuat"
    field :fulfillment_status, :string, default: "pending"
    field :payment_status, :string, default: "unpaid"
    field :total_harga, :decimal   # ← Decimal, BUKAN float!
    field :shipped_at, :utc_datetime
    field :no_resi, :string

    # Relasi: order milik 1 organization
    belongs_to :organization, Lababersih.Accounts.Organization, foreign_key: :org_id
    belongs_to :store, Lababersih.Sales.Store
    belongs_to :customer, Lababersih.Customers.Customer

    # Relasi: 1 order punya banyak items
    has_many :items, Lababersih.Orders.OrderItem

    timestamps(type: :utc_datetime)  # auto: inserted_at, updated_at
  end
end

Field Types yang Paling Sering Muncul

belongs_to vs has_many

# 1 Order milik 1 Store (FK ada di tabel orders)
# Order →→ Store
belongs_to :store, Lababersih.Sales.Store

# 1 Order punya banyak Items (FK ada di tabel order_items)
# Order ←← Items
has_many :items, Lababersih.Orders.OrderItem

# Cara ingat:
# belongs_to = aku punya kolom xxx_id yang nunjuk ke tabel lain
# has_many   = tabel lain punya kolom yang nunjuk ke aku

Changeset — Bouncer Data

Changeset = pipeline validasi yang data WAJIB lewati sebelum boleh masuk database. Bayangkan bouncer di pintu club — cek KTP, cek umur, cek dresscode. Kalau ada yang gak lolos, TOLAK, gak ada negosiasi.

def changeset(order, attrs) do
  order
  |> cast(attrs, [:nomor_pesanan, :customer_name, :platform,
                   :total_harga, :org_id, :store_id])
  |> validate_required([:customer_name, :platform, :org_id])
  |> validate_inclusion(:platform, ["tiktok", "shopee", "mengantar", "pos"])
  |> validate_inclusion(:order_status, @order_statuses)
  |> foreign_key_constraint(:org_id)
end

Baca dari atas ke bawah — ini pipeline (pakai |> pipe dari Bab 3):

Changeset Return Error, Bukan Throw

# Changeset gak pernah crash/throw. Dia simpan error di struct:
changeset = Order.changeset(%Order{}, %{platform: "lazada"})

changeset.valid?   # false
changeset.errors   # [
                   #   customer_name: {"can't be blank", [validation: :required]},
                   #   platform: {"is invalid", [validation: :inclusion]}
                   # ]

# Kalau kamu coba insert changeset yang invalid:
Repo.insert(changeset)
# => {:error, changeset}  ← database GAK disentuh

# Kalau valid:
Repo.insert(changeset)
# => {:ok, %Order{id: "PS2603-00001", ...}}  ← masuk database

Migrations — Ubah Struktur Database

Migration = cara aman mengubah struktur database (tambah kolom, buat tabel baru, hapus field). Setiap perubahan di-record sebagai file, jadi bisa di-track di Git dan di-rollback kalau salah.

# File: priv/repo/migrations/20260330_create_orders.exs

defmodule Lababersih.Repo.Migrations.CreateOrders do
  use Ecto.Migration

  def change do
    create table(:orders, primary_key: false) do
      add :id, :string, primary_key: true        # PS2603-00001
      add :org_id, references(:organizations, type: :binary_id), null: false
      add :nomor_pesanan, :string
      add :customer_name, :string, null: false
      add :platform, :string, null: false
      add :order_status, :string, default: "dibuat"
      add :total_harga, :decimal, default: 0

      timestamps(type: :utc_datetime)
    end

    create index(:orders, [:org_id])                 # index untuk filter by org
    create index(:orders, [:org_id, :order_status])  # index untuk filter status
  end
end

Command yang Kamu Perlu Tau

# Jalankan semua migration yang belum dijalankan
$ mix ecto.migrate

# Undo migration terakhir (kalau salah)
$ mix ecto.rollback

# Lihat status migration mana yang sudah/belum dijalankan
$ mix ecto.migrations

# HATI-HATI: hapus database + buat ulang + migrate dari awal
$ mix ecto.reset    # JANGAN di production!

LabaBersih v2 sekarang punya 36 migration files. Setiap kali kamu tambah fitur yang butuh perubahan database, file baru ditambahkan di akhir.

Repo — Pintu Masuk Database

Repo = satu-satunya cara bicara ke database. Semua operasi lewat sini. Gak ada jalan pintas.

Operasi Dasar

# ── BACA (Read) ────────────────────────────────

# Ambil 1 record by ID (raise error kalau gak ada)
order = Repo.get!(Order, "PS2603-00001")

# Ambil 1 record by ID (return nil kalau gak ada)
order = Repo.get(Order, "PS2603-00001")

# Ambil semua record
orders = Repo.all(Order)

# Ambil 1 berdasarkan kondisi
order = Repo.get_by(Order, nomor_pesanan: "TK-583220220389")


# ── TULIS (Write) ───────────────────────────────

# Insert record baru
{:ok, order} = %Order{}
               |> Order.changeset(attrs)   # validasi dulu
               |> Repo.insert()            # baru masuk DB

# Update record yang sudah ada
{:ok, order} = order
               |> Order.changeset(%{order_status: "diproses"})
               |> Repo.update()

# Hapus record
{:ok, _} = Repo.delete(order)


# ── HITUNG ──────────────────────────────────────

# Hitung jumlah record
count = Repo.aggregate(Order, :count)

Repo.transaction — All or Nothing

Ini yang paling KRITIS untuk LabaBersih. Repo.transaction menjamin: kalau 1 langkah gagal, SEMUA langkah batal. Gak ada keadaan setengah-setengah.

Contoh Nyata: ship_order (5 Langkah Atomic)

Saat Nelly scan barcode untuk kirim pesanan, 5 hal harus terjadi bersamaan:

def ship_order(order_id, actor_email) do
  Repo.transaction(fn ->
    # Ambil order + items dari database
    order = Order
            |> Repo.get!(order_id)
            |> Repo.preload(:items)

    # Validasi: hanya order yang belum shipped yang boleh di-ship
    unless order.fulfillment_status in ~w(pending ready_to_ship picking packed) do
      Repo.rollback({:invalid_status, order.fulfillment_status})
    end

    # Step 1: Update status → shipped
    {:ok, order} = order |> Order.changeset(%{
      order_status: "diproses",
      fulfillment_status: "shipped",
      shipped_at: DateTime.utc_now()
    }) |> Repo.update()

    # Step 2: Potong stok per item (FEFO lot consumption)
    {hpp_total, _} = consume_stock(order)

    # Step 3: Generate jurnal penjualan
    generate_sale_journal(order, hpp_total)

    # Step 4: Generate jurnal HPP
    generate_hpp_journal(order, hpp_total)

    # Step 5: Audit trail
    create_audit_trail(order, actor_email, "shipped")

    order
  end)
end

Apa yang terjadi kalau Step 3 gagal?

Repo.rollback — Batal dengan Alasan

# Di dalam transaction, kalau ada yang salah:
Repo.rollback(:already_shipped)                         # alasan: atom
Repo.rollback({:invalid_status, "selesai"})              # alasan: tuple
Repo.rollback({:insufficient_stock, "Forbest", 3, 5})  # detail: punya 3, butuh 5

# Di luar transaction, caller handle:
case Orders.ship_order(id, email) do
  {:ok, order} ->
    # sukses, lanjut
  {:error, :already_shipped} ->
    # "Order sudah dikirim sebelumnya"
  {:error, {:insufficient_stock, product, has, need}} ->
    # "Stok Forbest tidak cukup (ada: 3, butuh: 5)"
end

Ecto.Query — Bangun Query dengan Pipe

Ecto.Query memungkinkan kamu bangun database query menggunakan Elixir syntax. Kamu gak perlu tulis SQL mentah — tapi Ecto juga BUKAN hide SQL. Setiap Ecto query bisa diterjemahkan 1:1 ke SQL.

Query Sederhana

import Ecto.Query

# Ambil semua order yang status "dikirim"
query = from o in Order,
  where: o.order_status == "diproses",
  where: o.fulfillment_status == "shipped",
  order_by: [desc: o.shipped_at]

orders = Repo.all(query)

# SQL equivalent:
# SELECT * FROM orders
# WHERE order_status = 'diproses' AND fulfillment_status = 'shipped'
# ORDER BY shipped_at DESC

Query Building dengan Pipe (Composable)

Ini kekuatan Ecto — query bisa dibangun step by step dan di-compose pakai pipe:

# Dari code ASLI LabaBersih: Orders.list_orders/2

def list_orders(org_id, opts \\ []) do
  # Mulai dengan query dasar (SELALU filter org_id!)
  query = from o in Order,
    where: o.org_id == ^org_id,
    order_by: [desc: o.inserted_at]

  # Tambah filter status (kalau user pilih tab filter)
  query = case Keyword.get(opts, :status) do
    nil    -> query                                        # gak filter
    status -> from o in query, where: o.order_status == ^status  # tambah WHERE
  end

  # Tambah filter platform (kalau user pilih dropdown)
  query = case Keyword.get(opts, :platform) do
    nil      -> query
    platform -> from o in query, where: o.platform == ^platform
  end

  # Tambah search (kalau user ketik di search bar)
  query = case Keyword.get(opts, :q) do
    nil -> query
    q   -> from o in query,
             where: ilike(o.nomor_pesanan, ^"%#{q}%")
               or ilike(o.customer_name, ^"%#{q}%")
  end

  # Eksekusi query final
  Repo.all(query) |> Repo.preload(:items)
end

Tanda ^ (Pin Operator) di Query

# ^ artinya: "pakai NILAI dari variable ini, bukan sebagai kolom database"

org_id = "abc-123"
status = "diproses"

from o in Order,
  where: o.org_id == ^org_id,       # ^org_id = "abc-123" (value)
  where: o.order_status == ^status   # ^status = "diproses" (value)

# Tanpa ^: Ecto kira org_id adalah nama kolom, bukan variable Elixir

Preloading — Hindari N+1 Query

Ini masalah klasik database yang Ecto handle secara eksplisit.

Masalah N+1 Query

# 1 query ambil 100 orders
orders = Repo.all(Order)

# 100 query ambil items per order!
Enum.each(orders, fn order ->
  items = order.items  # ← QUERY ke DB tiap loop
end)

# Total: 101 queries! Lambat!

# 1 query ambil orders
# 1 query ambil SEMUA items sekaligus
orders = Repo.all(Order)
         |> Repo.preload(:items)

# Total: 2 queries! Cepat!
# Ecto auto-match items ke order-nya

# Preload bisa nested:
order = Repo.get!(Order, id)
        |> Repo.preload(items: :product)
# 3 query: orders + order_items + products
# Tanpa preload: 1 + N + N*M queries

# Preload di query langsung:
orders = from(o in Order,
  where: o.org_id == ^org_id,
  preload: [:items, :store]
) |> Repo.all()

Advisory Lock — Anti Race Condition

Ini fitur KRITIS untuk LabaBersih. Order ID kita format PS2603-00001, bukan UUID random. Artinya ada sequential number yang harus unik. Masalah: kalau 2 orang import XLSX bersamaan, bisa generate ID yang sama.

Masalah Race Condition

# User A dan User B import XLSX bersamaan:
#
# Waktu    User A                    User B
# 00:01    Baca max ID → 00042       Baca max ID → 00042
# 00:02    Generate → 00043          Generate → 00043  ← DUPLIKAT!
# 00:03    Insert PS2603-00043       Insert PS2603-00043  ← ERROR!

Solusi: Advisory Lock

# Dari code ASLI LabaBersih: Orders.create_order/2

def create_order(attrs, items_attrs) do
  Repo.transaction(fn ->
    org_id = Map.get(attrs, :org_id)

    # Advisory lock: "kunci" ID generation untuk org ini
    # Request lain ANTRI sampai lock dilepas
    lock_key = :erlang.phash2({org_id, "order"})
    Repo.query!("SELECT pg_advisory_xact_lock($1)", [lock_key])

    # Sekarang AMAN: gak ada request lain yang bisa generate ID bersamaan
    order_id = generate_order_id(org_id)    # PS2603-00043

    # Insert order + items...
  end)
  # Lock otomatis dilepas saat transaction selesai
end

LabaBersih pakai advisory lock di setiap ID generation:

Decimal — Uang WAJIB Decimal, BUKAN Float

Ini bukan soal Ecto aja — ini prinsip fundamental semua software keuangan. Jangan pernah pakai float untuk uang.

Kenapa Float Bahaya untuk Uang

# Float di komputer = APPROXIMASI, bukan exact

# JavaScript (v1 pakai ini):
# 0.1 + 0.2 = 0.30000000000000004  ← BUKAN 0.3!

# Elixir float (JANGAN pakai untuk uang):
0.1 + 0.2   # => 0.30000000000000004

# Elixir Decimal (SELALU pakai untuk uang):
Decimal.add("0.1", "0.2")   # => #Decimal<0.3>  ← exact!

Impact di Skala LabaBersih

# 6.300 order/hari × 30 hari = 189.000 order/bulan
# Kalau setiap order ada selisih Rp 0.0001 karena float rounding...
# 189.000 × Rp 0.0001 = ??? (unpredictable!)
#
# Bisa kecil, bisa juga akumulasi jadi Rp ribuan per bulan.
# Trial balance gak balance. Auditor bingung.
#
# Dengan Decimal: selisih = SELALU Rp 0. Exact.

Cara Pakai Decimal di Elixir

# Buat Decimal dari string (AMAN):
price = Decimal.new("200000")

# Operasi matematika:
Decimal.add(price, "50000")      # 250.000
Decimal.sub(price, "16000")      # 184.000
Decimal.mult(price, "0.03")      # 6.000 (fee 3%)
Decimal.div(price, "3")          # 66666.666...

# Perbandingan (JANGAN pakai == untuk Decimal):
Decimal.compare(a, b) == :eq     # equal
Decimal.compare(a, b) == :gt     # a > b
Decimal.gt?(a, b)                 # shortcut: a > b?

# Di LabaBersih, jurnal WAJIB balanced:
total_debit = Decimal.add(piutang, fee_admin)
total_credit = pendapatan
unless Decimal.equal?(total_debit, total_credit) do
  Repo.rollback(:debit_credit_not_balanced)
end

Semuanya Terhubung — Flow Lengkap

Sekarang kamu udah tau 4 komponen Ecto. Ini gimana mereka bekerja sama saat Nelly create order:

# FLOW: User klik "Buat Pesanan" di browser
# ────────────────────────────────────────────

# 1. SCHEMA — define struktur Order
#    (sudah ada, gak dijalankan tiap request)

# 2. CHANGESET — validasi data dari form
changeset = %Order{} |> Order.changeset(%{
  customer_name: "Budi Santoso",
  platform: "tiktok",
  total_harga: "200000",          # string → Decimal otomatis
  org_id: current_org_id
})
# Kalau invalid → return error ke browser, DATABASE GAK DISENTUH

# 3. REPO + TRANSACTION — masukkan ke database (atomic)
Repo.transaction(fn ->
  # Advisory lock → generate unique ID
  Repo.query!("SELECT pg_advisory_xact_lock($1)", [lock_key])
  order_id = "PS2603-00043"

  # Insert order
  {:ok, order} = changeset |> Repo.insert()

  # Insert items (1 QUERY untuk semua items, bukan 1 per item)
  Repo.insert_all(OrderItem, items_data)

  order
end)

# 4. QUERY — Nanti saat tampilkan di list:
orders = from(o in Order,
  where: o.org_id == ^org_id,
  preload: [:items, :store]
) |> Repo.all()

Checklist Review — Pertanyaan Kamu Bisa Tanya

Red Flags — Bahaya yang Harus Kamu Kenali

Ringkasan Bab 4