mongo-lyon 1.2.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (87) hide show
  1. data/LICENSE.txt +190 -0
  2. data/README.md +344 -0
  3. data/Rakefile +202 -0
  4. data/bin/mongo_console +34 -0
  5. data/docs/1.0_UPGRADE.md +21 -0
  6. data/docs/CREDITS.md +123 -0
  7. data/docs/FAQ.md +116 -0
  8. data/docs/GridFS.md +158 -0
  9. data/docs/HISTORY.md +225 -0
  10. data/docs/REPLICA_SETS.md +72 -0
  11. data/docs/TUTORIAL.md +247 -0
  12. data/docs/WRITE_CONCERN.md +28 -0
  13. data/lib/mongo.rb +77 -0
  14. data/lib/mongo/collection.rb +872 -0
  15. data/lib/mongo/connection.rb +875 -0
  16. data/lib/mongo/cursor.rb +449 -0
  17. data/lib/mongo/db.rb +607 -0
  18. data/lib/mongo/exceptions.rb +68 -0
  19. data/lib/mongo/gridfs/grid.rb +106 -0
  20. data/lib/mongo/gridfs/grid_ext.rb +57 -0
  21. data/lib/mongo/gridfs/grid_file_system.rb +145 -0
  22. data/lib/mongo/gridfs/grid_io.rb +394 -0
  23. data/lib/mongo/gridfs/grid_io_fix.rb +38 -0
  24. data/lib/mongo/repl_set_connection.rb +342 -0
  25. data/lib/mongo/util/conversions.rb +89 -0
  26. data/lib/mongo/util/core_ext.rb +60 -0
  27. data/lib/mongo/util/pool.rb +185 -0
  28. data/lib/mongo/util/server_version.rb +71 -0
  29. data/lib/mongo/util/support.rb +82 -0
  30. data/lib/mongo/util/uri_parser.rb +181 -0
  31. data/lib/mongo/version.rb +3 -0
  32. data/mongo.gemspec +34 -0
  33. data/test/auxillary/1.4_features.rb +166 -0
  34. data/test/auxillary/authentication_test.rb +68 -0
  35. data/test/auxillary/autoreconnect_test.rb +41 -0
  36. data/test/auxillary/repl_set_auth_test.rb +58 -0
  37. data/test/auxillary/slave_connection_test.rb +36 -0
  38. data/test/auxillary/threaded_authentication_test.rb +101 -0
  39. data/test/bson/binary_test.rb +15 -0
  40. data/test/bson/bson_test.rb +614 -0
  41. data/test/bson/byte_buffer_test.rb +190 -0
  42. data/test/bson/hash_with_indifferent_access_test.rb +38 -0
  43. data/test/bson/json_test.rb +17 -0
  44. data/test/bson/object_id_test.rb +154 -0
  45. data/test/bson/ordered_hash_test.rb +197 -0
  46. data/test/collection_test.rb +893 -0
  47. data/test/connection_test.rb +303 -0
  48. data/test/conversions_test.rb +120 -0
  49. data/test/cursor_fail_test.rb +75 -0
  50. data/test/cursor_message_test.rb +43 -0
  51. data/test/cursor_test.rb +457 -0
  52. data/test/db_api_test.rb +715 -0
  53. data/test/db_connection_test.rb +15 -0
  54. data/test/db_test.rb +287 -0
  55. data/test/grid_file_system_test.rb +244 -0
  56. data/test/grid_io_test.rb +120 -0
  57. data/test/grid_test.rb +200 -0
  58. data/test/load/thin/load.rb +24 -0
  59. data/test/load/unicorn/load.rb +23 -0
  60. data/test/replica_sets/connect_test.rb +86 -0
  61. data/test/replica_sets/connection_string_test.rb +32 -0
  62. data/test/replica_sets/count_test.rb +35 -0
  63. data/test/replica_sets/insert_test.rb +53 -0
  64. data/test/replica_sets/pooled_insert_test.rb +55 -0
  65. data/test/replica_sets/query_secondaries.rb +96 -0
  66. data/test/replica_sets/query_test.rb +51 -0
  67. data/test/replica_sets/replication_ack_test.rb +66 -0
  68. data/test/replica_sets/rs_test_helper.rb +27 -0
  69. data/test/safe_test.rb +68 -0
  70. data/test/support/hash_with_indifferent_access.rb +199 -0
  71. data/test/support/keys.rb +45 -0
  72. data/test/support_test.rb +19 -0
  73. data/test/test_helper.rb +83 -0
  74. data/test/threading/threading_with_large_pool_test.rb +90 -0
  75. data/test/threading_test.rb +87 -0
  76. data/test/tools/auth_repl_set_manager.rb +14 -0
  77. data/test/tools/repl_set_manager.rb +266 -0
  78. data/test/unit/collection_test.rb +130 -0
  79. data/test/unit/connection_test.rb +98 -0
  80. data/test/unit/cursor_test.rb +99 -0
  81. data/test/unit/db_test.rb +96 -0
  82. data/test/unit/grid_test.rb +49 -0
  83. data/test/unit/pool_test.rb +9 -0
  84. data/test/unit/repl_set_connection_test.rb +72 -0
  85. data/test/unit/safe_test.rb +125 -0
  86. data/test/uri_test.rb +91 -0
  87. metadata +202 -0
data/docs/GridFS.md ADDED
@@ -0,0 +1,158 @@
1
+ # GridFS in Ruby
2
+
3
+ GridFS, which stands for "Grid File Store," is a specification for storing large files in MongoDB. It works by dividing a file into manageable chunks and storing each of those chunks as a separate document. GridFS requires two collections to achieve this: one collection stores each file's metadata (e.g., name, size, etc.) and another stores the chunks themselves. If you're interested in more details, check out the [GridFS Specification](http://www.mongodb.org/display/DOCS/GridFS+Specification).
4
+
5
+ ### The Grid class
6
+
7
+ The [Grid class](Mongo/Grid.html) represents the core GridFS implementation. Grid gives you a simple file store, keyed on a unique ID. This means that duplicate filenames aren't a problem. To use the Grid class, first make sure you have a database, and then instantiate a Grid:
8
+
9
+
10
+ @db = Mongo::Connection.new.db('social_site')
11
+ @grid = Grid.new(@db)
12
+
13
+ #### Saving files
14
+ Once you have a Grid object, you can start saving data to it. The data can be either a string or an IO-like object that responds to a #read method:
15
+
16
+
17
+ # Saving string data
18
+ id = @grid.put("here's some string / binary data")
19
+
20
+ # Saving IO data and including the optional filename
21
+ image = File.open("me.jpg")
22
+ id2 = @grid.put(image, :filename => "me.jpg")
23
+
24
+
25
+ Grid#put returns an object id, which you can use to retrieve the file:
26
+
27
+
28
+ # Get the string we saved
29
+ file = @grid.get(id)
30
+
31
+ # Get the file we saved
32
+ image = @grid.get(id2)
33
+
34
+
35
+ #### File metadata
36
+
37
+ There are accessors for the various file attributes:
38
+
39
+
40
+ image.filename
41
+ # => "me.jpg"
42
+
43
+ image.content_type
44
+ # => "image/jpg"
45
+
46
+ image.file_length
47
+ # => 502357
48
+
49
+ image.upload_date
50
+ # => Mon Mar 01 16:18:30 UTC 2010
51
+
52
+ # Read all the image's data at once
53
+ image.read
54
+
55
+ # Read the first 100k bytes of the image
56
+ image.read(100 * 1024)
57
+
58
+
59
+ When putting a file, you can set many of these attributes and write arbitrary metadata:
60
+
61
+
62
+ # Saving IO data
63
+ file = File.open("me.jpg")
64
+ id2 = @grid.put(file,
65
+ :filename => "my-avatar.jpg"
66
+ :content_type => "application/jpg",
67
+ :_id => 'a-unique-id-to-use-in-lieu-of-a-random-one',
68
+ :chunk_size => 100 * 1024,
69
+ :metadata => {'description' => "taken after a game of ultimate"})
70
+
71
+
72
+ #### Safe mode
73
+
74
+ A kind of safe mode is built into the GridFS specification. When you save a file, and MD5 hash is created on the server. If you save the file in safe mode, an MD5 will be created on the client for comparison with the server version. If the two hashes don't match, an exception will be raised.
75
+
76
+
77
+ image = File.open("me.jpg")
78
+ id2 = @grid.put(image, "my-avatar.jpg", :safe => true)
79
+
80
+
81
+ #### Deleting files
82
+
83
+ Deleting a file is as simple as providing the id:
84
+
85
+
86
+ @grid.delete(id2)
87
+
88
+
89
+ ### The GridFileSystem class
90
+
91
+ [GridFileSystem](http://api.mongodb.org/ruby/current/Mongo/GridFileSystem.html) is a light emulation of a file system and therefore has a couple of unique properties. The first is that filenames are assumed to be unique. The second, a consequence of the first, is that files are versioned. To see what this means, let's create a GridFileSystem instance:
92
+
93
+ #### Saving files
94
+
95
+ @db = Mongo::Connection.new.db("social_site")
96
+ @fs = GridFileSystem.new(@db)
97
+
98
+ Now suppose we want to save the file 'me.jpg.' This is easily done using a filesystem-like API:
99
+
100
+
101
+ image = File.open("me.jpg")
102
+ @fs.open("me.jpg", "w") do |f|
103
+ f.write image
104
+ end
105
+
106
+
107
+ We can then retrieve the file by filename:
108
+
109
+
110
+ image = @fs.open("me.jpg", "r") {|f| f.read }
111
+
112
+
113
+ No problems there. But what if we need to replace the file? That too is straightforward:
114
+
115
+
116
+ image = File.open("me-dancing.jpg")
117
+ @fs.open("me.jpg", "w") do |f|
118
+ f.write image
119
+ end
120
+
121
+
122
+ But a couple things need to be kept in mind. First is that the original 'me.jpg' will be available until the new 'me.jpg' saves. From then on, calls to the #open method will always return the most recently saved version of a file. But, and this the second point, old versions of the file won't be deleted. So if you're going to be rewriting files often, you could end up with a lot of old versions piling up. One solution to this is to use the :delete_old options when writing a file:
123
+
124
+
125
+ image = File.open("me-dancing.jpg")
126
+ @fs.open("me.jpg", "w", :delete_old => true) do |f|
127
+ f.write image
128
+ end
129
+
130
+
131
+ This will delete all but the latest version of the file.
132
+
133
+
134
+ #### Deleting files
135
+
136
+ When you delete a file by name, you delete all versions of that file:
137
+
138
+
139
+ @fs.delete("me.jpg")
140
+
141
+
142
+ #### Metadata and safe mode
143
+
144
+ All of the options for storing metadata and saving in safe mode are available for the GridFileSystem class:
145
+
146
+
147
+ image = File.open("me.jpg")
148
+ @fs.open('my-avatar.jpg', w,
149
+ :content_type => "application/jpg",
150
+ :metadata => {'description' => "taken on 3/1/2010 after a game of ultimate"},
151
+ :_id => 'a-unique-id-to-use-instead-of-the-automatically-generated-one',
152
+ :safe => true) { |f| f.write image }
153
+
154
+
155
+ ### Advanced Users
156
+
157
+ Astute code readers will notice that the Grid and GridFileSystem classes are merely thin wrappers around an underlying [GridIO class](http://api.mongodb.org/ruby/current/Mongo/GridIO.html). This means that it's easy to customize the GridFS implementation presented here; just use GridIO for all the low-level work, and build the API you need in an external manager class similar to Grid or GridFileSystem.
158
+
data/docs/HISTORY.md ADDED
@@ -0,0 +1,225 @@
1
+ # MongoDB Ruby Driver History
2
+
3
+ ### 1.2.4
4
+ 2011-2-23
5
+
6
+ * Fix the exception message shown when there's an IOError (malditogeek)
7
+ * Another update to map-reduce docs for v1.8. Note that if you use the new
8
+ output option {:out => {:inline => true}}, then you must also specify
9
+ :raw => true.
10
+
11
+ ### 1.2.3
12
+ 2011-2-22
13
+
14
+ * Update docs for map-reduce command
15
+ * Minor doc fix
16
+
17
+ ### 1.2.2
18
+ 2011-2-15
19
+
20
+ * Improved replica set failover for edge case.
21
+ * Fix for REE on OSX (Hongli Lai)
22
+
23
+ ### 1.2.1
24
+ 2011-1-18
25
+
26
+ * Enable authentication with connection pooling.
27
+ * Allow custom logging with Connection#instrument (CodeMonkeySteve)
28
+ * Minor fixes and doc improvements.
29
+
30
+ ### 1.2.0
31
+ 2011-1-18
32
+
33
+ * Some minor improvements. See commit history.
34
+
35
+ ### 1.2.rc0
36
+ 2011-1-5
37
+
38
+ Lots of cleanup and minor bug fixes.
39
+ * Issues resolved: http://jira.mongodb.org/browse/RUBY/fixforversion/10222
40
+ * Updated Java BSON to Java driver 2.4.
41
+ * Platform gem for JRuby bson.
42
+
43
+ ### 1.1.5
44
+ 2010-12-15
45
+
46
+ * ReplSetConnection class. This must be used for replica set connections from
47
+ now on. You can still use Connection.multi, but that method has been deprecated.
48
+ * Automated replica set tests. rake test:rs
49
+ * Check that request and response ids match.
50
+ * Several bug fixes. See the commit history for details.
51
+
52
+ ### 1.1.4
53
+ 2010-11-30
54
+
55
+ * Important connection failure fix.
56
+ * ObjectId#to_s optimization (David Cuadrado).
57
+
58
+ ### 1.1.3
59
+ 2010-11-29
60
+
61
+ * Distributed reads for replica set secondaries. See /docs/examples/replica_set.rb and
62
+ http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html for details.
63
+ * Note: when connecting to a replica set, you must use Connection#multi.
64
+ * Cursor#count takes optional skip and limit
65
+ * Collection#ensure_index for caching index creation calls
66
+ * Collection#update and Collection#remove now return error object when using safe mode
67
+ * Important fix for int/long serialization on bug introduced in 1.0.9
68
+ * Numerous tweaks and bug fixes.
69
+
70
+ ### 1.1.2
71
+ 2010-11-4
72
+
73
+ * Two critical fixes to automated failover and replica sets.
74
+ * Bug passing :timeout to Cursor.
75
+ * Permit safe mode specification on Connection, Collection, and DB levels.
76
+ * Specify replica set name on connect to verify connection to the right set.
77
+ * Misc. reorganization of project and docs.
78
+
79
+ ### 1.1.1
80
+ 2010-10-14
81
+
82
+ * Several critical JRuby bug fixes
83
+ * Fixes for JRuby in 1.9 mode
84
+ * Check keys and move id only when necessary for JRuby encoder
85
+
86
+ ## 1.1
87
+ 2010-10-4
88
+
89
+ * Official JRuby support via Java extensons for BSON (beta)
90
+ * Connection#lock! and Connection#unlock! for easy fsync lock
91
+ * Note: BSON::Code is no longer a subclass of String.
92
+
93
+ ### 1.0.9
94
+ 2010-9-20
95
+
96
+ * Significant performance improvements (with a lot of help from Hongli Lai)
97
+
98
+ ### 1.0.8
99
+ 2010-8-27
100
+
101
+ * Cursor#rewind! and more consistent Cursor Enumberable behavior
102
+ * Deprecated ObjectID for ObjectId
103
+ * Numerous minor bug fixes.
104
+
105
+ ### 1.0.7
106
+ 2010-8-4
107
+
108
+ * A few minor test/doc fixes.
109
+ * Better tests for replica sets and replication acknowledgment.
110
+ * Deprecated DB#error and DB#last_status
111
+
112
+ ### 1.0.6
113
+ 2010-7-26
114
+
115
+ * Replica set support.
116
+ * Collection#map_reduce bug fix.
117
+
118
+ ### 1.0.5
119
+ 2010-7-13
120
+
121
+ * Fix for bug introduced in 1.0.4.
122
+
123
+ ### 1.0.4
124
+ 2010-7-13
125
+
126
+ * Removed deprecated
127
+ * Cursor admin option
128
+ * DB#query
129
+ * DB#create_index (use Collection#create_index)
130
+ * DB#command only takes hash options now
131
+ * j2bson executable (neomantra)
132
+ * Fixed bson_ext compilation on Solaris (slyphon)
133
+ * System JS helpers (neovintage)
134
+ * Use one mutex per thread on pooled connections (cremes)
135
+ * Check for CursorNotFound response flag
136
+ * MapReduce can return raw command output using :raw
137
+ * BSON::OrderedHash equality with other Ruby hashes (Ryan Angilly)
138
+ * Fix for broken Socket.send with large payloads (Frédéric De Jaeger)
139
+ * Lots of minor improvements. See commmits.
140
+
141
+ ### 1.0.3
142
+ 2010-6-15
143
+
144
+ * Optimiztion for BSON::OrderedHash
145
+ * Some important fixes.
146
+
147
+ ### 1.0.2
148
+ 2010-6-5
149
+
150
+ This is a minor release for fixing an incompatibility with MongoDB v1.5.2
151
+
152
+ * Fix for boolean response on commands for core server v1.5.2
153
+ * BSON.read_bson_document and b2json executable (neomantra)
154
+ * BSON::ObjectID() shortcut for BSON::ObjectID.from_string (tmm1)
155
+ * Various bug fixes.
156
+
157
+ ### 1.0.1
158
+ 2010-5-7
159
+
160
+ * set Encoding.default_internal
161
+ * DEPRECATE JavaScript string on Collection#find. You now must specify $where explicitly.
162
+ * Added Grid#exist? and GridFileSystem#exist?
163
+ * Support for replication acknowledgment
164
+ * Support for $slice
165
+ * Namespaced OrderedHash under BSON (sleverbor)
166
+
167
+ ## 1.0
168
+ 2010-4-29
169
+ Note: if upgrading from versions prior to 0.20, be sure to upgrade
170
+ to 0.20 before upgrading to 1.0.
171
+
172
+ * Inspected ObjectID is represented in MongoDB extended json format.
173
+ * Support for tailable cursors.
174
+ * Configurable query response batch size (thx. to Aman Gupta)
175
+
176
+ * bson_ext installs on early release of Ruby 1.8.5 (dfitzgibbon)
177
+ * Deprecated DB#create_index. Use Collection#create_index index.
178
+ * Removed deprecated Grid#put syntax; no longer requires a filename.
179
+
180
+ ### 0.20.1
181
+ 2010-4-7
182
+
183
+ * Added bson gem dependency.
184
+
185
+ ### 0.20
186
+ 2010-4-7
187
+
188
+ If upgrading from a previous version of the Ruby driver, please read these notes carefully,
189
+ along with the 0.20_UPGRADE doc.
190
+
191
+ * Support for new commands:
192
+ * Collection#find_and_modify
193
+ * Collection#stats
194
+ * DB#stats
195
+ * Query :fields options allows for values of 0 to exclude fields (houdini, railsjedi).
196
+ * GridFS
197
+ * Option to delete old versions of GridFileSystem entries.
198
+ * Filename is now optional for Grid#put.
199
+ * Option to write arbitrary attributes to a file: @grid.put(@data, :favorite_phrase => "blimey!")
200
+ * Indexes created on the chunks collection are now unique. If you have an existing chunks collection,
201
+ you may want to remove
202
+ * Removed the following deprecated items:
203
+ * GridStore class
204
+ * RegexpOfHolding class
205
+ * Paired connections must now be initialized with Connection.paired
206
+
207
+ * BSON-related code extracted into two separate gems: bson and bson_ext (thx to Chuck Remes).
208
+ * mongo_ext no longer exists.
209
+ * BSON::Binary constructor can now take a string, which will be packed into an array.
210
+ * Exception class adjustments:
211
+ * Mongo::InvalidObjectID moved to BSON::InvalidObjectID
212
+ * Mongo::InvalidDocument moved to BSON::InvalidDocument
213
+ * Mongo::InvalidStringEncoding moved to BSON::InvalidStringEncoding
214
+ * Mongo::InvalidName replaced by Mongo::InvalidNSName and BSON::InvalidKeyName
215
+ * BSON types are now namespaced under the BSON module. These types include:
216
+ * Binary
217
+ * ObjectID
218
+ * Code
219
+ * DBRef
220
+ * MinKey and MaxKey
221
+ * Extensions compile on Rubinius (Chuck Remes).
222
+
223
+ ## Prior to 0.20
224
+
225
+ See git revisions.
@@ -0,0 +1,72 @@
1
+ # Replica Sets in Ruby
2
+
3
+ Here follow a few considerations for those using the MongoDB Ruby driver with [replica sets](http://www.mongodb.org/display/DOCS/Replica+Sets).
4
+
5
+ ### Setup
6
+
7
+ First, make sure that you've configured and initialized a replica set.
8
+
9
+ Use `ReplSetConnection.new` to connect to a replica set. This method, which accepts a variable number of arugments,
10
+ takes a list of seed nodes followed by any connection options. You'll want to specify at least two seed nodes. This gives
11
+ the driver more chances to connect in the event that any one seed node is offline. Once the driver connects, it will
12
+ cache the replica set topology as reported by the given seed node and use that information if a failover is later required.
13
+
14
+ @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017])
15
+
16
+ ### Read slaves
17
+
18
+ If you want to read from a seconday node, you can pass :read_secondary => true to ReplSetConnection#new.
19
+
20
+ @connection = ReplSetConnection.new(['n1.mydb.net', 27017], ['n2.mydb.net', 27017], ['n3.mydb.net', 27017],
21
+ :read_secondary => true)
22
+
23
+ A random secondary will be chosen to be read from. In a typical multi-process Ruby application, you'll have a good distribution of reads across secondary nodes.
24
+
25
+ ### Connection Failures
26
+
27
+ Imagine that either the master node or one of the read nodes goes offline. How will the driver respond?
28
+
29
+ If any read operation fails, the driver will raise a *ConnectionFailure* exception. It then becomes the client's responsibility to decide how to handle this.
30
+
31
+ If the client decides to retry, it's not guaranteed that another member of the replica set will have been promoted to master right away, so it's still possible that the driver will raise another *ConnectionFailure*. However, once a member has been promoted to master, typically within a few seconds, subsequent operations will succeed.
32
+
33
+ The driver will essentially cycle through all known seed addresses until a node identifies itself as master.
34
+
35
+ ### Recovery
36
+
37
+ Driver users may wish to wrap their database calls with failure recovery code. Here's one possibility, which will attempt to connection
38
+ every half second and time out after thirty seconds.
39
+
40
+ # Ensure retry upon failure
41
+ def rescue_connection_failure(max_retries=60)
42
+ retries = 0
43
+ begin
44
+ yield
45
+ rescue Mongo::ConnectionFailure => ex
46
+ retries += 1
47
+ raise ex if retries > max_retries
48
+ sleep(0.5)
49
+ retry
50
+ end
51
+ end
52
+
53
+ # Wrapping a call to #count()
54
+ rescue_connection_failure do
55
+ @db.collection('users').count()
56
+ end
57
+
58
+ Of course, the proper way to handle connection failures will always depend on the individual application. We encourage object-mapper and application developers to publish any promising results.
59
+
60
+ ### Testing
61
+
62
+ The Ruby driver (>= 1.1.5) includes unit tests for verifying replica set behavior. They reside in *tests/replica_sets*. You can run them as a group with the following rake task:
63
+
64
+ rake test:rs
65
+
66
+ The suite will set up a five-node replica set by itself and ensure that driver behaves correctly even in the face
67
+ of individual node failures. Note that the `mongod` executable must be in the search path for this to work.
68
+
69
+ ### Further Reading
70
+
71
+ * [Replica Sets](http://www.mongodb.org/display/DOCS/Replica+Set+Configuration)
72
+ * [Replics Set Configuration](http://www.mongodb.org/display/DOCS/Replica+Set+Configuration)