1.x
Browse documentationOpen

byrcsc/laravel-data-sync · 1.x

Health checks.

What sync:doctor verifies, which findings are failures and which are warnings, and how to use it in a deploy pipeline.

php artisan sync:doctor
php artisan sync:doctor --strict

sync:doctor inspects the installation and its operational dependencies and reports two kinds of finding. Failures exit non-zero. Warnings do not, unless --strict is given.

Run it after installing, after changing disks or connections, and in your deploy pipeline. It is designed to turn a silent 2 a.m. failure into a deploy-time one.

Failures

CheckFails when
Configurationdata-sync config is invalid — an unknown definition class, a duplicate name, an unknown override key, a bad cron expression, a bad retention value, a connection with no driver, or an FTP/SFTP driver whose Flysystem adapter is missing
Tablessync_files, sync_runs, sync_row_failures, or job_batches is missing
DefinitionsA registered definition cannot be resolved or fails validation
ConnectionsA data-sync.connections entry cannot list files
SourcesA definition's source cannot be listed
Transfer destinationsA transfer's destination disk cannot be listed
Working disksThe staging or archive disk rejects a write-and-delete probe
Cache locksThe cache store cannot acquire and release a lock

The probe writes a small file into the configured staging and archive paths and removes it again, so a misconfigured bucket policy shows up here rather than half way through a 400,000-row import.

Failures are deduplicated, so one broken connection shared by three definitions is reported once.

Warnings

CheckWarns when
matchOn indexesA definition's match columns have no matching unique or primary index on the destination table
Stuck runsA run has been running for more than an hour
Staging driverThe staging disk uses the local driver

All three are worth reading rather than silencing.

A missing unique index on matchOn() means concurrent chunk jobs can insert the same logical row twice, and upsert() has nothing to conflict on. The index columns must match the matchOn() set exactly, in any order.

A stuck run is almost always a worker that died mid-batch. Restart the worker; the batch resumes with whatever chunks have not run. If the batch is gone, retry the run.

A local staging disk is a single-machine configuration. On one box it is correct and the warning is expected noise. Across machines it means a worker will look for a staged file that is not there. See queues and workers.

--strict in a pipeline

php artisan sync:doctor --strict

--strict makes any warning a non-zero exit, which is what you want in CI or a deploy gate — with one caveat: a single-machine deployment will always warn about the local staging disk, so --strict there fails permanently. Either point staging at shared storage, or use plain sync:doctor and read the warnings.

What it does not check

  • Whether files are actually arriving. A source that is reachable and empty passes. Alert on run history for that, not on the doctor.
  • Whether a definition's mapping matches today's file. Schema validation happens when a file is read, because a header is a property of a file rather than of a configuration. Use --dry-run for that.
  • Queue workers. It verifies job_batches exists, not that anything is consuming the queue.
  • Retention drift. It validates the retention values, not whether pruning has been running.

Running it from code

use ByRcsc\LaravelDataSync\Actions\InspectInstallation;

$report = app(InspectInstallation::class)();

$report->failures;   // list<string>
$report->warnings;   // list<string>

Useful for a /health endpoint or a scheduled check that posts to Slack. It performs real I/O against every source and disk, so run it on a schedule rather than per request.