Skip to content
Record based Erlang driver for MongoDB with gridfs support
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Erlmongo is a pretty complete Erlang driver for mongodb.

It supports records and proplists as datatypes. Strings can be lists or binaries, but strings received from mongodb (as a result of find) will be binaries. The only built in limitation is in regards to record field names. They need to start with [a-z] and be in ascii (because of records). Record values can of course be anything. It's a stupid idea to use non ascii characters as field names anyway.

Because of the way records work in Erlang, you need to call mongoapi:recinfo/2 before using any record, or define each record in erlmongo.hrl.

When you're using a selector (picking which fields in the document you wish to get from mongodb), they have to be in the same sequence as they were defined in the record. For instance:

% -record(mydoc {name, i}).
% This will work
Mong:findOne(#mydoc{i = 10}, [, #mydoc.i]).
% This will NOT work
Mong:findOne(#mydoc{i = 10}, [#mydoc.i,]).

Connections are always single:

  • master/slave - read and write from master

  • master/master - pick a master at random and use it for everything

  • replica pairs - find out which is master and connect to it

If your usage pattern is read heavy and want to use slaves for reading, connect to them with singleServer call. Don't write to slave connections or bad things will happen.

Always use an atom for naming connections. The connection process will register itself on that name.

Connection info is saved in an application variable (erlmongo,connections) and updated with every call to: singleServer, masterSlave, replicaPairs, masterMaster and deleteConnection. If mongodb process crashes for some reason, connections will be restarted. Also if the application itself is stopped and started. You can add a connections variable to file:

% def is name of connection, types can be: masterSlave,masterMaster or replicaPairs. This is how singleServer info is saved:
{env, [{def,{masterSlave,{"localhost",27017},{"localhost",27017}}}]},


% Set mongodb server info. singleServer(PoolName) is the same as singleServer(PoolName,"localhost:27017")
% Create an interface for test database (it has to be a binary)
Mong = mongoapi:new(def,<<"test">>).

% Save a new document
Mong:save(#mydoc{name = "MyDocument", i = 10}).
% Return the document, but only the "i" field (+ _id which always gets returned)
Mong:findOne(#mydoc{i = 10}, []).

% With proplists
Mong:save("mydoc", [{"name", "MyDocument"}, {"i", 10}]).
Mong:findOne("mydoc", [{"i", 10}], [{"name", 1}]).

% Set Index. First parameter is so that the driver knows what collection 
%  we mean. If you have an already constructed record laying around use that.
%  No need to construct a new record just so the driver can read the name.
% Second parameter the index we wish to create. 1 = ascending, -1 = descending.
Mong:ensureIndex(#mydoc{}, [{#mydoc.i, 1}, {, -1}])

% Find examples:

% Parameters: Search criteria, field selector, docs to skip, docs to return
Mong:find(#mydoc{i = 4}, [], 0, 0).
% Same thing but with #search record that provides default parameters
Mong:find(#search{criteria = #mydoc{i = 4}, field_selector = []}).

% Find with options
Mong:findOpt(#mydoc{i = 4}, undefined, [explain], 0, 0).
% Same thing as above
Mong:findOpt(#search{criteria = #mydoc{i = 4}}, [explain]).
% Also the same, with proplists
Mong:findOpt("mydoc", #search{criteria = [{"i",  4}]}, [explain]).

% Embedded records
Mong:save(#mydoc{name = "zembedom", i = 10, address = #address{city = "ny", street = "some", country = "us"}}).
Mong:find(#mydoc{address = #address{city = "la"}}, undefined, 0, 0).

% Advanced queries (supported: gt, lt, gte, lte, ne, in, nin, all, size, exists):
% Documents with even i
Mong:find(#mydoc{i = {mod, 2, 0}}, undefined, 0,0).
% Documents with i larger than 2:
Mong:find(#mydoc{i = {gt, 2}}, undefined, 0,0).
% Documents with i between 2 and 5: 
Mong:find(#mydoc{i = {in, {gt, 2}, {lt, 5}}}, undefined, 0,0).
% in example: 
Mong:find(#mydoc{tags = {in, [2,3,4]}}, undefined, 0,0).
% exists example: 
Mong:find(#mydoc{tags = {exists, false}}, undefined, 0,0).

% GridFS
{ok, Bin} = file:read_file("SomeFile").
% To open file for writing, use gfsNew
PID = Mong:gfsNew("myfile").
% You can set parameters: mime, meta (embedded document), aliases (array of names), chunk size (default 256k)
%                         flushLimit (at which buffer size data gets flushed to mongodb, def. 1MB)
% PID = Mong:gfsNew("myfile", [{chunkSize, 100}]).
% You can also set collection name (default is fd)
% PID = Mong:gfsNew("myfilecol", "myfile", []).
% Reading
PID = Mong:gfsOpen(#gfs_file{filename = "myfile"}).
Res = Mong:gfsRead(PID,100000).

Supported operation list


  • remove

  • save

  • insert

  • update

  • batchInsert

  • ensureIndex

  • deleteIndex

  • deleteIndexes

  • count

  • dropCollection

  • createCollection

  • group


  • find

  • findopt

  • cursor - getMore - closeCursor

  • findOne


  • eval

  • stats

  • runCmd

  • repairDatabase

  • cloneDatabase

  • dropDatabase

  • addUser

  • setProfilingLevel

  • getProfilingLevel


  • gfsNew

  • gfsWrite

  • gfsOpen

  • gfsRead

  • gfsDelete

  • gfsFlush

  • gfsClose


Sergej Jurečko
Something went wrong with that request. Please try again.