documentation

Databases & snapshots

One embedded MariaDB, one database per site. SQL from the command line, dumps in and out, and a restore point saved before anything destructive.

The db command

agent-local db SLUG                            # connection details
agent-local db SLUG "SELECT * FROM wp_users"   # run a statement
agent-local db SLUG tables                     # list tables
agent-local db SLUG gui                        # open Adminer
agent-local db SLUG search efront.dev          # where a string still lives: table, column, count
agent-local db SLUG search-replace old new --apply   # dry run without --apply
agent-local db SLUG import dump.sql.gz         # replace contents; snapshot first
agent-local db SLUG export [FILE]              # dump to a file
agent-local db SLUG reset                      # empty it (grants kept)

Imports and restores stream through the same collation-fixing loader as site imports, so dump size does not matter. On a WordPress site URLs are rewritten on import unless --keep-urls says otherwise; other kinds load as-is. Adminer is one click away at https://SLUG.test/.agent-local — the tools page every site carries, local only.

Snapshots

agent-local db SLUG snapshot [NAME]    # save a restore point
agent-local db SLUG snapshots          # list them
agent-local db SLUG restore [NAME]     # default: the newest
  • Automatic before every destructive operation — db import, db reset, restore and delete each save the current contents first. A snapshot that fails stops the operation.
  • Written atomically — a snapshot is streamed to a temp file and renamed into place, so a crash mid-write never leaves a half-file the list would call healthy.
  • A failed restore rolls itself back — if the dump being restored will not load, the snapshot taken moments before is put back automatically. A bad file cannot leave you with an empty database.
  • Plain `.sql.gz` — loadable anywhere, not a private format.
  • The pre-delete snapshot survives the site — recreate and restore, or import it into a different site.

Checkpoints

agent-local checkpoint SLUG before-updates     # database snapshot + copy-on-write clone of wp-content
agent-local checkpoint SLUG --scope all         # …or the whole docroot
agent-local checkpoint SLUG --list
agent-local rollback SLUG 20260904-183000-before-updates

A checkpoint is files and database together under one name — the save-point to take before a risky plugin update or migration. On APFS the file copy is a clone: seconds and near-zero space regardless of size. A rollback restores both and restarts the pool; what was there is kept beside the checkpoint as pre-rollback-<time>, so a rollback is itself undoable. Non-WordPress sites checkpoint the whole docroot.