Rongo 
MongoDB API Wrapper for Roblox
v2.1.1
Use the Rongo Web API to utilize self-hosted instances
Read our article on the MongoDB Developer Hub
Download on Roblox 
Download on Github 
Install with Wally 
View Source 
For Self Hosted MongoDB Instances
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 
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(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
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!
- MongoDB Developer Hub Article
- MongoStore - An alternative to DataStoreService
- Self-hosted MongoDB support
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 toRongo.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 newRongo.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
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
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!
