Installation

Ruby Versions

The driver works and is consistently tested on Ruby 1.8.6, 1.8.7, and 1.9.2, and JRuby 1.5.1.

Note that if you're on 1.8.7, be sure that you're using a patchlevel >= 249. There
are some IO bugs in earlier versions.

Gems

The driver's gems are hosted at Rubygems.org. Make sure you're
using the latest version of rubygems:

$ gem update --system

Then you can install the mongo gem as follows:

$ gem install mongo

The driver also requires the bson gem:

$ gem install bson

And for a significant performance boost, you'll want to install the C extensions:

$ gem install bson_ext

Note that bson_ext isn't used with JRuby. Instead, some native Java extensions are bundled with the bson gem.
If you ever need to modify these extenions, you can recompile with the following rake task:

$ rake build:java

From the GitHub source

The source code is available at http://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

Bundled with the driver are many examples, located in the "docs/examples" subdirectory. Samples include using
the driver and using the GridFS class GridStore. MongoDB must be running for
these examples to work, of course.

GridFS

The Ruby driver include two abstractions for storing large files: Grid and GridFileSystem.
The Grid class is a Ruby implementation of MongoDB's GridFS file storage
specification. GridFileSystem is essentailly the same, but provides a more filesystem-like API
and assumes that filenames are unique.

An instance of both classes represents an individual file store. See the API reference
for details, and see examples/gridfs.rb for code that uses many of the Grid
features (metadata, content type, seek, tell, etc).

Notes

Thread Safety

The driver is thread-safe.

Connection Pooling

The driver implements connection pooling. By default, only one
socket connection will be opened to MongoDB. However, if you're running a
multi-threaded application, you can specify a maximum pool size and a maximum
timeout for waiting for old connections to be released to the pool.

Though the pooling architecture will undoubtedly evolve, it currently owes much credit
to the connection pooling implementations in ActiveRecord and PyMongo.

Forking

Certain Ruby application servers work by forking, and it has long been necessary to
re-establish the child process's connection to the database after fork. But with the release
of v1.3.0, the Ruby driver detects forking and reconnects automatically.

String Encoding

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, it may not be a well-formed UTF-8
string.

Primary Keys

The _id field 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 Connection#db method.

db = Mongo::Connection.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 may already exist in the
database. 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'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'] ||= Mongo::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

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:

Shoulda and Mocha

Running the test suite requires shoulda and mocha. You can install them as follows:

$ gem install shoulda
$ gem install mocha

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

Documentation

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

$ rake ydoc

Then open the file +ydoc/index.html+.

Release Notes

See HISTORY.

Credits

See CREDITS.

License

Copyright 2008-2010 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.