1 ADR 0003 v1 backup restore export guarantees
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0003: v1 Backup, Restore, and Export Guarantees

Status: proposed Date: 2026-05-10

Context

Memories must not become a trap for personal and family media. The backup, restore, and export model affects data ownership, migration cost, operational trust, and future compatibility.

The v1 architecture uses PostgreSQL as authoritative runtime metadata and library/stored-objects for immutable original media bytes. JSON/JSONL export is planned for inspectability and exit, but treating it as a full restore source in v1 would require import fidelity, secret handling, migration replay, worker recovery semantics, tombstones, and compatibility guarantees that are larger than the baseline slice.

Options Considered

Option Summary Benefits Costs / Risks
A PostgreSQL dump plus stored objects is fidelity restore; JSON/JSONL is inspectable export Boring, reliable, easy for self-hosters to reason about Export is not a full restore/migration source in v1
B JSON/JSONL plus stored objects is also a fidelity restore source Strong exit story Requires full importer, compatibility, tombstones, auth/secret decisions, and migration semantics too early
C Built-in scheduled backups and restore UI in v1 User-friendly High operational surface: retention, pruning, alerts, restore selection, rollback, compatibility, remote targets

Decision

Choose Option A: PostgreSQL dump plus stored objects for fidelity restore; JSON/JSONL for inspectable exit.

The v1 fidelity restore unit is:

  • A consistent PostgreSQL dump.
  • library/stored-objects/.
  • Restore-relevant configuration, secrets, app version, and schema/migration compatibility metadata.

library/derived/ is optional cache and may be regenerated. library/exports/ is optional historical export output. library/upload-staging/ is temporary and not authoritative.

The official v1 backup path requires maintenance mode or stopped write-capable services. Fully online backup is not a guaranteed v1 path.

JSON/JSONL export is a full, versioned, inspectable snapshot. It is not an authoritative v1 restore mechanism.

For the v1 baseline, export generation is Core API-owned and synchronous rather than delegated to media workers. This keeps backup/export truth at the same boundary as PostgreSQL metadata and avoids giving workers broad database-shaped export authority. Worker-backed or chunked export generation remains a future scalability path behind the Core API export contract.

v1 defers automated scheduled backups, backup retention/pruning UI, restore UI, rollback restore points, remote backup targets, and incremental export.

Restore Semantics

Restore from the fidelity unit must preserve:

  • Stored object records, checksums, and original media bytes.
  • Original assets, media items, ownership, and provenance.
  • Metadata records, user overrides, source/effective provenance, and contribution metadata snapshots.
  • Albums/events and membership.
  • Trash lifecycle state for restorable media.
  • Sharing groups, memberships, shared libraries, policies, contributions, and original download policy snapshots.
  • People/face records, assignments, merge requests, approvals, and provenance when implemented.
  • Processing issues and enough worker job state for safe recovery.

Active worker leases are not restored as active leases. On restore/startup, leased or running jobs are treated as retryable, expired, or failed according to recovery rules.

Export Semantics

v1 exports are full snapshots only. Incremental export is deferred.

Each export manifest must include:

  • Export format version.
  • Source app version.
  • Database schema/migration version.
  • Source instance identifier.
  • Snapshot/export identifier.
  • Created timestamp.
  • Included data classes.
  • Per-file checksums.
  • Compatibility notes.
  • A clear marker that v1 restore from export is not supported.

Consequences

  • The first restore story is inspectable, boring, and operationally realistic for a self-hoster.
  • Backup documentation must be explicit that a DB dump alone is insufficient because original bytes live in library/stored-objects.
  • Export remains valuable for exit/migration analysis without over-promising re-import fidelity.
  • Future work can add scheduled backups, restore UI, export import, or incremental exports behind new specs/ADRs.
  • Very large libraries may eventually need chunked or worker-assisted export generation, but v1 intentionally favors a simpler Core-owned export path for inspectability and boundary clarity.

Revisit Triggers

Revisit this decision when Memories adds automated backups, remote backup targets, restore UI, export re-import, incremental export, worker-assisted export generation, external migration tooling, online backup guarantees, or object storage backends.