diff --git a/README.md b/README.md index 2cb1577..ea62d63 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,12 @@ This documentation includes other articles of interest, include: 1. [A tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html). 2. [Replica Sets in Ruby](http://api.mongodb.org/ruby/current/file.REPLICA_SETS.html). 3. [Write Concern in Ruby](http://api.mongodb.org/ruby/current/file.WRITE_CONCERN.html). -4. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html). -5. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html). -6. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html). -6. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html). -7. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html). +4. [Read Preference in Ruby](http://api.mongodb.org/ruby/current/file.READ_PREFERENCE.html). +5. [GridFS in Ruby](http://api.mongodb.org/ruby/current/file.GridFS.html). +6. [Frequently Asked Questions](http://api.mongodb.org/ruby/current/file.FAQ.html). +7. [History](http://api.mongodb.org/ruby/current/file.HISTORY.html). +8. [Release plan](http://api.mongodb.org/ruby/current/file.RELEASES.html). +9. [Credits](http://api.mongodb.org/ruby/current/file.CREDITS.html). Here's a quick code sample. Again, see the [MongoDB Ruby Tutorial](http://api.mongodb.org/ruby/current/file.TUTORIAL.html) for much more: diff --git a/Rakefile b/Rakefile index d684254..e8bbe5b 100644 --- a/Rakefile +++ b/Rakefile @@ -141,7 +141,7 @@ task :ydoc do require File.join(File.dirname(__FILE__), 'lib', 'mongo') out = File.join('ydoc', Mongo::VERSION) FileUtils.rm_rf('ydoc') - system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/HISTORY.md,docs/CREDITS.md,docs/RELEASES.md" + system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e ./yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/READ_PREFERENCE.md,docs/HISTORY.md,docs/CREDITS.md,docs/RELEASES.md" end namespace :bamboo do diff --git a/docs/READ_PREFERENCE.md b/docs/READ_PREFERENCE.md new file mode 100644 index 0000000..eedb7c3 --- /dev/null +++ b/docs/READ_PREFERENCE.md @@ -0,0 +1,39 @@ +# Read Preference in Ruby + +## Setting the read preference + +You can using the `:read` option to specify a query's read preference. There are for now two possible options: + + @collection.find({:doc => 'foo'}, :read => :primary) + @collection.find({:doc => 'foo'}, :read => :secondary) + +In the first case, the query will be directed to the primary node in a replica set. In the second, the query will be sent +to a secondary node. The driver will attempt to choose a secondary node that's nearby, as determined by ping time. If more +than one secondary node is closeby (e.g, responds to pings within 10ms), then a random node within this subset will be chosen. + +## Read preference inheritance + +The Ruby driver allows you to set read preference on each of four levels: the connection, database, collection, and cursor (or read operation). +Objects will inherit the default read preference from their parents. Thus, if you set a read preference of `{:read => :secondary}` when creating +a new connection, then all databases and collections created from that connection will inherit the same setting. See this code example: + + @con = Mongo::ReplSetConnection.new([['localhost', 27017], ['localhost', 27018]], :read => :secondary) + @db = @con['test'] + @collection = @db['foo'] + @collection.find({:name => 'foo'}) + + @collection.find({:name => 'bar'}, :read => :primary) + +Here, the first call to Collection#find will use the inherited read preference, `{:read => :secondary}`. But the second call +to Collection#find overrides this setting by setting the preference to `:primary`. + +You can examine the read preference on any object by calling its `read_preference` method: + + @con.read_preference + @db.read_preference + @collection.read_preference + +## Future work + +In the v2.0 release of the driver, you'll also be able to specify a read preference consisting of a set of tags. This way, +you'll be able to direct reads to a replica set member. You can follow this issue's progress here: (https://jira.mongodb.org/browse/RUBY-326).