Skip to main content
Version: v5.7.0

opschain admin migrate-logs

Included from Basic tier

The control plane of the historical log_lines backfill: on a drop-in estate the adopted log_lines table can hold years of step, workflow and node-background-task output, and this lane re-encodes it, one owning attempt at a time, into the sealed segments and blob store the v2 log reads (ReadLogLines / FollowLogs replay) serve — original timestamps preserved, so retention math holds across the move.

Every verb only flips durable server-side state and returns: the worker runs INSIDE the server as a cluster-singleton on the cron leader, resumes from its cursor across restarts and failovers, and your laptop leaving changes nothing. Reads dual-serve throughout — a migrated owner is served from segments, an unmigrated one from log_lines — so there is no dark window.

The migration never deletes log_lines. It copies and verifies: per owner, the line count and a content digest are compared source against the stored segments, and the verdict lands in the log_migration_evidence table. Deletion is the separate purge verb, which an operator runs once the blob store is confirmed accurate and captured by backups — it deletes only owners holding a verified evidence row and refuses while nothing is verified.

SubcommandPurpose
statusPhase states, counters and the row estimate — opschain docs cli/admin-migrate-logs-status.
startStart (or restart) the migrate-and-verify sweep — opschain docs cli/admin-migrate-logs-start.
pausePause the active phase — opschain docs cli/admin-migrate-logs-pause.
resumeResume the paused phase from its cursor — opschain docs cli/admin-migrate-logs-resume.
purgeDelete source rows for verified owners only — opschain docs cli/admin-migrate-logs-purge.

The verbs authenticate with the admin bearer, resolved like every fleet verb: --auth-token, then OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login; the server from --server, OPSCHAIN_SERVER or the active context. The backfill requires the PostgreSQL store — on an embedded SQLite server the verbs answer a named precondition error, since only adopted estates carry log_lines.

Progress is visible from any machine via status (-o json for scripting) and in the audit trail: lifecycle events (api:logs:migration) record started/paused/resumed/completed with the completion verdict, and warn:logs:migration records skipped or failed owners. There is deliberately no GUI screen — the lane serves migrating estates only.

Space posture​

During the migration each verified owner is stored twice — the compressed segment beside its source rows — until the operator purges; at rest after the purge the estate is far smaller (compressed blobs vs a row per line). Budget roughly the compressed size of the historical log bytes as transient extra storage, and expect purge churn to need autovacuum headroom on log_lines (the scheduled admin database vacuum lane covers it — log_lines is in the default churn set).

See also​

  • opschain docs cli/admin-database-vacuum — reclaiming log_lines space after a purge.
  • opschain docs events — the api:logs:migration / warn:logs:migration lifecycle events.