Relationships & Constraints
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub uses a schema-driven model to manage connections between infrastructure data nodes. Relationships define how different nodes interact, while constraints enforce data integrity across branches and temporal points. Every relationship and constraint must exist in the schema layer before the database can store associated data.
Sources: dev/constitution.md:27-31, backend/AGENTS.md:10-14
Relationship Architecture
Relationships in Infrahub connect nodes within a graph-based infrastructure topology. The schema defines relationship kinds, directionality, and identifiers to maintain a single source of truth for data structure.
Sources: specs/2026-05-schema-doc-migration.md:120-121, dev/constitution.md:29-30
Relationship Kinds and Direction
Infrahub supports multiple relationship types to model complex infrastructure. These include standard node-to-node connections and specialized hierarchical structures. Relationships include direction and identifiers to distinguish between source and destination nodes.
Sources: specs/2026-05-schema-doc-migration.md:120-121
Hierarchical Relationships
Hierarchical mode enables tree-like structures through parent and children auto-relationships. These relationships use a hierarchical discriminator in the schema to determine behavior and labeling.
- Parent Relationship: Connects a child node to its single parent.
- Children Relationship: Connects a parent node to multiple children using a cardinality of "many".
- Peer Labels: Hierarchical relationships can reflect labels derived from the peer kind (e.g., a "Site" relationship instead of a generic "Parent" label).
Sources: dev/specs/003-parent-children-labels/tasks.md:23-26, dev/specs/003-parent-children-labels/tasks.md:46-51, specs/2026-05-schema-doc-migration.md:121-125
This diagram illustrates the directional flow and cardinality between parent and child nodes in a hierarchical relationship.
Data Constraints and Integrity
Infrahub enforces strict integrity rules to prevent data corruption. All write operations must validate against the active schema for the target branch and specific point in time.
Sources: dev/constitution.md:27-35
Validation Rules
The system validates nodes, attributes, and relationships against the schema before committing writes to the database. This process includes checking uniqueness constraints and relationship cardinality.
| Constraint Type | Description | Enforcement Point |
|---|---|---|
| Uniqueness | Ensures specific attribute values are unique within a defined scope. | Pre-commit validation |
| Cardinality | Enforces the number of allowed connections for a relationship (e.g., One-to-Many). | Write mutation |
| Schema Strict Mode | Prevents the existence of data not explicitly defined in the active schema. | API/Schema Layer |
| Temporal Filter | Ensures constraints are valid for the specific point in time of the request. | Database Query |
Sources: dev/constitution.md:31-35, dev/constitution.md:46-50, specs/2026-05-schema-doc-migration.md:129-131
Branch-Aware Constraints
Every constraint operates correctly across Infrahub's branching model. Code must not assume it runs only on a default branch. All database queries include branch and temporal filters to resolve edge activity using priority ordering.
Sources: dev/constitution.md:46-52
This flowchart shows the validation sequence required to ensure data integrity during a write operation.
Relationship Schema Properties
The schema defines metadata for relationships that controls how they appear and function within the platform.
- hierarchical: A boolean flag indicating if the relationship follows parent/child logic.
- kind: Specifies the category of the relationship.
- name: The technical identifier for the relationship.
- label: The human-friendly string displayed in the UI.
- peer: Reference to the node schema at the other end of the relationship.
Sources: dev/specs/003-parent-children-labels/tasks.md:23-26, dev/specs/003-parent-children-labels/tasks.md:41-43
Peer-Derived Labeling Logic
For hierarchical relationships, the system can derive labels from the peer node kind. For example, if a "Region" node has a child "Site", the relationship label on the Site node can dynamically show "Region" instead of "Parent".
Sources: dev/specs/003-parent-children-labels/tasks.md:23-33
# Conceptual logic for relationship label derivation
def get_relationship_label(relationship_schema, peer_schema=None):
if relationship_schema.hierarchical and peer_schema and peer_schema.label:
return peer_schema.label
return relationship_schema.label or relationship_schema.name
Sources: dev/specs/003-parent-children-labels/tasks.md:41-43
Summary
Relationships and constraints form the foundation of Infrahub's data integrity model. By enforcing schema-driven validation and branch-aware constraints, Infrahub ensures that infrastructure data remains consistent and reliable across complex branching and temporal scenarios. All nodes and connections are governed by strict cardinality and uniqueness rules defined in the schema layer.