eloquent-migrations

name	eloquent-migrations
description	Eloquent ORM + MySQL migration patterns for this monorepo. Use when defining models, writing migrations, setting up relationships, or seeding data in apps/laravel/. Triggers on tasks involving database tables, foreign keys, indexes, model factories, or seeders.
frameworks	["laravel","eloquent"]
languages	["php"]
category	database
updated	"2026-04-29T00:00:00.000Z"

Eloquent ORM + Migrations Skill

Quick Reference

When to Use: Creating tables, defining Eloquent models, writing relationships, or generating seed data

Database: MySQL 8 (managed via Docker Compose mysql service)

Migrations location: apps/laravel/database/migrations/

Migration Pattern

// database/migrations/2025_01_01_000001_create_todos_table.php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('todos', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')
                  ->constrained()
                  ->cascadeOnDelete();
            $table->string('title');
            $table->boolean('completed')->default(false);
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('todos');
    }
};

Column Type Reference

Use Case	Blueprint method
Auto-increment PK	$table->id()
UUID PK	$table->uuid('id')->primary()
Required string	$table->string('name')
Optional text	$table->text('bio')->nullable()
Boolean with default	$table->boolean('completed')->default(false)
Timestamps	$table->timestamps()
Soft deletes	$table->softDeletes()
Foreign key (user_id)	$table->foreignId('user_id')->constrained()->cascadeOnDelete()
Enum	$table->enum('role', ['user', 'admin'])->default('user')
JSON	$table->json('meta')->nullable()

Eloquent Model

// app/Models/Todo.php
namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Todo extends Model
{
    use HasFactory;

    protected $fillable = ['title', 'completed'];

    protected $casts = [
        'completed' => 'boolean',
    ];

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

User Model (existing — relevant relationships)

// Relationships to add to app/Models/User.php
use Illuminate\Database\Eloquent\Relations\HasMany;

public function todos(): HasMany
{
    return $this->hasMany(Todo::class);
}

Relationship Types

// One-to-Many
public function posts(): HasMany
{
    return $this->hasMany(Post::class);
}

// Belongs-to (inverse)
public function author(): BelongsTo
{
    return $this->belongsTo(User::class, 'user_id');
}

// Many-to-Many
public function roles(): BelongsToMany
{
    return $this->belongsToMany(Role::class);
}

Factory

// database/factories/TodoFactory.php
namespace Database\Factories;

use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

class TodoFactory extends Factory
{
    public function definition(): array
    {
        return [
            'user_id'   => User::factory(),
            'title'     => $this->faker->sentence(4),
            'completed' => $this->faker->boolean(20), // 20% complete
        ];
    }
}

Seeder

// database/seeders/DatabaseSeeder.php
namespace Database\Seeders;

use App\Models\Todo;
use App\Models\User;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        User::factory(10)->create()->each(function ($user) {
            Todo::factory(5)->create(['user_id' => $user->id]);
        });
    }
}

Migration Commands

# Run all pending migrations
docker compose exec api php artisan migrate

# Rollback the last batch
docker compose exec api php artisan migrate:rollback

# Fresh database + reseed
docker compose exec api php artisan migrate:fresh --seed

# Check migration status
docker compose exec api php artisan migrate:status

# Generate migration file
docker compose exec api php artisan make:migration create_features_table

Common Query Patterns

// Retrieve all todos for authenticated user, newest first
$todos = $request->user()->todos()->latest()->get();

// Find with 404 guard
$todo = Todo::findOrFail($id);

// Scoped query
$completed = Todo::where('user_id', $userId)
    ->where('completed', true)
    ->get();

// Create via relationship
$todo = $request->user()->todos()->create([
    'title' => $request->title,
]);

// Update
$todo->update(['completed' => true]);

// Delete
$todo->delete();

Adding a New Table Checklist

1. docker compose exec api php artisan make:model Feature -mfs
2. Edit migration file with columns and indexes
3. Add $fillable and $casts to model
4. Add relationship methods to related models
5. Write factory definition() returning realistic data
6. Run docker compose exec api php artisan migrate
7. (Optional) docker compose exec api php artisan db:seed --class=FeatureSeeder