AceDB-3.0

AceDB-3.0 manages the SavedVariables of your addon. It offers profile management, smart defaults and namespaces for modules.

Creating a new Database using the :New function will return a new DBObject. A database will inherit all functions of the DBObjectLib listed here.

If you create a new namespaced child-database (:RegisterNamespace), you'll get a DBObject as well, but note that the child-databases cannot individually change their profile, and are linked to their parents profile - and because of that, the profile related APIs are not available. Only :RegisterDefaults and :ResetProfile are available on child-databases.

Tutorial

This walk-through covers the core concepts (profiles, smart defaults and namespaces) with examples. For exact method signatures and parameters, follow the links into the API reference below.

Getting Started

First, declare the SavedVariables table in your addon's .toc file:

## SavedVariables: AceDBExampleDB

Then create the database object with :New, passing the name of that table.

WARNING

You must create the database after the ADDON_LOADED event has fired for your addon (that is, in OnInitialize); otherwise the table you read will be replaced when the real SavedVariables loads.

AceDBExample = LibStub("AceAddon-3.0"):NewAddon("AceDBExample")

function AceDBExample:OnInitialize()
    self.db = LibStub("AceDB-3.0"):New("AceDBExampleDB")
end

Accessing & Storing Data

A database object exposes its data through several scopes (see Scopes below). The most commonly used is profile, which lets each character choose which named profile is active.

Reading and writing is just plain table access; you can store strings, numbers, or whole nested tables:

function AceDBExample:OnEnable()
    if self.db.profile.optionA then
        self.db.profile.playerName = UnitName("player")
        -- You're not limited to `profile`: read and write any scope the same way, and you can mix them freely on one database
        self.db.char.money = GetMoney()    -- per-character
        self.db.global.installed = true    -- account-wide
    end
end

To organize your settings, nest tables however you like; they behave like any other Lua table.

Defaults

Defaults are defined as a table laid out exactly like you want your database to look. You pass them to :New as the second argument (or set them later with :RegisterDefaults). Because one defaults table covers every scope at once, the top-level keys are the scope names (profile, char, global, ...).

local defaults = {
    profile = {
        optionA = true,
        optionB = false,
        suboptions = {
            subOptionA = false,
            subOptionB = true,
        },
    }
}

function AceDBExample:OnInitialize()
    self.db = LibStub("AceDB-3.0"):New("AceDBExampleDB", defaults)
end

Defaults are served transparently when a key has not been set, and they are never written to the SavedVariables file, so users only persist values they have actually changed.

Smart Defaults

There are two "magic" keys you can use inside a defaults table.

The first is ['*'], which provides a default for any key that was not explicitly defined:

local defaults = {
    profile = {
        modules = {
            ['*'] = {
                enabled = true,
                visible = true,
            },
            moduleB = {
                enabled = false,
                visible = true,
            },
        }
    }
}

With these defaults, reading self.db.profile.modules.moduleA.enabled returns true: moduleA was never declared, so it inherits the ['*'] table. Keys that are explicitly defined (like moduleB) do not inherit anything from ['*'].

The second magic key is ['**']. It works like ['*'], except it is also inherited by the sibling keys in the same table:

local defaults = {
    profile = {
        modules = {
            ['**'] = {
                enabled = true,
                visible = true,
            },
            moduleB = {
                enabled = false,
                --visible = true,
            },
        }
    }
}

Here visible is commented out of moduleB, yet self.db.profile.modules.moduleB.visible still returns true, because the explicitly-defined moduleB inherits the missing field from ['**'].

TIP

The difference is subtle but important: ['*'] only fills in undefined sibling keys, while ['**'] is also merged into defined siblings. Use ['**'] when you want every entry to share a base set of fields.

A ['*'] value can also be a plain value rather than a table; for example ['*'] = false for a table that tracks which modules are enabled, with an explicit true for the ones that are on.

Reacting to Profile Changes

When the active profile changes, the values behind self.db.profile change too, so anything you derived from those settings (frame positions, visibility, options panels) needs to be refreshed. AceDB tells you this happened through callbacks, fired via CallbackHandler-1.0.

Three callbacks all signal "the active profile changed": the user switched profiles, copied a profile into the active one, or reset it. Register the same handler for all three:

function MyAddon:OnInitialize()
    self.db = LibStub("AceDB-3.0"):New("MyAddonDB")
    self.db.RegisterCallback(self, "OnProfileChanged", "RefreshConfig")
    self.db.RegisterCallback(self, "OnProfileCopied", "RefreshConfig")
    self.db.RegisterCallback(self, "OnProfileReset", "RefreshConfig")
end

function MyAddon:RefreshConfig()
    -- re-read self.db.profile and reapply your settings here
end

TIP

Every addon that uses profiles should handle these three callbacks for a smooth, consistent transition whenever the active profile changes.

For the complete list of callbacks and their arguments, see the Callbacks section below.

Scopes

Data can be saved in different scopes, depending on its intended usage. The following scopes are available:

• char: Character-specific data. Every character has its own database.
• realm: Realm-specific data. All of the players characters on the same realm share this database.
• class: Class-specific data. All of the players characters of the same class share this database.
• race: Race-specific data. All of the players characters of the same race share this database.
• faction: Faction-specific data. All of the players characters of the same faction share this database.
• factionrealm: Faction and realm specific data. All of the players characters on the same realm and of the same faction share this database.
• locale: Locale specific data, based on the locale of the players game client.
• global: Global Data. All characters on the same account share this database.
• profile: Profile-specific data, and the most commonly used scope. All characters using the same profile share this database; the user can choose the active profile and manage the profiles of all of their characters.

Each of these is a live view into the saved table for the relevant key. You read and write them like ordinary Lua tables and AceDB persists the correct slice automatically.

Profiles work a little differently, because the user can switch which one is active:

• db.profile is the table of the currently active profile: the one whose name :GetCurrentProfile returns. This is what your addon reads and writes for ordinary settings ( db.profile.fontSize = 12).
• Which profile is active is tracked per character: AceDB keeps a character → profile name map in the SavedVariables, so every character remembers its own choice. A character with no stored choice falls back to the default profile: the defaultProfile you passed to :New ("Default" if you passed true), or a character-specific profile if you passed nothing.
• db.profiles is the table of all profiles, keyed by profile name (every profile that exists in the database, shared across the account). :GetProfiles lists their names; :SetProfile switches the active one (creating it if the name is new), which re-points db.profile at that profile's table and stores the choice for the current character. :CopyProfile, :DeleteProfile and :ResetProfile manage them. Changing the profile fires the profile callbacks so your addon can re-apply settings.

So in a typical addon, self.db.profile is "the user's current settings", self.db.profiles is "every saved settings set", and the active selection is remembered separately for each character.

API Reference

New

method#

AceDB:New(tbl, defaults?, defaultProfile?)

Creates a new database object that can be used to handle database settings and profiles.

By default, an empty DB is created, using a character specific profile.

You can override the default profile used by passing any profile name as the third argument, or by passing true as the third argument to use a globally shared profile called "Default".

Note that there is no token replacement in the default profile name, passing a defaultProfile as "char" will use a profile named "char", and not a character-specific profile.

Parameters

Parameter	Type	Default	Description
tbl	string | table		The name of the variable, or table to use for the database.
defaults (optional)	table		A table of database defaults.
defaultProfile (optional)	string | boolean		The name of the default profile. If not set, each character defaults to its own profile named "CharacterName - RealmName" (for example, "Thrall - Silvermoon"). Pass true to instead default to a single shared profile named "Default".

Returns

Type	Description
table	The new database object.

Example

-- Create an empty DB using a character-specific default profile.
self.db = LibStub("AceDB-3.0"):New("MyAddonDB")

-- ...or with a defaults table and a shared "Default" profile:
local defaults = { profile = { enabled = true } }
self.db = LibStub("AceDB-3.0"):New("MyAddonDB", defaults, true)

CopyProfile

method#

DBObjectLib:CopyProfile(name, silent?)

Copies a named profile into the current profile, overwriting any conflicting settings.

Parameters

Parameter	Type	Default	Description
name	string		The name of the profile to be copied into the current profile.
silent (optional)	boolean		If true, do not raise an error when the profile does not exist.

DeleteProfile

method#

DBObjectLib:DeleteProfile(name, silent?)

Deletes a named profile.

This profile must not be the active profile.

Parameters

Parameter	Type	Default	Description
name	string		The name of the profile to be deleted.
silent (optional)	boolean		If true, do not raise an error when the profile does not exist.

GetCurrentProfile

method#

DBObjectLib:GetCurrentProfile()

Returns the current profile name used by the database.

Returns

Type	Description
string	The current profile name used by the database.

GetNamespace

method#

DBObjectLib:GetNamespace(name, silent?)

Returns an already existing namespace from the database object.

Parameters

Parameter	Type	Default	Description
name	string		The name of the namespace.
silent (optional)	boolean		If true, the namespace is optional; silently return nil if it is not found.

Returns

Type	Description
table	The namespace object if found.

GetProfiles

method#

DBObjectLib:GetProfiles(tbl?)

Returns a table with the names of the existing profiles in the database.

You can optionally supply a table to re-use for this purpose.

Parameters

Parameter	Type	Default	Description
tbl (optional)	table		A table to store the profile names in.

Returns

Type	Description
table	profiles: The table of profile names.
number	count: The number of profiles in the table.

Example

local profiles, count = self.db:GetProfiles()

RegisterDefaults

method#

DBObjectLib:RegisterDefaults(defaults)

Sets the defaults table for the given database object by clearing any that are currently set, and then setting the new defaults.

Parameters

Parameter	Type	Default	Description
defaults	table		A table of defaults for this database.

RegisterNamespace

method#

DBObjectLib:RegisterNamespace(name, defaults?)

Creates a new database namespace, directly tied to the database.

This is a full scale database in its own rights other than the fact that it cannot control its profile individually.

Parameters

Parameter	Type	Default	Description
name	string		The name of the new namespace.
defaults (optional)	table		A table of values to use as defaults.

Returns

Type	Description
table	The new namespace database object.

Example

local module = self.db:RegisterNamespace("MyModule", { profile = { enabled = true } })

ResetDB

method#

DBObjectLib:ResetDB(defaultProfile?)

Resets the entire database, using the string defaultProfile as the new default profile.

Parameters

Parameter	Type	Default	Description
defaultProfile (optional)	string | boolean		The profile name to use as the default. May also be true for a shared global profile called "Default".

Returns

Type	Description
table	The database object.

ResetProfile

method#

DBObjectLib:ResetProfile(noChildren?, noCallbacks?)

Resets the current profile to the default values (if specified).

Parameters

Parameter	Type	Default	Description
noChildren (optional)	boolean		If set to true, the reset will not be populated to the child namespaces of this DB object.
noCallbacks (optional)	boolean		If set to true, won't fire the OnProfileReset callback.

SetProfile

method#

DBObjectLib:SetProfile(name)

Changes the profile of the database and all of it's namespaces to the supplied named profile.

Parameters

Parameter	Type	Default	Description
name	string		The name of the profile to set as the current profile.

Callbacks

AceDB fires a set of callbacks through CallbackHandler-1.0, notifying you of all important changes to the database. The CallbackHandler API is embedded directly on the database object, so you register a callback with:

db.RegisterCallback(target, "EventName", "method")

where target is the object to call back on (commonly self), "EventName" is one of the callbacks below, and "method" is the name of the method to invoke on target (it may be omitted to call a method of the same name as the event). db.UnregisterCallback(target, "EventName") and db.UnregisterAllCallbacks(target) are also available.

All callbacks receive the database object as their first argument; most provide additional information in further arguments.

OnNewProfile

callback#

OnNewProfile(db, profile)

Fires when a new profile is created. Commonly used to apply custom defaults that cannot be handled through AceDB's defaults table.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.
profile	string		The key of the new profile.

OnProfileChanged

callback#

OnProfileChanged(db, newProfile)

Fires after the active profile has been changed (including as part of a database reset).

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.
newProfile	string		The key of the now-active profile.

OnProfileDeleted

callback#

OnProfileDeleted(db, profile)

Fires after a profile has been deleted.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.
profile	string		The key of the deleted profile.

OnProfileCopied

callback#

OnProfileCopied(db, sourceProfile)

Fires after a profile has been copied into the current active profile.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.
sourceProfile	string		The key of the profile that was copied from.

OnProfileReset

callback#

OnProfileReset(db)

Fires after the current profile has been reset to its default values.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.

OnDatabaseReset

callback#

OnDatabaseReset(db)

Fires after the whole database has been reset. Note that OnProfileChanged is fired immediately afterwards as well.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.

OnProfileShutdown

callback#

OnProfileShutdown(db)

Fires before the active profile is changed, allowing you to save any pending state to the outgoing profile.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.

OnDatabaseShutdown

callback#

OnDatabaseShutdown(db)

Fires on logout (PLAYER_LOGOUT), just before the database is cleaned of all AceDB metadata and defaults are stripped from the SavedVariables.

Parameters

Parameter	Type	Default	Description
db	table		The database object the callback fires on.