Repository navigation
Description
Overview
A completed archive becomes a compact file at its final path, and all temporary files and locks are removed. This issue is part of milestone M5 (archive).
Background & Motivation
During export, morango writes the archive to <path>.partial. The final path must exist only when the export completed. A reader can then trust that a file at the final path is a complete archive.
The dequeue step moves rows from Buffer to Store in the archive. This leaves free pages in the file. VACUUM reclaims them, but it needs up to twice the file size in free space. The target disk does not always have this space. The archive uses incremental auto-vacuum instead, which reclaims pages in place.
Design: spec. Plan: implementation plan, Task 21.
Description & Expected Outcomes
The archive keeps its manifest as a typed value. A write of a new manifest replaces all manifest entries.
When the archive is finalized, the archive records completed_at in the manifest and reclaims free pages. Then the archive closes its connection and removes the archive alias. It renames <path>.partial to <path> and releases the archive lock.
After finalization, a call to discard does nothing. The final file stays in place.
Deliverables & Contracts
The feature delivers these capabilities:
Archive.write_manifest(manifest)replaces all manifest entries.Archive.manifestreturns the current manifest value.Archive.finalize()produces the final file and cleans up all temporary state.
Acceptance Criteria
- After
finalize,pathexists, and<path>.partial,<path>.partial-journaland<path>.lockdo not exist. - After
finalize, the archive alias is not inconnections.databases, andfinalizedisTrue. - A reopened archive shows
completed_atset, and all other manifest fields are unchanged. - If 5,000 buffer rows are inserted and deleted before
finalize, the final file is smaller than the partial file beforefinalize. - A call to
discardafterfinalizedoes not change or delete the final file. - The rename test passes in the
windowstox environment.
Technical Pointers & Architecture
- Target Components / Context:
morango/sync/archive.py(Archive,ArchiveManifest). - Related Patterns: Spec §3.5 describes the finalize sequence.
- Data Model & Schema Considerations: Uses
ArchiveManifestEntryrows from Store archive metadata in a morango table #376. No new schema. - Resilience & Failure Modes: If finalization fails, the export fails. The caller calls
close(), which discards the partial file. There is no resume before Phase 3.
Notes & Tradeoffs
- Dependencies: Blocked by: Give archive metadata a typed, immutable form #377 (
ArchiveManifestvalue object), Create and discard an archive database file #378 (Archive.createanddiscard), Prevent two exports to the same archive path #379 (archive lock). Blocks: Start and close sync sessions with a disk connection #383. - Testing Requirements: Unit tests in
tests/testapp/tests/sync/test_archive.py. Mark the rename test with@pytest.mark.windows. - Tradeoffs & Alternatives Considered: The spec rejects
VACUUMat finalize because of its free-space cost. - Compatibility & Migrations:
auto_vacuum=INCREMENTALis set when the archive is created, before any table exists (Create and discard an archive database file #378).
Metadata
- Complexity: Medium
- Target Branch: release-v0.9.x
AI Usage
Drafted with Claude (Claude Code) from the approved design spec and implementation plan. The author reviewed the requirements, and the code references were checked against the release-v0.9.x codebase.
Activity
ArpitaSamanta10 commentedon Nov 19, 2026
@bjester
I would love to work on this issue can you assign this for me
/assign
learning-equality-bot commentedon Nov 19, 2026
Hi! 👋
Thanks so much for your interest! This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues. If there are no unassigned 'help wanted' issues available, please wait until new ones are added.
We really appreciate your willingness to help. 😊
Are you preparing for Google Summer of Code? See our GSoC guidelines.