Neo4j Database Handling
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub-backup manages Neo4j database operations through specialized workflows tailored to different Neo4j editions and deployment environments. The system handles backup creation, metadata generation, and restoration while accounting for the architectural differences between Neo4j Community and Enterprise editions.
The primary goal of Neo4j database handling is to ensure data integrity across consistent backup snapshots. The tool integrates with Docker Compose and Kubernetes to orchestrate container states, especially when dealing with editions that require service interruptions for consistent dumping.
Sources: AGENTS.md, src/internal/app/backup.go:94-106
Neo4j Edition Detection
The application determines the Neo4j edition at runtime to select the appropriate backup or restore strategy. It executes a Cypher query through the cypher-shell within the database container to identify the edition.
This diagram illustrates the process Infrahub-backup uses to identify which Neo4j edition is active.
Sources: src/internal/app/backup_metadata.go:68-87
Edition Identification Logic
- Command:
cypher-shell -u <user> -p <pass> -d system --format plain "CALL dbms.components() YIELD edition" - Normalization: The tool converts the output to lowercase and trims whitespace or quotes.
- Fallback: If detection fails, the system defaults to the community edition workflow for safety.
Sources: src/internal/app/backup_metadata.go:42-53, src/internal/app/backup_metadata.go:89-105
Backup Workflows
Backup procedures vary significantly based on the detected Neo4j edition. Enterprise edition supports online backups, whereas Community edition requires stopping application containers to perform a consistent file dump.
Edition-Specific Procedures
| Edition | Consistency Method | Implementation Detail |
|---|---|---|
| Enterprise | Online Backup | Uses neo4j-admin backup or neo4j-admin database backup |
| Community | Offline Dump | Stops Infrahub containers, then uses neo4j-admin dump |
Sources: src/internal/app/backup.go:94-106, src/internal/app/backup_neo4j.go:13-33
Community Edition Workflow
When Community Edition is detected, the InfrahubOps controller manages a 10-second safety delay to allow user intervention before stopping services. It stops application containers, performs the database dump, and ensures services restart regardless of the backup outcome.
Sources: src/internal/app/backup.go:101-140
The sequence shows the container orchestration required for Community edition backups.
Sources: src/internal/app/backup.go:124-140
Restoration Logic
Restoration requires strict compatibility between the backup artifact and the target Neo4j instance. The ResolveRestoreEdition function prevents incompatible operations, such as attempting to restore an Enterprise backup onto a Community edition instance.
Sources: src/internal/app/backup_metadata.go:56-66
Restore Compatibility Matrix
| Backup Edition | Target Edition | Outcome |
|---|---|---|
| Community | Enterprise | Allowed (Uses community restore method) |
| Enterprise | Community | Blocked (Throws error) |
| Community | Community | Allowed |
| Enterprise | Enterprise | Allowed |
Sources: src/internal/app/backup_metadata.go:58-65
Data Integrity and Metadata
Every Neo4j backup includes structured metadata and checksums to ensure the archive remains valid during transit and storage.
Metadata Schema
The BackupMetadata struct tracks essential database details:
Neo4jEdition: The edition active during backup creation.Components: A list of included backup items (e.g., "database").Checksums: A map of relative file paths to their SHA256 hashes.
Sources: src/internal/app/backup_metadata.go:18-30, src/internal/app/backup_metadata.go:118-128
Checksum Validation
The system calculates checksums for all files within the database directory during backup creation. During restore, it recalculates these hashes and compares them against the metadata to detect corruption.
Sources: src/internal/app/backup_checksums.go:17-49, src/internal/app/backup_checksums.go:73-95
Neo4j Watchdog
For specific environments, the project includes a neo4j_watchdog binary. This tool assists in monitoring the database state or ensuring operations complete correctly within Kubernetes or Docker environments. The watchdog is built and included in the release container images.
Sources: specs/001-k8s-helm-backup/plan.md:55-58, AGENTS.md:120-125
Summary
Neo4j Database Handling in Infrahub-backup is a multi-edition strategy that prioritizes data consistency. By automating edition detection, the tool seamlessly manages the transition between online Enterprise backups and the coordinated container stops required for Community edition dumps. This architecture, supported by strict metadata validation and checksumming, ensures that database restores are both safe and reliable across different deployment backends.