kbaum-mongo 0.18.3p
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE.txt +202 -0
- data/README.rdoc +339 -0
- data/Rakefile +138 -0
- data/bin/bson_benchmark.rb +59 -0
- data/bin/fail_if_no_c.rb +11 -0
- data/examples/admin.rb +42 -0
- data/examples/capped.rb +22 -0
- data/examples/cursor.rb +48 -0
- data/examples/gridfs.rb +88 -0
- data/examples/index_test.rb +126 -0
- data/examples/info.rb +31 -0
- data/examples/queries.rb +70 -0
- data/examples/simple.rb +24 -0
- data/examples/strict.rb +35 -0
- data/examples/types.rb +36 -0
- data/lib/mongo/collection.rb +609 -0
- data/lib/mongo/connection.rb +672 -0
- data/lib/mongo/cursor.rb +403 -0
- data/lib/mongo/db.rb +555 -0
- data/lib/mongo/exceptions.rb +66 -0
- data/lib/mongo/gridfs/chunk.rb +91 -0
- data/lib/mongo/gridfs/grid.rb +79 -0
- data/lib/mongo/gridfs/grid_file_system.rb +101 -0
- data/lib/mongo/gridfs/grid_io.rb +338 -0
- data/lib/mongo/gridfs/grid_store.rb +580 -0
- data/lib/mongo/gridfs.rb +25 -0
- data/lib/mongo/types/binary.rb +52 -0
- data/lib/mongo/types/code.rb +36 -0
- data/lib/mongo/types/dbref.rb +40 -0
- data/lib/mongo/types/min_max_keys.rb +58 -0
- data/lib/mongo/types/objectid.rb +180 -0
- data/lib/mongo/types/regexp_of_holding.rb +45 -0
- data/lib/mongo/util/bson_c.rb +18 -0
- data/lib/mongo/util/bson_ruby.rb +606 -0
- data/lib/mongo/util/byte_buffer.rb +222 -0
- data/lib/mongo/util/conversions.rb +87 -0
- data/lib/mongo/util/ordered_hash.rb +140 -0
- data/lib/mongo/util/server_version.rb +69 -0
- data/lib/mongo/util/support.rb +26 -0
- data/lib/mongo.rb +63 -0
- data/mongo-ruby-driver.gemspec +28 -0
- data/test/auxillary/autoreconnect_test.rb +42 -0
- data/test/binary_test.rb +15 -0
- data/test/bson_test.rb +427 -0
- data/test/byte_buffer_test.rb +81 -0
- data/test/chunk_test.rb +82 -0
- data/test/collection_test.rb +515 -0
- data/test/connection_test.rb +160 -0
- data/test/conversions_test.rb +120 -0
- data/test/cursor_test.rb +379 -0
- data/test/db_api_test.rb +780 -0
- data/test/db_connection_test.rb +16 -0
- data/test/db_test.rb +272 -0
- data/test/grid_file_system_test.rb +210 -0
- data/test/grid_io_test.rb +78 -0
- data/test/grid_store_test.rb +334 -0
- data/test/grid_test.rb +87 -0
- data/test/objectid_test.rb +125 -0
- data/test/ordered_hash_test.rb +172 -0
- data/test/replica/count_test.rb +34 -0
- data/test/replica/insert_test.rb +50 -0
- data/test/replica/pooled_insert_test.rb +54 -0
- data/test/replica/query_test.rb +39 -0
- data/test/slave_connection_test.rb +36 -0
- data/test/test_helper.rb +42 -0
- data/test/threading/test_threading_large_pool.rb +90 -0
- data/test/threading_test.rb +87 -0
- data/test/unit/collection_test.rb +61 -0
- data/test/unit/connection_test.rb +117 -0
- data/test/unit/cursor_test.rb +93 -0
- data/test/unit/db_test.rb +98 -0
- metadata +127 -0
data/LICENSE.txt
ADDED
@@ -0,0 +1,202 @@
|
|
1
|
+
Apache License
|
2
|
+
Version 2.0, January 2004
|
3
|
+
http://www.apache.org/licenses/
|
4
|
+
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
6
|
+
|
7
|
+
1. Definitions.
|
8
|
+
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
11
|
+
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
13
|
+
the copyright owner that is granting the License.
|
14
|
+
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
16
|
+
other entities that control, are controlled by, or are under common
|
17
|
+
control with that entity. For the purposes of this definition,
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
19
|
+
direction or management of such entity, whether by contract or
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
22
|
+
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
24
|
+
exercising permissions granted by this License.
|
25
|
+
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
27
|
+
including but not limited to software source code, documentation
|
28
|
+
source, and configuration files.
|
29
|
+
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
31
|
+
transformation or translation of a Source form, including but
|
32
|
+
not limited to compiled object code, generated documentation,
|
33
|
+
and conversions to other media types.
|
34
|
+
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
36
|
+
Object form, made available under the License, as indicated by a
|
37
|
+
copyright notice that is included in or attached to the work
|
38
|
+
(an example is provided in the Appendix below).
|
39
|
+
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
46
|
+
the Work and Derivative Works thereof.
|
47
|
+
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
49
|
+
the original version of the Work and any modifications or additions
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
61
|
+
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
64
|
+
subsequently incorporated within the Work.
|
65
|
+
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
72
|
+
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
78
|
+
where such license applies only to those patent claims licensable
|
79
|
+
by such Contributor that are necessarily infringed by their
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
82
|
+
institute patent litigation against any entity (including a
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
85
|
+
or contributory patent infringement, then any patent licenses
|
86
|
+
granted to You under this License for that Work shall terminate
|
87
|
+
as of the date such litigation is filed.
|
88
|
+
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
91
|
+
modifications, and in Source or Object form, provided that You
|
92
|
+
meet the following conditions:
|
93
|
+
|
94
|
+
(a) You must give any other recipients of the Work or
|
95
|
+
Derivative Works a copy of this License; and
|
96
|
+
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
98
|
+
stating that You changed the files; and
|
99
|
+
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
102
|
+
attribution notices from the Source form of the Work,
|
103
|
+
excluding those notices that do not pertain to any part of
|
104
|
+
the Derivative Works; and
|
105
|
+
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
108
|
+
include a readable copy of the attribution notices contained
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
111
|
+
of the following places: within a NOTICE text file distributed
|
112
|
+
as part of the Derivative Works; within the Source form or
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
114
|
+
within a display generated by the Derivative Works, if and
|
115
|
+
wherever such third-party notices normally appear. The contents
|
116
|
+
of the NOTICE file are for informational purposes only and
|
117
|
+
do not modify the License. You may add Your own attribution
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
120
|
+
that such additional attribution notices cannot be construed
|
121
|
+
as modifying the License.
|
122
|
+
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
124
|
+
may provide additional or different license terms and conditions
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
128
|
+
the conditions stated in this License.
|
129
|
+
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
133
|
+
this License, without any additional terms or conditions.
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
135
|
+
the terms of any separate license agreement you may have executed
|
136
|
+
with Licensor regarding such Contributions.
|
137
|
+
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
140
|
+
except as required for reasonable and customary use in describing the
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
142
|
+
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
152
|
+
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
158
|
+
incidental, or consequential damages of any character arising as a
|
159
|
+
result of this License or out of the use or inability to use the
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
162
|
+
other commercial damages or losses), even if such Contributor
|
163
|
+
has been advised of the possibility of such damages.
|
164
|
+
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
168
|
+
or other liability obligations and/or rights consistent with this
|
169
|
+
License. However, in accepting such obligations, You may act only
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
174
|
+
of your accepting any such warranty or additional liability.
|
175
|
+
|
176
|
+
END OF TERMS AND CONDITIONS
|
177
|
+
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
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]
|
190
|
+
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
192
|
+
you may not use this file except in compliance with the License.
|
193
|
+
You may obtain a copy of the License at
|
194
|
+
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
196
|
+
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
200
|
+
See the License for the specific language governing permissions and
|
201
|
+
limitations under the License.
|
202
|
+
|
data/README.rdoc
ADDED
@@ -0,0 +1,339 @@
|
|
1
|
+
= Introduction
|
2
|
+
|
3
|
+
This is the 10gen-supported Ruby driver for MongoDB[http://www.mongodb.org].
|
4
|
+
|
5
|
+
Here's a quick code sample. See the MongoDB Ruby Tutorial
|
6
|
+
(http://www.mongodb.org/display/DOCS/Ruby+Tutorial) for much more.
|
7
|
+
|
8
|
+
require 'rubygems'
|
9
|
+
require 'mongo'
|
10
|
+
include Mongo
|
11
|
+
|
12
|
+
db = Connection.new.db('sample-db')
|
13
|
+
coll = db.collection('test')
|
14
|
+
|
15
|
+
coll.remove
|
16
|
+
3.times do |i|
|
17
|
+
coll.insert({'a' => i+1})
|
18
|
+
end
|
19
|
+
puts "There are #{coll.count()} records. Here they are:"
|
20
|
+
coll.find().each { |doc| puts doc.inspect }
|
21
|
+
|
22
|
+
= Installation
|
23
|
+
|
24
|
+
The driver's gems are hosted on Gemcutter[http://gemcutter.org]. If you haven't
|
25
|
+
installed a gem from Gemcutter before, you'll need to set up Gemcutter first:
|
26
|
+
|
27
|
+
$ gem install gemcutter
|
28
|
+
$ gem tumble
|
29
|
+
|
30
|
+
Once you've installed Gemcutter, install the mongo gem as follows:
|
31
|
+
|
32
|
+
$ gem install mongo
|
33
|
+
|
34
|
+
For a significant performance boost, you should also install the driver's C
|
35
|
+
extensions:
|
36
|
+
|
37
|
+
$ gem install mongo_ext
|
38
|
+
|
39
|
+
=== From the GitHub source
|
40
|
+
|
41
|
+
The source code is available at http://github.com/mongodb/mongo-ruby-driver.
|
42
|
+
You can either clone the git repository or download a tarball or zip file.
|
43
|
+
Once you have the source, you can use it from wherever you downloaded it or
|
44
|
+
you can install it as a gem from the source by typing
|
45
|
+
|
46
|
+
$ rake gem:install
|
47
|
+
|
48
|
+
To install the C extensions from source, type this instead:
|
49
|
+
|
50
|
+
$ rake gem:install_extensions
|
51
|
+
|
52
|
+
That's all there is to it!
|
53
|
+
|
54
|
+
= Examples
|
55
|
+
|
56
|
+
For extensive examples, see the MongoDB Ruby Tutorial
|
57
|
+
(http://www.mongodb.org/display/DOCS/Ruby+Tutorial).
|
58
|
+
|
59
|
+
Bundled with the driver are many examples, located in the "examples" subdirectory. Samples include using
|
60
|
+
the driver and using the GridFS class GridStore. MongoDB must be running for
|
61
|
+
these examples to work, of course.
|
62
|
+
|
63
|
+
Here's how to start MongoDB and run the "simple.rb" example:
|
64
|
+
|
65
|
+
$ cd path/to/mongo
|
66
|
+
$ ./mongod run
|
67
|
+
... then in another window ...
|
68
|
+
$ cd path/to/mongo-ruby-driver
|
69
|
+
$ ruby examples/simple.rb
|
70
|
+
|
71
|
+
See also the test code, especially test/test_db_api.rb.
|
72
|
+
|
73
|
+
= GridStore
|
74
|
+
|
75
|
+
The GridStore class is a Ruby implementation of MongoDB's GridFS file storage
|
76
|
+
system. An instance of GridStore is like an IO object. See the RDocs for
|
77
|
+
details, and see examples/gridfs.rb for code that uses many of the GridStore
|
78
|
+
features (metadata, content type, rewind/seek/tell, etc).
|
79
|
+
|
80
|
+
Note that the GridStore class is not automatically required when you require
|
81
|
+
'mongo'. You also need to require 'mongo/gridfs'
|
82
|
+
|
83
|
+
Example code:
|
84
|
+
|
85
|
+
include GridFS
|
86
|
+
|
87
|
+
# Store the text "Hello, world!" in the grid store.
|
88
|
+
GridStore.open(database, 'filename', 'w') do |f|
|
89
|
+
f.puts "Hello, world!"
|
90
|
+
end
|
91
|
+
|
92
|
+
# Output "Hello, world!"
|
93
|
+
GridStore.open(database, 'filename', 'r') do |f|
|
94
|
+
puts f.read
|
95
|
+
end
|
96
|
+
|
97
|
+
# Add text to the grid store.
|
98
|
+
GridStore.open(database, 'filename', 'w+') do |f|
|
99
|
+
f.puts "But wait, there's more!"
|
100
|
+
end
|
101
|
+
|
102
|
+
# Retrieve everything, outputting "Hello, world!\nBut wait, there's more!\n"
|
103
|
+
GridStore.open(database, 'filename', 'r') do |f|
|
104
|
+
puts f.read
|
105
|
+
end
|
106
|
+
|
107
|
+
|
108
|
+
= Notes
|
109
|
+
|
110
|
+
== Thread Safety
|
111
|
+
|
112
|
+
The driver is thread-safe.
|
113
|
+
|
114
|
+
== Connection Pooling
|
115
|
+
|
116
|
+
As of 0.18, the driver implements connection pooling. By default, only one
|
117
|
+
socket connection will be opened to MongoDB. However, if you're running a
|
118
|
+
multi-threaded application, you can specify a maximum pool size and a maximum
|
119
|
+
timeout for waiting for old connections to be released to the pool.
|
120
|
+
|
121
|
+
To set up a pooled connection to a single MongoDB instance:
|
122
|
+
|
123
|
+
@conn = Connection.new("localhost", 27017, :pool_size => 5, :timeout => 5)
|
124
|
+
|
125
|
+
A pooled connection to a paired instance would look like this:
|
126
|
+
|
127
|
+
@conn = Connection.new({:left => ["db1.example.com", 27017],
|
128
|
+
:right => ["db2.example.com", 27017]}, nil,
|
129
|
+
:pool_size => 20, :timeout => 5)
|
130
|
+
|
131
|
+
Though the pooling architecture will undoubtedly evolve, it currently owes much credit
|
132
|
+
to the connection pooling implementations in ActiveRecord and PyMongo.
|
133
|
+
|
134
|
+
== Using with Phusion Passenger
|
135
|
+
|
136
|
+
When passenger is in smart spawning mode you need to be sure that child
|
137
|
+
processes forked by passenger will create a new connection to the database.
|
138
|
+
activerecord-mongo-adapter handles this for you, so if you are using that
|
139
|
+
you shouldn't need to worry about it. Otherwise you'll either need to use
|
140
|
+
conservative spawning[http://www.modrails.org/documentation/Users%20guide.html#RailsSpawnMethod]
|
141
|
+
or handle reconnecting when passenger forks a new process:
|
142
|
+
|
143
|
+
if defined?(PhusionPassenger)
|
144
|
+
PhusionPassenger.on_event(:starting_worker_process) do |forked|
|
145
|
+
if forked
|
146
|
+
# Call db.connect_to_master to reconnect here
|
147
|
+
end
|
148
|
+
end
|
149
|
+
end
|
150
|
+
|
151
|
+
The above code should be put in _environment.rb_ or in an initialization
|
152
|
+
script.
|
153
|
+
|
154
|
+
See this thread[http://groups.google.com/group/mongodb-user/browse_thread/thread/f31e2d23de38136a]
|
155
|
+
for more details on this issue.
|
156
|
+
|
157
|
+
== String Encoding
|
158
|
+
|
159
|
+
The BSON ("Binary JSON") format used to communicate with Mongo requires that
|
160
|
+
strings be UTF-8 (http://en.wikipedia.org/wiki/UTF-8).
|
161
|
+
|
162
|
+
Ruby 1.9 has built-in character encoding support. All strings sent to Mongo
|
163
|
+
and received from Mongo are converted to UTF-8 when necessary, and strings
|
164
|
+
read from Mongo will have their character encodings set to UTF-8.
|
165
|
+
|
166
|
+
When used with Ruby 1.8, the bytes in each string are written to and read from
|
167
|
+
Mongo as-is. If the string is ASCII all is well, because ASCII is a subset of
|
168
|
+
UTF-8. If the string is not ASCII, it may not be a well-formed UTF-8
|
169
|
+
string.
|
170
|
+
|
171
|
+
== Primary Keys
|
172
|
+
|
173
|
+
The field _id is a primary key. It is treated specially by the database, and
|
174
|
+
its use makes many operations more efficient. The value of an _id may be of
|
175
|
+
any type. The database itself inserts an _id value if none is specified when
|
176
|
+
a record is inserted.
|
177
|
+
|
178
|
+
=== Primary Key Factories
|
179
|
+
|
180
|
+
A primary key factory is a class you supply to a DB object that knows how to
|
181
|
+
generate _id values. If you want to control _id values or even their types,
|
182
|
+
using a PK factory lets you do so.
|
183
|
+
|
184
|
+
You can tell the Ruby Mongo driver how to create primary keys by passing in
|
185
|
+
the :pk_factory option to the Connection#db method.
|
186
|
+
|
187
|
+
db = Mongo::Connection.new.db('dbname', :pk_factory => MyPKFactory.new)
|
188
|
+
|
189
|
+
A primary key factory object must respond to :create_pk, which should take a
|
190
|
+
hash and return a hash which merges the original hash with any primary key
|
191
|
+
fields the factory wishes to inject.
|
192
|
+
|
193
|
+
NOTE: if the object already has a primary key, the factory should not inject
|
194
|
+
a new key; this means that the object may already exist in the database.
|
195
|
+
The idea here is that whenever a record is inserted,
|
196
|
+
the :pk_factory object's +create_pk+ method will be called and
|
197
|
+
the new hash returned will be inserted.
|
198
|
+
|
199
|
+
Here is a sample primary key factory, taken from the tests:
|
200
|
+
|
201
|
+
class TestPKFactory
|
202
|
+
def create_pk(row)
|
203
|
+
row['_id'] ||= Mongo::ObjectID.new
|
204
|
+
row
|
205
|
+
end
|
206
|
+
end
|
207
|
+
|
208
|
+
Here's a slightly more sophisticated one that handles both symbol and string
|
209
|
+
keys. This is the PKFactory that comes with the MongoRecord code (an
|
210
|
+
ActiveRecord-like framework for non-Rails apps) and the AR Mongo adapter code
|
211
|
+
(for Rails):
|
212
|
+
|
213
|
+
class PKFactory
|
214
|
+
def create_pk(row)
|
215
|
+
return row if row[:_id]
|
216
|
+
row.delete(:_id) # in case it exists but the value is nil
|
217
|
+
row['_id'] ||= Mongo::ObjectID.new
|
218
|
+
row
|
219
|
+
end
|
220
|
+
end
|
221
|
+
|
222
|
+
A database's PK factory object may be set either when a DB object is created
|
223
|
+
or immediately after you obtain it, but only once. The only reason it is
|
224
|
+
changeable at all is so that libraries such as MongoRecord that use this
|
225
|
+
driver can set the PK factory after obtaining the database but before using it
|
226
|
+
for the first time.
|
227
|
+
|
228
|
+
== The DB Class
|
229
|
+
|
230
|
+
=== Primary Key factories
|
231
|
+
|
232
|
+
See the section on "Primary Keys" above.
|
233
|
+
|
234
|
+
=== Strict mode
|
235
|
+
|
236
|
+
Each database has an optional strict mode. If strict mode is on, then asking
|
237
|
+
for a collection that does not exist will raise an error, as will asking to
|
238
|
+
create a collection that already exists. Note that both these operations are
|
239
|
+
completely harmless; strict mode is a programmer convenience only.
|
240
|
+
|
241
|
+
To turn on strict mode, either pass in :strict => true when obtaining a DB
|
242
|
+
object or call the :strict= method:
|
243
|
+
|
244
|
+
db = Connection.new.db('dbname', :strict => true)
|
245
|
+
# I'm feeling lax
|
246
|
+
db.strict = false
|
247
|
+
# No, I'm not!
|
248
|
+
db.strict = true
|
249
|
+
|
250
|
+
The method DB#strict? returns the current value of that flag.
|
251
|
+
|
252
|
+
== Cursors
|
253
|
+
|
254
|
+
Random cursor fun facts:
|
255
|
+
|
256
|
+
- Cursors are enumerable.
|
257
|
+
|
258
|
+
- The query doesn't get run until you actually attempt to retrieve data from a
|
259
|
+
cursor.
|
260
|
+
|
261
|
+
- Cursors have a to_a method.
|
262
|
+
|
263
|
+
|
264
|
+
= Testing
|
265
|
+
|
266
|
+
If you have the source code, you can run the tests. There's a separate rake task for testing with
|
267
|
+
the mongo_ext C extension enabled.
|
268
|
+
|
269
|
+
$ rake test:c
|
270
|
+
|
271
|
+
Or, to test without the extension:
|
272
|
+
|
273
|
+
$ rake test:ruby
|
274
|
+
|
275
|
+
These will run both unit and functional tests. To run these tests alone:
|
276
|
+
|
277
|
+
$ rake test:unit
|
278
|
+
$ rake test:functional
|
279
|
+
|
280
|
+
To run any individual rake tasks with the C extension enabled, just pass C_EXT=true to the task:
|
281
|
+
|
282
|
+
$ rake test:unit C_EXT=true
|
283
|
+
|
284
|
+
If you want to test replica pairs, you can run the following tests
|
285
|
+
individually:
|
286
|
+
|
287
|
+
$ rake test:pair_count
|
288
|
+
$ rake test:pair_insert
|
289
|
+
$ rake test:pair_query
|
290
|
+
|
291
|
+
It's also possible to test replica pairs with connection pooling:
|
292
|
+
|
293
|
+
$ rake test:pooled_pair_insert
|
294
|
+
|
295
|
+
===Shoulda and Mocha
|
296
|
+
|
297
|
+
Running the test suite requires shoulda and mocha. You can install them as follows:
|
298
|
+
|
299
|
+
$ gem install shoulda
|
300
|
+
$ gem install mocha
|
301
|
+
|
302
|
+
The tests assume that the Mongo database is running on the default port. You
|
303
|
+
can override the default host (localhost) and port (Connection::DEFAULT_PORT) by
|
304
|
+
using the environment variables MONGO_RUBY_DRIVER_HOST and
|
305
|
+
MONGO_RUBY_DRIVER_PORT.
|
306
|
+
|
307
|
+
= Documentation
|
308
|
+
|
309
|
+
This documentation is available online at http://api.mongodb.org/ruby. You can
|
310
|
+
generate the documentation if you have the source by typing
|
311
|
+
|
312
|
+
$ rake ydoc
|
313
|
+
|
314
|
+
Then open the file +ydoc/index.html+.
|
315
|
+
|
316
|
+
|
317
|
+
= Release Notes
|
318
|
+
|
319
|
+
See HISTORY.
|
320
|
+
|
321
|
+
= Credits
|
322
|
+
|
323
|
+
See CREDITS.
|
324
|
+
|
325
|
+
= License
|
326
|
+
|
327
|
+
Copyright 2008-2010 10gen Inc.
|
328
|
+
|
329
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
330
|
+
you may not use this file except in compliance with the License.
|
331
|
+
You may obtain a copy of the License at
|
332
|
+
|
333
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
334
|
+
|
335
|
+
Unless required by applicable law or agreed to in writing, software
|
336
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
337
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
338
|
+
See the License for the specific language governing permissions and
|
339
|
+
limitations under the License.
|
data/Rakefile
ADDED
@@ -0,0 +1,138 @@
|
|
1
|
+
# -*- mode: ruby; -*-
|
2
|
+
require 'rubygems'
|
3
|
+
require 'rubygems/specification'
|
4
|
+
require 'fileutils'
|
5
|
+
require 'rake'
|
6
|
+
require 'rake/testtask'
|
7
|
+
require 'rake/gempackagetask'
|
8
|
+
begin
|
9
|
+
require 'rake/contrib/rubyforgepublisher'
|
10
|
+
rescue LoadError
|
11
|
+
end
|
12
|
+
require 'rbconfig'
|
13
|
+
include Config
|
14
|
+
ENV['TEST_MODE'] = 'TRUE'
|
15
|
+
|
16
|
+
desc "Test the MongoDB Ruby driver."
|
17
|
+
task :test do
|
18
|
+
puts "\nThis option has changed."
|
19
|
+
puts "\nTo test the driver with the c-extensions:\nrake test:c\n"
|
20
|
+
puts "To test the pure ruby driver: \nrake test:ruby"
|
21
|
+
end
|
22
|
+
|
23
|
+
namespace :test do
|
24
|
+
|
25
|
+
desc "Test the driver with the c extension enabled."
|
26
|
+
task :c do
|
27
|
+
ENV['C_EXT'] = 'TRUE'
|
28
|
+
Rake::Task['test:unit'].invoke
|
29
|
+
Rake::Task['test:functional'].invoke
|
30
|
+
Rake::Task['test:pooled_threading'].invoke
|
31
|
+
Rake::Task['test:drop_databases'].invoke
|
32
|
+
ENV['C_EXT'] = nil
|
33
|
+
end
|
34
|
+
|
35
|
+
desc "Test the driver using pure ruby (no c extension)"
|
36
|
+
task :ruby do
|
37
|
+
ENV['C_EXT'] = nil
|
38
|
+
Rake::Task['test:unit'].invoke
|
39
|
+
Rake::Task['test:functional'].invoke
|
40
|
+
Rake::Task['test:pooled_threading'].invoke
|
41
|
+
Rake::Task['test:drop_databases'].invoke
|
42
|
+
end
|
43
|
+
|
44
|
+
Rake::TestTask.new(:unit) do |t|
|
45
|
+
t.test_files = FileList['test/unit/*_test.rb']
|
46
|
+
t.verbose = true
|
47
|
+
end
|
48
|
+
|
49
|
+
Rake::TestTask.new(:functional) do |t|
|
50
|
+
t.test_files = FileList['test/*_test.rb']
|
51
|
+
t.verbose = true
|
52
|
+
end
|
53
|
+
|
54
|
+
Rake::TestTask.new(:pooled_threading) do |t|
|
55
|
+
t.test_files = FileList['test/threading/*.rb']
|
56
|
+
t.verbose = true
|
57
|
+
end
|
58
|
+
|
59
|
+
Rake::TestTask.new(:pair_count) do |t|
|
60
|
+
t.test_files = FileList['test/replica/count_test.rb']
|
61
|
+
t.verbose = true
|
62
|
+
end
|
63
|
+
|
64
|
+
Rake::TestTask.new(:pair_insert) do |t|
|
65
|
+
t.test_files = FileList['test/replica/insert_test.rb']
|
66
|
+
t.verbose = true
|
67
|
+
end
|
68
|
+
|
69
|
+
Rake::TestTask.new(:pooled_pair_insert) do |t|
|
70
|
+
t.test_files = FileList['test/replica/pooled_insert_test.rb']
|
71
|
+
t.verbose = true
|
72
|
+
end
|
73
|
+
|
74
|
+
Rake::TestTask.new(:pair_query) do |t|
|
75
|
+
t.test_files = FileList['test/replica/query_test.rb']
|
76
|
+
t.verbose = true
|
77
|
+
end
|
78
|
+
|
79
|
+
Rake::TestTask.new(:auto_reconnect) do |t|
|
80
|
+
t.test_files = FileList['test/auxillary/autoreconnect_test.rb']
|
81
|
+
t.verbose = true
|
82
|
+
end
|
83
|
+
|
84
|
+
task :drop_databases do |t|
|
85
|
+
puts "Dropping test database..."
|
86
|
+
require File.join(File.dirname(__FILE__), 'lib', 'mongo')
|
87
|
+
include Mongo
|
88
|
+
con = Connection.new(ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost',
|
89
|
+
ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT)
|
90
|
+
con.drop_database('ruby-mongo-test')
|
91
|
+
end
|
92
|
+
end
|
93
|
+
|
94
|
+
desc "Generate documentation"
|
95
|
+
task :rdoc do
|
96
|
+
version = eval(File.read("mongo-ruby-driver.gemspec")).version
|
97
|
+
out = File.join('html', version.to_s)
|
98
|
+
FileUtils.rm_rf('html')
|
99
|
+
system "rdoc --main README.rdoc --op #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
|
100
|
+
end
|
101
|
+
|
102
|
+
desc "Generate YARD documentation"
|
103
|
+
task :ydoc do
|
104
|
+
require File.join(File.dirname(__FILE__), 'lib', 'mongo')
|
105
|
+
out = File.join('ydoc', Mongo::VERSION)
|
106
|
+
FileUtils.rm_rf('ydoc')
|
107
|
+
system "yardoc lib/**/*.rb lib/mongo/**/*.rb -e docs/yard_ext.rb -p docs/templates -o #{out} --title MongoRuby-#{Mongo::VERSION}"
|
108
|
+
end
|
109
|
+
|
110
|
+
desc "Publish documentation to mongo.rubyforge.org"
|
111
|
+
task :publish => [:rdoc] do
|
112
|
+
# Assumes docs are in ./html
|
113
|
+
Rake::RubyForgePublisher.new(GEM, RUBYFORGE_USER).upload
|
114
|
+
end
|
115
|
+
|
116
|
+
namespace :gem do
|
117
|
+
|
118
|
+
desc "Install the gem locally"
|
119
|
+
task :install do
|
120
|
+
sh "gem build mongo-ruby-driver.gemspec"
|
121
|
+
sh "gem install mongo-*.gem"
|
122
|
+
sh "rm mongo-*.gem"
|
123
|
+
end
|
124
|
+
|
125
|
+
desc "Install the optional c extensions"
|
126
|
+
task :install_extensions do
|
127
|
+
sh "gem build mongo-extensions.gemspec"
|
128
|
+
sh "gem install mongo_ext-*.gem"
|
129
|
+
sh "rm mongo_ext-*.gem"
|
130
|
+
end
|
131
|
+
|
132
|
+
end
|
133
|
+
|
134
|
+
task :default => :list
|
135
|
+
|
136
|
+
task :list do
|
137
|
+
system 'rake -T'
|
138
|
+
end
|