Versioning

As your addon evolves, the structure of its saved variables may need to change. You might add new settings, rename existing ones, reorganize data, or remove values that are no longer used.

LibSavedVars uses version numbers to detect when a player's saved data was created with an older version of your addon. This allows you to perform migrations only when they are needed.

Why Version Saved Variables?

Consider an addon that originally stored only one setting:

local defaults = {
    enabled = true,
}

Later, you decide to reorganize your settings:

local defaults = {
    general = {
        enabled = true,
    },
}

Existing users still have data stored in the old format. Without versioning, your addon would have no reliable way to determine whether a migration is required.

Version numbers solve this problem.

Specifying the Version

Every New... function accepts a version number as its second parameter.

local settings = LibSavedVars:NewAccountWide(
    "MyAddonSavedVariables",
    2,
    nil,
    defaults
)

When LibSavedVars loads the saved variables, it compares the stored version with the version supplied by your addon.

• If the versions are the same, no migration is necessary.

• If the stored version is lower, your migration code can update the saved data before the new version is recorded.

Incrementing the Version

Increase the version number only when an existing user's saved data requires modification.

Examples include:

• Renaming settings.

• Moving data to a different location.

• Converting one data format into another.

• Removing obsolete settings.

• Splitting or combining configuration tables.

Simply adding a new default value usually does not require a version increase because missing settings are supplied automatically from the defaults table.

For example:

Version 1:

local defaults = {
    enabled = true,
}

Version 2:

local defaults = {
    enabled = true,
    showTooltips = true,
}

Since showTooltips is provided by the defaults table, existing users receive the new setting automatically without migrating their saved data.

When to Increase the Version

Increase the version when the meaning or location of saved data changes.

For example:

Before:

settings.enabled

After:

settings.general.enabled

Because the existing data must be moved, this change requires a new version and a migration.

How LibSavedVars Tracks Versions

LibSavedVars stores the current version alongside your saved variables. Each time the addon loads, it compares the stored version with the version passed to the New... function.

After a successful migration, the stored version is updated automatically. You do not need to write or manage the version number yourself.

Versioning vs. Defaults

Defaults and versioning serve different purposes.

Feature | Purpose -- | -- Defaults | Provide values for settings that do not yet exist. Versioning | Detect when existing saved data needs to be modified.

A good rule of thumb is:

• New setting? Add it to the defaults table.

• Existing data changes? Increase the version and perform a migration.

Next Step

Versioning identifies when a player's saved data needs to be updated. The actual changes are performed through migrations, which allow you to safely modify existing saved variables while preserving the player's settings.

The next section explains how to create and use migrations in LibSavedVars.