Rongo

Starnamics · April 15, 2022, 2:13am

MongoDB API Wrapper for Roblox
v1.0.0

Read our article on the MongoDB Developer Hub

Want an alternative to DataStore? Check out MongoStore

Download on Roblox
Download on Github
Install with Wally
View Source

What is Rongo?

Rongo is an open-source API wrapper for MongoDB, which is a document oriented database program.

Rongo gives developers an easy to use, object oriented & type safe module which serves as an interface to MongoDB’s Data API for developers to use as an alternative to DataStoreService or a variety of other uses!

Rongo is still in early development & I plan to extend it as more MongoDB API’s are released & to add additional features to it.

Rongo is licensed under the MIT License

How do I install Rongo?

It is pretty simple to install Rongo, all you need to do is either get the model on Roblox or download the file on Github!

Once you’ve gotten either of those, insert it into ServerScriptService & then you’re ready to start using it!

You can also install Rongo via Wally by adding rongo = "starnamics/rongo@1.1.2" into your wally.toml file (make sure to get the latest version on Wally)

Scroll down for some usage examples & documentation

Examples

Setting up the Data API

Follow the steps below to get MongoDB’s Data API Setup

1 - Click on the “Data API” page in MongoDB

2 - Enable the Data API

(make sure to select the sources)

3 - Copy your API ID & store it somewhere safe

(only copy this, don’t copy the entire URL)

4 - Click on the “Create API Key” button

5 - Enter a name then press the generate button

Copy your API key & store it somewhere safe

Once you’ve done all these steps you should be good to go and you’re ready to setup Rongo in your game!

Using Rongo in your game

After you’ve set up the Data API & installed Rongo in your game, you can start using it. Below will teach you the basics of getting it set up!

1 - Create a script in ServerScriptService

2 - Paste the code below into the new script

local ServerScriptService = game:GetService("ServerScriptService")
local Rongo = require(ServerScriptService.Rongo) --// Replace this with the location of the Rongo module

local Client = Rongo.new(YOUR_API_ID, YOUR_API_KEY) --// Replace these with the ID and key you stored earlier!
local Cluster = Client:GetCluster("Cluster Name") --// Replace this with the name of your cluster (usually "Cluster0")
local Database = Cluster:GetDatabase("example") --// Replace this with the name of your database!
local Collection = Database:GetCollection("example") --// Replace this with the name of your collection inside your database

Above is some code to get you started, make sure to fill in the arguments!

3 - Inserting a document in your collection
Below the code above, you can paste this below to learn how to insert a document inside of your collection!

local MyDocument = {
	["name"] = "This is my first document!",
	["description"] = "I inserted this using Rongo!"
}
Collection:InsertOne(MyDocument) --// This will insert the document you typed out above!
local NewDocument = Collection:FindOne({["name"] = MyDocument.name}) --// This will find the document you just created!
print("My Document:",NewDocument) --// This will print out your document into the output!

That’s all for the basic setup of Rongo! If you’d like to learn more, read our documentation!

Documentation

Classes

Client
Cluster
Database
Collection

Functions

Module

function Rongo.new(AppId: string,AppKey: string) -> Client
   AppId: The ID inside your Data API URL
   AppiKey: The API Key which you generated in MongoDB

Client

function Client:GetCluster(Name: string) -> Cluster
   Name: The name of your Cluster, the default one is usually 'Cluster0'

Cluster

function Cluster:GetDatabase(Name: string) -> Database
   Name: The name of your database

Database

function Database:GetCollection(Name: string) -> Collection
   Name: The name of your collection inside the database

Collection

function Collection:FindOne(Filter: {[string]: string | {[string]: string}}?): {[string]: any?}
   Filter: The filter for finding the document, refer to MongoDB documentation for examples

function Collection:FindMany(Filter: {[string]: string | {[string]: string}}?,Limit: number?,Sort: {any?}?,Skip: number?): {{[string]: any?}}
   Filter: The filter for finding the documents, refer to MongoDB documentation for examples
   Limit: The maximum amount of documents that will be returned (Default: 1000)
   Sort: The dictionary used to sort the documents, refer to MongoDB documentation for examples (Default: {})
   Skip: The amount of documents to skip (Default: 0)

function Collection:InsertOne(Document: {[string]: any?}): string?
   Document: The document you'd like to insert into the collection

function Collection:InsertMany(Documents: {{[string]: any?}}): string?
   Documents: The documents you'd like to insert into the collection

function Collection:UpdateOne(Filter: string,Update: {[string]: any?},Upsert: boolean?): {["matchedCount"]: number,["modifiedCount"]: number,["upsertedId"]: string?}?
   Filter: The filter for updating the document, refer to MongoDB documentation for examples
   Update: The dictionary for the updated document
   Upsert: Whether or not the document should be inserted if it does not exist (Default: false)

function Collection:UpdateMany(Filter: string,Update: {[string]: any?},Upsert: boolean?): {["matchedCount"]: number,["modifiedCount"]: number,["upsertedId"]: string?}?
   Filter: The filter for updating the documents, refer to MongoDB documentation for examples
   Update: The dictionary for the updated documents
   Upsert: Whether or not the documents should be inserted if it does not exist (Default: false)

function Collection:ReplaceOne(Filter: string,Replacement: {[string]: any?},Upsert: boolean?}) : {["matchedCount"]: number,["modifiedCount"]: number,["upsertedId"]: string?}?
   Filter: The filter for replacing the document, refer to MongoDB documentation for examples
   Replacement: The document to replace the current one with
   Upsert: Whether or not the documents should be inserted if it does not exist (Default: false)

function Collection:DeleteOne(Filter: {[string]: string | {[string]: string}}?): {[string]: any?}
   Filter: The filter for deleting the document, refer to MongoDB documentation for examples

function Collection:DeleteMany(Filter: {[string]: string | {[string]: string}}?): {[string]: any?}
   Filter: The filter for deleting the documents, refer to MongoDB documentation for examples

Resources

These are some open-source resources which make use of Rongo!

Credits

Rongo was developed by @Starnamics & was made possible by MongoDB

Feel free to use Rongo in whatever way you want as long as it follows the license terms

Thank you!

Exp_Bread · April 15, 2022, 2:22am

I would love to try this a bit later

Starnamics · June 27, 2022, 8:35am

If you’re encountering a 404 error, try changing the beta in the URL variable in the module to v1 and see if that fix works.

I’ll publish a fix shortly!

kuhanaklobasa · July 30, 2022, 9:27pm

Wow, thats so cool. I was looking for exactly this (too lazy to host a web server ;_;).
You should make a discord server for this and scale the project

Bulldo344 · July 30, 2022, 9:51pm

Does this include self-hosted versions of MongoDB? Every single one doesn’t support self-hosted instance of MongoDB.

Starnamics · July 31, 2022, 7:32am

You’ll need to make an API that has the same paths as the Data API to do this.

EatSleepCodeRepeat · August 13, 2022, 10:57am

Would this be better to use for a larg-scale game rather than an external server?

Starnamics · August 15, 2022, 6:35am

If you’re interested in using an external database, I do highly recommend MongoDB as it’s an easy to use service and requires minimal setup compared to other external databases, however if you’re using it for a large game, you might need to spend a bit of money on it (free tier works great though as long as your game isn’t getting too many players) and either way, MongoDB is pretty affordable for their more advanced tiers.

EatSleepCodeRepeat · August 17, 2022, 4:58pm

i’m aware of that, my question was would this be more effective to use than an external database?

Starnamics · August 18, 2022, 5:43am

Oh, well it really depends on your use-case but for myself, I do find it much easier to use than other external databases. Plus, not a lot of external databases have Roblox modules made for them so you might need to make your own if you want to implement them in Roblox.

Starnamics · September 1, 2022, 4:23pm

Rongo now has an article on the MongoDB developer hub!

Read it here: Storing Roblox Game Data in MongoDB Atlas Using Rongo | MongoDB

shr2mp · September 2, 2022, 6:26am

Such as? Because I really don’t think you need an external datastore just to run a Roblox game.

Starnamics · September 2, 2022, 1:31pm

External Databases can be more reliable than Roblox’s DataStores.

This thread contains many other reasons on the use-cases. Please read it before making decisions such as telling people not to use my module.

EatSleepCodeRepeat · September 2, 2022, 2:47pm

I wouldn’t say they are more reliable. In fact I’d vouch Roblox’s datastore are more reliable and more convenient for the following reasons.

You don’t have to worry about data size, costing and hosting.
If Roblox datastores are down (this rarely happens), the chances are that httpservice is down too. (either way no hosting service guarantees 100% uptime)
No need for extra knowledge regarding servers, networking or databases

Point is better avoid external databases unless you necessarily have to use them like in my case.

shr2mp · September 3, 2022, 2:22am

There’s nothing about the use-cases on this thread. Also it’s quite funny how you flagged my post to get it taken down, my post was about the wrapper you made it was nothing off-topic.

Roblox’s datastore API hasn’t gone down in a while, It’s more reliable now and in fact more reliable than an external datastore just like @EatSleepCodeRepeat stated.

Starnamics · November 23, 2022, 8:54am

I’ve published Rongo to Wally so you can now install it by putting rongo = "starnamics/rongo@1.1.2" into your wally.toml file.

prpldev · November 23, 2022, 3:10pm

I feel like there are always reasons to use one thing over another, in my case, the database is also used for a discord bot, website, etc.

noxiirity · March 28, 2023, 11:02pm

Is it possible to retrieve all documents from a collection using this?

I’ve tried using collection:FindMany({}), a bit like what you’d do with the node driver (collection.find({})), however it doesn’t work ([RONGO] Request Failed: HTTP 400 (Bad Request))

I’ve had to set up my own API endpoint which returns all the documents at once, however it’d be nice to cut this middleman out and do it directly through Roblox.

i_iMikey · March 29, 2023, 12:28am

Is it possible to use this API Wrapper with the Community version of MongoDB? I’m not using MongoDB Atlas so it seems I can’t use the Data API, which is what this seems to be using.

Starnamics · March 30, 2023, 3:08am

I believe you can do it by using collection:FindMany({filter: {}}) or something of that sort, you’ll need to check the MongoDB Data API documentation for that.