Skip to content
R2X framework logoR2X framework logor2x-core

Upgrade Systems Between Versions

r2x-core provides a framework for defining version upgrades using UpgradeStep and UpgradeType. Upgrades are staged to handle both raw data files and system objects.

Understand Upgrade Types

Section titled “Understand Upgrade Types”

r2x-core supports two types of upgrades through UpgradeType:

>>> from r2x_core import UpgradeType
>>>
>>> # FILE: Upgrade raw data files before loading into a system
>>> UpgradeType.FILE
<UpgradeType.FILE: 'FILE'>
>>>
>>> # SYSTEM: Upgrade already-loaded System objects
>>> UpgradeType.SYSTEM
<UpgradeType.SYSTEM: 'SYSTEM'>

FILE upgrades are useful when the data format or schema changes between versions. SYSTEM upgrades are useful when the system model structure changes.

Inspect Upgrade Configuration

Section titled “Inspect Upgrade Configuration”

View the UpgradeStep structure to understand how upgrades are defined:

>>> from r2x_core import UpgradeStep, UpgradeType
>>>
>>> # Create an example upgrade step definition
>>> class_name = UpgradeStep.__name__
>>> print(f"Upgrade step class: {class_name}")
Upgrade step class: UpgradeStep

Execute a single step

Section titled “Execute a single step”

Define the transformation and execute it against a small system before using it in a workflow. This example checks the returned result and changed system name:

>>> from r2x_core import System, UpgradeStep, UpgradeType, run_upgrade_step
>>> def rename(system: System) -> System:
...     system.name = "upgraded"
...     return system
>>> step = UpgradeStep(name="rename", func=rename, target_version="2.0.0", upgrade_type=UpgradeType.SYSTEM)
>>> result = run_upgrade_step(System(name="original"), step=step)
>>> result.is_ok()
True
>>> result.unwrap().name
'upgraded'

Selection, version comparison and rollback are separate concerns; see the upgrade error contract.

See Also

Section titled “See Also”