›
byrcsc/laravel-data-sync · 1.x
Check configuration, disks, connections, tables, and indexes before a sync runs.
php artisan sync:doctor
php artisan sync:doctor --strictsync: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.
| Check | Fails when |
|---|---|
| Configuration | data-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 |
| Tables | sync_files, sync_runs, sync_row_failures, or job_batches is missing |
| Definitions | A registered definition cannot be resolved or fails validation |
| Connections | A data-sync.connections entry cannot list files |
| Sources | A definition's source cannot be listed |
| Transfer destinations | A transfer's destination disk cannot be listed |
| Working disks | The staging or archive disk rejects a write-and-delete probe |
| Cache locks | The 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.
| Check | Warns when |
|---|---|
matchOn indexes | A definition's match columns have no matching unique or primary index on the destination table |
| Stuck runs | A run has been running for more than an hour |
| Staging driver | The 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 pipelinephp 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.
--dry-run for that.job_batches exists, not that anything is
consuming the queue.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.