›
byrcsc/laravel-data-sync · 2.x
Run, inspect, retry, prune, and diagnose syncs through Artisan.
| Command | What it does |
|---|---|
sync:run [name] [--now] [--force] [--dry-run] | Discover or fetch files, then process them |
sync:status [name] [--failures] [--limit=] | Recent runs, counters, batch progress |
sync:retry <run> [--failed-rows] | Retry a finished run, or replay its failed rows |
sync:doctor [--strict] | Check the installation and its dependencies |
sync:prune | Enforce the retention windows |
| `make:sync <name> [--transfer | --api |
php artisan sync:run
php artisan sync:run products
php artisan sync:run products --now
php artisan sync:run products --force
php artisan sync:run products --dry-run| Argument / option | Effect |
|---|---|
name | One registered definition. Omitted, every enabled definition runs |
--now | Process in this process instead of dispatching to the queue |
--force | Process a checksum that has already completed |
--dry-run | Validate and count without writing; implies in-process |
For an API sync or a database sync, the command fetches the records in its own process before it dispatches anything. A fetch that fails records a failed run and exits non-zero.
Prints one line per run plus a per-definition summary of discovered, skipped, and deferred files. Exits non-zero when a definition throws, a schema mismatch, an unreachable source, an invalid definition. A definition whose discovery lock is held is reported and exits zero, because an overlapping run is a normal condition.
Details in running a sync.
php artisan sync:status
php artisan sync:status products --limit=25
php artisan sync:status --failures| Argument / option | Effect |
|---|---|
name | Limit history to one definition |
--limit= | Maximum runs to display; defaults to 10 |
--failures | Print one line per failed row for the listed runs |
Runs are listed newest first. For runs with a queued batch, the progress column reads the batch record. Always exits zero, including when there is no history.
After the table, the command warns about each API or database sync whose last
data-sync.stalled_watermark_runs runs all finished without completed,
because its watermark has stopped moving.
Details in run history and status.
php artisan sync:retry 01JQ8Z3M0K2N4P6R8T0V2X4Y6A
php artisan sync:retry 412 --failed-rows| Argument / option | Effect |
|---|---|
run | A run ULID or numeric id; the run must have finished |
--failed-rows | Replay only the captured failed-row payloads, in this process |
Without the flag, the preserved copy of the file is restored to staging and dispatched as a new run, from the archive disk for a completed run, from the failed disk for one that failed or was cancelled.
Exits non-zero when the run is unknown or unfinished, when no stored copy
remains, when payload capture was off and --failed-rows was asked for, or when
--failed-rows is used on a transfer.
Details in failures and retries.
php artisan sync:doctor
php artisan sync:doctor --strict| Option | Effect |
|---|---|
--strict | Treat warnings as failures |
Prints each failure and warning, then a summary. Exits non-zero on any failure,
or on any warning with --strict.
Details in health checks.
php artisan sync:pruneNo arguments. Enforces the four retention windows and prints what it removed:
Pruned 412 runs, 1204 row failures, 88 archives, and 3 failed files.Scheduled daily unless data-sync.register_schedules is false. Exits non-zero
when a disk cannot be listed or a file cannot be deleted, naming the config key
at fault.
Details in retention and pruning.
php artisan make:sync ProductsSync
php artisan make:sync Products # same class
php artisan make:sync StatementsTransfer --transfer
php artisan make:sync BookingsSync --api
php artisan make:sync LegacyOrdersSync --database| Argument / option | Effect |
|---|---|
name | The definition class name |
--transfer | Generate a TransferDefinition instead |
--api | Generate an ApiSyncDefinition instead |
--database | Generate a DatabaseSyncDefinition instead |
Pass at most one of --transfer, --api, and --database.
Writes to app/Syncs/. The Sync or Transfer suffix is appended when absent,
and the class is namespaced under the application's root namespace. Exits
non-zero when the file already exists, it never overwrites.
The generated class is a skeleton that points at User. A transfer skeleton
uses a local disk, an API skeleton uses https://api.example.com/<name>, and a
database skeleton reads the users table on a legacy connection. Register
the class in data-sync.syncs yourself. The command does not touch config.
Every command returns 0 on success and 1 on failure. Two behaviours are
worth calling out for scripts and schedulers:
sync:run exits zero when discovery is locked by another invocation.sync:doctor exits zero on warnings unless --strict is given, and a
single-machine deployment always warns about its local staging disk.