[Release] MockDataStoreService - seamless local development & testing with datastores



This is an open-source module that emulates datastores in Lua rather than using the actual service. This is useful for testing in offline projects / local place files with code/frameworks that need to have access to datastores.

The MockDataStoreService behaves exactly like DataStoreService – it has the same API, and will also work even if the place is not currently published to a game with Studio API access enabled (it will act as a DataStoreService with no data stored on the back-end, unless you import some data from a json string manually using the module).

A small top-level helper module is provided (DataStoreService) that automatically detects and selects which datastores should be used (real datastores for published games with API access, mock datastores for offline games / published games without API access).

It is recommended to use this code in the structure that it is provided in, and to simply call require(path.to.DataStoreService) instead of game:GetService("DataStoreService") anywhere in your code to use it properly.


local MockDataStoreService = require(the.path.to.MockDataStoreService)

-- Use as actual DataStoreService, i.e.:

local gds = MockDataStoreService:GetGlobalDataStore()
local ds = MockDataStoreService:GetDataStore("TestName", "TestScope")
local ods = MockDataStoreService:GetOrderedDataStore("TestName")

local value = ds:GetAsync("TestKey")
ds:SetAsync("TestKey", "TestValue")
local value = ds:IncrementAsync("IntegerKey", 3)
local value = ds:UpdateAsync("UpdateKey", function(oldValue) return newValue end)
local value = ds:RemoveAsync("TestKey")
local connection = ds:OnUpdate("UpdateKey", function(value) print(value) end)

local pages = ods:GetSortedAsync(true, 50, 1, 100)
	for _, pair in ipairs(pages:GetCurrentPage()) do
		local key, value = pair.key, pair.value
		-- (...)
until pages.IsFinished or pages:AdvanceToNextPageAsync()

local budget = MockDataStoreService:GetRequestBudgetForRequestType(

-- Import/export data to a specific datastore:

ds:ImportFromJSON({ -- feed table or json string representing contents of datastore
	TestKey = "Hello world!"; -- a key value pair
	AnotherKey = {a = 1, b = 2}; -- another key value pair
	-- (...)


-- Import/export entirety of MockDataStoreService:

MockDataStoreService:ImportFromJSON({ -- feed table or json string
	DataStore = { -- regular datastores
		TestName = { -- name of datastore
			TestScope = { -- scope of datastore
				TestKey = "Hello world!"; -- a key value pair
				AnotherKey = {1,2,3}; -- another key value pair
				-- (...)
	GlobalDataStore = { -- the (one) globaldatastore
		TestKey = "Hello world!"; -- a key value pair
		AnotherKey = {1,2,3}; -- another key value pair
		-- (...)
	OrderedDataStore = { -- ordered datastores
		TestName = { -- name of ordered datastore
			TestScope = { -- scope of ordered datastore
				TestKey = 15; -- a key value pair
				AnotherKey = 3; -- another key value pair
				-- (...)



  • Identical API and near-identical behaviour compared to real DataStoreService.
  • Error messages are more verbose/accurate than the ones generated by actual datastores, which makes development/bug-fixing easier.
  • Throws descriptive errors for attempts at storing invalid data, telling you exactly which part of the data is invalid. (credit to @Corecii’s helper function)
  • Emulates the yielding of datastore requests (waits a random amount of time before returning from the call).
  • Extra API for json-exporting/importing contents of one/all datastores for easy testing.
  • All operations safely deep-copy values where necessary (not possible to alter values in the datastore by externally altering tables, etc).
  • Enforces the “6 seconds between writes on the same key” rule.
  • Enforces datastore budgets correctly: budget are set and increased at the rates of the actual service, requests will be throttled if the budget is exceeded, and if there are too many throttled requests in the queue then new requests will error instead of throttling.

Get the module:

Download the module directly:
DataStoreService.rbxm (15.6 KB)

Or grab the module from the library:

Or get the source code here: (and submit PRs/issues!)

Feel free to leave questions, comments, requests for improvements, and bug reports here, or as issues on the GitHub repository!

Details on DataStoreService for Advanced Developers

This is neat for CI testing, I like it!


This is awesome, thanks!


Thanks for the contribution. This is awesome!


It would be good to simulate the request limits for the data store as well.


Need some ice for that burn

Thank God this exists though. I was so annoyed I was no joke gonna make one, arguably of worse functionality, at home. Wonderful.


As you can see in the OP, that’s already on the TODO list. It was a non-trivial amount of work to implement so I left it out for v1. If you want you can file a pull request for it if you can manage to edit the code in a clean way to support it!

EDIT: budgeting and throttling is now supported!


This has been updated to fully support datastore budgeting and throttling of requests, and the code has been cleaned up (better file structure)!

As far as I am aware, this now perfectly emulates DataStoreService behavior. I spent a lot of time checking scenarios and making sure this module reflects the behavior. If you do spot inconsistencies between this module and the actual service, please let me know.

Thanks @Validark for comments and small improvements on v1 of the code, and @LouieK22 for initial work done on the 6 second write rule.


Wow thanks for all of this, it’s super cool!