Skip to main content

Schema migration

Unlike most databases that support a single schema at a time, in Infrahub it is possible to have a different schema per branch. This is possible because the schema itself is stored in the database like any other object.

For every update to the schema, Infrahub will automatically execute some data validations and/or migrations to ensure that the data currently in the branch is compliant with the new schema.

The validations and the migrations will also be applied:

  • As part of a Proposed Change
  • During a branch rebase
  • During a branch merge
info

While a new version of the schema can be directly loaded into the main branch, the recommendation is to create a new branch and to integrate the changes into the main branch via a Proposed Change.

State: absent or present​

The format of the schema is declarative and incremental to allow schemas to be composed from multiple sources.

To remove an existing Node, Generic, Attribute or Relationship from the schema it is required to use the state: absent flag to explicitly indicate that this element must be deleted. Without this flag the element will be ignored but it will not be removed.

  - name: Rack
    namespace: Infra
    state: absent
    attributes:
      - name: name
        kind: Text
    [..]
info

The default value is state: present and doesn't have to be provided on all elements of the schema.

Remove existing text field values​

Removing an existing value for a text field of a schema node, like description or label, can be performed by specifying an empty string value for this field and re-loading the schema.

Rename existing elements​

All elements of the schema are identified by a human-readable identifier that allows schemas to be reused across environments:

  • For Node and Generic, the identifier is the Kind which is composed of namespace+name
  • For Attribute and Relationship the identifier is the name

Since namespace & name are used to identify the elements of the schema, if you need to update them after loading the schema an additional step will be required.

In order to update the human-readable identifier, it's required to temporarily provide the internal identifier of the element directly in the configuration. All Node, Generic, Attribute or Relationship have their unique identifier that can be found easily in the schema explorer in the frontend http://localhost:8000/schema. The schema explorer provides two complementary views: a list view for browsing models and inspecting their full definition, and an interactive graph view that visualizes the relationships between models. Toggle between them using the switch at the top-right of the schema page. The internal identifier should be a UUID4, with 36 characters.

  - name: Rack
    namespace: Infra
    attributes:
      - id: 76df607c-883f-4cf6-9087-353dc2d863e5
        name: rack_name
        kind: Text
    [..]

Restrictions​

Most changes to an existing schema are supported but there are a few properties that can't be updated in the current release:

  • Properties that can't be updated on a Node or a Generic: branch
  • Properties that can't be updated on an Attribute: branch
  • Properties that can't be updated on a Relationship: branch, direction, hierarchical
  • Properties that can't be updated on an Attribute inherited from a Generic: optional

A reference guide for validators and migrations is available

Known limitations​

  • When updating the identifier on a relationship, the existing relationships won't be impacted or updated even if it was the last relationship using a given identifier. ISSUE-2472
  • Updating Nodes when Generics are updated ISSUE-5793