# Workspace Migrations

Workspace Migrations are C# scripts designed to evolve your graph's data and schema over time. Similar to database migrations in traditional software development, they allow you to perform one-time updates, data cleanups, or schema transformations in a controlled and tracked manner.

Migrations are useful for:

Propagating schema changes (e.g., renaming fields, moving data) from development to production.
Bulk updating nodes (e.g., normalizing data formats).
Seeding initial data or configuration.
Triggering complex re-indexing or data enrichment workflows.

# Migration Task Node

Migrations are stored in the graph as nodes of type _MigrationTask. This allows the system to track their execution status and ensure they are not run multiple times unintentionally.

Admins can create, manage, trigger, and monitor the progress of migrations through the Advanced > Migrations interface in the Curiosity Workspace settings. This UI provides a way to view the status, logs, and error messages for each migration task.

# File-Based Configuration

When managing workspace customizations via file export/import (e.g., using a Git repository), migrations are stored in the code/migration-tasks directory of the export zip or folder structure.

Each migration file typically contains the metadata attributes and the code to run.

# Execution Scope

Migrations run in a specialized MigrationCodeExecutionScope. This scope provides access to the graph and utility tools necessary for performing data operations.

The following objects are available within a migration script:

Object	Type	Description
`Graph` / `G`	`Mosaik.GraphDB.Safe.Graph`	Provides thread-safe read/write access to the graph.
`Q()` / `Query()`	`IQuery`	Entry point for the fluent query builder to find data.
`Progress`	`IProgressReporter`	Use `Progress.Set(count, total)` and `Progress.Message("...")` to report status to the UI.
`Logger`	`ILogger`	Standard logging interface for information, warnings, and errors.
`CancellationToken`	`CancellationToken`	Token to check if the migration has been cancelled (`ThrowIfCancellationRequested()`).
`ChatAI`	`ChatAI`	Helper for interacting with configured AI providers.

# Lifecycle

Creation: A migration is defined (via UI or import) with Status set to Created.
Trigger: Migrations can be triggered manually via the management interface or automatically on startup if TriggerRunOnStartup is true.
Execution:
- The system compiles the MigrationCode.
- The status updates to Running.
- The code executes.
Completion:
- If successful, status becomes CompletedSuccessfully.
- If an exception occurs, status becomes Failed, and ErrorMessage is populated.

Once a migration is CompletedSuccessfully, it will not run again automatically on startup.