Datastores

The Datastore service allows you to store permanent data to use between sessions such as player items and skill points. Datastores work per game so you can only access the data of a game from that game.

For temporary data, you can store this inside of your scripts using tables which won't be permanent.

Limitations

Rate Limit

The datastore service has a rate limit of (30 + (10 * [amount of players])) requests per minute. For example a server with 5 players would have a limit of 80 requests per minute.

This ratelimit is per server instance, not per game.

Read and write functions have their own individual rate limits.

You can create as many datastores as you want with each one having a limit.

Datastores also can only be accessed from server scripts.

Datastore Size

You can store up to 65,535 bytes of data.

Key Length

A key inside of a datastore can be up to 32 characters.

info

When testing your game locally in the Creator, Datastore requests will not be made to the server and your data will not be saved after the session ends. To test you need to upload your place to the website and test the requests.

Examples

Store a player's currency

A lot of games use a currency system and you may want to store this permanently. Let's make a simple currency datastore.

When making datastore requests, we need to first define a datastore.

The Datastore keyword is a global, meaning you can use it from any server script.

To access a data store we use the GetDatastore method with the name of the datastore name which is usually the ID of the player.

local ds = Datastore:GetDatastore("Player_" .. player.UserID)

This will create a datastore object which we can run different methods on.

You should also always wait for the data to be loaded before attempting to run a method on it.

You can wait for the data to load using either the Loaded event or check the Loading property.

To wait we can do the following

local ds = Datastore:GetDatastore("Player_" .. player.UserID)
ds.Loaded:Connect(function ()
    -- Run data store functions here
end)

Our datastore is essentially a dictionary, similar to a table. It has a unique key and a value.

Key	Value
Coins	60
Points	750

First let's see how we can save the player's data. Let's imagine we have a round system, and once the round ends, we want to give all players that stayed alive 5 points.

To set data we will use the Set method.

local alivePlayers = {} -- We store alive players here from our game logic

for _, player in ipairs(alivePlayers) do

    -- Get the specific datastore for this player
    local ds = Datastore:GetDatastore("Player_" .. player.UserId)

    -- Wait for our datastore to load
    ds.Loaded:Connect(function ()
        -- Set the coins using your callback syntax
        ds:Set("Coins", 5, function(success, errorMessage)
            if not success then
                warn("Failed to set coins for " .. player.Name .. ": " .. tostring(errorMessage))
            else
                print(player.Name .. "'s coins have been set to 5!")
            end
        end)
    end)
end

Now this sets the users coins to 5, however it did not add to the player's coins. To add we would need to first get their current coins.

To get the data we will use the Get method.

local alivePlayers = {}

for _, player in ipairs(alivePlayers) do

    local ds = Datastore:GetDatastore("Player_" .. player.UserId)

    local coins -- Store a local value of the player's coins

    ds.Loaded:Connect(function ()
        -- Attempts to get the value of "Coins"
        ds:Get("Coins", function(value, success, error)
            if not success then
                print(error)
            else
                coins = value
                print(player.Name .. " has " .. value .. " coins.")
            end
        end)
    end)

    -- Now that we have their current coins we add 5
    coins = coins + 5

    -- Now use the Set method again to set the user's coins to the new coins value
end

Delete a player's data

There may be instances where you want to delete some data fully from a player. Deleting is also just as simple as setting and getting the data.

To delete data we will use the Remove method.

local ds = Datastore:GetDatastore("Player_" .. player.UserId)
while ds.Loading do
    wait()
end

-- We attempt to remove the player's data with the key "Coins"
ds:Remove("Coins", function(success, error)
    if not success then
        print(error)
    else
        print(player.Name .. "'s coins have been removed!")
    end
end)