Managing Multiple SavedVariables Files

Most addons only require a single SavedVariables file. However, larger addons may benefit from separating data into multiple files based on purpose, size, or lifecycle.

LibSavedVars supports managing multiple SavedVariables files, allowing each file to have its own defaults, versioning, migrations, and storage behavior.

---

Why Use Multiple SavedVariables Files?

Separating data can improve organization and maintenance.

Common reasons to use multiple SavedVariables files include:

• Separating user settings from cached or historical data.
• Keeping large temporary datasets separate from configuration.
• Reducing the impact of migrations.
• Allowing different update schedules for different data types.
• Making debugging and troubleshooting easier.

For example:

MyAddon_Settings.lua
    User preferences
    UI configuration
    Account options

MyAddon_Data.lua
    Cached information
    Imported data
    Historical records

---

Creating Multiple SavedVariables Objects

Each SavedVariables file is created independently.

Example:

local settingsDefaults = {
    enabled = true,
    scale = 1.0,
}

local dataDefaults = {
    entries = {},
}

Create the settings file:

local settings = LibSavedVars:NewAccountWide(
    "MyAddon_Settings",
    1,
    nil,
    settingsDefaults
)

Create the data file:

local data = LibSavedVars:NewAccountWide(
    "MyAddon_Data",
    1,
    nil,
    dataDefaults
)

The addon now has two separate saved variable objects.

---

Independent Versioning

Each SavedVariables file has its own version number.

Example:

local settings = LibSavedVars:NewAccountWide(
    "MyAddon_Settings",
    3,
    nil,
    settingsDefaults
)

local data = LibSavedVars:NewAccountWide(
    "MyAddon_Data",
    7,
    nil,
    dataDefaults
)

The settings file can evolve independently from the data file.

For example:

MyAddon_Settings
    Version 3

MyAddon_Data
    Version 7

A migration in one file does not affect the other.

---

Independent Migrations

Each SavedVariables object maintains its own migration chain.

Example:

settings:Migrate(2, function(savedVars)

    savedVars.opacity = 0.8

end)

settings:Migrate(3, function(savedVars)

    savedVars.ui = {
        scale = savedVars.scale
    }

    savedVars.scale = nil

end)

The data file can have a completely separate migration history:

data:Migrate(2, function(savedVars)

    savedVars.entries = {}

end)

data:Migrate(3, function(savedVars)

    savedVars.version = 3

end)

---

Separating Configuration and Cached Data

A common design pattern is to separate permanent user choices from rebuildable data.

Example:

Settings File

MyAddon_Settings
{
    enabled = true,
    window = {
        x = 100,
        y = 100,
    }
}

Contains:

• User preferences.
• Configuration.
• Options.

Data File

MyAddon_Data
{
    history = {},
    cache = {},
}

Contains:

• Cached information.
• Temporary data.
• Rebuildable records.

This separation makes it easier to clear cached data without affecting user preferences.

---

Using Different Storage Models

Different SavedVariables files can use different storage models.

Example:

Account-wide settings:

local settings = LibSavedVars:NewAccountWide(
    "MyAddon_Settings",
    1,
    nil,
    settingsDefaults
)

Character data:

local characterData = LibSavedVars:NewCharacterSettings(
    "MyAddon_CharacterData",
    1,
    nil,
    characterDefaults
)

This allows an addon to combine:

Account-wide:
    UI preferences
    Global options

Character:
    Character notes
    Build information
    Per-character data

---

Defaults Trimming with Multiple Files

Defaults trimming can be enabled independently for each SavedVariables object.

Example:

settings:EnableDefaultsTrimming()

data:EnableDefaultsTrimming()

This allows each file to remove unnecessary default values before saving.

For large data files, you may choose not to enable trimming if most values are generated dynamically.

---

Multiple Namespaces vs Multiple Files

LibSavedVars supports both namespaces and multiple SavedVariables files.

Namespaces

Useful when data belongs together:

MyAddonSavedVariables
{
    Combat = {}
    Inventory = {}
}

Advantages:

• One SavedVariables file.
• Shared versioning.
• Shared lifecycle.

---

Multiple Files

Useful when data should be independent:

MyAddon_Settings
MyAddon_Data

Advantages:

• Separate versions.
• Separate migrations.
• Easier cleanup.
• Smaller individual files.

---

Recommended Organization

A large addon might use a structure like:

MyAddon_Settings
    Version: 5
    User preferences

MyAddon_Profile
    Version: 3
    Character/account profiles

MyAddon_Cache
    Version: 8
    Temporary cached information

Each file has:

• Its own defaults.
• Its own version.
• Its own migrations.
• Its own LibSavedVars object.

---

Best Practices

When managing multiple SavedVariables files:

• Use separate files for logically independent data.
• Keep user preferences separate from generated data.
• Give each file a clear purpose.
• Maintain independent migration histories.
• Avoid duplicating the same data in multiple files.
• Use namespaces when data belongs together.
• Use multiple files when data has different lifecycles.

---

Summary

Multiple SavedVariables files allow large addons to organize persistent data more effectively.

LibSavedVars supports independent management of each file, including:

• Separate defaults.
• Separate versions.
• Separate migrations.
• Separate trimming behavior.
• Different storage models.

For small addons, a single SavedVariables file is usually best. For larger addons, separating configuration, profiles, and data storage can significantly improve maintainability and long-term stability.