Installation

The first line tells RubyGems to add the GitHub gem repository. You only
need to run this command once.

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

Note: when you install the gem this way it is called “mongo”, not
“mongodb-mongo”. In either case, you “require 'mongo'” in your
source code.

Optional C Extension

There is a separate gem containing optional C extensions that will increase
the performance of the driver. To use the optional extensions just install
the gem by typing

$ sudo gem install mongodb-mongo_ext

To install 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.

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'.

Notes

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 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.

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'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:

Cursors

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 mongo.rubyforge.org. You can generate
the documentation if you have the source by typing

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.