Skip to content
Newer
Older
100644 101 lines (56 sloc) 7.2 KB
f2c49cf update README
Tony Hannan authored
1 This is the MongoDB driver for Erlang. [MongoDB](http://www.mongodb.org) is a document-oriented database management system. A driver is a client library that provides an API for connecting to MongoDB servers, performing queries and updates on those servers, and performing administrative tasks like creating indexes and viewing statistics.
b3ae3bf add README
Tony Hannan authored
2
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
3 This version of the driver supports connecting to a single server or replica set, and pooling of both types of connections. Both connection types and pools are thread-safe, i.e. multiple processes can use the same connection/pool simultaneously without interfering with each other.
b3ae3bf add README
Tony Hannan authored
4
d4cfcfc Add how to download to README
Tony Hannan authored
5 This driver is implemented as an Erlang application named *mongodb*. It depends on another Erlang library application named [*bson*](http://github.com/TonyGen/bson-erlang), which defines the document type and its standard binary representation. You need both of these. Below we describe the mongodb application; you should also see the bson application to understand the document type.
b3ae3bf add README
Tony Hannan authored
6
aec087c edit Readme
Tony Hannan authored
7 ### Installing
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
8
9 Download and compile each application
b3ae3bf add README
Tony Hannan authored
10
d4cfcfc Add how to download to README
Tony Hannan authored
11 $ git clone git://github.com/TonyGen/bson-erlang.git bson
12 $ git clone git://github.com/TonyGen/mongodb-erlang.git mongodb
b3ae3bf add README
Tony Hannan authored
13 $ cd bson
14 $ erlc -o ebin -I include src/*.erl
15 $ cd ../mongodb
16 $ erlc -o ebin -I include -I .. src/*.erl
17 $ cd ..
18
19 Then install them in your standard Erlang library location or include them in your path on startup
20
21 $ erl -pa bson/ebin mongodb/ebin
22
aec087c edit Readme
Tony Hannan authored
23 ### Starting
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
24
b3ae3bf add README
Tony Hannan authored
25 The mongodb application needs be started before using (to initialize an internal ets table of counters)
26
27 > application:start (mongodb).
28
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
29 Although the mongodb application includes several modules, you should only need to use *mongo*, which is the top-level interface for the driver, and the generic *pool* if desired. Likewise, you should only need to use the *bson* module in the bson application.
30
aec087c edit Readme
Tony Hannan authored
31 ### Connecting
b3ae3bf add README
Tony Hannan authored
32
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
33 To connect to a mongodb server listening on `localhost:27017` (or any address & port of your choosing)
b3ae3bf add README
Tony Hannan authored
34
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
35 > Host = {localhost, 27017}.
36 > {ok, Conn} = mongo:connect (Host).
b3ae3bf add README
Tony Hannan authored
37
0a8cc8c Documents are now tuples instead of lists
Tony Hannan authored
38 `27017` is the default port so you could elide it in this case and just supply `localhost` as the argument. `mongo:connect` returns `{error, Reason}` if it failed to connect.
b3ae3bf add README
Tony Hannan authored
39
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
40 Remember to close the connection when finished using it via `mongo:disconnect`.
41
42 To connect to a replica set named "rs1" with seed list of members: `localhost:27017` & `localhost:27018`
43
44 > Replset = {<<"rs1">>, [{localhost, 27017}, {localhost, 27018}]}.
aa1741b fix accepting rs_connection in mongo:do
Tony Hannan authored
45 > Conn = mongo:rs_connect (Replset).
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
46
47 `mongo:do` below will connect to the primary or a secondary in the replica set depending on the read-mode supplied.
48
aec087c edit Readme
Tony Hannan authored
49 ### Querying
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
50
51 A database operation happens in the context of a connection (single server or replica set), database, read-mode, and write-mode. These four parameters are supplied once at the beginning of a sequence of read/write operations. Furthermore, if one of the operations fails no further operations in the sequence are executed and an error is returned for the entire sequence.
b3ae3bf add README
Tony Hannan authored
52
53 > mongo:do (safe, master, Conn, test, fun() ->
0a8cc8c Documents are now tuples instead of lists
Tony Hannan authored
54 mongo:delete (foo, {}),
55 mongo:insert (foo, {x,1, y,2}),
56 mongo:find (foo, {x,1}) end).
b3ae3bf add README
Tony Hannan authored
57
67f7d50 small typos in README
Tony Hannan authored
58 `safe`, along with `{safe, GetLastErrorParams}` and `unsafe`, are write-modes. Safe mode makes a *getLastError* request after every write in the sequence. If the reply says it failed then the rest of the sequence is aborted and `mongo:do` returns `{failure, {write_failure, Reason}}`, or `{failure, not_master}` when connected to a slave. An example write failure is attempting to insert a duplicate key that is indexed to be unique. Alternatively, unsafe mode issues every write without a confirmation, so if a write fails you won't know about it and remaining operations will be executed. This is unsafe but faster because you there is no round-trip delay.
b3ae3bf add README
Tony Hannan authored
59
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
60 `master`, along with `slave_ok`, are read-modes. `master` means every query in the sequence must read fresh data (from a master/primary server). If the connected server is not a master then the first read will fail, the remaining operations will be aborted, and `mongo:do` will return `{failure, not_master}`. `slave_ok` means every query is allowed to read stale data from a slave/secondary (fresh data from a master is fine too).
b3ae3bf add README
Tony Hannan authored
61
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
62 `Conn` is the connection or rs_connection we send the operations to. If the connection fails during one of the operations then the remaining operations are aborted and `{failure, {connection_failure, Reason}}` is returned.
b3ae3bf add README
Tony Hannan authored
63
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
64 `test` is the name of the database in this example. Collections accessed in the sequence (`foo` in this example) are taken from the database given in this fourth argument. If a collection is missing from the database it will be automatically created upon first access.
b3ae3bf add README
Tony Hannan authored
65
4ef9e7b edit README
Tony Hannan authored
66 If there are no errors in the sequence of operations then the result of the last operation is returned as the result of the entire `mongo:do` command. It is wrapped in an *ok* tuple as in `{ok, Result}` to distinguish it from an error.
b3ae3bf add README
Tony Hannan authored
67
d6fd289 Fix wire protocol bit flags order. Catch not_master read and write er…
Tony Hannan authored
68 `mongo:find` returns a *cursor* holding the pending list of results, which are accessed using `mongo:next` to get the next result, and `mongo:rest` to get the remaining results. Either one throws `{cursor_expired, Cursor}` if the cursor was idle for more than 10 minutes. This exception is caught by `mongo:do` and returned as `{failure, {cursor_expired, Cursor}}`. `mongo:rest` also closes the cursor, otherwise you should close the cursor when finished using `mongo:close_cursor`.
b3ae3bf add README
Tony Hannan authored
69
e7bc02e edoc annotations in src comments
Tony Hannan authored
70 See the [*mongo*](http://github.com/TonyGen/mongodb-erlang/blob/master/src/mongo.erl) module for a description of all operations. A type specification is provided with each operation so you know the expected arguments and results. The spec line also has a comment if it performs a side-effect such as IO and what exceptions it may throw. No comment means it is a pure function. Also, see the [*bson* module](http://github.com/TonyGen/bson-erlang/blob/master/src/bson.erl) in the bson application for details on the document type and its value types.
b3ae3bf add README
Tony Hannan authored
71
aec087c edit Readme
Tony Hannan authored
72 ### Administering
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
73
fe00618 auth & add_user
Tony Hannan authored
74 This driver does not provide helper functions for commands. Use `mongo:command` directly and refer to the [MongoDB documentation](http://www.mongodb.org/display/DOCS/Commands) for how to issue raw commands.
75
76 There are functions for complex commands like `mongo:auth`, `mongo:add_user`, and `mongo:create_index`.
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
77
aec087c edit Readme
Tony Hannan authored
78 ### Pooling
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
79
5cbf4de Update types and Readme that referred to old pool name
Tony Hannan authored
80 A single (replset-)connection is thread-safe, i.e. multiple `mongo:do` actions can access it simultaneously. However, if you want to increase concurrency by using multiple connection simultaneously, you can create a pool of connections using the generic `resource_pool` module with the appropriate factory object supplied by `mongo` module.
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
81
82 To create a connection pool of max size 10 to a single Host
83
5cbf4de Update types and Readme that referred to old pool name
Tony Hannan authored
84 > Pool = resource_pool:new (mongo:connect_factory (Host), 10).
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
85
86 To create a rs-connection pool of max size 10 to a Replset
87
5cbf4de Update types and Readme that referred to old pool name
Tony Hannan authored
88 > Pool = resource_pool:new (mongo:rs_connect_factory (Replset), 10).
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
89
90 To get a (replset-)connection from the pool
91
5cbf4de Update types and Readme that referred to old pool name
Tony Hannan authored
92 > {ok, Conn} = resource_pool:get (Pool).
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
93
5cbf4de Update types and Readme that referred to old pool name
Tony Hannan authored
94 `Conn` can then be supplied to `mongo:do`. `resource_pool:get` will return `{error, Reason}` if can't connect.
187d967 mongo:do accepts connnection() or rs_connection()
Tony Hannan authored
95
e94cec0 edoc generation
Tony Hannan authored
96 Close the pool when done using it and all its connections via `resource_pool:close`.
97
98 ### More Documentation
99
100 [API Docs](http://api.mongodb.org/erlang/mongodb/) - Documentation generated from source code comments
Something went wrong with that request. Please try again.