Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Database / Panduan Database Migration dan...
Database

Panduan Database Migration dan Seeder untuk Development, Testing, dan Production

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
12 min read
11 views

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

  1. Jangan mengedit migration yang sudah dijalankan di server mana pun. Buat migration baru.
  2. Selalu tulis down() dan uji dengan migrate:rollback di lokal.
  3. Satu perubahan logis per migration.
  4. 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 setelah php artisan config:cache. Seeder biasanya dijalankan sebelum cache dibuat, tetapi untuk keamanan, Anda bisa memindahkan nilai ini ke config/seeding.php dan membacanya dengan config().

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:

  • --force wajib karena Laravel meminta konfirmasi di production.
  • --isolated memakai atomic lock sehingga bila ada beberapa server yang deploy bersamaan, hanya satu yang menjalankan migration (membutuhkan cache driver yang mendukung lock, seperti redis atau database).
  • Yang dijalankan di production hanya seeder referensi, bukan db:seed penuh.
  • 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() dan insert() massal untuk data referensi besar, bukan create() dalam loop.
  • Gunakan WithoutModelEvents di seeder development agar observer tidak mengirim email atau memanggil API.
  • Backfill data besar lewat command dengan chunkById, bukan di dalam migration.
  • Gunakan schema:dump untuk 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 --seed dan 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

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

Bagikan artikel:

Artikel lainnya