149 lines
4.3 KiB
Plaintext
149 lines
4.3 KiB
Plaintext
= Introduction
|
|
|
|
This is a Ruby driver for the 10gen Mongo DB. For more information about
|
|
Mongo, see http://www.mongodb.org.
|
|
|
|
Note: this driver is still alpha quality. The API will change, as *may* the
|
|
data saved to the database (especially primary key values). Do *_not_* use
|
|
this for any production data yet.
|
|
|
|
Start by reading the XGen::Mongo::Driver::Mongo and XGen::Mongo::Driver::DB
|
|
documentation, then move on to XGen::Mongo::Driver::Collection and
|
|
XGen::Mongo::Driver::Cursor.
|
|
|
|
A quick code sample:
|
|
|
|
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 }
|
|
|
|
= Installation
|
|
|
|
Install the "mongo" gem by typing
|
|
|
|
$ sudo gem install mongo
|
|
|
|
The source code is available at http://github.com/jimm/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
|
|
|
|
|
|
= Demo
|
|
|
|
You can see and run the examples if you've downloaded the source. Mongo must
|
|
be running, of course.
|
|
|
|
$ ruby examples/simple.rb
|
|
|
|
See also the test code, especially tests/test_db_api.rb.
|
|
|
|
|
|
= 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.
|
|
|
|
The project mongo-qa (http://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, run
|
|
|
|
$ rake mongo_qa
|
|
$ rake test
|
|
|
|
The mongo_qa task uses the "git clone" command to make a copy of that project
|
|
in a directory named mongo-qa. If the directory already exists, then the
|
|
mongo_qa task uses "git pull" to updated the code that's there. The Ruby
|
|
driver tests will then use some of the data files from that project when it
|
|
runs BSON tests. You can delete this directory at any time if you don't want
|
|
to run those tests any more.
|
|
|
|
|
|
= Documentation
|
|
|
|
This documentation is available online at http://mongo.rubyforge.org. 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.
|
|
|
|
|
|
= To Do
|
|
|
|
* Add group_by. Need to figure out how we are going to send functions. The
|
|
current thinking is that Mongo will allow a subset of JavaScript (which we
|
|
would have to send as a string), but this is still under discussion.
|
|
|
|
* Add explain and hint support.
|
|
|
|
* Only update message sizes once, not after every write of a value. This will
|
|
require an explicit call to update_message_length in each message subclass.
|
|
|
|
* Tests for update and repsert.
|
|
|
|
* Add a way to specify a collection of databases on startup (a simple array of
|
|
IP address/port numbers, perhaps, or a hash or something). The driver would
|
|
then find the master and, on each subsequent command, ask that machine if it
|
|
is the master before proceeding.
|
|
|
|
* Tests that prove that this driver's ObjectID and Geir's Java version do the
|
|
same thing. (I've done so manually.)
|
|
|
|
* Support more types: REF, SYMBOL, CODE_W_SCOPE, etc.
|
|
|
|
* Introduce optional per-database and per-collection PKInjector.
|
|
|
|
* More tests.
|
|
|
|
* Study src/main/ed/db/{dbcollection,dbcursor,db}.js and ByteEncoder.java in
|
|
the Babble code. That's what I should be writing to.
|
|
|
|
|
|
= 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.
|
|
|
|
|
|
= License
|
|
|
|
Copyright (C) 2008-2009 10gen Inc.
|
|
|
|
This program is free software: you can redistribute it and/or modify it under
|
|
the terms of the GNU Affero General Public License, version 3, as published by
|
|
the Free Software Foundation.
|
|
|
|
This program is distributed in the hope that it will be useful, but WITHOUT
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
|
|
details.
|
|
|
|
See http://www.gnu.org/licenses for a copy of the GNU Affero General Public
|
|
License.
|