Mongo, Restheart, and Dokku

Mongo is a popular NoSQL database nowadays. It has several advantages compared to relational databases (schema-less, key-value store, scalable, distributed, propagated consistency) but the main advantage, IMHO, is that JSON is the lingua franca for the data structures it stores and the queries you use. JSON is a nice, simple data structure representation. It can be easily passed between the database and the application; and it can be converted to/from a string and an object in the native language you use. Mongo has many native-language APIs available for interfacing your application with the database, so you should be able to connect your application with Mongo.

Unfortunately, Xamarin Forms applications, written in C#, are Portable Class Library (PCL) applications, and the C# API for Mongo can’t work. Unfortunately, PCL apps and libraries can only link with other PCL libraries that have the same or additional target platforms. So, a PCL app that is targeting Windows, Android, and iOS cannot link with a library that only targets Windows, or only Android, or only iOS.

However, all is not lost. Restheart is an open source REST API server for Mongo databases. You can easily write a layer to encapsulate the calls that you need to access your Mongo database. There aren’t many functions you have to write beyond the usual CRUD, and the signatures for the method are just strings.


The installations instructions are on the website. Get the latest production version of Mongo. Then, execute the installation file. After it completes, create a directory for the database.

md data/db

To run Mongo, type

mongod --dbpath data/db

To set up Restheart, either copy the latest from, or clone the git repository for Restheart. If you are going to build it from scratch, you will need Maven, Java, and various other tools. Note, I highly recommend you build Restheart from git because the documentation is quite poor, and the only really good way to understand the server is to debug it.

To run Restheart, type java -jar ./restheart/target/restheart.jar, or the appropriate jar file. You can specify a configuration file for Restheart as a parameter when executing the jar.


In a SQL database, data are stored in tables. In Mongo, data are stored in a collection. As with SQL, Mongo has CRUD statements for access to the database. The equivalent in Mongo of a row in a SQL table is a document, and is simply a JSON string. A projection of a JSON structure is equivalent to a projection in SQL. If you convert the JSON into a Newtonsoft JObject, you can make a projection of one key/value pair using the [] operator. As in SQL, an index can be created to improve search time.


Example in Mongo shell
Example in Restheart
 Create database
 Create a database named db1.
 Create a database named db1.
use db1
NOTE: you need to insert a collection to actually create the database while using the Mongo shell.
NOTE: Do not set data or you will create a record with that data in the database. It can’t be deleted!
Create table
Create collection
 Create a collection named “col”.
Insert a row in a table
Insert a document in a collecton
Insert {“a1″:”b1”} in collection col.
payload is {“a1″:”b1”}
header is Content-Type: application/json
NOTE: The record type/value doesn’t have to be unique. So, you can insert duplicates if you like.
Read a row
Read a document
Find {} — find all records in collection col.
or just db.col.find()
header is Content-Type: application/json
Read a row
Read a document
Find { “a1” : <value> } — find all records with key a1 in collection col.
db.col.find({“a1”:{$regex : “.*” }})
NOTE: Make sure to note the correct syntax. The Restheart arg parser is very, very poor. E.g., using parentheses instead of equal sign:
This will return all records with a1, which is not what you intended!
To limit the find to the “first” record (whatever that means), add ‘&pagelimit=1’ to the args of the GET url.
Read a row
Read a document with projection
Find { “a1” : <value> } — find all records with key a1 in collection col, but only show keys of “cc”. For example, suppose there is one record, {{“aa”:”bb”}, {“cc”:”dd”}}. Return {“cc”:”dd”}.
db.col.find({“aa”:{$regex : “.*” }}).projection({“cc”:1})
 Update a row
 Update a document
Update {“a1″:”*.”} to {“a1″:”asdf”}
header is Content-Type: application/json
payload is {“a1″:”asdf”}
 Delete a row
 Delete a document
 Delete a record with a particular key/value, { “a1” : <value> }.
 Delete a table
 Delete a collection
 Nuke an entire collection col.
 Delete database
 Delete database
 Nuke the entire database db1.
header contains If-Match:<the id of the database>, e.g., 570e3dc71d9563251070fab3


NOTE: Restheart normally requires an “ETag” header entry, i.e., “If-Match: 570e3dc71d9563251070fab3”, where that number is an ID of the record to delete. You can turn off ETag checking in a configuration file, which you can specify on the java command line.

To get a value, you will have to parse the json for the field of interest. You can use projection to help you with that.

Running Mongo and Restheart on Dokku

To run a Mongo database and a Restheart server on Dokku, you can get a copy of my Github example, then modify it for your needs. The example is here.



Posted in Tip