📘 Modul 04: Model & Eloquent ORM
Pakem menghadirkan Human ORM murni bergaya Laravel Eloquent di atas Rust. Menggabungkan kemudahan sintaks Active Record dengan kecepatan zero-cost abstraction dan type-safety Rust.
1. Membuat Model & Migrasi (canting make:model)
canting make:model ProductPerintah ini akan secara otomatis:
Membuat file model di
src/app/models/product.rs.Membuat file migrasi SQL baru di
database/migrations/<timestamp>_create_products_table.sql.Mendaftarkan modul ke
src/app/models/mod.rs.
2. Menjalankan Migrasi Database
Pakem memiliki migration runner otomatis yang mendukung SQLite, PostgreSQL, MySQL, dan Microsoft SQL Server (MSSQL):
# Menjalankan seluruh migrasi yang tertunda
canting migrate
# Memeriksa status migrasi yang telah diterapkan
canting migrate:status
# Membatalkan (rollback) migrasi terakhir
canting migrate:rollbackContoh file migrasi SQL (database/migrations/20261025_create_products_table.sql):
CREATE TABLE IF NOT EXISTS products (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name VARCHAR(255) NOT NULL,
price REAL NOT NULL,
stock INTEGER NOT NULL DEFAULT 0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);3. Definisi Model dengan Makro PakemModel
Model di Pakem didefinisikan menggunakan derive macro #[derive(PakemModel)] yang sangat bersih dan ekspresif:
use pakem::prelude::*;
#[derive(Debug, Serialize, Deserialize, FromRow, Clone, Default, PakemModel)]
#[table("products")]
pub struct Product {
pub id: i64,
pub name: String,
pub price: f64,
pub stock: i32,
pub created_at: Option<String>,
pub updated_at: Option<String>,
pub deleted_at: Option<String>, // ✨ Otomatis mengaktifkan Smart Soft Deletes!
}NOTE
Semua entitas model di Pakem menggunakan atribut deklaratif #[table("nama_tabel")]. Cukup dengan menyertakan field deleted_at: Option<String>, model otomatis mendukung fitur Smart Soft Deletes tanpa perlu konfigurasi tambahan.
4. Operasi CRUD Modern & Bersih (Unified Request)
Seluruh controller di Pakem menggunakan satu parameter tunggal req: Request (Unified Request Bundle). Akses database dilakukan secara natural melalui req.db() tanpa extractor mentah Axum dan tanpa tanda ampersand & yang merepotkan:
A. Create (Menambah Data Baru)
// Cara 1: Menggunakan instance Model
let mut product = Product {
name: "Laptop Gaming Ultra".to_string(),
price: 15_000_000.0,
stock: 10,
..Default::default()
};
let product_id = product.save(req.db()).await?;
println!("Produk berhasil disimpan dengan ID: {}", product_id);
// Cara 2: Langsung via Fluent Query Builder (Cepat & Praktis)
Product::query(req.db())
.insert([
("name", "Laptop Gaming Ultra"),
("price", "15000000"),
("stock", "10"),
])
.await?;B. Read (Mencari Data Berdasarkan ID)
// Cara 1: Menggunakan find_or_fail (Sangat elegan, langsung dapat Model atau otomatis 404 jika tidak ditemukan)
let product = Product::find_or_fail(req.db(), 1).await?;
println!("Ditemukan: {} — Rp {}", product.name, product.price);
// Cara 2: Menggunakan find (Mengembalikan Option<Product>)
if let Some(product) = Product::find(req.db(), 1).await? {
println!("Ditemukan: {} — Rp {}", product.name, product.price);
}
// Cara 3: Mengambil semua data aktif sekaligus (Laravel: all())
let all_products = Product::all(req.db()).await?;C. Update (Memperbarui Data)
// Cara 1: Cari objek, ubah nilainya, lalu simpan kembali
let mut product = Product::find_or_fail(req.db(), 1).await?;
product.price = 14_500_000.0;
product.stock -= 1;
product.save(req.db()).await?;
// Cara 2: Update langsung via Fluent Query Builder (Tanpa perlu fetch terlebih dahulu)
Product::query(req.db())
.where_eq("id", 1)
.update([
("price", "14500000"),
("stock", "9"),
])
.await?;D. Delete (Menghapus Data)
// Cara 1: Hapus berdasarkan ID (Laravel: destroy(id))
Product::destroy(req.db(), 1).await?;
// Cara 2: Hapus via Query Builder (Otomatis Soft Delete jika model memiliki deleted_at)
Product::query(req.db()).where_eq("id", 1).delete().await?;
// Cara 3: Hapus fisik permanen dari tabel (Force Delete)
Product::query(req.db()).where_eq("id", 1).force_delete().await?;5. Eloquent Fluent Query Builder
Query builder Pakem dirancang chainable, lurus, dan ekspresif. Database pool dioper di awal via Product::query(req.db()), sehingga metode eksekusi akhir (.get(), .first(), .paginate()) bebas dari argumen tambahan:
// Ambil semua produk dengan harga > 5 juta, stok > 0, urutkan termurah, ambil 10 teratas
let products = Product::query(req.db())
.where_gt("price", 5_000_000.0)
.where_gt("stock", 0)
.order_by("price", "ASC")
.limit(10)
.get()
.await?;
// Ambil record pertama yang cocok
let top_product = Product::query(req.db())
.where_eq("category", "electronics")
.order_by("sales", "DESC")
.first()
.await?;
// Pagination otomatis (Laravel Style)
let (page, per_page) = req.pagination(); // Otomatis membaca query params ?page=1&per_page=15
let paginator = Product::query(req.db())
.where_gt("stock", 0)
.paginate(page, per_page)
.await?;
// Pada Controller RESTful API, paginator dapat langsung dikembalikan:
// req.paginate(paginator)6. Relasi Model (One-Line Relationships & Eager Loading)
Pakem menghadirkan sintaks relasi 1-baris deklaratif di dalam blok impl Model. Tidak ada lagi boilerplate fungsi relasi yang panjang dan rumit:
A. Definisi Relasi pada Model
// 1. Model User: Memiliki banyak Post dan satu Profile
impl User {
has_many!(posts: Post, "user_id");
has_one!(profile: Profile, "user_id");
}
// 2. Model Post: Milik User dan memiliki banyak Tag (Many-to-Many via pivot)
impl Post {
belongs_to!(author: User, user_id);
belongs_to_many!(tags: Tag, "post_tag", "post_id", "tag_id");
}B. Mengakses Relasi di Controller
Setelah didefinisikan, method relasi langsung tersedia dan dapat dipanggil dengan req.db():
// Mengambil semua artikel milik user
let posts = user.posts(req.db()).await?;
// Mengambil profil user
let profile = user.profile(req.db()).await?;
// Mengambil pembuat artikel (author)
let author = post.author(req.db()).await?;
// Mengambil tag-tag artikel
let tags = post.tags(req.db()).await?;C. Pencegahan Masalah N+1 Query (Eager Loading)
Selalu gunakan eager loading .with("relation_name") saat mengambil data relasi untuk koleksi:
// Mengambil seluruh post beserta data user penulisnya dalam 1 query optimal
let posts_with_authors = Post::query(req.db())
.with("user")
.get()
.await?;7. Model Factory & Faker Engine (canting make:factory)
Pakem menyediakan sistem pembuatan data tiruan (mock / seeding) otomatis berkecepatan tinggi ala Laravel Factory dengan lokalisasi data Indonesia:
A. Membuat Factory Baru via CLI
canting make:factory UserFactoryFile database/factories/user_factory.rs akan dibuat secara otomatis:
use pakem::prelude::*;
use crate::app::models::user::User;
pub struct UserFactory;
impl UserFactory {
pub fn new() -> Self {
Self
}
}
impl Factory<User> for UserFactory {
fn definition(&self) -> User {
User {
name: Faker::name(),
email: Faker::unique_email(),
phone: Faker::phone(),
created_at: Some(Faker::datetime_recent()),
updated_at: Some(Faker::datetime_recent()),
..Default::default()
}
}
}
impl HasFactory<UserFactory> for User {
fn factory() -> UserFactory {
UserFactory::new()
}
}B. Penggunaan di Seeder atau Unit Test
// 1. Buat 100 User baru langsung masuk ke database
let users = User::factory().count(100).create(req.db()).await?;
// 2. Modifikasi atribut dengan State Modifier
let admins = User::factory()
.count(5)
.state(|u| {
u.role = "admin".to_string();
})
.create(req.db())
.await?;
// 3. Buat objek in-memory tanpa menyentuh database
let mock_user = User::factory().make_one();8. Dukungan Multi-Database & Microsoft SQL Server (MSSQL)
Pakem Framework dirancang untuk bekerja secara seragam di berbagai engine database modern:
SQLite: Pilihan ideal untuk pengembangan lokal (Zero-Config).
PostgreSQL: Direkomendasikan untuk aplikasi skala besar dengan query kompleks dan konkurensi tinggi.
MySQL / MariaDB: Standar industri aplikasi web modern.
Microsoft SQL Server (MSSQL): Solusi database enterprise dengan protokol biner TDS pure-Rust (Tiberius + bb8 pool).
A. Fitur Driver Microsoft SQL Server (MSSQL)
Pakem mengintegrasikan driver TDS murni tanpa memerlukan instalasi driver C/ODBC tambahan:
Auto-Translation Dialek T-SQL:
- Primary Key:
INTEGER PRIMARY KEY AUTOINCREMENT$
- Primary Key:
ightarrow$ INT IDENTITY(1,1) PRIMARY KEY.
- Tipe Waktu:
DATETIME$
ightarrow$ DATETIME2 DEFAULT CURRENT_TIMESTAMP.
- Teks Panjang:
TEXT$
ightarrow$ NVARCHAR(MAX).
- Boolean:
BOOLEAN$
ightarrow$ BIT.
- DDL Bersyarat:
CREATE TABLE IF NOT EXISTS$
ightarrow$ IF NOT EXISTS (SELECT * FROM sys.tables WHERE name = '...') CREATE TABLE (...).
Paginasi ANSI/T-SQL Otomatis:
Method
.paginate(page, per_page)dan.limit().offset()otomatis dikompilasi ke sintaks:sqlORDER BY id OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLYEksekusi ORM Fluen:
Seluruh operasi model berjalan identik dengan database lainnya:
rust// Query model di MSSQL sama persis dan sepenuhnya teroptimasi let users = User::query(req.db()) .where_eq("role", "admin") .order_by("created_at", "DESC") .get() .await?;Native Direct Access:
Jika Anda membutuhkan akses langsung ke client TDS Tiberius untuk query raw atau stored procedure:
rustif let Some(pool) = req.db().mssql() { let mut conn = pool.get().await?; let stream = conn.query("EXEC sp_my_procedure @P1", &[&user_id]).await?; }
B. Format Connection String MSSQL (Universal Smart Parser)
Pakem v0.6.1 menyematkan Smart Universal Parser yang secara otomatis mengenali dan mengonversi format connection string apa pun yang Anda tulis di file .env:
Format JDBC — IP:Port Langsung (Paling Cepat / Direkomendasikan untuk Enterprise & Rumah Sakit):
envDATABASE_URL="jdbc:sqlserver://192.168.10.29:1433;user=sa;password=123;database=DBSIMRS;trustServerCertificate=true"TIP
Menentukan port secara langsung (misal
:1433) akan membypass pencarian UDP SQL Server Browser (port 1434), membuat koneksi langsung terbuka secara instan (< 1ms).Format JDBC — Named Instance: Jika SQL Server Anda menggunakan Named Instance (misal
\SQL2012), wajib menggunakan double-backslash (\\) agar tidak ter-escape oleh parser.env:envDATABASE_URL="jdbc:sqlserver://192.168.10.29\\SQL2012;user=sa;password=123;database=DBSIMRS;trustServerCertificate=true"Format URL Standard (Otomatis Dikonversi oleh Pakem):
envDATABASE_URL="sqlserver://sa:YourPassword123@localhost:1433?database=pakem_db&trustServerCertificate=true"Format ADO Connection String:
envDATABASE_URL="Server=192.168.10.29,1433;Database=DBSIMRS;User Id=sa;Password=123;TrustServerCertificate=true;"
C. Tips Performa MSSQL di Lingkungan Produksi (Hospital & Enterprise)
- Gunakan Mode Release saat Menjalankan Aplikasi: Jalankan dengan
cargo run --release. Pada mode debug standar Rust, verifikasi Bcrypt password memakan waktu ~300ms–600ms CPU. Pada mode release, proses tersebut teroptimasi penuh menjadi hanya ~15ms–25ms. - Koneksi Pool Pre-Warmed Otomatis: Pakem secara default menginisialisasi minimal 2 koneksi aktif (
min_idle = 2) di memori, sehingga request login pertama tidak perlu menanggung latensi handshake TCP dan autentikasi TLS TDS. - Pastikan Kolom Pencarian Login Memiliki Index: Pada tabel pengguna SIMRS yang besar, pastikan kolom
emailatauusernamememiliki index di SQL Server (CREATE NONCLUSTERED INDEX IX_users_email ON users(email);) agar proses lookup login instan tanpa table scan.
9. Transaksi Database ACID Fluen (Zero-Ampersand, Zero-Pipes, Zero-Generics)
Pakem menghadirkan sistem transaksi database ACID yang dirancang khusus untuk kenyamanan developer:
❌ Tanpa Tanda Ampersand
&tx: Tidak perlu meminjam (borrowing) transaksi secara rumit antar pemanggilan.❌ Tanpa Tanda Pipa
|: Bebas dari pengetikan simbol pipa yang sulit dijangkau jari pada keyboard.❌ Tanpa Anotasi Turbofish
<>: Ekstraksi baris data berlangsung mulus dan transparan ke format JSON/nilai tanpa generic rumit yang membingungkan developer baru.
Pakem menyediakan dua gaya penulisan transaksi yang sama-sama elegan dan bebas Anda pilih:
A. Gaya 1: Direct Transaction Handle (tx.table(...))
Sangat cocok untuk transaksi langsung di dalam fungsi, service layer, atau controller:
// 1. Mulai transaksi dari Request atau DatabasePool
let tx = req.begin().await?;
// 2. Lakukan operasi secara berantai tanpa tanda ampersand '&'
tx.table("accounts")
.where_eq("id", 1)
.decrement("balance", 50000)
.await?;
tx.table("accounts")
.where_eq("id", 2)
.increment("balance", 50000)
.await?;
// 3. Simpan perubahan secara permanen
tx.commit().await?;B. Gaya 2: Contextual Request (req.table(...))
Sangat intuitif bagi developer Laravel, di mana context request secara otomatis memelihara transaksi aktif:
// 1. Buka transaksi pada level Request
req.begin().await?;
// 2. Operasi tabel langsung melalui req
req.table("accounts").await?.where_eq("id", 1).decrement("balance", 50000).await?;
req.table("accounts").await?.where_eq("id", 2).increment("balance", 50000).await?;
// 3. Selesaikan transaksi
req.commit().await?;C. Facade DB
Anda juga dapat menggunakan facade DB yang familiar:
use pakem::prelude::*;
// Menggunakan DB::begin
let tx = DB::begin(req.db()).await?;
tx.table("wallets").where_eq("id", 1).decrement("balance", 10000).await?;
tx.commit().await?;
// Atau blok eksekusi otomatis (Auto-Commit saat Ok, Auto-Rollback saat Err)
DB::transaction(req.db(), |tx| async move {
tx.table("wallets").where_eq("id", 1).decrement("balance", 10000).await?;
tx.table("wallets").where_eq("id", 2).increment("balance", 10000).await?;
Ok::<(), sqlx::Error>(())
}).await?;D. Fitur Transaksi Lanjutan:
Auto-Rollback on Drop: Jika sebuah transaksi keluar dari scope fungsi tanpa pernah memanggil
.commit().await?(misalnya karena?return error lebih awal), Pakem secara otomatis membatalkan (rollback) seluruh perubahan di background secara non-blocking!Savepoint & Partial Rollback:
rustlet tx = req.begin().await?; tx.table("orders").insert([("status", "pending")]).await?; // Tandai titik simpan tx.savepoint("step_1").await?; // Lakukan operasi eksperimental tx.table("logs").insert([("action", "test")]).await?; // Batalkan hanya perubahan setelah savepoint tx.rollback_to("step_1").await?; tx.commit().await?;
10. Smart Declarative Soft Deletes
Pakem menyematkan dukungan Soft Deletes cerdas yang terintegrasi langsung dengan derive macro #[derive(PakemModel)]:
A. Deklarasi Model
Cukup tambahkan field deleted_at: Option<String> pada struct Model Anda:
#[derive(Debug, Serialize, Deserialize, FromRow, Clone, Default, PakemModel)]
#[table("products")]
pub struct Product {
pub id: i64,
pub name: String,
pub price: f64,
pub created_at: Option<String>,
pub updated_at: Option<String>,
pub deleted_at: Option<String>, // ✨ Otomatis mengaktifkan Soft Deletes!
}TIP
Anti-Crash Safety: Model yang tidak memiliki field
deleted_atsecara cerdas tidak akan menyisipkan klausaWHERE deleted_at IS NULLyang invalid, sehingga mencegah query SQL error pada tabel warisan (legacy).
B. Querying dengan Filter Otomatis
Secara default, query Model atau TableQueryBuilder hanya mengambil data aktif:
// Hanya mengambil produk yang belum terhapus (deleted_at IS NULL)
let active_products = Product::query(req.db()).get().await?;
// Sertakan data yang terhapus sementara
let all_products = Product::query(req.db()).with_trashed().get().await?;
// Ambil HANYA data yang terhapus (Trash Box)
let trashed = Product::query(req.db()).only_trashed().get().await?;C. Operasi Soft Delete, Restore, dan Force Delete
// 1. Soft Delete (Mengisi deleted_at dengan waktu saat ini)
Product::query(req.db()).where_eq("id", 1).delete().await?;
// 2. Restore (Mengembalikan deleted_at menjadi NULL)
Product::query(req.db()).where_eq("id", 1).restore().await?;
// 3. Force Delete (Menghapus baris fisik secara permanen dari tabel)
Product::query(req.db()).where_eq("id", 1).force_delete().await?;Navigasi Modul:
Sebelumnya: Modul 03: Controller & Request
Berikutnya: Modul 05: Blade Template Engine ➔
Kembali ke: Daftar Isi Dokumentasi