Satu basis kode, tiga kebutuhan data yang berbeda: data contoh untuk development, data terisolasi untuk testing, dan data referensi yang aman untuk production.
Overview
Migration dan seeder sering ditulis seadanya: satu DatabaseSeeder raksasa yang membuat 500 produk palsu, akun admin@admin.com dengan password password, dan dijalankan di mana saja. Akibatnya:
- seeder data palsu tidak sengaja dijalankan di production,
- test lambat karena seluruh seeder dijalankan untuk setiap test,
- deploy gagal karena migration mengubah kolom pada tabel berisi jutaan baris,
- data referensi (provinsi, metode pembayaran) berbeda antara server satu dan lainnya.
Artikel ini memisahkan tanggung jawab dengan jelas:
| Lingkungan | Kebutuhan | Alat |
|---|---|---|
| Development | Data contoh realistis dan banyak | Factory + DevelopmentSeeder |
| Testing | Data minimal, terisolasi per test | Factory di dalam test + RefreshDatabase |
| Production | Data referensi dan akun awal, aman dijalankan berulang | ReferenceDataSeeder idempoten |
Hasil akhir: struktur seeder per lingkungan, factory dengan state dan relasi, seeder idempoten untuk production, alur deploy migration yang aman, serta teknik mengubah skema tabel besar tanpa downtime panjang.
Prerequisites
| Komponen | Versi |
|---|---|
| PHP | 8.3+ (disarankan 8.4) |
| Laravel | 13.x |
| Database | MySQL 8.0+ / PostgreSQL 15+; SQLite in-memory untuk test |
| Testing | Pest 4 atau PHPUnit 12 |
Skema contoh mengikuti artikel Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration (customers, products, categories, orders, order_items, payments).
Step-by-step Tutorial
Langkah 1: Pahami Siklus Hidup Migration
Perintah yang paling sering dipakai:
| Perintah | Fungsi | Aman di production? |
|---|---|---|
php artisan migrate |
Menjalankan migration yang belum dijalankan | Ya, dengan --force |
php artisan migrate:status |
Melihat migration yang sudah/belum jalan | Ya |
php artisan migrate --pretend |
Menampilkan SQL tanpa menjalankannya | Ya |
php artisan migrate:rollback --step=1 |
Membatalkan batch terakhir | Hati-hati |
php artisan migrate:fresh --seed |
Drop semua tabel lalu migrate ulang | Tidak pernah |
php artisan migrate:refresh |
Rollback semua lalu migrate ulang | Tidak pernah |
Lindungi production dari perintah destruktif. Laravel menyediakan pengaman bawaan:
// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\DB;
public function boot(): void
{
DB::prohibitDestructiveCommands($this->app->isProduction());
}
Dengan ini, migrate:fresh, migrate:refresh, migrate:reset, dan db:wipe akan menolak berjalan di production.
Langkah 2: Aturan Menulis Migration
- Jangan mengedit migration yang sudah dijalankan di server mana pun. Buat migration baru.
- Selalu tulis
down()dan uji denganmigrate:rollbackdi lokal. - Satu perubahan logis per migration.
- Pisahkan perubahan skema dan perubahan data bila datanya besar.
Contoh menambah kolom dengan aman:
php artisan make:migration add_weight_to_products_table
public function up(): void
{
Schema::table('products', function (Blueprint $table) {
$table->unsignedInteger('weight_gram')->default(0)->after('stock');
});
}
public function down(): void
{
Schema::table('products', function (Blueprint $table) {
$table->dropColumn('weight_gram');
});
}
Periksa SQL sebelum dijalankan:
php artisan migrate --pretend
2026_10_19_100000_add_weight_to_products_table ..........................
⇂ alter table `products` add `weight_gram` int unsigned not null default '0' after `stock`
Langkah 3: Susun Seeder per Lingkungan
Struktur yang disarankan:
database/seeders/
├── DatabaseSeeder.php ← pengatur: memilih seeder sesuai lingkungan
├── Reference/
│ ├── ReferenceDataSeeder.php ← dijalankan di SEMUA lingkungan
│ ├── PaymentMethodSeeder.php
│ └── RoleSeeder.php
├── AdminUserSeeder.php ← akun awal (production: dari .env)
└── DevelopmentSeeder.php ← data palsu, HANYA local/staging
// database/seeders/DatabaseSeeder.php
namespace Database\Seeders;
use Database\Seeders\Reference\ReferenceDataSeeder;
use Illuminate\Database\Seeder;
class DatabaseSeeder extends Seeder
{
public function run(): void
{
$this->call(ReferenceDataSeeder::class);
$this->call(AdminUserSeeder::class);
if (app()->environment(['local', 'staging'])) {
$this->call(DevelopmentSeeder::class);
}
}
}
Langkah 4: Seeder Data Referensi yang Idempoten
Seeder production harus aman dijalankan berkali-kali: menjalankannya dua kali tidak boleh menghasilkan data ganda. Gunakan upsert() atau updateOrCreate() dengan kunci alami (kode, slug), bukan ID.
// database/seeders/Reference/PaymentMethodSeeder.php
namespace Database\Seeders\Reference;
use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;
class PaymentMethodSeeder extends Seeder
{
public function run(): void
{
$now = now();
$methods = [
['code' => 'transfer', 'name' => 'Transfer Bank', 'is_active' => true],
['code' => 'qris', 'name' => 'QRIS', 'is_active' => true],
['code' => 'va_bca', 'name' => 'Virtual Account BCA', 'is_active' => true],
['code' => 'cod', 'name' => 'Bayar di Tempat', 'is_active' => false],
];
DB::table('payment_methods')->upsert(
array_map(fn ($m) => $m + ['created_at' => $now, 'updated_at' => $now], $methods),
uniqueBy: ['code'],
update: ['name', 'updated_at'], // is_active tidak ditimpa: bisa diubah admin
);
}
}
Perhatikan parameter update: kolom yang boleh diubah admin melalui aplikasi (is_active) tidak ikut ditimpa saat seeder dijalankan ulang.
// database/seeders/Reference/ReferenceDataSeeder.php
namespace Database\Seeders\Reference;
use Illuminate\Database\Seeder;
class ReferenceDataSeeder extends Seeder
{
public function run(): void
{
$this->call([
RoleSeeder::class,
PaymentMethodSeeder::class,
]);
}
}
Langkah 5: Akun Admin Awal Tanpa Password Bawaan
Jangan pernah menulis password production di kode. Ambil dari environment, dan jangan menimpa akun yang sudah ada:
// database/seeders/AdminUserSeeder.php
namespace Database\Seeders;
use App\Models\User;
use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Str;
class AdminUserSeeder extends Seeder
{
public function run(): void
{
$email = env('SEED_ADMIN_EMAIL', 'admin@example.test');
if (User::where('email', $email)->exists()) {
$this->command?->info("Admin {$email} sudah ada, dilewati.");
return;
}
$password = env('SEED_ADMIN_PASSWORD') ?: Str::password(16);
User::create([
'name' => 'Administrator',
'email' => $email,
'password' => Hash::make($password),
'email_verified_at' => now(),
])->assignRole('admin');
if (! env('SEED_ADMIN_PASSWORD')) {
$this->command?->warn("Password admin dibuat acak: {$password}");
$this->command?->warn('Simpan sekarang; password ini tidak ditampilkan lagi.');
}
}
}
env()di luar file config tidak lagi terbaca setelahphp artisan config:cache. Seeder biasanya dijalankan sebelum cache dibuat, tetapi untuk keamanan, Anda bisa memindahkan nilai ini keconfig/seeding.phpdan membacanya denganconfig().
Contoh assignRole() di atas memakai spatie/laravel-permission; sesuaikan dengan sistem peran Anda.
Langkah 6: Factory dengan State dan Relasi
Factory adalah fondasi seeder development dan test.
// database/factories/ProductFactory.php
namespace Database\Factories;
use Illuminate\Database\Eloquent\Factories\Factory;
use Illuminate\Support\Str;
class ProductFactory extends Factory
{
public function definition(): array
{
$name = fake()->unique()->words(3, true);
return [
'sku' => strtoupper(fake()->unique()->bothify('PRD-####??')),
'name' => Str::title($name),
'slug' => Str::slug($name).'-'.Str::lower(Str::random(4)),
'price' => fake()->numberBetween(10, 500) * 1000, // kelipatan seribu
'stock' => fake()->numberBetween(0, 200),
'is_active' => true,
];
}
public function outOfStock(): static
{
return $this->state(fn () => ['stock' => 0]);
}
public function inactive(): static
{
return $this->state(fn () => ['is_active' => false]);
}
}
// database/factories/OrderFactory.php
namespace Database\Factories;
use App\Enums\OrderStatus;
use App\Models\Customer;
use Illuminate\Database\Eloquent\Factories\Factory;
class OrderFactory extends Factory
{
public function definition(): array
{
return [
'customer_id' => Customer::factory(),
'code' => 'INV-'.fake()->unique()->numerify('########'),
'address_snapshot' => ['city' => fake()->city(), 'street' => fake()->streetAddress()],
'status' => OrderStatus::Pending,
'subtotal' => 0,
'shipping_cost' => 15000,
'total' => 15000,
'placed_at' => fake()->dateTimeBetween('-90 days'),
];
}
public function paid(): static
{
return $this->state(fn () => ['status' => OrderStatus::Paid]);
}
}
Langkah 7: Seeder Development yang Cepat dan Realistis
// database/seeders/DevelopmentSeeder.php
namespace Database\Seeders;
use App\Models\{Category, Customer, Order, Product};
use Illuminate\Database\Console\Seeds\WithoutModelEvents;
use Illuminate\Database\Eloquent\Factories\Sequence;
use Illuminate\Database\Seeder;
class DevelopmentSeeder extends Seeder
{
use WithoutModelEvents; // tidak mengirim email/notifikasi dari observer saat seeding
public function run(): void
{
$categories = Category::factory()->count(8)->create();
$products = Product::factory()
->count(120)
->state(new Sequence(
['is_active' => true],
['is_active' => true],
['is_active' => false], // sepertiga produk nonaktif
))
->create()
->each(fn (Product $p) => $p->categories()->attach(
$categories->random(rand(1, 3))->pluck('id')
));
$customers = Customer::factory()->count(50)->create();
Order::factory()
->count(300)
->recycle($customers) // pakai pelanggan yang sudah ada
->create()
->each(function (Order $order) use ($products) {
$lines = $products->where('is_active', true)->random(rand(1, 4));
$subtotal = 0;
foreach ($lines as $product) {
$qty = rand(1, 3);
$order->items()->create([
'product_id' => $product->id,
'product_name' => $product->name,
'unit_price' => $product->price,
'quantity' => $qty,
'line_total' => $product->price * $qty,
]);
$subtotal += $product->price * $qty;
}
$order->update(['subtotal' => $subtotal, 'total' => $subtotal + $order->shipping_cost]);
});
}
}
recycle() mencegah factory membuat 300 pelanggan baru, sehingga satu pelanggan punya beberapa pesanan, persis seperti data sungguhan.
Jalankan di lokal:
php artisan migrate:fresh --seed
INFO Seeding database.
Database\Seeders\Reference\ReferenceDataSeeder ............ RUNNING
Database\Seeders\Reference\RoleSeeder ............... 12 ms DONE
Database\Seeders\Reference\PaymentMethodSeeder ...... 6 ms DONE
Database\Seeders\AdminUserSeeder .................... 210 ms DONE
Database\Seeders\DevelopmentSeeder .................. 3,412 ms DONE
Langkah 8: Database untuk Testing
Test sebaiknya tidak bergantung pada DevelopmentSeeder. Setiap test membuat data yang ia butuhkan sendiri melalui factory.
Konfigurasi phpunit.xml:
<php>
<env name="APP_ENV" value="testing"/>
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>
</php>
SQLite in-memory sangat cepat, tetapi perilakunya berbeda dari MySQL (misalnya pada fungsi tanggal dan JSON). Untuk test yang bergantung pada fitur khusus MySQL/PostgreSQL, gunakan database test terpisah dengan engine yang sama seperti production.
// tests/Pest.php
uses(Tests\TestCase::class, Illuminate\Foundation\Testing\RefreshDatabase::class)->in('Feature');
// tests/Feature/CheckoutTest.php
use App\Models\{Customer, Product};
use Database\Seeders\Reference\PaymentMethodSeeder;
beforeEach(function () {
$this->seed(PaymentMethodSeeder::class); // hanya data referensi yang dibutuhkan
});
it('menolak checkout produk yang stoknya habis', function () {
$customer = Customer::factory()->create();
$product = Product::factory()->outOfStock()->create();
$this->actingAs($customer->user)
->postJson('/api/v1/checkout', [
'items' => [['product_id' => $product->id, 'quantity' => 1]],
'payment_method' => 'qris',
])
->assertUnprocessable()
->assertJsonValidationErrors('items.0.quantity');
});
Untuk proyek dengan banyak migration, percepat test dengan schema dump:
php artisan schema:dump --prune
Perintah ini menyimpan skema ke database/schema/mysql-schema.sql dan menghapus file migration lama. Saat test atau migrate pada database kosong, Laravel memuat file SQL tersebut terlebih dahulu lalu menjalankan migration yang lebih baru. Lakukan ini hanya bila seluruh lingkungan (termasuk production) sudah menjalankan semua migration lama.
Langkah 9: Alur Migration di Production
Urutan deploy yang aman:
php artisan down --render="errors::503" --retry=60 # opsional, untuk migration berisiko
git pull origin main
composer install --no-dev --optimize-autoloader
php artisan migrate --force --isolated
php artisan db:seed --class="Database\Seeders\Reference\ReferenceDataSeeder" --force
php artisan optimize
php artisan queue:restart
php artisan up
Catatan penting:
--forcewajib karena Laravel meminta konfirmasi di production.--isolatedmemakai atomic lock sehingga bila ada beberapa server yang deploy bersamaan, hanya satu yang menjalankan migration (membutuhkan cache driver yang mendukung lock, sepertiredisataudatabase).- Yang dijalankan di production hanya seeder referensi, bukan
db:seedpenuh. - Selalu backup database sebelum migration yang mengubah atau menghapus kolom.
Langkah 10: Mengubah Tabel Besar Tanpa Downtime Panjang
Mengganti nama atau tipe kolom pada tabel berisi jutaan baris dapat mengunci tabel. Gunakan pola expand → migrate → contract yang dibagi ke beberapa rilis:
Rilis 1 (expand): tambah kolom baru, nullable.
Schema::table('orders', function (Blueprint $table) {
$table->string('channel', 20)->nullable()->after('status');
});
Kode aplikasi mulai menulis ke kolom lama dan baru sekaligus.
Rilis 1 (migrate data) dengan command terpisah, bukan di dalam migration:
// app/Console/Commands/BackfillOrderChannel.php
public function handle(): int
{
DB::table('orders')
->whereNull('channel')
->chunkById(1000, function ($orders) {
DB::table('orders')
->whereIn('id', $orders->pluck('id'))
->update(['channel' => 'web']);
$this->output->write('.');
});
return self::SUCCESS;
}
chunkById memproses per 1.000 baris sehingga lock pendek dan memori stabil.
Rilis 2 (contract): kode hanya membaca kolom baru, lalu migration menjadikan kolom NOT NULL dan menghapus kolom lama.
Untuk MySQL, alter tabel sangat besar bisa juga memakai alat seperti gh-ost atau pt-online-schema-change.
Troubleshooting
| Error / Gejala | Penyebab | Solusi |
|---|---|---|
Nothing to migrate padahal ada file baru |
Nama class bentrok, atau file berada di folder lain | Periksa migrate:status; gunakan migration anonim (return new class extends Migration) |
Table 'x' already exists |
Tabel dibuat manual atau migration pernah gagal di tengah | Di lokal: migrate:fresh. Di production: periksa tabel migrations, perbaiki secara manual dengan hati-hati |
Class "Database\Seeders\..." not found |
Namespace tidak sesuai folder atau autoload belum diperbarui | Sesuaikan namespace, jalankan composer dump-autoload |
| Seeder menghasilkan data ganda di production | Seeder memakai create() biasa |
Ubah ke upsert() / updateOrCreate() dengan kunci alami |
Unique constraint failed di factory |
fake()->unique() habis variasi, atau unik antar proses paralel |
Tambahkan suffix acak, atau gunakan Sequence |
| Test lambat sekali | Setiap test menjalankan seluruh seeder / ratusan migration | Seed hanya yang dibutuhkan; gunakan schema:dump |
| Test lolos di SQLite tapi gagal di MySQL | Perbedaan perilaku engine | Jalankan test di engine yang sama dengan production, minimal di CI |
This command is prohibited from running in this environment |
prohibitDestructiveCommands aktif |
Ini pengaman yang disengaja; jangan jalankan perintah destruktif di production |
| Deploy berhenti karena migration mengunci tabel | Alter kolom pada tabel besar | Gunakan pola expand-migrate-contract dan backfill bertahap |
Best Practices
Keamanan
- Aktifkan
DB::prohibitDestructiveCommands()di production. - Tidak ada password, token, atau data pribadi asli di seeder dan factory.
- Seeder production hanya berisi data referensi dan akun awal, dengan password dari environment atau dibuat acak.
- Backup sebelum migration yang destruktif, dan uji proses restore secara berkala.
Performa
- Gunakan
upsert()daninsert()massal untuk data referensi besar, bukancreate()dalam loop. - Gunakan
WithoutModelEventsdi seeder development agar observer tidak mengirim email atau memanggil API. - Backfill data besar lewat command dengan
chunkById, bukan di dalam migration. - Gunakan
schema:dumpuntuk mempercepat test dan instalasi baru.
Maintainability
- Pisahkan seeder per lingkungan dan per tanggung jawab.
- Factory adalah dokumentasi hidup tentang bentuk data yang valid; rawat dengan state yang bermakna (
paid(),outOfStock()). - Jalankan
migrate:fresh --seeddan seluruh test di CI pada setiap pull request untuk memastikan migration dan seeder tidak rusak. - Catat migration yang membutuhkan langkah manual atau backfill di
CHANGELOG.md.
Related Articles
- Cara Merancang Database Laravel dari Requirement hingga ERD dan Migration
- Memahami Eloquent Relationships: One-to-One, One-to-Many, dan Many-to-Many dengan Studi Kasus
- Soft Delete, Audit Trail, dan Activity Log: Cara Melacak Perubahan Data Aplikasi
- Membangun Laravel Starter Kit yang Reusable untuk Berbagai Jenis Aplikasi Bisnis
- Membuat Dokumentasi API dan Panduan Instalasi Source Code Laravel untuk Pelanggan
Last Tested
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS (production), SQLite 3.45 (test) |
| Pest | 4.x |
| Tanggal | 19 Oktober 2026 |