86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
|
# Changelog
|
||
|
|
|
||
|
|
All notable changes to `laravel-workkit` are documented here. This project
|
||
|
|
follows [Keep a Changelog](https://keepachangelog.com/) 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).
|