Health check & database maintenance

./maho health-check inspects a Maho project for problems that do not show up as errors: files left behind by a Magento or OpenMage core, database rows that belong to a module you removed, tables that hold more free space than data, an encryption key that cannot decrypt what is stored. Run it after a migration, after an upgrade, after removing a module, and periodically in production.

./maho health-check
./maho health-check --check-zero-dates   # also scan every date column for stored zero dates (slow)

The same report is available in the admin under System > Tools > Health Check, next to the PHP, database and cache facts of the server. The admin page reports; the CLI also offers to clean up.

The checks

Every check prints OK or a warning with the reason and the fix. The checks below are grouped by what they look at.

Files and code

Encryption

Leftovers of removed modules v26.9+

A module you delete from the project takes its code away and leaves its rows. Nothing else reports those rows, because ./maho migrate is forward-only.

Rows that belong to a disabled module are listed separately and kept. Enable the module again, or remove it for good and rerun the check.

Database

Cleanup prompts

When the CLI finds a leftover it can remove safely, it asks first:

Checking cron job declarations...
Warning: Found 1 cron job(s) with no code left to run them:
- my_sync: class My_Observer does not exist (12 cron_schedule row(s))
    core_config_data: crontab/jobs/my_sync/run/model
Unless disabled, they are scheduled on every cron run and can never execute,
and their pending rows are never deleted until the declaration is removed.

Delete the configuration and schedule rows of my_sync? [y/N]

Answer N to keep everything. Run with --no-interaction to skip every prompt, for example from a monitoring script. Nothing is ever deleted without a y, and the report-only checks (unclaimed config sections and tables) never prompt at all.

Table bloat and db:optimize v26.9+

A table that had many rows deleted keeps its disk space. On InnoDB the space stays inside the table file as free extents. On PostgreSQL the dead rows wait for a vacuum. On SQLite the freed pages sit on the freelist. The health check flags a table when both thresholds are met:

Bloat this size usually means rows were purged in bulk, or that a cleanup job such as ./maho log:clean is not running. Fix the cause first, then reclaim the space:

./maho db:optimize                       # scan, list the bloated tables, confirm, rebuild them
./maho db:optimize --dry-run             # print the statements without running anything
./maho db:optimize --table=log_visitor   # rebuild a table whatever its size (repeatable)
./maho db:optimize --all                 # rebuild every table
./maho db:optimize --force               # skip the confirmation, for a scripted maintenance window

The scan prints a table with the size on disk, the reclaimable estimate and the share, then asks for confirmation. After each rebuild it prints the space it freed, measured before and after.

This is a maintenance-window operation. Each backend rebuilds the data in place:

Some details that change what the numbers mean:

• MySQL reads fresh statistics from information_schema, not the daily cached ones, so the scan reflects the current state. With innodb_file_per_table off, every table lives in the shared tablespace, a rebuild never returns space to the filesystem, and the scan reports nothing with a note saying why.
• PostgreSQL infers the reclaimable space from the dead-tuple share, which is a statistics estimate. A large standing share means autovacuum is not keeping up, or is blocked by a long transaction or an abandoned replication slot. Fix that before you run VACUUM FULL by hand.
• SQLite has no per-table accounting, so the scan reports the database file as one entry.
• With a table prefix configured, only the prefixed tables are scanned and rebuilt. Other tables in a shared database are left alone.
• The command refuses to run inside an open transaction, since no backend can rebuild a table in one.

Automate it

The CLI exits with a non-zero code when a check fails, so it fits a cron job or a monitoring probe:

0 6 * * * cd /var/www/maho && ./maho health-check --no-interaction >> var/log/health-check.log 2>&1

Keep --check-zero-dates out of the scheduled run on a large store: it scans every date column of every table.