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)
	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 pairs(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()

SetDoDebugWriting​

</>
DataStore:SetDoDebugWriting(debugWriting: boolean) → ()

Set to true to debug writing this data store

GetFullPath​

</>
DataStore:GetFullPath() → string

Returns the full path for the datastore

SetAutoSaveTimeSeconds​

</>
DataStore:SetAutoSaveTimeSeconds(autoSaveTimeSeconds: number | nil) → ()

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

SetSyncOnSave​

</>
DataStore:SetSyncOnSave(syncEnabled: boolean) → ()

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

DidLoadFail​

</>
DataStore:DidLoadFail() → boolean

Returns whether the datastore failed.

PromiseLoadSuccessful​

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

Returns whether the datastore has loaded successfully.\

Save​

</>
DataStore:Save() → Promise

Saves all stored data.

Sync​

</>
DataStore:Sync() → 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(userIdList: {number} | nil) → ()

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

GetUserIdList​

</>
DataStore:GetUserIdList() → {number} | nil

Returns a list of user ids or nil

PromiseViewUpToDate​

</>
DataStore:PromiseViewUpToDate() → 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": 99,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetDoDebugWriting",
            "desc": "Set to true to debug writing this data store",
            "params": [
                {
                    "name": "debugWriting",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 134,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetFullPath",
            "desc": "Returns the full path for the datastore",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 144,
                "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": "autoSaveTimeSeconds",
                    "desc": "",
                    "lua_type": "number | nil"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 154,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "SetSyncOnSave",
            "desc": "How frequent the data store will autosave (or sync) to the cloud",
            "params": [
                {
                    "name": "syncEnabled",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 165,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "DidLoadFail",
            "desc": "Returns whether the datastore failed.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 175,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "PromiseLoadSuccessful",
            "desc": "Returns whether the datastore has loaded successfully.\\",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<boolean>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 192,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "Save",
            "desc": "Saves all stored data.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 204,
                "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": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 214,
                "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": "userIdList",
                    "desc": "",
                    "lua_type": "{ number } | nil"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 223,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "GetUserIdList",
            "desc": "Returns a list of user ids or nil",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ number } | nil"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 235,
                "path": "src/datastore/src/Server/DataStore.lua"
            }
        },
        {
            "name": "PromiseViewUpToDate",
            "desc": "Overridden helper method for data store stage below.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 244,
                "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": 122,
                "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)\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 pairs(Players:GetPlayers()) do\n\ttask.spawn(handlePlayer, player)\nend\n```",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 65,
        "path": "src/datastore/src/Server/DataStore.lua"
    }
}