/mongo-ruby-driver

Ruby driver for the 10gen MongoDB

Primary LanguageRubyApache License 2.0Apache-2.0

Introduction ↑

This is a Ruby driver for MongoDB.

Here is a quick code sample. See the files in the “examples” subdirectory for many more.

require 'mongo'

include XGen::Mongo::Driver

db = Mongo.new('localhost').db('sample-db')
coll = db.collection('test')

coll.clear
3.times { |i| coll.insert({'a' => i+1}) }
puts "There are #{coll.count()} records. Here they are:"
coll.find().each { |doc| puts doc.inspect }

This driver also includes an implementation of a GridStore class, a Ruby interface to Mongo’s GridFS storage.

Installation ↑

The driver’s gems are hosted on Gemcutter. If you haven’t installed a gem from Gemcutter before you’ll need to set up Gemcutter first

$ gem install gemcutter
$ gem tumble

If (or once) you have Gemcutter setup, install the “mongo” gem by typing

$ gem install mongo

For a significant performance boost, you should also install the driver’s C extensions:

$ gem install mongo_ext

From the GitHub source ↑

The source code is available at github.com/mongodb/mongo-ruby-driver. You can either clone the git repository or download a tarball or zip file. Once you have the source, you can use it from wherever you downloaded it or you can install it as a gem from the source by typing

$ rake gem:install

To install the C extensions from source, type this instead:

$ rake gem:install_extensions

That’s all there is to it!

Examples ↑

There are many examples in the “examples” subdirectory. Samples include using the driver and using the GridFS class GridStore. Mongo must be running for these examples to work, of course.

Here’s how to start mongo and run the “simple.rb” example:

$ cd path/to/mongo
$ ./mongod run
... then in another window ...
$ cd path/to/mongo-ruby-driver
$ ruby examples/simple.rb

See also the test code, especially test/test_db_api.rb.

The Driver ↑

Here is some simple example code:

require 'rubygems'        # not required for Ruby 1.9
require 'mongo'

include XGen::Mongo::Driver
db = Mongo.new.db('my-db-name')
things = db.collection('things')

things.clear
things.insert('a' => 42)
things.insert('a' => 99, 'b' => Time.now)
puts things.count                               # => 2
puts things.find('a' => 42).next_object.inspect # {"a"=>42}

GridStore ↑

The GridStore class is a Ruby implementation of Mongo’s GridFS file storage system. An instance of GridStore is like an IO object. See the rdocs for details, and see examples/gridfs.rb for code that uses many of the GridStore features like metadata, content type, rewind/seek/tell, etc.

Note that the GridStore class is not automatically required when you require ‘mongo’. You need to require ‘mongo/gridfs’.

Example code:

GridStore.open(database, 'filename', 'w') { |f|
  f.puts "Hello, world!"
}
GridStore.open(database, 'filename, 'r') { |f|
  puts f.read         # => Hello, world!\n
}
GridStore.open(database, 'filename', 'w+') { |f|
  f.puts "But wait, there's more!"
}
GridStore.open(database, 'filename, 'r') { |f|
  puts f.read         # => Hello, world!\nBut wait, there's more!\n
}

Notes ↑

Thread Safety ↑

mongo-ruby-driver is thread safe.

Using with Phusion Passenger ↑

When passenger is in smart spawning mode you need to be sure that child processes forked by passenger will create a new connection to the database. activerecord-mongo-adapter handles this for you, so if you are using that you shouldn’t need to worry about it. Otherwise you’ll either need to use conservative spawning or handle reconnecting when passenger forks a new process:

if defined?(PhusionPassenger)
  PhusionPassenger.on_event(:starting_worker_process) do |forked|
    if forked
      # Call db.connect_to_master to reconnect here
    end
  end
end

The above code should be put in environment.rb or an initialization script.

See this thread for more details on this issue.

String Encoding ↑

The BSON (“Binary JSON”) format used to communicate with Mongo requires that strings be UTF-8 (en.wikipedia.org/wiki/UTF-8).

Ruby 1.9 has built-in character encoding support. All strings sent to Mongo and received from Mongo are converted to UTF-8 when necessary, and strings read from Mongo will have their character encodings set to UTF-8.

When used with Ruby 1.8, the bytes in each string are written to and read from Mongo as-is. If the string is ASCII all is well, because ASCII is a subset of UTF-8. If the string is not ASCII then it may not be a well-formed UTF-8 string.

Primary Keys ↑

The field _id is a primary key. It is treated specially by the database, and its use makes many operations more efficient. The value of an _id may be of any type. The database itself inserts an _id value if none is specified when a record is inserted.

Primary Key Factories ↑

A primary key factory is a class you supply to a DB object that knows how to generate _id values. If you want to control _id values or even their types, using a PK factory lets you do so.

You can tell the Ruby Mongo driver how to create primary keys by passing in the :pk option to the Mongo#db method.

include XGen::Mongo::Driver
db = Mongo.new.db('dbname', :pk => MyPKFactory.new)

A primary key factory object must respond to :create_pk, which should take a hash and return a hash which merges the original hash with any primary key fields the factory wishes to inject. NOTE: if the object already has a primary key, the factory should not inject a new key; this means that the object is being used in a repsert but it already exists. The idea here is that whenever a record is inserted, the :pk object’s create_pk method will be called and the new hash returned will be inserted.

Here is a sample primary key factory, taken from the tests:

class TestPKFactory
  def create_pk(row)
    row['_id'] ||= XGen::Mongo::Driver::ObjectID.new
    row
  end
end

Here’s a slightly more sophisticated one that handles both symbol and string keys. This is the PKFactory that comes with the MongoRecord code (an ActiveRecord-like framework for non-Rails apps) and the AR Mongo adapter code (for Rails):

class PKFactory
  def create_pk(row)
    return row if row[:_id]
    row.delete(:_id)      # in case it exists but the value is nil
    row['_id'] ||= XGen::Mongo::Driver::ObjectID.new
    row
  end
end

A database’s PK factory object may be set either when a DB object is created or immediately after you obtain it, but only once. The only reason it is changeable at all is so that libraries such as MongoRecord that use this driver can set the PK factory after obtaining the database but before using it for the first time.

The DB Class ↑

Primary Key factories ↑

See the section on “Primary Keys” above.

Strict mode ↑

Each database has an optional strict mode. If strict mode is on, then asking for a collection that does not exist will raise an error, as will asking to create a collection that already exists. Note that both these operations are completely harmless; strict mode is a programmer convenience only.

To turn on strict mode, either pass in :strict => true when obtaining a DB object or call the :strict= method:

db = XGen::Mongo::Driver::Mongo.new.db('dbname', :strict => true)
# I'm feeling lax
db.strict = false
# No, I'm not!
db.strict = true

The method DB#strict? returns the current value of that flag.

Cursors ↑

Random cursor fun facts:

  • Cursors are enumerable.

  • The query doesn’t get run until you actually attempt to retrieve data from a cursor.

  • Cursors have a to_a method.

Testing ↑

If you have the source code, you can run the tests.

$ rake test

The tests assume that the Mongo database is running on the default port. You can override the default host (localhost) and port (Mongo::DEFAULT_PORT) by using the environment variables MONGO_RUBY_DRIVER_HOST and MONGO_RUBY_DRIVER_PORT.

The project mongo-qa (github.com/mongodb/mongo-qa) contains many more Mongo driver tests that are language independent. To run thoses tests as part of the “rake test” task, download the code “next to” this directory. So, after installing the mongo-qa code you would have these two directories next to each other:

$ ls
mongo-qa
mongo-ruby-driver
$ rake test

The tests run just fine if the mongo-qa directory is not there.

Additionally, the script bin/validate is used by the mongo-qa project’s validator script.

Documentation ↑

This documentation is available online at api.mongodb.org/ruby. You can generate the documentation if you have the source by typing

$ rake rdoc

Then open the file html/index.html.

Release Notes ↑

See the git log comments.

Credits ↑

Adrian Madrid, aemadrid@gmail.com

  • bin/mongo_console

  • examples/benchmarks.rb

  • examples/irb.rb

  • Modifications to examples/simple.rb

  • Found plenty of bugs and missing features.

  • Ruby 1.9 support.

  • Gem support.

  • Many other code suggestions and improvements.

Aman Gupta, aman@tmm1.net

  • Collection#save

Jon Crosby, jon@joncrosby.me

  • Some code clean-up

John Nunemaker, railstips.org

  • Collection#create_index takes symbols as well as strings

  • Fix for Collection#save

  • Add logger convenience methods to connection and database

David James, djames@sunlightfoundation.com

  • Fix dates to return as UTC

Paul Dlug, paul.dlug@gmail.com

  • Generate _id on the client side if not provided

  • Collection#insert and Collection#save return _id

License ↑

Copyright 2008-2009 10gen Inc.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.