Laravel Sync Laravel Package

Getting Started

This release adds table filters to database jobs — the first real lever for controlling what gets pulled rather than just where from. If you already use the package for refreshing a local/staging database from a MySQL source, this is the feature to adopt first.

Minimal path:

1. Update and re-publish config/stubs — composer update then check whether the job stub or config schema changed. The filters key is new; existing jobs without it should behave exactly as before, so upgrade risk is low.
2. Look first at your job definition (the class or config array that describes a database job). That's where filters lives — one object keyed by table name.
3. Start with one filter on your largest table. Pick the table that dominates dump size or import time — typically an events/audit/logs table — and add a "last N days" filter on its timestamp column:

'filters' => [
    'audit_logs' => [
        'mode'  => 'recent',      // confirm exact key/mode names in the job schema
        'column' => 'created_at',
        'days'  => 30,
    ],
],

4. Run the job once and diff the row counts between source and destination for the filtered table. That single check tells you whether your column and window semantics are what you assumed.

First real use case: a dev refresh job that pulls ~40 tables but only 30 days of audit_logs and none of failed_jobs — import time drops from minutes to seconds, and you stop copying noise you never query.

Implementation Patterns

Skip-noise filters as a job default. Put filters in a shared base job or a config preset so every environment-refresh job inherits sane exclusions (logs, sessions, cache, Telescope tables). Override per job only where a table genuinely needs data.

Time-window everything user-facing. For local development, "last 30 days of orders" is almost always more useful than "all orders" — it's smaller, and recent rows exercise the code paths you're actually working on. Apply the same window to parent and child tables so relationships stay internally consistent.

Environment-split jobs. Define one job for local dev (aggressive filters: short windows, several skipped tables) and one for staging/QA (lighter filters). Same job class, different filters payload — this is the cleanest way to avoid a "why does staging have less data than prod" conversation.

Filter the tables you don't query, window the tables you do. Two distinct modes for two distinct problems: skip for tables that exist only to satisfy foreign keys or migrations, window for tables where recency matters.

Pair with your seeders deliberately. If a seeder inserts fixtures into a table you're also filtering, decide which wins. Filtering a table to near-empty and then seeding it is usually fine; skipping a table's data and then seeding it can trip unique constraints if the filter only removed some rows.

CI and test-database workflows. Filters make a "pull a realistic subset before an integration run" job practical — a windowed slice of production-shaped data is far better for catching bugs than hand-written fixtures, and now it's small enough to be acceptable.

Gotchas and Tips

A missing filter column fails the job — by design. This is fail-fast validation, not a bug: the filter can't be evaluated if the column isn't there. The practical consequence is that schema drift in the source breaks your job. If a timestamp column gets renamed or a table's shape changes upstream, your daily refresh dies rather than silently pulling everything. Watch the job's failure notifications, and treat filter columns as part of your job's contract with the source schema.

Trimmed before import ≠ trimmed before transfer. The dump is fetched in full and trimmed afterwards. Filters cut import time and destination size dramatically, but if your pain point is the download over a slow link, a skip filter on a giant table still won't help as much as you'd hope. Measure both phases before celebrating.

Referential integrity is your job, not the package's. If you skip a parent table's data but keep child rows, or window a parent to 30 days while leaving children unfiltered, you'll import orphaned rows. MySQL dump imports often run with FK checks disabled, so this fails silently — you get a database that looks fine until a join returns nothing. Rule of thumb: filter a table, filter everything that references it with the same window.

Timezones and boundary semantics. "Last N days" is relative to something — server time, app timezone, or UTC. A column stored in UTC with an app configured to a local timezone can shift your window by hours, which matters at the edges. Verify with a row you know the timestamp of, and prefer UTC-stored columns.

Filters are validated before fetch, so config errors are cheap. Typos in table names or mode keys should surface immediately rather than after a long download. Use that: iterate on filter config by running the job's validation/dry-run path rather than a full fetch, if one is exposed.

Don't filter the tables your feature work depends on and forget it. A window that seemed generous six months ago can now silently exclude the exact historical rows a bug report is about. Periodically sanity-check that the window still covers your realistic debugging horizon — or make the window a job parameter so you can widen it for a one-off investigation.

Extension point to watch: the filter evaluation is described as validating against the source before fetch. If you need custom filtering logic (soft-delete awareness, tenant scoping, non-timestamp criteria), that validation/evaluation layer is where to look for a hook before reaching for post-import cleanup scripts — which are slower and leave the destination briefly inconsistent.