[🎉 2.1.0] Rongo - MongoDB API Wrapper for Roblox (WITH SELF-HOSTING SUPPORT)

Rongo :tada:

MongoDB API Wrapper for Roblox
v2.1.1

:sparkles: Use the Rongo Web API to utilize self-hosted instances :sparkles:

Read our article on the MongoDB Developer Hub


Download on Roblox :inbox_tray:
Download on Github :link:
Install with Wally :dog:
View Source :computer:

For Self Hosted MongoDB Instances :sparkles:


IMPORTANT NOTICE:

Rongo has been updated to version 2.0.0; this is a breaking change, the internals of Rongo has been entirely rewritten to provide a better developer experience and also compatibility fixes, if you are using an older version of Rongo and would like to update, the core change would be the way you initialize a new client, you now need to put the full Data API URL as the first argument and your API key in the second.

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 extremely 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@2.1.1" into your wally.toml file (make sure to get the latest version on Wally)

Scroll down for some usage examples & documentation :slight_smile:


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
image

2 - Enable the Data API
image
(make sure to select the sources)

3 - Copy your API ID & store it somewhere safe
image
image
(only copy this, don’t copy the entire URL)

4 - Click on the “Create API Key” button
image

5 - Enter a name then press the generate button
image

Copy your API key & store it somewhere safe
image

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(DATA_API_URL, YOUR_API_KEY) --// Replace these with the ID and key you stored earlier!
local Cluster = Client:GetCluster("Cluster") --// Replace this with the name of your cluster (usually "Cluster0")
local Database = Cluster:GetDatabase("Database") --// Replace this with the name of your database!
local Collection = Database:GetCollection("Collection") --// 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!

Find all documents in a collection

Traditionally with MongoDB, to find all documents in a collection you’d simply run find({}), with an empty dictionary for a filter, however due to the way Lua handles JSON, this is not possible, however a work around would be:

Collection:FindMany({["_id"] = { ["$exists"] = true }}))

This will list any document which has an _id index, which should be all documents within a collection; this same method applies to any of the endpoints in which you would like to filter all documents.


Documentation

partially outdated, new documentation coming soon

Classes

Client
Cluster
Database
Collection

Functions

Module

function Rongo.new(Url: string,Key: string) -> Client
   Url: Your Data API URL
   Key: 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}}?, Projection: {[string]: number}?, Sort: {[string]: number}?,Limit: number?, Skip: number?) : {{[string]: any}}?
   Filter: The filter for finding the documents, refer to MongoDB documentation for examples
   Projection: A [MongoDB projection](https://www.mongodb.com/docs/manual/tutorial/project-fields-from-query-results/) for matched documents returned by the operation
   Sort: The dictionary used to sort the documents, refer to MongoDB documentation 
   for examples (Default: {})
   Limit: The maximum amount of documents that will be returned (Default: 1000)
   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!


Change Log

Version 2.1.0

Rongo has been updated to Version 2.1.0, introducing some minor changes and support for external and self-hosted MongoDB instances.
This change includes:

  • New Rongo.auth() method to pass as the second argument to Rongo.new(), accepting uri, emailpassword, key and bearer as the first argument and the pertaining value(s) as the second and third arguments.
  • Support for self-hosted instances that utilize the Rongo Web API to connect. This can be done using the API URL in the first argument of Rongo.new() and the new Rongo.auth("uri",...) for the authentication argument.

No action is required from your end if you are not interested in using self-hosted instances; the change did implement minor bug fixes however so I would recommend updating to the latest version.

Old Change Logs

Version 2.0.0

Rongo has reached Version 2.0.0, this is still in early stages and you may encounter bugs.
This change included:

  • A complete rewrite of Rongo internals, updating them to match the current state of the MongoDB Data API
  • Additional authentication types (API Key, Bearer Token and Email/Password)
  • Added additional endpoints (Aggregate)
  • Clearer and more detailed errors & error handling
  • Bug fixes to common issues with 1.0.0

Rongo Web API :sparkles:

You can now deploy your own 1:1 Rongo compatible API to interact with self-hosted MongoDB instances!

It is as simple as clicking a button and deploying to your own server, then all you need to do is use the following code:

local Client = Rongo.new("https://api.example.com", Rongo.auth("uri","mongodb://...")

It should work straight out of the box with any MongoDB instance.

Important to note that the current version does not have pre-implemented authentication or rate-limiting, among other security features, please keep this in mind.

Find the Rongo Web API on Github :sparkles:

Feel free to use https://rongo.untitledgames.dev to test it out! (I will most likely shutdown this API at some point, please do not use it in production.


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! :slight_smile:

67 Likes

I would love to try this a bit later

2 Likes

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!

3 Likes

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

4 Likes

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

3 Likes

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

2 Likes

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

2 Likes

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.

2 Likes

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

2 Likes

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.

2 Likes

Rongo now has an article on the MongoDB developer hub!

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

3 Likes

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

1 Like

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.

2 Likes

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.

  1. You don’t have to worry about data size, costing and hosting.
  2. If Roblox datastores are down (this rarely happens), the chances are that httpservice is down too. (either way no hosting service guarantees 100% uptime)
  3. 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.

1 Like

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.

2 Likes

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.

2 Likes

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.

2 Likes

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.

1 Like

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.

2 Likes

You was pretty much correct, all you needed to do is collection:FindMany() and it returns them all. Thanks!

2 Likes