Skip to main content

DataStore

This item only works when running on the server. Server

Wraps the datastore object to provide async cached loading and saving. See DataStoreStage for more API.

Has the following features

  • Automatic saving every 5 minutes
  • Jitter (doesn't save all at the same time)
  • De-duplication (only updates data it needs)
  • Battle tested across multiple top games.
local playerMoneyValue = Instance.new("IntValue")
playerMoneyValue.Value = 0

local dataStore = DataStore.new(DataStoreService:GetDataStore("test"), "test-store")
dataStore:Load("money", 0):Then(function(money)
	playerMoneyValue.Value = money
	dataStore:StoreOnValueChange("money", playerMoneyValue)
end):Catch(function()
	-- TODO: Notify player
end)

To use a datastore for a player, it's recommended you use the PlayerDataStoreService. This looks something like this. See ServiceBag for more information on service initialization. 

local serviceBag = ServiceBag.new()
local playerDataStoreService = serviceBag:GetService(require("PlayerDataStoreService"))

serviceBag:Init()
serviceBag:Start()

local topMaid = Maid.new()

local function handlePlayer(player: Player)
	local maid = Maid.new()

	local playerMoneyValue = Instance.new("IntValue")
	playerMoneyValue.Name = "Money"
	playerMoneyValue.Value = 0
	playerMoneyValue.Parent = player

	maid:GivePromise(playerDataStoreService:PromiseDataStore(player)):Then(function(dataStore)
		maid:GivePromise(dataStore:Load("money", 0))
			:Then(function(money)
				playerMoneyValue.Value = money
				maid:GiveTask(dataStore:StoreOnValueChange("money", playerMoneyValue))
			end)
	end)

	topMaid[player] = maid
end
Players.PlayerAdded:Connect(handlePlayer)
Players.PlayerRemoving:Connect(function(player)
	topMaid[player] = nil
end)
for _, player in Players:GetPlayers() do
	task.spawn(handlePlayer, player)
end

Properties​

Saving​

</>
DataStore.Saving: Signal<Promise>

Prop that fires when saving. Promise will resolve once saving is complete.

Functions​

new​

</>
DataStore.new(
robloxDataStore: DataStore,
key: string
) → DataStore

Constructs a new DataStore. See DataStoreStage for more API.

local dataStore = serviceBag:GetService(PlayerDataStoreService):PromiseDataStore(player):Yield()

SetSessionLockingEnabled​

</>
DataStore.SetSessionLockingEnabled(
self: DataStore,
sessionLockingEnabled: boolean
) → ()

Sets session locking enabled

SetSessionMessagingEnabled​

</>
DataStore.SetSessionMessagingEnabled(
self: DataStore,
isEnabled: boolean,
serviceBag: ServiceBag--

Required when enabling

) → ()

Sets session messaging enabled.

Currently this only works in conjunction with session locking, and allows for a session lock to gracefully close when requested by another session.

GetKey​

</>
DataStore.GetKey(self: DataStore) → string

Returns the key for this datastore

GetSessionId​

</>
DataStore.GetSessionId(self: DataStore) → string

Returns the session id for this datastore

PromiseSessionLockingFailed​

</>
DataStore.PromiseSessionLockingFailed(self: DataStore) → Promise<>

Returns a promise that rejects on datastore cleanup, and resolves only when the session locking code completely fails

PromiseCloseSession​

</>
DataStore.PromiseCloseSession(self: DataStore) → Promise<>

Returns a promise that resolves when the session is closed. If the session is already closed, or session locking is not enabled, the promise resolves immediately.

SetDoDebugWriting​

</>
DataStore.SetDoDebugWriting(
self: DataStore,
debugWriting: boolean
) → ()

Set to true to debug writing this data store

GetFullPath​

</>
DataStore.GetFullPath(self: DataStore) → string

Returns the full path for the datastore

SetAutoSaveTimeSeconds​

</>
DataStore.SetAutoSaveTimeSeconds(
self: DataStore,
autoSaveTimeSeconds: number?
) → ()

How frequent the data store will autosave (or sync) to the cloud. If set to nil then the datastore will not do any syncing.

GetAutoSaveTimeSeconds​

</>
DataStore.GetAutoSaveTimeSeconds(self: DataStore) → number?

Returns how frequent the data store will autosave (or sync) to the cloud.

SetSyncOnSave​

</>
DataStore.SetSyncOnSave(
self: DataStore,
syncEnabled: boolean
) → ()

How frequent the data store will autosave (or sync) to the cloud

DidLoadFail​

</>
DataStore.DidLoadFail(self: DataStore) → boolean

Returns whether the datastore failed.

PromiseLoadSuccessful​

</>
DataStore.PromiseLoadSuccessful(self: DataStore) → Promise<boolean>

Returns whether the datastore has loaded successfully.\

Save​

</>
DataStore.Save(self: DataStore) → Promise

Saves all stored data.

SaveAndCloseSession​

</>
DataStore.SaveAndCloseSession(self: DataStore) → Promise

Saves all stored data.

Sync​

</>
DataStore.Sync(self: DataStore) → Promise

Same as saving the data but it also loads fresh data from the datastore, which may consume additional data-store query calls.

SetUserIdList​

</>
DataStore.SetUserIdList(
self: DataStore,
userIdList: {number}?
) → ()

Sets the user id list associated with this datastore. Can be useful for GDPR compliance.

GetUserIdList​

</>
DataStore.GetUserIdList(self: DataStore) → {number}?

Returns a list of user ids or nil

PromiseViewUpToDate​

</>
DataStore.PromiseViewUpToDate(self: DataStore) → Promise

Overridden helper method for data store stage below.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new DataStore. See [DataStoreStage] for more API.\n\n```lua\nlocal dataStore = serviceBag:GetService(PlayerDataStoreService):PromiseDataStore(player):Yield()\n```",
            "params": [
                {
                    "name": "robloxDataStore",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "key",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 136,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetSessionLockingEnabled",
            "desc": "Sets session locking enabled",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "sessionLockingEnabled",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 175,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetSessionMessagingEnabled",
            "desc": "Sets session messaging enabled.\n\nCurrently this only works in conjunction with session locking, and allows for a session lock\nto gracefully close when requested by another session.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "isEnabled",
                    "desc": "",
                    "lua_type": "boolean"
                },
                {
                    "name": "serviceBag",
                    "desc": "Required when enabling",
                    "lua_type": "ServiceBag"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 198,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetKey",
            "desc": "Returns the key for this datastore",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 226,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetSessionId",
            "desc": "Returns the session id for this datastore",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 234,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "PromiseSessionLockingFailed",
            "desc": "Returns a promise that rejects on datastore cleanup, and resolves only when the session locking\ncode completely fails",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 244,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "PromiseCloseSession",
            "desc": "Returns a promise that resolves when the session is closed. If the session is already closed, or\nsession locking is not enabled, the promise resolves immediately.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 254,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetDoDebugWriting",
            "desc": "Set to true to debug writing this data store",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "debugWriting",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 272,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetFullPath",
            "desc": "Returns the full path for the datastore",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 282,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetAutoSaveTimeSeconds",
            "desc": "How frequent the data store will autosave (or sync) to the cloud. If set to nil then the datastore\nwill not do any syncing.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "autoSaveTimeSeconds",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 292,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetAutoSaveTimeSeconds",
            "desc": "Returns how frequent the data store will autosave (or sync) to the cloud.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number?\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 301,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetSyncOnSave",
            "desc": "How frequent the data store will autosave (or sync) to the cloud",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "syncEnabled",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 310,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "DidLoadFail",
            "desc": "Returns whether the datastore failed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 320,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "PromiseLoadSuccessful",
            "desc": "Returns whether the datastore has loaded successfully.\\",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<boolean>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 337,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "Save",
            "desc": "Saves all stored data.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 349,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SaveAndCloseSession",
            "desc": "Saves all stored data.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 357,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "Sync",
            "desc": "Same as saving the data but it also loads fresh data from the datastore, which may consume\nadditional data-store query calls.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 369,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetUserIdList",
            "desc": "Sets the user id list associated with this datastore. Can be useful for GDPR compliance.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                },
                {
                    "name": "userIdList",
                    "desc": "",
                    "lua_type": "{ number }?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 378,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetUserIdList",
            "desc": "Returns a list of user ids or nil",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ number }?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 390,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "PromiseViewUpToDate",
            "desc": "Overridden helper method for data store stage below.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "DataStore"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 399,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "Saving",
            "desc": "Prop that fires when saving. Promise will resolve once saving is complete.",
            "lua_type": "Signal<Promise>",
            "source": {
                "line": 161,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        }
    ],
    "types": [],
    "name": "DataStore",
    "desc": "Wraps the datastore object to provide async cached loading and saving. See [DataStoreStage] for more API.\n\nHas the following features\n* Automatic saving every 5 minutes\n* Jitter (doesn't save all at the same time)\n* De-duplication (only updates data it needs)\n* Battle tested across multiple top games.\n\n```lua\nlocal playerMoneyValue = Instance.new(\"IntValue\")\nplayerMoneyValue.Value = 0\n\nlocal dataStore = DataStore.new(DataStoreService:GetDataStore(\"test\"), \"test-store\")\ndataStore:Load(\"money\", 0):Then(function(money)\n\tplayerMoneyValue.Value = money\n\tdataStore:StoreOnValueChange(\"money\", playerMoneyValue)\nend):Catch(function()\n\t-- TODO: Notify player\nend)\n```\n\nTo use a datastore for a player, it's recommended you use the [PlayerDataStoreService]. This looks\nsomething like this. See [ServiceBag] for more information on service initialization.\n\n```lua\nlocal serviceBag = ServiceBag.new()\nlocal playerDataStoreService = serviceBag:GetService(require(\"PlayerDataStoreService\"))\n\nserviceBag:Init()\nserviceBag:Start()\n\nlocal topMaid = Maid.new()\n\nlocal function handlePlayer(player: Player)\n\tlocal maid = Maid.new()\n\n\tlocal playerMoneyValue = Instance.new(\"IntValue\")\n\tplayerMoneyValue.Name = \"Money\"\n\tplayerMoneyValue.Value = 0\n\tplayerMoneyValue.Parent = player\n\n\tmaid:GivePromise(playerDataStoreService:PromiseDataStore(player)):Then(function(dataStore)\n\t\tmaid:GivePromise(dataStore:Load(\"money\", 0))\n\t\t\t:Then(function(money)\n\t\t\t\tplayerMoneyValue.Value = money\n\t\t\t\tmaid:GiveTask(dataStore:StoreOnValueChange(\"money\", playerMoneyValue))\n\t\t\tend)\n\tend)\n\n\ttopMaid[player] = maid\nend\nPlayers.PlayerAdded:Connect(handlePlayer)\nPlayers.PlayerRemoving:Connect(function(player)\n\ttopMaid[player] = nil\nend)\nfor _, player in Players:GetPlayers() do\n\ttask.spawn(handlePlayer, player)\nend\n```",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 66,
        "path": "src/datastore/src/Server/DataStore.lua"
    }
}