laravel-workkit/CHANGELOG.md

Changelog

All notable changes to laravel-workkit are documented here. This project follows Keep a Changelog and keeps every release backward-compatible with the previous minor (see PRINCIPLES/laravel-composer-packages.md § Backward compatibility).

Unreleased

Added

• workkit:stats (+ StatsService) — terminal "admin overview": per-Eloquent-model row counts (fast information_schema estimate on MySQL, --exact for COUNT(*)), largest tables by size, total database size, and a compact queue + backup summary. Models are auto-discovered from app/Models or config('workkit.stats.models'). --json for machine consumption; degrades gracefully on non-MySQL drivers.
• workkit:queue:health (+ QueueHealthService) — per-queue depth / due / delayed / reserved counts and oldest-due-job age for the database queue driver, failed-jobs totals (+ last N hours), and STALLED-queue detection (due work past max_age_minutes with nothing reserved → worker likely down). Exits non-zero on any breach for cron/monitoring; thresholds under config('workkit.queue.*') with per-queue depth overrides. QueueHealthService::evaluate() is a pure, unit-testable function.
• New config blocks workkit.stats.* and workkit.queue.* (read with explicit code-side defaults, so consumers who published an older config are unaffected).

Added — backups

• workkit:db:restore --fresh — drops every table + view in the target before importing, the only reliable fix for a restore failing with errno 150 / error 3780 against a dirty or partially-migrated schema. The wipe is performed via the same mysql client and database the import uses (built from the connection's $cfg, scoped to DATABASE()), so a url DSN / unix_socket / read-write split can never make the wipe and the import target different databases.
• Pre-restore safety snapshot — --fresh first takes and verifies a snapshot of the current database (named *.pre-restore.sql.xz.enc) and aborts before dropping anything if it can't be written; opt out with --no-safety-backup. On a post-wipe import failure the command prints the exact workkit:db:restore --file=<snapshot> recovery command.
• workkit:db:verify (+ workkit:db:backup --verify) — proves a backup decrypts with this host's APP_KEY and is a complete, non-truncated xz stream, without touching the database; flags a missing mysqldump completion marker and compares the on-disk sha256 against the metadata sidecar. --all checks every backup.
• Metadata sidecar — workkit:db:backup writes a best-effort <file>.meta.json (size, sha256, created_at, cipher params) next to each backup. Never fails a good backup if it can't be written.
• workkit:db:prune-backups --keep-min (config backup.retention_min_keep, default 5) — always keeps the N newest backups regardless of age, so an aggressive --days can never leave zero recovery points. Prune now also removes a backup's sidecar alongside it and sweeps orphaned sidecars.
• Restore safeguards — the source backup is verified before any destructive step; a dirty (non-empty) target is reported with a --fresh hint; an import that incompatibly fails prints actionable guidance; a non-trivial backup that imports zero tables is flagged as a possible silent failure. The confirm line now shows the backup size.
• New public BackupService helpers (all additive): verify(), dropAllTables(), countTables(), estimateDatabaseBytes(), backupFiles(), restoreCandidates(), metaPathFor(), humanBytes(), runResult().

Changed

• BackupService::decryptDecompressImport() now prepends SET FOREIGN_KEY_CHECKS=0; to the import stream so a hand-rolled dump lacking mysqldump's own header still imports into an empty database regardless of table order. Harmless for mysqldump output (which sets/restores its own session vars), and the whole import is one short-lived session so the relaxed check never leaks. This does not rescue a restore onto a dirty schema with incompatible column types — use --fresh for that.
• File selection in restore/prune now ignores *.meta.json sidecars while still finding custom --out-named backups (it denies the sidecar suffix rather than allow-listing one extension). The restore auto-pick also skips *.pre-restore.* snapshots so a recovery snapshot of a known-bad database is never restored by accident.

Notes

• Existing BackupService method signatures and all config keys are unchanged; new behavior is additive or confined to the new --fresh path. New nested config keys are read with explicit code-side defaults, so a consumer who published an older config/workkit.php is unaffected.
• The README is now backup-documented and brought up to the standard Blax OSS package skeleton (badges, feature list, Star History).