Back up and restore

Pitot is one process and one persistent data directory. Back up the directory as a unit.

The directory holds atomic telemetry Parquet batches, rebuildable query state, and the control SQLite database. Preserve all three together.

Take a cold backup

1. Record the running version and configuration, keeping secrets out of ordinary logs and tickets.
2. Stop Pitot cleanly and wait for the process to exit. Shutdown closes the shared listener before draining the telemetry commit workers, so a clean exit leaves no accepted request waiting for publication.
3. Copy or snapshot the complete data directory, preserving ownership and permissions.
4. Start Pitot and confirm /readyz.
5. Periodically restore a backup into an isolated directory. Verify sign-in and a known telemetry query after restoring.

Not while it is running

Do not take a recursive copy of a live data directory. A storage-level snapshot is acceptable only if it gives a crash-consistent point-in-time view of the whole directory at once. A copy that walks the tree while commits publish can capture related files from different moments.

Restore

1. Stop the destination process.
2. Move any existing data directory aside. Do not merge a backup into one.
3. Restore the complete directory with its original ownership and permissions.
4. Start the same version that created the backup, then verify /readyz, sign-in, and a known telemetry query.
5. Upgrade separately, once the restored instance is known healthy.

Upgrading

Follow Upgrade for release checks, format changes and rollback.

Never delete an account from the control database

Removing a user row cascades to sessions, OAuth grants and owned dashboards. To get someone back in, use the login-link path in troubleshooting instead.