mongo 1.1.1 → 1.1.2
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE.txt +1 -13
- data/{README.rdoc → README.md} +113 -151
- data/Rakefile +17 -4
- data/docs/1.0_UPGRADE.md +21 -0
- data/docs/CREDITS.md +119 -0
- data/docs/HISTORY.md +158 -0
- data/docs/TUTORIAL.md +247 -0
- data/lib/mongo.rb +1 -1
- data/lib/mongo/collection.rb +67 -32
- data/lib/mongo/connection.rb +39 -8
- data/lib/mongo/cursor.rb +1 -1
- data/lib/mongo/db.rb +19 -6
- data/lib/mongo/exceptions.rb +3 -0
- data/lib/mongo/gridfs/grid.rb +4 -1
- data/lib/mongo/gridfs/grid_file_system.rb +5 -2
- data/lib/mongo/util/pool.rb +115 -0
- data/mongo.gemspec +4 -5
- data/test/bson/bson_test.rb +3 -1
- data/test/collection_test.rb +30 -0
- data/test/connection_test.rb +65 -52
- data/test/cursor_test.rb +27 -0
- data/test/replica_sets/connect_test.rb +24 -1
- data/test/safe_test.rb +42 -0
- data/test/unit/db_test.rb +2 -0
- data/test/unit/grid_test.rb +49 -0
- data/test/unit/safe_test.rb +125 -0
- metadata +18 -22
- data/HISTORY +0 -215
- data/bin/bson_benchmark.rb +0 -59
- data/bin/fail_if_no_c.rb +0 -11
- data/bin/insert.rb +0 -35
- data/bin/oid.rb +0 -13
- data/examples/admin.rb +0 -43
- data/examples/capped.rb +0 -22
- data/examples/cursor.rb +0 -48
- data/examples/gridfs.rb +0 -44
- data/examples/index_test.rb +0 -126
- data/examples/info.rb +0 -31
- data/examples/queries.rb +0 -70
- data/examples/simple.rb +0 -24
- data/examples/strict.rb +0 -35
- data/examples/types.rb +0 -36
data/LICENSE.txt
CHANGED
@@ -175,18 +175,7 @@
|
|
175
175
|
|
176
176
|
END OF TERMS AND CONDITIONS
|
177
177
|
|
178
|
-
|
179
|
-
|
180
|
-
To apply the Apache License to your work, attach the following
|
181
|
-
boilerplate notice, with the fields enclosed by brackets "[]"
|
182
|
-
replaced with your own identifying information. (Don't include
|
183
|
-
the brackets!) The text should be enclosed in the appropriate
|
184
|
-
comment syntax for the file format. We also recommend that a
|
185
|
-
file or class name and description of purpose be included on the
|
186
|
-
same "printed page" as the copyright notice for easier
|
187
|
-
identification within third-party archives.
|
188
|
-
|
189
|
-
Copyright [yyyy] [name of copyright owner]
|
178
|
+
Copyright 2008-2010 10gen, Inc.
|
190
179
|
|
191
180
|
Licensed under the Apache License, Version 2.0 (the "License");
|
192
181
|
you may not use this file except in compliance with the License.
|
@@ -199,4 +188,3 @@
|
|
199
188
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
200
189
|
See the License for the specific language governing permissions and
|
201
190
|
limitations under the License.
|
202
|
-
|
data/{README.rdoc → README.md}
RENAMED
@@ -1,95 +1,97 @@
|
|
1
|
-
|
1
|
+
# Introduction
|
2
2
|
|
3
|
-
This is the 10gen-supported Ruby driver for MongoDB
|
3
|
+
This is the 10gen-supported Ruby driver for [MongoDB](http://www.mongodb.org).
|
4
4
|
|
5
|
-
|
6
|
-
(http://www.mongodb.org/display/DOCS/Ruby+Tutorial) for much more.
|
5
|
+
This documentation includes other articles of interest, include:
|
7
6
|
|
8
|
-
|
9
|
-
|
10
|
-
|
7
|
+
1. [A tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html).
|
8
|
+
2. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html).
|
9
|
+
3. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html).
|
11
10
|
|
12
|
-
|
13
|
-
|
11
|
+
Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html)
|
12
|
+
for much more:
|
14
13
|
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
14
|
+
require 'rubygems'
|
15
|
+
require 'mongo'
|
16
|
+
include Mongo
|
17
|
+
|
18
|
+
db = Connection.new.db('sample-db')
|
19
|
+
coll = db.collection('test')
|
20
|
+
|
21
|
+
coll.remove
|
22
|
+
3.times do |i|
|
23
|
+
coll.insert({'a' => i+1})
|
24
|
+
end
|
25
|
+
puts "There are #{coll.count()} records. Here they are:"
|
26
|
+
coll.find().each { |doc| puts doc.inspect }
|
21
27
|
|
22
|
-
|
28
|
+
# Installation
|
23
29
|
|
24
|
-
|
30
|
+
### Ruby Versions
|
25
31
|
|
26
32
|
The driver works and is consistently tested on Ruby 1.8.6, 1.8.7, and 1.9.2, and JRuby 1.5.1.
|
27
33
|
|
28
34
|
Note that if you're on 1.8.7, be sure that you're using a patchlevel >= 249. There
|
29
35
|
are some IO bugs in earlier versions.
|
30
36
|
|
31
|
-
|
37
|
+
### Gems
|
32
38
|
|
33
|
-
The driver's gems are hosted at Rubygems.org
|
39
|
+
The driver's gems are hosted at [Rubygems.org](http://rubygems.org). Make sure you're
|
34
40
|
using the latest version of rubygems:
|
35
41
|
|
36
|
-
|
42
|
+
$ gem update --system
|
37
43
|
|
38
44
|
Then you can install the mongo gem as follows:
|
39
45
|
|
40
|
-
|
46
|
+
$ gem install mongo
|
41
47
|
|
42
48
|
The driver also requires the bson gem:
|
43
49
|
|
44
|
-
|
50
|
+
$ gem install bson
|
45
51
|
|
46
52
|
And for a significant performance boost, you'll want to install the C extensions:
|
47
53
|
|
48
|
-
|
54
|
+
$ gem install bson_ext
|
49
55
|
|
50
56
|
Note that bson_ext isn't used with JRuby. Instead, some native Java extensions are bundled with the bson gem.
|
51
57
|
If you ever need to modify these extenions, you can recompile with the following rake task:
|
52
58
|
|
53
|
-
|
59
|
+
$ rake build:java
|
54
60
|
|
55
|
-
|
61
|
+
### From the GitHub source
|
56
62
|
|
57
63
|
The source code is available at http://github.com/mongodb/mongo-ruby-driver.
|
58
64
|
You can either clone the git repository or download a tarball or zip file.
|
59
65
|
Once you have the source, you can use it from wherever you downloaded it or
|
60
66
|
you can install it as a gem from the source by typing
|
61
67
|
|
62
|
-
|
68
|
+
$ rake gem:install
|
63
69
|
|
64
70
|
To install the C extensions from source, type this instead:
|
65
71
|
|
66
|
-
|
72
|
+
$ rake gem:install_extensions
|
67
73
|
|
68
74
|
That's all there is to it!
|
69
75
|
|
70
|
-
|
76
|
+
# Examples
|
71
77
|
|
72
|
-
For extensive examples, see the MongoDB Ruby Tutorial
|
73
|
-
(http://www.mongodb.org/display/DOCS/Ruby+Tutorial).
|
78
|
+
For extensive examples, see the [MongoDB Ruby Tutorial](http://www.mongodb.org/display/DOCS/Ruby+Tutorial).
|
74
79
|
|
75
|
-
Bundled with the driver are many examples, located in the "examples" subdirectory. Samples include using
|
80
|
+
Bundled with the driver are many examples, located in the "docs/examples" subdirectory. Samples include using
|
76
81
|
the driver and using the GridFS class GridStore. MongoDB must be running for
|
77
82
|
these examples to work, of course.
|
78
83
|
|
79
84
|
Here's how to start MongoDB and run the "simple.rb" example:
|
80
85
|
|
81
|
-
|
82
|
-
|
83
|
-
|
84
|
-
|
85
|
-
|
86
|
+
$ cd path/to/mongo
|
87
|
+
$ ./mongod run
|
88
|
+
... then in another window ...
|
89
|
+
$ cd path/to/mongo-ruby-driver
|
90
|
+
$ ruby docs/examples/simple.rb
|
86
91
|
|
87
92
|
See also the test code, especially test/test_db_api.rb.
|
88
93
|
|
89
|
-
|
90
|
-
|
91
|
-
Note: The GridStore class has been deprecated. Use either the Grid or GridFileSystem
|
92
|
-
classes to take advantage of GridFS.
|
94
|
+
# GridFS
|
93
95
|
|
94
96
|
The Ruby driver include two abstractions for storing large files: Grid and GridFileSystem.
|
95
97
|
The Grid class is a Ruby implementation of MongoDB's GridFS file storage
|
@@ -101,87 +103,56 @@ for details, and see examples/gridfs.rb for code that uses many of the Grid
|
|
101
103
|
features (metadata, content type, seek, tell, etc).
|
102
104
|
|
103
105
|
Examples:
|
104
|
-
|
106
|
+
# Write a file on disk to the Grid
|
107
|
+
file = File.open('image.jpg')
|
108
|
+
grid = Grid.new(db)
|
109
|
+
id = grid.put(file)
|
105
110
|
|
106
|
-
|
107
|
-
|
111
|
+
# Retrieve the file
|
112
|
+
file = grid.get(id)
|
113
|
+
file.read
|
108
114
|
|
109
|
-
|
110
|
-
|
111
|
-
|
112
|
-
|
113
|
-
end
|
115
|
+
# Get all the file's metata
|
116
|
+
file.filename
|
117
|
+
file.content_type
|
118
|
+
file.metadata
|
114
119
|
|
115
|
-
|
116
|
-
fs = GridFileSystem.new(db)
|
117
|
-
fs.open('filename', 'r') do |f|
|
118
|
-
puts f.read
|
119
|
-
end
|
120
|
+
# Notes
|
120
121
|
|
121
|
-
|
122
|
-
file = File.open('image.jpg')
|
123
|
-
grid = Grid.new(db)
|
124
|
-
id = grid.put(file)
|
125
|
-
|
126
|
-
# Retrieve the file
|
127
|
-
file = grid.get(id)
|
128
|
-
file.read
|
129
|
-
|
130
|
-
# Get all the file's metata
|
131
|
-
file.filename
|
132
|
-
file.content_type
|
133
|
-
file.metadata
|
134
|
-
|
135
|
-
= Notes
|
136
|
-
|
137
|
-
== Thread Safety
|
122
|
+
## Thread Safety
|
138
123
|
|
139
124
|
The driver is thread-safe.
|
140
125
|
|
141
|
-
|
126
|
+
## Connection Pooling
|
142
127
|
|
143
|
-
As of
|
128
|
+
As of v0.18, the driver implements connection pooling. By default, only one
|
144
129
|
socket connection will be opened to MongoDB. However, if you're running a
|
145
130
|
multi-threaded application, you can specify a maximum pool size and a maximum
|
146
131
|
timeout for waiting for old connections to be released to the pool.
|
147
132
|
|
148
133
|
To set up a pooled connection to a single MongoDB instance:
|
149
134
|
|
150
|
-
|
151
|
-
|
152
|
-
A pooled connection to a paired instance would look like this:
|
153
|
-
|
154
|
-
@conn = Connection.new({:left => ["db1.example.com", 27017],
|
155
|
-
:right => ["db2.example.com", 27017]}, nil,
|
156
|
-
:pool_size => 20, :timeout => 5)
|
135
|
+
@conn = Connection.new("localhost", 27017, :pool_size => 5, :timeout => 5)
|
157
136
|
|
158
137
|
Though the pooling architecture will undoubtedly evolve, it currently owes much credit
|
159
138
|
to the connection pooling implementations in ActiveRecord and PyMongo.
|
160
139
|
|
161
|
-
|
140
|
+
## Using with Phusion Passenger and Unicorn
|
162
141
|
|
163
|
-
When
|
164
|
-
processes
|
165
|
-
activerecord-mongo-adapter handles this for you, so if you are using that
|
166
|
-
you shouldn't need to worry about it. Otherwise you'll either need to use
|
167
|
-
conservative spawning[http://www.modrails.org/documentation/Users%20guide.html#RailsSpawnMethod]
|
168
|
-
or handle reconnecting when passenger forks a new process:
|
142
|
+
When Passenger and Unicorn are in smart spawning mode you need to be sure that child
|
143
|
+
processes will create a new connection to the database. In Passenger, this can be handled like so:
|
169
144
|
|
170
|
-
|
171
|
-
|
172
|
-
|
173
|
-
|
145
|
+
if defined?(PhusionPassenger)
|
146
|
+
PhusionPassenger.on_event(:starting_worker_process) do |forked|
|
147
|
+
if forked
|
148
|
+
# Create new connection here
|
149
|
+
end
|
174
150
|
end
|
175
151
|
end
|
176
|
-
end
|
177
|
-
|
178
|
-
The above code should be put in _environment.rb_ or in an initialization
|
179
|
-
script.
|
180
152
|
|
181
|
-
|
182
|
-
for more details on this issue.
|
153
|
+
The above code should be put into a Rails initializer or other initialization script.
|
183
154
|
|
184
|
-
|
155
|
+
## String Encoding
|
185
156
|
|
186
157
|
The BSON ("Binary JSON") format used to communicate with Mongo requires that
|
187
158
|
strings be UTF-8 (http://en.wikipedia.org/wiki/UTF-8).
|
@@ -191,18 +162,18 @@ and received from Mongo are converted to UTF-8 when necessary, and strings
|
|
191
162
|
read from Mongo will have their character encodings set to UTF-8.
|
192
163
|
|
193
164
|
When used with Ruby 1.8, the bytes in each string are written to and read from
|
194
|
-
Mongo as
|
165
|
+
Mongo as is. If the string is ASCII, all is well, because ASCII is a subset of
|
195
166
|
UTF-8. If the string is not ASCII, it may not be a well-formed UTF-8
|
196
167
|
string.
|
197
168
|
|
198
|
-
|
169
|
+
## Primary Keys
|
199
170
|
|
200
|
-
The field
|
171
|
+
The `_id` field is a primary key. It is treated specially by the database, and
|
201
172
|
its use makes many operations more efficient. The value of an _id may be of
|
202
173
|
any type. The database itself inserts an _id value if none is specified when
|
203
174
|
a record is inserted.
|
204
175
|
|
205
|
-
|
176
|
+
### Primary Key Factories
|
206
177
|
|
207
178
|
A primary key factory is a class you supply to a DB object that knows how to
|
208
179
|
generate _id values. If you want to control _id values or even their types,
|
@@ -211,7 +182,7 @@ using a PK factory lets you do so.
|
|
211
182
|
You can tell the Ruby Mongo driver how to create primary keys by passing in
|
212
183
|
the :pk option to the Connection#db method.
|
213
184
|
|
214
|
-
|
185
|
+
db = Mongo::Connection.new.db('dbname', :pk => MyPKFactory.new)
|
215
186
|
|
216
187
|
A primary key factory object must respond to :create_pk, which should
|
217
188
|
take a hash and return a hash which merges the original hash with any
|
@@ -225,12 +196,12 @@ returned will be inserted.
|
|
225
196
|
|
226
197
|
Here is a sample primary key factory, taken from the tests:
|
227
198
|
|
228
|
-
|
229
|
-
|
230
|
-
|
231
|
-
|
199
|
+
class TestPKFactory
|
200
|
+
def create_pk(row)
|
201
|
+
row['_id'] ||= Mongo::ObjectID.new
|
202
|
+
row
|
203
|
+
end
|
232
204
|
end
|
233
|
-
end
|
234
205
|
|
235
206
|
Here's a slightly more sophisticated one that handles both symbol and string
|
236
207
|
keys. This is the PKFactory that comes with the MongoRecord code (an
|
@@ -252,13 +223,9 @@ changeable at all is so that libraries such as MongoRecord that use this
|
|
252
223
|
driver can set the PK factory after obtaining the database but before using it
|
253
224
|
for the first time.
|
254
225
|
|
255
|
-
|
256
|
-
|
257
|
-
=== Primary Key factories
|
258
|
-
|
259
|
-
See the section on "Primary Keys" above.
|
226
|
+
## The DB Class
|
260
227
|
|
261
|
-
|
228
|
+
### Strict mode
|
262
229
|
|
263
230
|
Each database has an optional strict mode. If strict mode is on, then asking
|
264
231
|
for a collection that does not exist will raise an error, as will asking to
|
@@ -266,90 +233,85 @@ create a collection that already exists. Note that both these operations are
|
|
266
233
|
completely harmless; strict mode is a programmer convenience only.
|
267
234
|
|
268
235
|
To turn on strict mode, either pass in :strict => true when obtaining a DB
|
269
|
-
object or call the
|
236
|
+
object or call the `:strict=` method:
|
270
237
|
|
271
|
-
|
272
|
-
|
273
|
-
|
274
|
-
|
275
|
-
|
238
|
+
db = Connection.new.db('dbname', :strict => true)
|
239
|
+
# I'm feeling lax
|
240
|
+
db.strict = false
|
241
|
+
# No, I'm not!
|
242
|
+
db.strict = true
|
276
243
|
|
277
244
|
The method DB#strict? returns the current value of that flag.
|
278
245
|
|
279
|
-
|
246
|
+
## Cursors
|
280
247
|
|
281
|
-
|
248
|
+
Notes:
|
282
249
|
|
283
|
-
|
250
|
+
* Cursors are enumerable (and have a #to_a method).
|
284
251
|
|
285
|
-
|
252
|
+
* The query doesn't get run until you actually attempt to retrieve data from a
|
286
253
|
cursor.
|
287
254
|
|
288
|
-
|
255
|
+
* Cursors will timeout on the server after 10 minutes. If you need to keep a cursor
|
256
|
+
open for more than 10 minutes, specify `:timeout => false` when you create the cursor.
|
289
257
|
|
290
258
|
|
291
|
-
|
259
|
+
# Testing
|
292
260
|
|
293
|
-
If you have the source code, you can run the tests.
|
294
|
-
the bson_ext C extension enabled.
|
261
|
+
If you have the source code, you can run the tests.
|
295
262
|
|
296
|
-
|
263
|
+
$ rake test:c
|
297
264
|
|
298
|
-
If you want to test the basic Ruby encoder, or if you're running JRuby:
|
265
|
+
If you want to test the basic Ruby encoder, without the C extension, or if you're running JRuby:
|
299
266
|
|
300
|
-
|
267
|
+
$ rake test:ruby
|
301
268
|
|
302
269
|
These will run both unit and functional tests. To run these tests alone:
|
303
270
|
|
304
|
-
|
305
|
-
|
271
|
+
$ rake test:unit
|
272
|
+
$ rake test:functional
|
306
273
|
|
307
274
|
To run any individual rake tasks with the C extension enabled, just pass C_EXT=true to the task:
|
308
275
|
|
309
|
-
|
276
|
+
$ rake test:unit C_EXT=true
|
310
277
|
|
311
|
-
If you want to test replica
|
278
|
+
If you want to test replica set, you can run the following tests
|
312
279
|
individually:
|
313
280
|
|
314
|
-
|
315
|
-
|
316
|
-
|
281
|
+
$ rake test:replica_set_count
|
282
|
+
$ rake test:replica_set_insert
|
283
|
+
$ rake test:replica_set_query
|
317
284
|
|
318
|
-
|
319
|
-
|
320
|
-
$ rake test:pooled_pair_insert
|
321
|
-
|
322
|
-
===Shoulda and Mocha
|
285
|
+
### Shoulda and Mocha
|
323
286
|
|
324
287
|
Running the test suite requires shoulda and mocha. You can install them as follows:
|
325
288
|
|
326
|
-
|
327
|
-
|
289
|
+
$ gem install shoulda
|
290
|
+
$ gem install mocha
|
328
291
|
|
329
292
|
The tests assume that the Mongo database is running on the default port. You
|
330
293
|
can override the default host (localhost) and port (Connection::DEFAULT_PORT) by
|
331
294
|
using the environment variables MONGO_RUBY_DRIVER_HOST and
|
332
295
|
MONGO_RUBY_DRIVER_PORT.
|
333
296
|
|
334
|
-
|
297
|
+
# Documentation
|
335
298
|
|
336
|
-
This documentation is available online at http://api.mongodb.org/ruby. You can
|
299
|
+
This documentation is available online at [http://api.mongodb.org/ruby](http://api.mongodb.org/ruby). You can
|
337
300
|
generate the documentation if you have the source by typing
|
338
301
|
|
339
|
-
|
302
|
+
$ rake ydoc
|
340
303
|
|
341
304
|
Then open the file +ydoc/index.html+.
|
342
305
|
|
343
|
-
|
344
|
-
= Release Notes
|
306
|
+
# Release Notes
|
345
307
|
|
346
308
|
See HISTORY.
|
347
309
|
|
348
|
-
|
310
|
+
# Credits
|
349
311
|
|
350
312
|
See CREDITS.
|
351
313
|
|
352
|
-
|
314
|
+
# License
|
353
315
|
|
354
316
|
Copyright 2008-2010 10gen Inc.
|
355
317
|
|