Custom Fresh Laravel Package

Technical Evaluation

What the package is. ramadan/custom-fresh is a Laravel dev-tooling package that extends the migrate:fresh workflow so a configured set of tables is excluded from the drop (and, depending on implementation, preserved or re-populated) while the rest of the schema is rebuilt. It targets a real ergonomic gap: teams keeping reference data — countries, currencies, plans, permissions, feature flags, taxonomy — in the database and tired of re-seeding it on every fresh rebuild.

What changed in v2.2.1. This is a meaningful release for an evaluator, not a cosmetic patch. Four things shift the picture:

1. Input validation on the preserved-table list — it now errors when a named table does not exist or when no tables are specified. This converts the single worst failure mode we flagged (a typo silently dropping data you meant to keep) from a silent failure into a loud one. That is a disproportionate risk reduction for a small amount of code.
2. Referential-integrity awareness — informational logging when dropped child tables reference preserved parent tables, with warnings gated behind the new --drop-referenced option. The package is now doing FK-graph reasoning, which is exactly where naive implementations break on Postgres ordering.
3. Migration-group awareness — it prompts for confirmation when --drop targets a table that shares a create migration with related tables, and in non-interactive mode it preserves the entire related group rather than guessing. Fail-safe defaults in CI are the right design call.
4. A new --drop flag and --drop-referenced option — the command is no longer purely subtractive. It now has its own flag semantics layered on top of Laravel's, which widens the surface area and the number of code paths to reason about.

Architecture fit. Still small and well-contained: service provider, config file, command. Still dev/CI-only, no request lifecycle, no runtime coupling, no production blast radius by design. Two caveats, one old and one new. The old one stands: it borrows against migrate:fresh internals, which have shifted across Laravel 8→12, so a subclass or vendor-copy inherits a compatibility treadmill. The new one: migration-group detection implies it reads and correlates migration files with table names, which is a deeper coupling to Laravel conventions (file naming, Schema::create parsing) than a thin wrapper. That is more capable but more brittle than what we assessed previously.

Integration feasibility. Still low effort — composer require --dev, publish config, enumerate tables, alias the command in a Makefile/composer script. Half a day for a working pilot. The added validation means a misconfigured table name now fails fast at command invocation rather than silently, which shortens the pilot feedback loop. Still require-dev only, never in the production dependency graph.

Technical risk. The supply-side profile is unchanged in kind but improved in signal: single maintainer, zero dependents, low visibility, but now with a visible incremental release cadence (v2.2.0 → v2.2.1), a properly formatted changelog, and compare links. The previously flagged future-dated release timestamp is less concerning now that we can see a coherent tag progression — treat it as resolved-ish, but still confirm the tag history on the repo. Hazards, revised:

• Drop semantics vs. data semantics. Unchanged and still the primary question: does it skip the drop (table survives with stale schema) or drop-and-restore (rows dumped and re-inserted)? Migration-group awareness suggests it at least understands which tables move together, but it does not tell us what happens when a preserved table gains a column in a later migration.
• Driver coverage. Still unaddressed in the notes. FK-graph reasoning is better on Postgres than ad-hoc dropping, but that logic is also where Postgres/MySQL/SQLite diverge most. The new referenced-parent warnings are a good sign; they are not evidence of a test matrix.
• Multiple connections / schema-qualified names. Still silent in the release notes. Still must ask.
• Interaction with --seed, --drop-views, --drop-types. Still unaddressed, and now compounded by --drop / --drop-referenced flag interactions.
• New flag surface. --drop and --drop-referenced add combinatorial behavior. Two flags with an interactive prompt and a non-interactive fallback is a state machine; the release notes describe the intended behavior but not the exit codes. Confirm that validation errors and declined prompts produce a non-zero exit in CI, otherwise the fail-safe becomes a fail-silent.
• Interactive prompts in automation. The non-interactive path preserves whole table groups rather than asking — good — but confirm it does not hang when stdin is a TTY-detecting CI runner.
• Blast radius. Narrowed by validation, not eliminated. A table name that exists but is the wrong table still passes validation and still gets preserved when it should have been rebuilt.

Key questions for the maintainer / spike. (Resolved items struck through.)

1. Are table names validated? Resolved in v2.2.1 — errors on non-existent tables and empty lists.
2. How are referenced/parent tables handled? Partially resolved — warnings logged, gated by --drop-referenced; confirm exact behavior on Postgres FK ordering.
3. Is the exclusion a skipped drop or a dump/restore, and what happens when a preserved table gains a column? (still open — highest priority)
4. Which Laravel and PHP versions are explicitly supported and tested in CI? (still open)
5. Which database drivers are exercised in tests? (still open)
6. Are schema-qualified names, views, and multiple connections supported? (still open)
7. How does it compose with --seed, --drop-views, and --drop-types? (still open)
8. What are the exit codes for validation failure and for a declined confirmation prompt in non-interactive mode?
9. Does migration-group detection parse migration files, and how does it behave with squashed schemas (schema:dump) or migrations that create tables conditionally?
10. License, and is the command a fork of Laravel's or a wrapper? (still open)

Integration Approach

Stack fit. Laravel-only, dev/CI-only. Sits in the same layer as seeders, factories, and RefreshDatabase. It complements rather than replaces db:seed; the healthy pattern remains idempotent seeders plus this package for expensive reference tables. Do not use it as a substitute for seeders.

Migration path. Pilot, pin, codify — largely unchanged, with two additions:

1. Add as require-dev with a pinned constraint (^2.2 or exact); commit composer.lock.
2. Publish config and enumerate preserved tables explicitly, one comment per table explaining why. This file is shared infrastructure and needs a named owner.
3. Pin to ≥ v2.2.1 specifically. The pre-2.2.1 behavior lacked table-name validation; that alone justifies refusing older tags.
4. Side-by-side comparison on the same commit: migrate:fresh --seed vs. the package command, then diff SHOW CREATE TABLE and row counts across every table. Any schema difference is a red flag.
5. Exercise the failure paths deliberately in the spike: name a table that does not exist (expect loud error), decline the group-confirmation prompt (expect full group preserved), and run both under a non-interactive CI shell to capture exit codes.
6. Wire into one entry point only (Makefile target or composer script alias) so there is a single revert point.
7. Add a CI job against the same driver as staging/production — not SQLite alone.
8. Document in the repo README: what is preserved, why, and how to add or remove a table.

Compatibility. Verify the constraint against your actual Laravel/PHP versions before piloting. Confirm behavior on the driver your CI and staging actually use; an SQLite-only validation remains close to worthless for a drop-ordering- and FK-sensitive tool, and v2.2.1 makes the tool more FK-sensitive, not less.

Sequencing. Still a two-week background thread: week 1 spike and validation, week 2 build-vs-buy. The build-vs-buy calculus has moved toward buy. Previously the in-house option was "a few dozen lines"; with migration-group correlation, FK-referenced-parent warnings, validated inputs, and an interactive/non-interactive split, a faithful reimplementation is now a real multi-day piece of work with its own edge cases. In-house remains the right answer if you only need the simple skip-the-drop behavior and can accept schema drift on preserved tables — but if the spike shows the group and FK handling works on your driver, adopting is the higher-EV path than reimplementing it badly.

Fallback. Unchanged: native migrate:fresh plus fast idempotent seeders, or schema:dump for large baselines. Slower per rebuild, zero dependency risk.

Operational Impact

Maintenance. Code footprint still small; the burden is governance plus now a slightly wider behavioral contract. The v2.2.1 changelog is a positive maintenance signal — disciplined, scoped, incremental. But still one maintainer, zero dependents, low visibility; plan for upstream going quiet. Keep the constraint pinned, own the config, and be ready to absorb the command. Quarterly check: does it support the current Laravel major, and is the repo still active?

Support. No vendor, no SLA, community issues only. Name an internal owner. Document the escape hatch (delete the dependency, restore the native command) so an on-call engineer does not have to reverse-engineer it — and now also document the --drop / --drop-referenced flag semantics, because they are non-obvious and team members will encounter them in the Makefile.

Scaling. No runtime scaling concern; zero production footprint. The relevant scale is team scale: every engineer running a local rebuild depends on the exclusion list being correct, and a wrong entry propagates to all environments at once. Modest real benefit in CI wall-clock where large reference tables are no longer re-seeded per run.

Failure modes and mitigations.

• Schema drift on preserved tables — a migration adds a column, the table is never rebuilt, CI passes locally but a fresh environment fails. Unmitigated by v2.2.1. Mitigate by rebuilding preserved tables in a scheduled CI job without the exclusion and by diffing schemas in the pilot.
• Silent data loss from a typo or renamed table — largely mitigated in v2.2.1 via table-name validation. Residual risk: a valid-but-wrong table name still passes.
• Wrong-table preservation — validation cannot catch intent. Mitigate with a post-run assertion in the wrapper that expected tables exist with expected row counts.
• CI hang or silent pass on prompt/validation — new in v2.2.1. Mitigate by capturing exit codes in the pilot and asserting non-zero on misconfiguration.
• Data leakage — preserving tables makes it easier to carry realistic data (including PII) onto local machines. Restrict preservation to genuinely non-sensitive reference tables; document the rule.
• Driver divergence — MySQL works, Postgres FK ordering or schema-qualified names fail. Test on the driver you deploy against.
• Migration-group detection brittleness — squashed schemas, conditionally-created tables, or non-standard migration filenames could make group correlation wrong. Confirm against your actual migration history.
• Abandonment / version lock — pin, documented removal path, standing in-house alternative.

Ramp-up. A Laravel developer is productive within an hour; the config file is the only thing they must read. The real cost is cultural: teaching the team that "fresh" no longer means "everything is fresh," that preserved tables are a shared contract, and now that --drop exists and can override that contract. That needs a short written convention in the repo, not a training session.

TPM verdict. Still low-risk, dev-only tooling solving a genuine annoyance — but v2.2.1 materially improves the risk profile by replacing silent failure with loud failure on the highest-severity hazard, and it raises the credible capability bar enough that in-housing is no longer the obvious default. Recommended: timeboxed spike pinned to ≥ v2.2.1, exercise the failure paths and the non-interactive CI behavior explicitly, then prefer adoption over reimplementation if the driver matrix and --seed composition check out. Keep it out of the production dependency graph; keep it documented as part of the build.