Erlang driver for MongoDB with gridfs that works with maps and proplists
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
ebin
src
.gitignore
LICENSE.txt
README.rdoc
rebar.config

README.rdoc

Info

Erlmongo is a pretty complete Erlang driver for mongodb.

All save/update/insert are safe and return if write succeeded.

It supports maps and proplists as datatypes. Strings can be lists or binaries, but strings received from mongodb (as a result of find) will be binaries.

Connections are pools (def. size 10) to master:

  • master/slave - read and write from master

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

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

Always use an atom for naming pools. Name will be used for a public named ets table. Runtime connection API: mongodb:singleServer/1,2 mongodb:replicaPairs/3 mongodb:replicaSets/2 mongodb:masterSlave/3 mongodb:connect/1 mongodb:sharded/2

Replica sets

% List of servers does not have to be the entire list of the replica set.
% Erlmongo will read the primary server from them and connect to it (even if not in the list).
mongodb:replicaSets(mypool,["127.0.0.1:30000","127.0.0.1:30001"]).
mongodb:connect(mypool).

Examples

make
erl
application:start(erlmongo).
% Set mongodb server info. singleServer(PoolName) is the same as singleServer(PoolName,10,"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("mycollection",#{name => "MyDocument", i => 10}).
% Return the document in map form
Mong:findOne("mycollection", #{i => 10}, map).

% With proplists
Mong:save("mydoc", [{"name", "MyDocument"}, {"i", 10}]).
% Return only _id and name field
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("mycollection", [{#mydoc.i, 1}, {#mydoc.name, -1}])

% Find examples:

% Or
M:find("mycollection",[{'or',[{"a",1},{"i",11}]}],undefined,0,100).

% Parameters: Search criteria, field selector, docs to skip, docs to return
Mong:find("mycollection",#{i => 4}, #{name => 1}, 0, 10).

% Find with options
Mong:findOpt("mycollection", #{i => 4}, undefined, [explain], 0, 0).

% Embedded records
Mong:save("mycollection",#{name => "zembedom", i => 10, address = #{city => "ny", street => "some", country => "us"}}).
Mong:find("mycollection",#{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("mycollection",#{i => {mod, 2, 0}}, undefined, 0,0).
% Documents with i larger than 2:
Mong:find("mycollection", #{i => {gt, 2}}, undefined, 0,0).
% Documents with i between 2 and 5:
Mong:find("mycollection", #{i => {in, {gt, 2}, {lt, 5}}}, undefined, 0,0).
% in example:
Mong:find("mycollection", #{tags => {in, [2,3,4]}}, undefined, 0,0).
% exists example:
Mong:find("mycollection", #{tags => {exists, false}}, undefined, 0,0).

% findandmodify command
Mong:runCmd([{"findandmodify", "collectionname"},{"query", [{"fn","onmeta.flv"},{"ch","somechan"}]},{"remove",1}]).

% GridFS
% Always run this on collection before writing the first file
Mong:gfsIndexes().
{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 Data types and modifiers

Look at bson:encode_element/1

Switching to mochijson's style proplists

Mochijson library has a different string/list encoding convention: string = binary array = list You can choose a preferred way to encode with mongoapi:set_encode_style/1. Selected style is set to a selected server and table and not for mongoapi module instance. An example:

...
12> Mong:set_encode_style(default).
ok
13> Mong:save("foobar", [{<<"data">>, [[1.1, 2.2], [3.3, 4.4]]}]).
** exception error: bad argument
     in function  unicode:characters_to_binary/1
        called as unicode:characters_to_binary([[1.1,2.2],[3.3,4.4]])
     in call from mongodb:encode_cstring/1
     in call from mongodb:encode_element/1
     in call from mongodb:'-encode/2-fun-0-'/3
     in call from lists:foldl/3
     in call from mongodb:encode/2
     in call from mongoapi:save/3
14> Mong:set_encode_style(mochijson).
ok
15> Mong:save("foobar", [{<<"data">>, [[1.1, 2.2], [3.3, 4.4]]}]).
{oid,<<"000af08b902dee723e000006">>}

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

  • gdsIndexes

  • gfsNew

  • gfsWrite

  • gfsOpen

  • gfsRead

  • gfsDelete

  • gfsFlush

  • gfsClose

Author

Sergej Jurečko