Skip to main content

Immutability and version control

Infrahub integrate an immutable database with native support for version control that was designed with Infrastructure Management in mind.

Immutability​

Data Immutability

Immutability at the database level is the idea that information within the database cannot be deleted or changed, and that all previous version will remain accessible.

Data Immutability is a perfect match for infrastructure management as it offer a built-in audit trail of all changes and it's always possible to access the full content of the database at any previous time.

Infrahub guarantee the immutability of the default branch by default (main)

Query a previous version of the data​

It's possible to query a previous version of the database by providing a specific timestamp either via the UI, via GraphQL or via the REST API

Version control​

The implementation of version control in Infrahub is inspired by Git but also different in several ways

A branch provide a safe environment to prepare and validate a change before integrating it into the default branch by opening a Proposed Change.

Branches are meant to be short lived, from a few seconds to a few weeks, and are hierarchical by nature which means that a branch can only be merged into the branch it was created from.

Currently only a single level of hierarchy is supported, meaning that all branches must be created from the default branch and be merged into the default branch.

Create a branch​

Branches in Infrahub are designed to be lightweight, while the recommendation is to keep the lifespan of a branch short, it's possible to have 10s of branches open at the same time. When creating a branch it's possible to provide a description and define if the branch should be Data Only or not. When a branch is flagged as Data Only it won't be extended to the Read-Write Repositories. By opposition, if a branch isn't Data Only it will be automatically created in all the Read-Write repositories.

Branch names are fairly permissive, but must conform to git ref format. For example, slashes (/) are allowed, tildes (~) are not.

A branch can be created via the UI, via GraphQL, via infrahubctl or by pushing a new branch to a managed Git repository.

info

Creating a branch won't create a copy of the database, only the changes applied in the branch will be stored in order to keep track of all changes.

Create a new branch using the UI

You can create a new branch in the frontend by using the button with a + sign in the top right corner, next to the name of the current branch, i.e., main.

Create a new branch using GraphQL

Use the GraphQL mutation below to create a new branch named cr1234

mutation {
  BranchCreate(data: { name: "cr1234", sync_with_git: true}) {
    ok
    object {
      id
      name
    }
  }
}
Create a new branch using infrahubctl

Use the command below to create a new branch named cr1234

infrahubctl branch create cr1234

Changes between branches​

To view all the changes in a branch

  1. Navigate to the branch page in the menu on the left under the Change Control section (or follow this link).

Branches list

  1. Select the branch in the list of available branches.
  2. Select on the Diff button and expand the changes to view the diff between the branch and main.

Branch diff

info

Only the changes in Branch Aware mode will be displayed in the diff view and only these changes will be included in a merge operation. Check the Branch Support section in the Schema documentation for more information.

Merge a branch​

During a merge operation, only the latest modified values in the branch will be applied to the destination branch and the history of the branch won't be carried over to the main branch. This behavior is required to guarantee the immutability of the default branch.

The diagram below present how various changes to 2 objects in the Branch A will be applied to the main branch during a merge operation. After the merge operation, all changes will be accessible in main at the time of the merge operation, not at the time they were applied in the branch.

info

Using a Proposed Change to merge a branch is recommended to guarantee that all changes are valid and compliant.

Rebase a branch​

If a branch is out of sync with the default branch or if it has some conflicts, it's possible to rebase it with the latest version of the default branch. Similar to the merge operation, during a rebase only the latest modified values in the branch will be conserved and the history of the branch won't be carried over.

The diagram below present how various changes to 2 objects in the Branch A will be updated during a rebase.

Conflicts between branches​

If the same attribute or the same relationship has been modified both in a branch and in main, the conflict will need to be resolved manually before the branch can be merged.

Conflicts in a branch can be resolved as part of a Proposed Change.