DataStore Pro Kit

A battle-tested data layer for Roblox experiences.

Overview

DataStore Pro Kit is a production-quality DataStore wrapper that sits between your game code and Roblox's DataStoreService. It eliminates the boilerplate and foot-guns that come with raw DataStore calls and gives you a reliable, high-performance data layer out of the box.

Problems it solves:

• Data loss on errors — automatic exponential-backoff retries with jitter so transient failures don't lose player progress.
• Rate-limit throttling — budget-aware request scheduling that waits for available credits instead of eating retries on 429s.
• Duplicate writes during teleports — optional MemoryStore-backed session locking prevents two servers from writing the same key at once.
• Schema evolution — sequential migration functions upgrade old data formats automatically when a player's data is loaded.
• Redundant reads — in-memory LRU cache with TTL expiration and dirty-entry tracking cuts DataStore reads dramatically.
• Race conditions — per-key concurrency locks serialise overlapping Get/Set/Update calls for the same player.
• Shutdown data loss — parallel SaveAll flushes every dirty entry during the ~30 s BindToClose window.

The kit ships four modules — DataStoreManager (core), SessionLock, Migration, and Cache — that work together or independently.

Installation

1. Download the .rbxm model file from your Baseplate purchase page.
2. In Roblox Studio, right-click ServerStorage → Insert from File… and select the .rbxm.
3. You should see a folder structure like:

   ServerStorage
     └─ DataStoreProKit
          ├─ DataStoreManager   (ModuleScript)
          ├─ SessionLock         (ModuleScript)
          ├─ Migration           (ModuleScript)
          └─ Cache               (ModuleScript)

4. Require the modules in your server scripts:

   local DataStoreManager = require(game.ServerStorage.DataStoreProKit.DataStoreManager)
   local SessionLock = require(game.ServerStorage.DataStoreProKit.SessionLock)
   -- Migration and Cache are used internally by DataStoreManager,
   -- but you can require them directly for advanced use cases.

Important: The kit must live in ServerStorage or ServerScriptService — never in ReplicatedStorage, because DataStoreService is server-only.

Quick Start

Drop this into a Script in ServerScriptService and you have working data persistence in under 60 lines:

local Players = game:GetService("Players")
local DataStoreManager = require(game.ServerStorage.DataStoreProKit.DataStoreManager)
local SessionLock = require(game.ServerStorage.DataStoreProKit.SessionLock)

-- 1. Create the manager
local manager = DataStoreManager.new({
    name = "PlayerData_v1",
    retryAttempts = 5,
    retryDelay = 1,
    cacheTTL = 60,
    schemaVersion = 1,
    defaultData = {
        coins = 0,
        level = 1,
        inventory = {},
        settings = { musicOn = true },
    },
})

-- 2. Create a session lock (prevents dual-server writes during teleports)
local sessionLock = SessionLock.new({
    dataStoreName = "PlayerData_v1",
})

-- 3. Table to hold loaded data per player
local playerData: { [number]: { [string]: any } } = {}

-- 4. Load on join
Players.PlayerAdded:Connect(function(player: Player)
    local acquired = sessionLock:Acquire(player.UserId)
    if not acquired then
        warn("Could not acquire session lock for", player.Name)
        player:Kick("Data is still saving on another server. Please rejoin.")
        return
    end

    local success, data = manager:Get(player.UserId)
    if success then
        playerData[player.UserId] = data
    else
        warn("Failed to load data for", player.Name, ":", data)
        player:Kick("Failed to load your data. Please rejoin.")
        sessionLock:Release(player.UserId)
    end
end)

-- 5. Save on leave
Players.PlayerRemoving:Connect(function(player: Player)
    local data = playerData[player.UserId]
    if data then
        manager:Set(player.UserId, data)
    end
    playerData[player.UserId] = nil
    sessionLock:Release(player.UserId)
end)

-- 6. Flush everything on shutdown
game:BindToClose(function()
    manager:SaveAll()
    sessionLock:ReleaseAll()
end)

API Reference

DataStoreManager

The core module. Handles reading, writing, caching, retries, and migrations.

DataStoreManager.new(config)

Creates a new manager instance. Config fields:

Core Methods

Utility Methods

SessionLock

Distributed lock backed by MemoryStoreService to prevent concurrent server writes.

SessionLock.new(config)

SessionLock Methods

Migration

Standalone schema migration module. Used internally by DataStoreManager but can be used directly for advanced scenarios.

Migration.new(config)

Migration Methods

Cache

In-memory LRU cache with TTL expiration and dirty-entry tracking. Used internally by DataStoreManager but available for standalone use.

Cache.new(config?)

Cache Methods

Session Locking

The Problem

When a player teleports between servers (or reconnects quickly), the departing server may still be executing its PlayerRemoving save while the new server loads the same key. This creates a race condition:

1. Server A starts saving Player_123's data.
2. Server B loads Player_123's data (gets the old copy).
3. Server A's save completes — writes newer data.
4. Server B eventually saves — overwrites Server A's newer data with the stale copy.

How Baseplate Solves It

The SessionLock module uses MemoryStoreService (a MemoryStore SortedMap) to create a distributed lock per player key. The flow:

• Acquire — Before loading data, call sessionLock:Acquire(playerId). It writes a lock entry containing the current server's JobId and a heartbeat timestamp.
• Heartbeat — A background thread refreshes the heartbeat every heartbeatInterval seconds (default 10) so the lock stays alive.
• Contention — If another server holds the lock, Acquire yields and retries up to acquireTimeout seconds (default 15). If the existing lock's heartbeat is older than lockTTL (default 30 s), it's considered stale and overwritten.
• Release — After saving, call sessionLock:Release(playerId) to remove the lock and stop the heartbeat.
• Crash recovery — If a server crashes without releasing, the lock auto-expires after lockTTL seconds because the heartbeat stops.

Example

local sessionLock = SessionLock.new({
    dataStoreName = "PlayerData_v1",
    lockTTL = 30,            -- lock expires after 30s without heartbeat
    heartbeatInterval = 10,  -- refresh every 10s
    acquireTimeout = 15,     -- wait up to 15s for another server
    acquireRetryDelay = 1,   -- poll every 1s while waiting
})

Players.PlayerAdded:Connect(function(player: Player)
    local acquired = sessionLock:Acquire(player.UserId)
    if not acquired then
        player:Kick("Your data is still saving on another server. Please rejoin in a moment.")
        return
    end
    -- Safe to load and use data now
end)

Players.PlayerRemoving:Connect(function(player: Player)
    -- Save data first, THEN release the lock
    manager:Set(player.UserId, playerData[player.UserId])
    sessionLock:Release(player.UserId)
end)

game:BindToClose(function()
    manager:SaveAll()
    sessionLock:ReleaseAll()
end)

When to Disable Session Locking

Session locking adds a MemoryStore round-trip on every join. You can skip it when:

• Your game is single-server (no teleports, no matchmaking).
• You use DataStoreManager:Update() exclusively — UpdateAsync is already atomic.
• You're in Studio testing and MemoryStore isn't available.

Schema Migrations

How It Works

Every data table stored by the kit contains a hidden _schemaVersion field. When DataStoreManager:Get() or :Update() loads data whose _schemaVersion is lower than the manager's configured schemaVersion, migration functions run sequentially from _schemaVersion + 1 through schemaVersion.

After migration, the kit immediately persists the upgraded data back to the DataStore. If that save fails, the entry is marked dirty so SaveAll can retry later.

Safety Guarantees

• The standalone Migration module pre-validates that every required migration function exists before touching the data, so data is never left in a partially-migrated state.
• If a migration function doesn't return a table, the migration is aborted and the original data is returned unchanged.
• If the data's version is ahead of the current version (e.g., after a rollback), it's returned unchanged with a warning.

Three-Version Migration Example

local manager = DataStoreManager.new({
    name = "PlayerData",
    schemaVersion = 3,
    migrations = {
        -- v0 → v1: Add a "coins" field (new players who predate the economy update)
        [1] = function(data)
            data.coins = data.coins or 0
            return data
        end,

        -- v1 → v2: Rename "xp" to "experience" for clarity
        [2] = function(data)
            data.experience = data.xp or 0
            data.xp = nil
            return data
        end,

        -- v2 → v3: Add nested settings table with defaults
        [3] = function(data)
            data.settings = data.settings or {
                musicOn = true,
                sfxVolume = 0.8,
                language = "en",
            }
            return data
        end,
    },
    defaultData = {
        coins = 0,
        experience = 0,
        level = 1,
        inventory = {},
        settings = {
            musicOn = true,
            sfxVolume = 0.8,
            language = "en",
        },
    },
})

What happens on load:

• A brand-new player receives defaultData with _schemaVersion = 3. No migrations run.
• A v0 player (no _schemaVersion field) runs migrations 1 → 2 → 3 sequentially.
• A v2 player only runs migration 3.
• A v3 player skips migrations entirely — returned from cache or DataStore as-is.

Caching

How the Cache Works

The Cache module implements an LRU (Least Recently Used) cache backed by a doubly-linked list and a hash map for O(1) reads, writes, and promotions.

• TTL expiration — Each entry has a timestamp. On read, if the entry is older than ttl seconds (default 60), it's lazily evicted and a cache miss is recorded.
• Dirty tracking — Entries written locally but not yet persisted to DataStore are flagged as dirty. SaveAll iterates only dirty entries for efficient flushing.
• LRU eviction — When the cache exceeds maxEntries (default 500), the least-recently-used non-dirty entry is evicted. Dirty entries are never evicted — if all entries are dirty, a warning is logged and eviction is skipped.
• Deep-copy isolation — Data is deep-copied on every cache read and write so that external mutations never corrupt internal state.

Tuning Settings

Monitoring

-- DataStoreManager exposes cache-related metrics:
local metrics = manager:GetMetrics()
print("Hit rate:", metrics.cacheHits / (metrics.cacheHits + metrics.cacheMisses))

-- The standalone Cache module has its own stats:
local cache = Cache.new({ ttl = 120, maxEntries = 200 })
local stats = cache:GetStats()
-- stats = { entries = 42, dirtyCount = 3, hitRate = 0.85 }

Budget Management

Roblox Rate Limits

Roblox imposes per-server request budgets on DataStore operations. Budgets regenerate over time, and if you exceed them your calls will be throttled or fail. The exact rates depend on the number of players in the server.

How the Kit Handles It

Before every DataStore call (GetAsync, SetAsync, UpdateAsync, RemoveAsync), the kit calls DataStoreService:GetRequestBudgetForRequestType() to check the remaining budget. If the budget is zero, the kit yields the current thread and polls every second until at least one credit is available, then proceeds with the request.

This means retries never waste budget on already-throttled requests, and your game won't error-spam the output when traffic is high. The kit logs a warning when throttling occurs so you can monitor it:

[DataStorePro] Request budget exhausted, throttling {type=SetIncrementAsync}

Inspecting Budgets at Runtime

local budget = manager:GetBudget()
print("Get budget:", budget.get)     -- e.g., 60
print("Set budget:", budget.set)     -- e.g., 60
print("Update budget:", budget.update) -- e.g., 60
print("List budget:", budget.list)   -- e.g., 5

Troubleshooting

Data Not Saving

Session Lock Conflicts

Migration Errors

General Tips

• Use manager:GetMetrics() to monitor error and retry rates.
• Use manager:GetBudget() to check if you're near DataStore rate limits.
• Always test in a Studio Team Test (multiple clients) to verify session locking works.
• Keep migration functions simple and idempotent — use data.field = data.field or default patterns.
• Never modify the _schemaVersion field manually in your game code.