Graph Database & Data Storage

Relevant source files

The following files were used as context for generating this wiki page:

• backend/AGENTS.md
• dev/constitution.md
• dev/guidelines/backend/checklist.md
• AGENTS.md
• dev/README.md
• dev/knowledge/backend/database-schema.md
• backend/infrahub/database/neo4j.py

Infrahub uses a graph-based infrastructure data management platform to provide Git-like branching and version control for infrastructure data. The system relies on Neo4j as its primary storage engine, utilizing a temporal graph model to track changes across branches and time.

All data within Infrahub is governed by a strict schema layer. Every node, attribute, and relationship must be defined in the schema before it can persist in the database. This architecture ensures that writes validate against active schemas for specific branches and points in time, maintaining high data integrity across the entire environment.

Sources: AGENTS.md:3-5, dev/constitution.md:29-32

Core Database Architecture

Infrahub integrates with Neo4j 2026.05 using the 6.2 driver. The backend implements an async-first architecture to handle database I/O, utilizing a specialized "Query class" pattern to execute Cypher queries.

Storage Layers and Components

The database schema consists of specific vertex and edge types that facilitate temporal branching:

Component Type	Description
Root	The top-level entry point for the graph structure.
Branch	Represents a distinct version-controlled line of development.
Node	The primary data entity defined by the schema.
Relationship	Defines connections between Nodes with specific cardinality.
Attribute	Represents a property field for a Node.
AttributeValue	The specific data value stored for an Attribute at a point in time.

Sources: AGENTS.md:9-10, backend/AGENTS.md:47-51, dev/constitution.md:65-67

Data Flow Architecture

The following diagram illustrates the flow from API request to database persistence:

This diagram shows how requests are validated against the schema before the Query Class pattern executes parameterized Cypher via the Neo4j driver.

Sources: backend/AGENTS.md:6-14, dev/constitution.md:33-36

Temporal Branching Model

Infrahub treats infrastructure data like code, implementing Git-like branching. Data is "branch-safe" by default, meaning every feature must operate correctly across multiple branches and temporal points.

Resolution Logic

The system resolves edge activity and node state using a specific priority ordering to handle temporal conflicts and branch inheritance. This logic ensures that the most relevant data is retrieved based on the current context.

Resolution Priority:

1. branch_level DESC
2. from (Timestamp) DESC
3. status ASC

Sources: dev/constitution.md:41-45

Branch Integrity Principles

• Temporal Filters: All database queries must include branch and temporal filters.
• Soft-Delete: The system uses soft-delete semantics for data nodes; hard-deletes are restricted to the deletion of branches themselves.
• Cross-Branch Side Effects: Modifications to branch-agnostic nodes are explicitly controlled to prevent unintended corruption across the graph.

Sources: dev/constitution.md:46-51, dev/guidelines/backend/checklist.md:79-85

Query Design and Performance

Database queries are designed for efficiency using set-based operations to avoid performance bottlenecks.

Query Standards

• Parameterization: String interpolation of user input into Cypher is forbidden. All queries must use the $param syntax to prevent Cypher injection.
• Data Retrieval: Queries must return only specific properties rather than entire nodes or relationships to minimize the memory footprint.
• Batching: The system uses batch queries when operating on multiple nodes to avoid N+1 query patterns.
• Validation: Developers use the EXPLAIN command in Neo4j during development to validate query plans and ensure efficiency.

Sources: dev/constitution.md:88-96, dev/guidelines/backend/checklist.md:46-52

This diagram represents the standardized approach for executing database operations, emphasizing parameterization and structured return types.

Sources: dev/constitution.md:65-67, dev/constitution.md:92-94

Database Migrations

Features requiring changes to the graph structure, indexes, or constraints necessitate a database migration.

Migration Management

Migrations are stored in backend/infrahub/core/migrations/graph/. The system tracks the database state through a GRAPH_VERSION identifier.

Step	Action
1	Define the migration in the core/migrations/graph/ directory.
2	Increment the GRAPH_VERSION in backend/infrahub/core/graph/__init__.py.
3	Set the minimum_version of the new migration to the previous version.
4	Verify consistency using pytest backend/tests/unit/core/graph/test_graph_version.py.

Sources: dev/guidelines/backend/checklist.md:16-25

Integrity During Migration

Migrations must maintain graph integrity by ensuring:

• Constraints are validated before writing.
• Unique constraints are respected throughout the process.
• Relationship cardinality (e.g., required relationships) is enforced during the transition.

Sources: dev/guidelines/backend/checklist.md:27-32, dev/constitution.md:33-36

Summary

Data storage in Infrahub is defined by a rigorous schema-driven approach utilizing Neo4j's graph capabilities. By combining a temporal branching model with strict query patterns and automated migrations, the system ensures that infrastructure data remains consistent, versioned, and performant. The architecture prioritizes branch safety and injection prevention to maintain the reliability of critical infrastructure topology.

Sources: dev/constitution.md:25-28, dev/constitution.md:120-123