esx_datastore

esx_datastore is a server-only library resource that stores arbitrary Lua tables as JSON in MySQL. Other resources use it for things like society armories, saved outfits (property → dressing) and accessory slots (user_mask, user_helmet). Use it when you need small, persistent key-value data that is tied to a player or to a job.

OverviewCopy Anchor Link

There are two kinds of datastores:

• Shared (shared = 1): one store for the whole server, without an owner. Typical for job data such as society_police.
• Per player (shared = 0): one store per character identifier. esx_datastore creates the missing datastore_data row for every non-shared datastore when a player loads (esx:playerLoaded).

InstallationCopy Anchor Link

CREATE TABLE `datastore` (
	`name` VARCHAR(60) NOT NULL,
	`label` VARCHAR(100) NOT NULL,
	`shared` INT NOT NULL,
	PRIMARY KEY (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE `datastore_data` (
	`id` INT NOT NULL AUTO_INCREMENT,
	`name` VARCHAR(60) NOT NULL,
	`owner` VARCHAR(60),
	`data` LONGTEXT,
	PRIMARY KEY (`id`),
	UNIQUE INDEX `index_datastore_data_name_owner` (`name`, `owner`),
	INDEX `index_datastore_data_name` (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

ensure oxmysql
ensure esx_lib
ensure es_extended
ensure esx_datastore

INSERT INTO `datastore` (`name`, `label`, `shared`) VALUES
	('society_mafia', 'Mafia', 1),   -- one store for the whole job
	('property', 'Property', 0);     -- one store per player

ConfigurationCopy Anchor Link

esx_datastore has no config.lua. Everything is driven by the rows in the datastore table.

Server eventsCopy Anchor Link

All three events are registered with AddEventHandler only, so they can be triggered from other server resources but not from clients. The callback runs synchronously.

esx_datastore:getSharedDataStoreCopy Anchor Link

TriggerEvent('esx_datastore:getSharedDataStore', name, cb)

TriggerEvent('esx_datastore:getSharedDataStore', 'society_police', function(store)
    if not store then return end

    local weapons = store.get('weapons') or {}
    weapons[#weapons + 1] = { name = 'WEAPON_PUMPSHOTGUN', count = 1 }
    store.set('weapons', weapons)
end)

esx_datastore:getDataStoreCopy Anchor Link

TriggerEvent('esx_datastore:getDataStore', name, owner, cb)

local xPlayer = ESX.GetPlayerFromId(source)

TriggerEvent('esx_datastore:getDataStore', 'property', xPlayer.getIdentifier(), function(store)
    if not store then return end

    local dressing = store.get('dressing') or {}
    print(('%s has %d saved outfits'):format(xPlayer.getName(), #dressing))
end)

esx_datastore:getDataStoreOwnersCopy Anchor Link

TriggerEvent('esx_datastore:getDataStoreOwners', name, cb)

Store objectCopy Anchor Link

Every store returned by the events above has these fields and functions:

Saving behaviorCopy Anchor Link

• Saves are debounced through xLib.timeout: the last change wins and the JSON is written 10 seconds after it.
• A failed write is logged ([esx_datastore] Save failed for ...) and rescheduled.
• On onResourceStop all stores are flushed, so a clean restart of esx_datastore does not lose data.

Integration tipsCopy Anchor Link

• Name society stores society_<job>. esx_society and the job addons expect that pattern.
• Use a per-player store (shared = 0) instead of new users columns for small optional data like favorites or saved presets.
• Keep values small. Every save writes the whole JSON blob of that store.
• Because getDataStore callbacks run synchronously, you can capture the store in a local variable and use it after the TriggerEvent call.

Common issuesCopy Anchor Link

• attempt to index a nil value (local 'store'): the datastore row is missing or was added after the resource started. Insert the row and restart.
• Outfits are not saved in the clothes shop: esx_clotheshop writes to a per-player datastore named property. No addon seeds it, so insert ('property', 'Property', 0) yourself.
• Data lost after killing the server process: changes from the last ~10 seconds are only in memory. Stop the server normally so stores get flushed.

RelatedCopy Anchor Link

• esx_addonaccount
• esx_addoninventory
• esx_society
• esx_clotheshop
• Database schema

Frequently asked questions