Download the PHP package nekoos/laravel-seed-drain without Composer

Laravel Seed Drain

Languages: English | Español

Incremental seed execution aligned with migrations.

artisan migrate --seed is useful for initial bootstrap, but it falls short in continuous automation workflows:

• Migrations have native incremental control.
• Seeders do not provide that same control by default.
• In repeated deployments, db:seed can be hard to scope to the right moment.

laravel-seed-drain simplifies this with an explicit temporary seeder queue. By default, it does not require additional database tables. Optionally, it can persist queue state in a dedicated database table.

What Problem It Solves

• Execute only relevant seeders after migrations.
• Avoid introducing extra tracking schema for seeder execution.
• Keep CI/CD workflows simple for development and production.
• Optionally separate seeders by logical queues (default, core, demo).

Core Idea

Register seeders during migration up().

Then execute a dedicated command to drain them.

Installation

Install the package via Composer:

Setup

Publish package files when you need to customize them:

Run migrations:

For contribution and local development guidelines, see CONTRIBUTING.md.

Proposed Public API

Default usage (default queue):

Explicit queues (fluent API):

By default, duplicate seeders are kept in the queue and executed in order.

Migration Example

seed:drain Command

Suggested options:

• --queue=default
• --queue=core --queue=demo (repeatable)
• --queue=core,demo (CSV)
• --queue=all
• --dedupe (optional fallback: compact duplicates before draining)
• --no-lock (disable execution lock for this run)
• --lock-store=... (cache store used by lock)
• --lock-seconds=... (lock TTL)
• --dry-run
• --clear
• --continue-on-failure
• --force

Examples:

seed:drain:doctor Command

Use diagnostics to validate the active queue store, lock setup, and queued items:

Events and Conditional Skip

The package dispatches events during drain execution:

• NekoOs\LaravelSeedDrain\Events\SeedDrainStarting
• NekoOs\LaravelSeedDrain\Events\SeederRunning
• NekoOs\LaravelSeedDrain\Events\SeederSkipped
• NekoOs\LaravelSeedDrain\Events\SeederSucceeded
• NekoOs\LaravelSeedDrain\Events\SeederFailed
• NekoOs\LaravelSeedDrain\Events\SeedDrainFinished

You can skip a seeder conditionally from a listener:

Recommended Automation

Development:

Production:

Package Philosophy

• No environment-specific magic in the package core.
• No extra database tables.
• Explicit API for technical teams.
• Clean integration with existing pipelines.

Best Practices

• Make seeders idempotent (upsert, updateOrCreate, firstOrCreate).
• Keep demo seeders separate from functional seeders.
• Treat --dedupe as a discretionary fallback, not as the default workflow.
• Use --dry-run in CI when you need auditability before execution.

Queue Persistence

• SEED_DRAIN_STORE=cache uses Laravel cache (default).
• SEED_DRAIN_STORE=file persists queue state to a file path.
• SEED_DRAIN_STORE=database persists queue state in a database table.
• In deploy environments where cache can be reset, prefer file or a persistent cache backend.
• Configure file path with SEED_DRAIN_FILE_PATH (ideally a persistent/shared path).

When using SEED_DRAIN_STORE=cache, persistence depends on the selected cache store:

• Redis: set SEED_DRAIN_CACHE_STORE=redis (or your Redis-backed cache store name).
• Database cache table: set SEED_DRAIN_CACHE_STORE=database.
• Any custom Laravel cache store: set SEED_DRAIN_CACHE_STORE to that store name.

When using SEED_DRAIN_STORE=database:

• Default table is seed_drain_queues.
• Override table with SEED_DRAIN_DB_TABLE.
• Override connection with SEED_DRAIN_DB_CONNECTION.
• Override logical queue key with SEED_DRAIN_DB_KEY.
• The package ships a migration for this table and auto-loads it.
• The database store also creates the table lazily if it does not exist yet.

Custom queue persistence is also supported by binding your own implementation of NekoOs\LaravelSeedDrain\Core\Contracts\QueueStoreInterface in the container.

Status

This README defines the target contract and API direction for the package.