Database Commands

The db command group provides comprehensive database management capabilities, including migrations, constraints, indexes, health checks, and low-level patch operations.

Command Overview

infrahubctl db [COMMAND]

migrate

Check the current format of the internal graph and apply necessary migrations.

infrahubctl db migrate [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--check`	`boolean`	Check migration status without applying	`False`
`--migration-number`	`integer`	Apply a specific migration by number	`None`

Environment Variables

INFRAHUB_CONFIG - Path to configuration file

Examples

Check Migration Status

Check what migrations need to run without applying them:

infrahubctl db migrate --check

Checking current state of the database
Database up-to-date (v10), no migration to execute.

Or if migrations are needed:

Checking current state of the database
Database needs to be updated (v10 -> v12), 2 migrations pending

Apply All Pending Migrations

Run all outstanding migrations:

infrahubctl db migrate

Checking current state of the database
Database needs to be updated (v10 -> v12), 2 migrations pending
Migration: 011_update_relationship_schema ✅
Migration: 012_add_node_metadata ✅

Apply Specific Migration

Run a specific migration regardless of current database version:

infrahubctl db migrate --migration-number 11

Migration 11 needs to be applied. Run `infrahub db migrate` to apply all outstanding migrations.
Migration: 011_update_relationship_schema ✅

Or re-apply an already applied migration:

infrahubctl db migrate --migration-number 8

Migration 8 will be re-applied.
Migration: 008_branch_hierarchy ✅

Migration Failure

If a migration fails:

Migration: 011_update_relationship_schema ❌
  Error: Constraint violation on Node.uuid
  Unable to create unique constraint

The migration process stops and reports errors. Fix the underlying issue before retrying.

check-inheritance

Check the database for vertices with incorrect inheritance and optionally fix them.

infrahubctl db check-inheritance [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--fix`	`boolean`	Fix incorrect node inheritance	`False`

Examples

Check for Inheritance Issues

infrahubctl db check-inheritance

✅ No schemas have had their inheritance updated

Or if issues are found:

Checking branch: main...done
Checking branch: feature-1...done

┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Branch     ┃ Kind             ┃ Incorrect Labels     ┃ Num Nodes ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ main       │ InfraDevice      │ ['CoreNode']         │ 15        │
│ feature-1  │ NetworkInterface │ ['InfraInterface']   │ 8         │
└────────────┴──────────────────┴──────────────────────┴───────────┘

❌ Use the --fix flag to fix the inheritance of any invalid nodes

Fix Inheritance Issues

infrahubctl db check-inheritance --fix

Checking branch: main...done
Fixing kind InfraDevice on branch main...done
Fixing kind NetworkInterface on branch feature-1...done

✅ All nodes have the correct inheritance

Note that migrations were run on the default branch for the following schema kinds: InfraDevice.
You should rebase any branches that include/will include changes using the migrated schemas

What It Checks

This command:

Identifies schemas with updated inheritance after creation
Verifies node labels match expected inheritance
Reports incorrect inheritance by branch and kind
Optionally runs migrations to fix label mismatches

check-duplicate-schema-fields

Check for duplicate schema attributes or relationships on the default branch.

infrahubctl db check-duplicate-schema-fields [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--fix`	`boolean`	Delete duplicate schema fields	`False`

Examples

Check for Duplicates

infrahubctl db check-duplicate-schema-fields

✅ No duplicate schema fields found

Or if duplicates exist:

┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Schema Kind      ┃ Schema UUID                          ┃ Field Name ┃ Field Type   ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ InfraDevice      │ 123e4567-e89b-12d3-a456-426614174000 │ name       │ attribute    │
│ InfraDevice      │ 123e4567-e89b-12d3-a456-426614174000 │ interfaces │ relationship │
└──────────────────┴──────────────────────────────────────┴────────────┴──────────────┘

❌ Use the --fix flag to fix the duplicate schema fields

Fix Duplicate Fields

infrahubctl db check-duplicate-schema-fields --fix

✅ Duplicate schema fields deleted from the default branch

The --fix option hard deletes earlier duplicates, keeping only the most recent field definition.

update-core-schema

Update the core schema to the latest version.

infrahubctl db update-core-schema [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--debug`	`boolean`	Enable debug logging	`False`

Examples

infrahubctl db update-core-schema

Core Schema Up to date, nothing to update

Or if updates are needed:

Core Schema has diff, will need to be updated
The Core Schema has been updated, make sure to rebase any open branches after the upgrade

With debug output:

infrahubctl db update-core-schema --debug

Core Schema has diff, will need to be updated
+ Added: CoreAccount.description
~ Modified: CoreRepository.location (optional: true -> false)
- Removed: (none)
The Core Schema has been updated
New schema hash: a1b2c3d4e5f6

constraint

Manage database constraints (uniqueness, existence).

infrahubctl db constraint [ACTION] [CONFIG_FILE]

Arguments

Argument	Description	Default
`ACTION`	Action to perform: `show`, `add`, or `drop`	`show`
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Examples

Show Constraints

List all database constraints:

infrahubctl db constraint show

                    Database Constraints
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Name                         ┃ Label        ┃ Property ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ node_uuid_unique             │ Node         │ uuid     │
│ attribute_uuid_unique        │ Attribute    │ uuid     │
│ relationship_uuid_unique     │ Relationship │ uuid     │
│ branch_name_unique           │ Branch       │ name     │
└──────────────────────────────┴──────────────┴──────────┘

Add Constraints

Create all defined constraints:

infrahubctl db constraint add

Adding constraints...
Created constraint: node_uuid_unique
Created constraint: attribute_uuid_unique
Created constraint: relationship_uuid_unique
Created constraint: branch_name_unique

Drop Constraints

Remove all constraints:

infrahubctl db constraint drop

Dropping constraints...
Dropped constraint: node_uuid_unique
Dropped constraint: attribute_uuid_unique

Warning: Dropping constraints can lead to data integrity issues.

index

Manage database indexes for query performance.

infrahubctl db index [ACTION] [CONFIG_FILE]

Arguments

Argument	Description	Default
`ACTION`	Action to perform: `show`, `add`, or `drop`	`show`
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Examples

Show Indexes

List all database indexes:

infrahubctl db index show

                         Database Indexes
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Name                 ┃ Label      ┃ Property       ┃ Type   ┃ Entity Type ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━┩
│ node_uuid_idx        │ Node       │ uuid           │ RANGE  │ NODE        │
│ node_kind_idx        │ Node       │ kind           │ RANGE  │ NODE        │
│ attr_name_idx        │ Attribute  │ name           │ RANGE  │ NODE        │
│ edge_branch_idx      │            │ branch         │ RANGE  │ RELATIONSHIP│
│ edge_status_idx      │            │ status         │ RANGE  │ RELATIONSHIP│
└──────────────────────┴────────────┴────────────────┴────────┴─────────────┘

Add Indexes

Create all defined indexes:

infrahubctl db index add

Adding indexes...
Created index: node_uuid_idx
Created index: node_kind_idx
Created index: attr_name_idx

Drop Indexes

Remove all indexes:

infrahubctl db index drop

Dropping indexes...
Dropped index: node_uuid_idx
Dropped index: node_kind_idx

selected-export

Export database structure of selected nodes without actual data.

infrahubctl db selected-export [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--kinds`	`list[string]`	Node kinds to export	`[]` (all)
`--uuids`	`list[string]`	Specific node UUIDs to export	`[]` (all)
`--query-limit`	`integer`	Maximum batch size	`1000`
`--export-dir`	`path`	Export directory	`infrahub-exports`

Examples

Export All Nodes

infrahubctl db selected-export

Retrieving batch of vertices and edges...done. Writing batch to export files...done.
Retrieving batch of vertices and edges...done. Writing batch to export files...done.
✅ Export complete
Export directory is here: /home/user/infrahub-exports/export-20240302-101523

Export Specific Kinds

infrahubctl db selected-export --kinds InfraDevice --kinds InfraInterface

Retrieving batch of vertices and edges...done. Writing batch to export files...done.
✅ Export complete
Export directory is here: /home/user/infrahub-exports/export-20240302-102045

Export Specific Nodes

infrahubctl db selected-export \
  --uuids 123e4567-e89b-12d3-a456-426614174000 \
  --uuids 123e4567-e89b-12d3-a456-426614174001

Custom Export Directory

infrahubctl db selected-export --export-dir /backup/db-exports

Export Format

Exports are saved as CSV files:

export-20240302-101523/
├── vertices.csv
└── edges.csv

vertices.csv:

db_id,labels,uuid,kind,namespace,name
"4:123:456","[""Node"",""InfraDevice""]","123e4567-e89b-12d3-a456-426614174000","InfraDevice","Infra","..."

edges.csv:

db_id,edge_type,start_node_id,end_node_id,branch,status,from,to
"5:234:567","HAS_ATTRIBUTE","4:123:456","4:123:789","main","active","1234567890",""

load-export

(Hidden) Load an anonymized export into Neo4j for analysis.

infrahubctl db load-export [EXPORT_DIR] [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`EXPORT_DIR`	Path to export directory	(required)
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--query-limit`	`integer`	Maximum batch size	`1000`

Example

infrahubctl db load-export infrahub-exports/export-20240302-101523

Loading vertices...
Loading 1000 [Node, InfraDevice] nodes...done
Loading 1000 [Node, InfraInterface] nodes...done
Loading 543 [Node, InfraInterface] nodes...done
Vertices loaded
Loading edges...
Loading 1000 HAS_ATTRIBUTE edges...done
Loading 1000 IS_RELATED edges...done
Loading 234 IS_PART_OF edges...done
Edges loaded
✅ Export loaded

Note: This is for analysis only, not backup/restore functionality.

check

Run database health checks and output results to CSV files.

infrahubctl db check [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--output-dir`	`path`	Directory for detailed results	`infrahub_db_check_<timestamp>`

Examples

Run All Health Checks

infrahubctl db check

Running database health checks...

Check 1: Duplicate Active Relationships
✅ No duplicate active relationships found

Check 2: Duplicated Relationship Nodes
✅ No duplicated relationship nodes found

Check 3: Duplicated Edges
Found 3 sets of duplicated edges
  Detailed results written to: infrahub_db_check_20240302-101523/duplicated_edges.csv

Check 4: Orphaned Relationships
✅ No orphaned relationships found

✅ Database health checks completed
Detailed results saved to: /home/user/infrahub_db_check_20240302-101523

Custom Output Directory

infrahubctl db check --output-dir /var/log/infrahub/db-checks

Check Types

The command runs four checks:

Duplicate Active Relationships - Finds multiple active relationship paths between the same nodes
Duplicated Relationship Nodes - Identifies relationship nodes with duplicate UUIDs
Duplicated Edges - Detects duplicate edges between vertices
Orphaned Relationships - Finds relationship nodes with fewer than 2 peers

Output Files

Results are saved as CSV files in the output directory:

duplicate_active_relationships.csv
duplicated_relationship_nodes.csv
duplicated_edges.csv
orphaned_relationships.csv

Example duplicated_edges.csv:

a_id,a_labels,b_id,b_labels,e_type,branch,status,time,num_edges
"4:123:456","[""Node""]","4:123:789","[""Attribute""]","HAS_ATTRIBUTE","main","active","1234567890",2

patch

Commands for planning, applying, and reverting database patches.

infrahubctl db patch [COMMAND]

patch plan

Create a patch plan from a PatchQuery and optionally apply it.

infrahubctl db patch plan [PATCH_PATH] [OPTIONS] [CONFIG_FILE]

Arguments

Argument	Description	Default
`PATCH_PATH`	Python path to PatchQuery class	(required)
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Options

Option	Type	Description	Default
`--patch-plans-dir`	`path`	Patch plans directory	`infrahub-patches`
`--apply`	`boolean`	Apply patch immediately after creating	`False`

Examples

Create a patch plan:

infrahubctl db patch plan infrahub.patch.queries.fix_branch_hierarchy

✅ Patch plan created at infrahub-patches/fix_branch_hierarchy_20240302_101523

Create and apply immediately:

infrahubctl db patch plan infrahub.patch.queries.fix_branch_hierarchy --apply

✅ Patch plan created at infrahub-patches/fix_branch_hierarchy_20240302_101523
✅ Patch plan successfully applied

patch apply

Apply a previously created patch plan.

infrahubctl db patch apply [PATCH_PLAN_DIR] [CONFIG_FILE]

Arguments

Argument	Description	Default
`PATCH_PLAN_DIR`	Path to patch plan directory	(required)
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Example

infrahubctl db patch apply infrahub-patches/fix_branch_hierarchy_20240302_101523

✅ Patch plan successfully applied

patch revert

Revert a previously applied patch plan.

infrahubctl db patch revert [PATCH_PLAN_DIR] [CONFIG_FILE]

Arguments

Argument	Description	Default
`PATCH_PLAN_DIR`	Path to patch plan directory	(required)
`CONFIG_FILE`	Path to configuration file	`infrahub.toml`

Example

infrahubctl db patch revert infrahub-patches/fix_branch_hierarchy_20240302_101523

✅ Patch plan successfully reverted

Patch Workflow

Typical patch workflow:

Create PatchQuery class defining the changes
Generate patch plan with patch plan
Review the plan files
Apply with patch apply or use --apply flag
If needed, revert with patch revert

Patch Plan Structure

Patch plans are saved as directories:

infrahub-patches/
└── fix_branch_hierarchy_20240302_101523/
    ├── plan.json
    ├── vertices_add.json
    ├── vertices_update.json
    ├── edges_add.json
    └── edges_update.json

Documentation Index

​Command Overview

​migrate

​Arguments

​Options

​Environment Variables

​Examples

​Check Migration Status

​Apply All Pending Migrations

​Apply Specific Migration

​Migration Failure

​check-inheritance

​Arguments

​Options

​Examples

​Check for Inheritance Issues

​Fix Inheritance Issues

​What It Checks

​check-duplicate-schema-fields

​Arguments

​Options

​Examples

​Check for Duplicates

​Fix Duplicate Fields

​update-core-schema

​Arguments

​Options

​Examples

​constraint

​Arguments

​Examples

​Show Constraints

​Add Constraints

​Drop Constraints

​index

​Arguments

​Examples

​Show Indexes

​Add Indexes

​Drop Indexes

​selected-export

​Arguments

​Options

​Examples

​Export All Nodes

​Export Specific Kinds

​Export Specific Nodes

​Custom Export Directory

​Export Format

​load-export

​Arguments

​Options

​Example

​check

​Arguments

​Options

​Examples

​Run All Health Checks

​Custom Output Directory

​Check Types

​Output Files

​patch

​patch plan

​Arguments

​Options

​Examples

​patch apply

​Arguments

​Example

​patch revert

​Arguments

​Example

​Patch Workflow

​Patch Plan Structure

​See Also

Command Overview

migrate

Arguments

Options

Environment Variables

Examples

Check Migration Status

Apply All Pending Migrations

Apply Specific Migration

Migration Failure

check-inheritance

Arguments

Options

Examples

Check for Inheritance Issues

Fix Inheritance Issues

What It Checks

check-duplicate-schema-fields

Arguments

Options

Examples

Check for Duplicates

Fix Duplicate Fields

update-core-schema

Arguments

Options

Examples

constraint

Arguments

Examples

Show Constraints

Add Constraints

Drop Constraints

index

Arguments

Examples

Show Indexes

Add Indexes

Drop Indexes

selected-export

Arguments

Options

Examples

Export All Nodes

Export Specific Kinds

Export Specific Nodes

Custom Export Directory

Export Format

load-export

Arguments

Options

Example

check

Arguments

Options

Examples

Run All Health Checks

Custom Output Directory

Check Types

Output Files

patch

patch plan

Arguments

Options

Examples

patch apply

Arguments

Example

patch revert

Arguments

Example

Patch Workflow

Patch Plan Structure

See Also