Plakar Storage Backend
Relevant source files
The following files were used as context for generating this wiki page:
The Plakar storage backend provides a deduplicated, content-addressable storage engine for Infrahub backups. It embeds the Plakar kloset library to manage backups as snapshots within a repository, supporting both local filesystem and S3-compatible remote storage. This backend serves as an alternative to the default compressed tarball archives, offering incremental backup capabilities that reduce storage costs by deduplicating data between backup runs.
Sources: specs/002-plakar-integration/spec.md:10-15, specs/002-plakar-integration/plan.md:7-12
Architecture and Data Flow
The Plakar implementation uses a streaming architecture to transfer data directly from Infrahub containers into a Plakar repository. This approach avoids creating intermediate temporary files on the local host during the backup process.
Backup Process
During a backup, the system creates one snapshot per component: the Neo4j database, the PostgreSQL task-manager database, and the backup metadata. Each component streams its data via exec stdout pipes directly into the Plakar snapshot builder. These snapshots are logically grouped together using a shared infrahub.backup-id tag based on a timestamp.
The diagram shows the flow of data from containerized databases through a streaming importer into the Plakar repository, where data is deduplicated.
Sources: specs/002-plakar-integration/spec.md:103-110, specs/002-plakar-integration/research.md:46-60
Restore Process
Restore operations utilize a local temporary directory. The system exports snapshots from the Plakar repository into this directory before pushing the data back into the respective database containers. This maintains compatibility with existing restore tools that expect files on disk.
Sources: specs/002-plakar-integration/spec.md:204-208, specs/002-plakar-integration/research.md:74-85
Key Components and Logic
Metadata and Tagging
Plakar snapshots use tags to store Infrahub-specific metadata. This allows for querying and grouping backups without extracting the underlying data.
| Tag Key | Description |
|---|---|
infrahub.backup-id | Shared timestamp grouping snapshots from a single run. |
infrahub.component | Identifies component type: neo4j, postgres, or metadata. |
infrahub.backup-status | Status of the backup group: complete or incomplete. |
infrahub.version | The version of Infrahub at the time of backup. |
infrahub.neo4j-edition | The edition of Neo4j (enterprise or community). |
Sources: specs/002-plakar-integration/data-model.md:54-65, specs/002-plakar-integration/spec.md:175-182
Deduplication Optimization
To maximize deduplication effectiveness, the Plakar backend requests uncompressed data from the source databases. Compressed streams are opaque to block-level deduplication because small changes in input cause large changes in the resulting compressed output.
- Neo4j Enterprise: Uses the
--compress=falseflag. - PostgreSQL: Uses the
-Fc -Z0flags to produce a custom format without compression.
Sources: specs/002-plakar-integration/spec.md:122-132, specs/002-plakar-integration/research.md:155-175
Repository Management
The backend manages the Plakar context, including the repository handle and the local cache directory used for deduplication state.
The sequence diagram illustrates the lifecycle of a Plakar repository connection during a backup operation.
Sources: src/internal/app/plakar.go:1-20, specs/002-plakar-integration/research.md:88-95
Configuration Options
The Plakar backend is opt-in and requires specific configuration to define the repository location and behavior.
| Configuration Flag | Env Variable | Default | Description |
|---|---|---|---|
--backend plakar | INFRAHUB_BACKEND | tarball | Selects the Plakar storage engine. |
--repo | INFRAHUB_REPO | N/A | Path to local dir or s3:// URI. |
--backup-id | INFRAHUB_BACKUP_ID | Latest | Specific ID for restore operations. |
--encrypt | N/A | false | Enables passphrase-protected encryption. |
Sources: specs/002-plakar-integration/data-model.md:10-20, specs/002-plakar-integration/research.md:104-125
Operational Guardrails
- Conflict Prevention: The system rejects archive-specific S3 flags (like
--s3-upload) when using the Plakar backend, requiring users to use the--repo s3://...syntax instead. - Integrity Protection: The system does not commit partial snapshots to the repository if a stream is interrupted or the process fails.
- Partial Backups: If one component fails in a multi-component backup, the successfully completed snapshots are kept but marked with
infrahub.backup-status=incomplete.
Sources: specs/002-plakar-integration/spec.md:150-155, specs/002-plakar-integration/spec.md:188-192
Summary
The Plakar Storage Backend integrates content-addressable storage into the Infrahub backup ecosystem. By streaming uncompressed database dumps directly into deduplicated snapshots, the system reduces storage overhead and disk I/O. It maintains operational safety through strict tagging conventions, metadata validation, and clear error handling for incompatible configurations.