Struct Migrator

Source

pub struct Migrator { /* private fields */ }

Expand description

The migration manager that orchestrates all migrations.

Implementations§

Source §

impl Migrator

Source

pub fn new() -> Self

Creates a new, empty migrator.

Source

pub fn builder() -> MigratorBuilder

Creates a builder for configuring the migrator.

§Example

let migrator = Migrator::builder()
    .default_version_key("schema_version")
    .default_data_key("payload")
    .build();

Source

pub fn define(entity: &str) -> MigrationPathBuilder<Start>

Starts defining a migration path for an entity.

Source

pub fn register<D>( &mut self, path: MigrationPath<D>, ) -> Result<(), MigrationError>

Registers a migration path with validation.

This method validates the migration path before registering it:

Checks for circular migration paths
Validates version ordering follows semver rules

§Errors

Returns an error if validation fails.

Source

pub fn load_from<D, T>( &self, entity: &str, data: T, ) -> Result<D, MigrationError>
where D: DeserializeOwned, T: Serialize,

Loads and migrates data from any serde-compatible format.

This is the generic version that accepts any type implementing Serialize. For JSON strings, use the convenience method load instead.

§Arguments

entity - The entity name used when registering the migration path
data - Versioned data in any serde-compatible format (e.g., toml::Value, serde_json::Value)

§Returns

The migrated data as the domain model type

§Errors

Returns an error if:

The data cannot be converted to the internal format
The entity is not registered
A migration step fails

§Example

// Load from TOML
let toml_data: toml::Value = toml::from_str(toml_str)?;
let domain: TaskEntity = migrator.load_from("task", toml_data)?;

// Load from JSON Value
let json_data: serde_json::Value = serde_json::from_str(json_str)?;
let domain: TaskEntity = migrator.load_from("task", json_data)?;

Source

pub fn load<D: DeserializeOwned>( &self, entity: &str, json: &str, ) -> Result<D, MigrationError>

Loads and migrates data from a JSON string.

This is a convenience method for the common case of loading from JSON. For other formats, use load_from instead.

§Arguments

entity - The entity name used when registering the migration path
json - A JSON string containing versioned data

§Returns

The migrated data as the domain model type

§Errors

Returns an error if:

The JSON cannot be parsed
The entity is not registered
A migration step fails

§Example

let json = r#"{"version":"1.0.0","data":{"id":"task-1","title":"My Task"}}"#;
let domain: TaskEntity = migrator.load("task", json)?;

Source

pub fn load_flat<D: DeserializeOwned>( &self, entity: &str, json: &str, ) -> Result<D, MigrationError>

Loads and migrates data from a flat format JSON string.

This is a convenience method for loading from flat format JSON where the version field is at the same level as the data fields.

§Arguments

entity - The entity name used when registering the migration path
json - A JSON string containing versioned data in flat format

§Returns

The migrated data as the domain model type

§Errors

Returns an error if:

The JSON cannot be parsed
The entity is not registered
A migration step fails

§Example

let json = r#"{"version":"1.0.0","id":"task-1","title":"My Task"}"#;
let domain: TaskEntity = migrator.load_flat("task", json)?;

Source

pub fn load_flat_from<D, T>( &self, entity: &str, value: T, ) -> Result<D, MigrationError>
where D: DeserializeOwned, T: Serialize,

Loads and migrates data from any serde-compatible format in flat format.

This method expects the version field to be at the same level as the data fields. It uses the registered migration path’s runtime-configured keys (respecting the Path > Migrator > Trait priority).

§Arguments

entity - The entity name used when registering the migration path
value - A serde-compatible value containing versioned data in flat format

§Returns

The migrated data as the domain model type

§Errors

Returns an error if:

The entity is not registered
The data format is invalid
A migration step fails

§Example

let toml_value: toml::Value = toml::from_str(toml_str)?;
let domain: TaskEntity = migrator.load_flat_from("task", toml_value)?;

Source

pub fn save<T: Versioned + Serialize>( &self, data: T, ) -> Result<String, MigrationError>

Saves versioned data to a JSON string.

This method wraps the provided data with its version information and serializes it to JSON format. The resulting JSON can later be loaded and migrated using the load method.

§Arguments

data - The versioned data to save

§Returns

A JSON string with the format: {"version":"x.y.z","data":{...}}

§Errors

Returns SerializationError if the data cannot be serialized to JSON.

§Example

let task = TaskV1_0_0 {
    id: "task-1".to_string(),
    title: "My Task".to_string(),
};

let migrator = Migrator::new();
let json = migrator.save(task)?;
// json: {"version":"1.0.0","data":{"id":"task-1","title":"My Task"}}

Source

pub fn save_flat<T: Versioned + Serialize>( &self, data: T, ) -> Result<String, MigrationError>

Saves versioned data to a JSON string in flat format.

Unlike save(), this method produces a flat JSON structure where the version field is at the same level as the data fields, not wrapped in a separate object.

§Arguments

data - The versioned data to save

§Returns

A JSON string with the format: {"version":"x.y.z","field1":"value1",...}

§Errors

Returns SerializationError if the data cannot be serialized to JSON.

§Example

let task = TaskV1_0_0 {
    id: "task-1".to_string(),
    title: "My Task".to_string(),
};

let migrator = Migrator::new();
let json = migrator.save_flat(task)?;
// json: {"version":"1.0.0","id":"task-1","title":"My Task"}

Source

pub fn load_vec_from<D, T>( &self, entity: &str, data: Vec<T>, ) -> Result<Vec<D>, MigrationError>
where D: DeserializeOwned, T: Serialize,

Loads and migrates multiple entities from any serde-compatible format.

This is the generic version that accepts any type implementing Serialize. For JSON arrays, use the convenience method load_vec instead.

§Arguments

entity - The entity name used when registering the migration path
data - Array of versioned data in any serde-compatible format

§Returns

A vector of migrated data as domain model types

§Errors

Returns an error if:

The data cannot be converted to the internal format
The entity is not registered
Any migration step fails

§Example

// Load from TOML array
let toml_array: Vec<toml::Value> = /* ... */;
let domains: Vec<TaskEntity> = migrator.load_vec_from("task", toml_array)?;

// Load from JSON Value array
let json_array: Vec<serde_json::Value> = /* ... */;
let domains: Vec<TaskEntity> = migrator.load_vec_from("task", json_array)?;

Source

pub fn load_vec<D: DeserializeOwned>( &self, entity: &str, json: &str, ) -> Result<Vec<D>, MigrationError>

Loads and migrates multiple entities from a JSON array string.

This is a convenience method for the common case of loading from a JSON array. For other formats, use load_vec_from instead.

§Arguments

entity - The entity name used when registering the migration path
json - A JSON array string containing versioned data

§Returns

A vector of migrated data as domain model types

§Errors

Returns an error if:

The JSON cannot be parsed
The entity is not registered
Any migration step fails

§Example

let json = r#"[
    {"version":"1.0.0","data":{"id":"task-1","title":"Task 1"}},
    {"version":"1.0.0","data":{"id":"task-2","title":"Task 2"}}
]"#;
let domains: Vec<TaskEntity> = migrator.load_vec("task", json)?;

Source

pub fn load_vec_flat<D: DeserializeOwned>( &self, entity: &str, json: &str, ) -> Result<Vec<D>, MigrationError>

Loads and migrates multiple entities from a flat format JSON array string.

This is a convenience method for loading from a JSON array where each element has the version field at the same level as the data fields.

§Arguments

entity - The entity name used when registering the migration path
json - A JSON array string containing versioned data in flat format

§Returns

A vector of migrated data as domain model types

§Errors

Returns an error if:

The JSON cannot be parsed
The entity is not registered
Any migration step fails

§Example

let json = r#"[
    {"version":"1.0.0","id":"task-1","title":"Task 1"},
    {"version":"1.0.0","id":"task-2","title":"Task 2"}
]"#;
let domains: Vec<TaskEntity> = migrator.load_vec_flat("task", json)?;

Source

pub fn load_vec_flat_from<D, T>( &self, entity: &str, data: Vec<T>, ) -> Result<Vec<D>, MigrationError>
where D: DeserializeOwned, T: Serialize,

Loads and migrates multiple entities from any serde-compatible format in flat format.

This method expects each element to have the version field at the same level as the data fields. It uses the registered migration path’s runtime-configured keys (respecting the Path > Migrator > Trait priority).

§Arguments

entity - The entity name used when registering the migration path
data - Vector of serde-compatible values in flat format

§Returns

A vector of migrated data as domain model types

§Errors

Returns an error if:

The entity is not registered
The data format is invalid
Any migration step fails

§Example

let toml_array: Vec<toml::Value> = /* ... */;
let domains: Vec<TaskEntity> = migrator.load_vec_flat_from("task", toml_array)?;

Source

pub fn save_vec<T: Versioned + Serialize>( &self, data: Vec<T>, ) -> Result<String, MigrationError>

Saves multiple versioned entities to a JSON array string.

This method wraps each item with its version information and serializes them as a JSON array. The resulting JSON can later be loaded and migrated using the load_vec method.

§Arguments

data - Vector of versioned data to save

§Returns

A JSON array string where each element has the format: {"version":"x.y.z","data":{...}}

§Errors

Returns SerializationError if the data cannot be serialized to JSON.

§Example

let tasks = vec![
    TaskV1_0_0 {
        id: "task-1".to_string(),
        title: "Task 1".to_string(),
    },
    TaskV1_0_0 {
        id: "task-2".to_string(),
        title: "Task 2".to_string(),
    },
];

let migrator = Migrator::new();
let json = migrator.save_vec(tasks)?;
// json: [{"version":"1.0.0","data":{"id":"task-1",...}}, ...]

Source

pub fn save_vec_flat<T: Versioned + Serialize>( &self, data: Vec<T>, ) -> Result<String, MigrationError>

Saves multiple versioned entities to a JSON array string in flat format.

This method serializes each item with the version field at the same level as the data fields, not wrapped in a separate object.

§Arguments

data - Vector of versioned data to save

§Returns

A JSON array string where each element has the format: {"version":"x.y.z","field1":"value1",...}

§Errors

Returns SerializationError if the data cannot be serialized to JSON.

§Example

let tasks = vec![
    TaskV1_0_0 {
        id: "task-1".to_string(),
        title: "Task 1".to_string(),
    },
    TaskV1_0_0 {
        id: "task-2".to_string(),
        title: "Task 2".to_string(),
    },
];

let migrator = Migrator::new();
let json = migrator.save_vec_flat(tasks)?;
// json: [{"version":"1.0.0","id":"task-1",...}, ...]