Skip to main content

Migrations

This item is only intended to be used by the module's authors. Private

Provides functionality for managing and applying data migrations.

Concept: As data schemas evolve over time, older data stored in DataStores needs to be updated to match the new structure. This module allows defining a series of migration steps (Types.MigrationStep) that transform data from one version of the schema to the next.

Workflow:

  1. Define migration steps using helpers like makeAddFieldsStep or makeTransformStep. Each step must have a unique name.
  2. Provide the list of steps to the Store via StoreContext.
  3. When data is loaded (Session:load), the apply function in this module is called.
  4. apply compares the list of all defined steps against the appliedMigrations list stored within the DataStoreRecord.
  5. It executes the apply function of any step that hasn't been applied yet, in the order they are defined.
  6. The apply function of each step receives the current data and returns the transformed data.
  7. The names of successfully applied steps are added to the appliedMigrations list, which is then saved back to the DataStoreRecord.

Idempotency: The system ensures migrations are idempotent (applying them multiple times has the same effect as applying them once) by checking the appliedMigrations list before running a step.

Error Handling: Each step's apply function is executed within a pcall to catch errors. If a step fails, the migration process stops, and the error is propagated.

Types​

ApplyParams​

</>
interface ApplyParams {
logger: Log.Logger--

Logger instance for logging migration progress and errors.

data: Data--

The current data loaded from the DataStore record's File.

steps: {Types.MigrationStep}--

The list of all defined migration steps for the store.

appliedMigrations: {string}--

The list of names of migration steps already applied to this specific data record, loaded from the DataStoreRecord.

}

Parameters for the apply function.

ApplyResult​

</>
interface ApplyResult {
data: Data--

The potentially modified data after applying necessary migration steps.

appliedMigrations: {string}--

The updated list of applied migration names, including any newly applied steps. This should be saved back to the DataStoreRecord.

}

Result returned by the apply function upon successful completion.

Functions​

validate​

</>
Migrations.validate(
steps: {Types.MigrationStep}--

The list of migration steps to validate.

) → ()

Validates that the provided migration steps adhere to the expected structure.

Errors

TypeDescription
stringThrows an error if any step is malformed.

makeAddFieldsStep​

</>
Migrations.makeAddFieldsStep(
name: string,--

The unique name for this migration step.

fields: Data--

A table containing the new fields and their default values.

) → Types.MigrationStep--

A migration step object.

Helper function to create a common type of migration step: adding new fields with default values to existing data. Uses a deep merge strategy.

makeTransformStep​

</>
Migrations.makeTransformStep(
name: string,--

The unique name for this migration step.

transformFunc: (currentValue: Data) → Data--

The function that takes the current data and returns the transformed data.

) → Types.MigrationStep--

A migration step object.

Helper function to create a migration step that applies a custom transformation function to the data.

apply​

</>
Migrations.apply(
params: ApplyParams--

The parameters for applying migrations.

) → Promise<ApplyResult>--

A Promise that resolves with the updated data and the new list of applied migration names.

Applies pending migration steps to the data.

Iterates through the defined steps and applies any step whose name is not present in the appliedMigrations list. Ensures idempotency and uses pcall for safe execution of each step's apply function.

Errors

TypeDescription
stringRejects if any migration step fails during `pcall`.

getStepNames​

</>
Migrations.getStepNames(
migrations: {Types.MigrationStep}--

The list of migration steps.

) → {string}--

A list containing only the names of the migration steps.

Utility function to extract just the names from a list of migration steps.

Show raw api
{
    "functions": [
        {
            "name": "validate",
            "desc": "Validates that the provided migration steps adhere to the expected structure.",
            "params": [
                {
                    "name": "steps",
                    "desc": "The list of migration steps to validate.",
                    "lua_type": "{Types.MigrationStep}"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "string",
                    "desc": "Throws an error if any step is malformed."
                }
            ],
            "source": {
                "line": 54,
                "path": "src/Migrations.luau"
            }
        },
        {
            "name": "makeAddFieldsStep",
            "desc": "Helper function to create a common type of migration step: adding new fields\nwith default values to existing data. Uses a deep merge strategy.",
            "params": [
                {
                    "name": "name",
                    "desc": "The unique name for this migration step.",
                    "lua_type": "string"
                },
                {
                    "name": "fields",
                    "desc": "A table containing the new fields and their default values.",
                    "lua_type": "Data"
                }
            ],
            "returns": [
                {
                    "desc": "A migration step object.",
                    "lua_type": "Types.MigrationStep"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 72,
                "path": "src/Migrations.luau"
            }
        },
        {
            "name": "makeTransformStep",
            "desc": "Helper function to create a migration step that applies a custom transformation\nfunction to the data.",
            "params": [
                {
                    "name": "name",
                    "desc": "The unique name for this migration step.",
                    "lua_type": "string"
                },
                {
                    "name": "transformFunc",
                    "desc": "The function that takes the current data and returns the transformed data.",
                    "lua_type": "(currentValue: Data) -> Data"
                }
            ],
            "returns": [
                {
                    "desc": "A migration step object.",
                    "lua_type": "Types.MigrationStep"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 93,
                "path": "src/Migrations.luau"
            }
        },
        {
            "name": "apply",
            "desc": "Applies pending migration steps to the data.\n\nIterates through the defined `steps` and applies any step whose name is not\npresent in the `appliedMigrations` list. Ensures idempotency and uses `pcall`\nfor safe execution of each step's `apply` function.",
            "params": [
                {
                    "name": "params",
                    "desc": "The parameters for applying migrations.",
                    "lua_type": "ApplyParams"
                }
            ],
            "returns": [
                {
                    "desc": "A Promise that resolves with the updated data and the new list of applied migration names.",
                    "lua_type": "Promise<ApplyResult>"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "string",
                    "desc": "Rejects if any migration step fails during `pcall`."
                }
            ],
            "source": {
                "line": 142,
                "path": "src/Migrations.luau"
            }
        },
        {
            "name": "getStepNames",
            "desc": "Utility function to extract just the names from a list of migration steps.",
            "params": [
                {
                    "name": "migrations",
                    "desc": "The list of migration steps.",
                    "lua_type": "{Types.MigrationStep}"
                }
            ],
            "returns": [
                {
                    "desc": "A list containing only the names of the migration steps.",
                    "lua_type": "{string}"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 199,
                "path": "src/Migrations.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "Data",
            "desc": "Alias for a generic data table type used in migrations.",
            "lua_type": "{ [string]: any }",
            "private": true,
            "source": {
                "line": 45,
                "path": "src/Migrations.luau"
            }
        },
        {
            "name": "ApplyParams",
            "desc": "Parameters for the `apply` function.",
            "fields": [
                {
                    "name": "logger",
                    "lua_type": "Log.Logger",
                    "desc": "Logger instance for logging migration progress and errors."
                },
                {
                    "name": "data",
                    "lua_type": "Data",
                    "desc": "The current data loaded from the DataStore record's File."
                },
                {
                    "name": "steps",
                    "lua_type": "{Types.MigrationStep}",
                    "desc": "The list of all defined migration steps for the store."
                },
                {
                    "name": "appliedMigrations",
                    "lua_type": "{string}",
                    "desc": "The list of names of migration steps already applied to this specific data record, loaded from the DataStoreRecord."
                }
            ],
            "source": {
                "line": 110,
                "path": "src/Migrations.luau"
            }
        },
        {
            "name": "ApplyResult",
            "desc": "Result returned by the `apply` function upon successful completion.",
            "fields": [
                {
                    "name": "data",
                    "lua_type": "Data",
                    "desc": "The potentially modified data after applying necessary migration steps."
                },
                {
                    "name": "appliedMigrations",
                    "lua_type": "{string}",
                    "desc": "The updated list of applied migration names, including any newly applied steps. This should be saved back to the DataStoreRecord."
                }
            ],
            "source": {
                "line": 125,
                "path": "src/Migrations.luau"
            }
        }
    ],
    "name": "Migrations",
    "desc": "Provides functionality for managing and applying data migrations.\n\n**Concept:** As data schemas evolve over time, older data stored\nin DataStores needs to be updated to match the new structure. This module\nallows defining a series of migration steps (`Types.MigrationStep`) that\ntransform data from one version of the schema to the next.\n\n**Workflow:**\n1. Define migration steps using helpers like `makeAddFieldsStep` or `makeTransformStep`.\n   Each step must have a unique `name`.\n2. Provide the list of steps to the `Store` via `StoreContext`.\n3. When data is loaded (`Session:load`), the `apply` function in this module is called.\n4. `apply` compares the list of all defined steps against the `appliedMigrations`\n   list stored within the `DataStoreRecord`.\n5. It executes the `apply` function of any step that hasn't been applied yet, in the\n   order they are defined.\n6. The `apply` function of each step receives the current data and returns the transformed data.\n7. The names of successfully applied steps are added to the `appliedMigrations` list,\n   which is then saved back to the `DataStoreRecord`.\n\n**Idempotency:** The system ensures migrations are idempotent (applying them multiple\ntimes has the same effect as applying them once) by checking the `appliedMigrations` list\nbefore running a step.\n\n**Error Handling:** Each step's `apply` function is executed within a `pcall` to catch\nerrors. If a step fails, the migration process stops, and the error is propagated.",
    "private": true,
    "source": {
        "line": 32,
        "path": "src/Migrations.luau"
    }
}