Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Record based Erlang driver for MongoDB with gridfs support
Erlang
tree: 7d426e7327

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
LICENSE.txt
Makefile
README.rdoc
erlmongo.app
erlmongo.hrl
erlmongo_app.erl
mongoapi.erl
mongodb.erl
mongodb_supervisor.erl

README.rdoc

Info

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.name, #mydoc.i]).
% This will NOT work
Mong:findOne(#mydoc{i = 10}, [#mydoc.i, #mydoc.name]).

WARNING: If you use modifier updates with {set,Value} ($set), do not use records. Mongo changes the document element sequence and this messes up record serialization.

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. Runtime connection API: mongodb:singleServer/1 mongodb:singleServer/2 mongodb:replicaPairs/3 mongodb:masterSlave/3 mongodb:connect/1

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 erlmongo.app 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}}}]},

Examples

make
erl
rr("erlmongo.hrl").
application:start(erlmongo).
% Set mongodb server info. singleServer(PoolName) is the same as singleServer(PoolName,"localhost:27017")
mongodb:singleServer(def).
mongodb:connect(def).
% 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}, [#mydoc.name]).

% 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}, {#mydoc.name, -1}])

% Find examples:

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

% 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", []).
Mong:gfsWrite(PID,Bin).
Mong:gfsClose(PID).
% Reading
PID = Mong:gfsOpen(#gfs_file{filename = "myfile"}).
Res = Mong:gfsRead(PID,100000).
Mong:gfsClose(PID).

Supported operation list

Collections

  • remove

  • save

  • insert

  • update

  • batchInsert

  • ensureIndex

  • deleteIndex

  • deleteIndexes

  • count

  • dropCollection

  • createCollection

  • group

Search

  • find

  • findopt

  • cursor - getMore - closeCursor

  • findOne

DB

  • eval

  • stats

  • runCmd

  • repairDatabase

  • cloneDatabase

  • dropDatabase

  • addUser

  • setProfilingLevel

  • getProfilingLevel

GridFS

  • gfsNew

  • gfsWrite

  • gfsOpen

  • gfsRead

  • gfsDelete

  • gfsFlush

  • gfsClose

Author

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