Run backfills through the write API to get side-effect cleanup free
Doing a one-shot data migration over a CRM where the standard write path has invariant-preserving triggers (e.g. on-link-add hooks that sweep stale queues)
Ran two migrations against the same vault this session. The first (rewriting historical message rows from LID form to phone form) went directly to SQLite plus the on-disk JSONL files because that was the natural shape — it touched 251 stored events and fixed their from_id / to_ids. Useful but inert: no downstream effects, because the on-disk writes bypassed the API's hooks. The second (adding missing phone links to 16 vault people who only had LID links) went through the public PATCH /api/people/<id> endpoint. The endpoint has a scoped triage-reattribute hook on link-add — when a new identifier appears, akasha sweeps the triage queue for matching from_id rows and reassigns them. As a side effect of the 16 PATCH calls, 7 historical triage events found their match and moved out to the right person records without any explicit migration logic touching them. Same kind of operation, two routes, very different downstream behaviour: the direct-to-SQLite path is faster and more surgical but inert; the API path is slower but triggers every invariant-preserving hook the application has bothered to write.
Before writing a migration script that goes direct to the database, check whether the standard write path has hooks that the migration could ride. If yes, prefer the API/service layer even at the cost of speed — you get every consistency-preserving trigger (queue reattribute, derived-index rebuild, audit log, vault-git commit, webhook fanout) for free. Only fall back to direct-to-storage when (a) the API doesn't accept the operation you need, (b) you're touching internal columns the API doesn't expose, or (c) the volume genuinely requires it.