mongo 0.1.0 → 0.15

data/README.rdoc

@@ -1,23 +1,15 @@
 = Introduction
 
-This is a Ruby driver for the 10gen Mongo DB. For more information about
-Mongo, see http://www.mongodb.org.
+This is a Ruby driver for MongoDB[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:
+Here is a quick code sample. See the files in the "examples" subdirectory for
+many more.
 
   require 'mongo'
 
-  include XGen::Mongo::Driver
+  include Mongo
 
-  db = Mongo.new('localhost').db('sample-db')
+  db = Connection.new('localhost').db('sample-db')
   coll = db.collection('test')
 
   coll.clear
@@ -25,32 +17,130 @@ A quick code sample:
   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
 
-Install the "mongo" gem by typing
+The driver's gems are hosted on Gemcutter[http://gemcutter.org]. 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
 
-  $ sudo gem install mongo
+  $ 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
+=== 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
 
+=== 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
+
+  $ gem install mongo_ext
+
+To install from source type this instead
+
+  $ rake gem:install_extensions
 
-= Demo
+That's all there is to it!
 
-You can see and run the examples if you've downloaded the source. Mongo must
-be running, of course.
+= 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 tests/test_db_api.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 Mongo
+  db = Connection.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
 
+== 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[http://www.modrails.org/documentation/Users%20guide.html#RailsSpawnMethod]
+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[http://groups.google.com/group/mongodb-user/browse_thread/thread/f31e2d23de38136a]
+for more details on this issue.
+
 == String Encoding
 
 The BSON ("Binary JSON") format used to communicate with Mongo requires that
@@ -62,7 +152,101 @@ 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.
+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 Connection#db method.
+
+  include Mongo
+  db = 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 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'] ||= Mongo::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'] ||= 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
+
+=== 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 = Connection.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
 
@@ -70,21 +254,23 @@ 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 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.
 
 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
+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:
 
-  $ rake mongo_qa
+  $ ls
+  mongo-qa
+  mongo-ruby-driver
   $ 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.
+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.
@@ -92,7 +278,7 @@ validator script.
 
 = Documentation
 
-This documentation is available online at http://mongo.rubyforge.org. You can
+This documentation is available online at http://api.mongodb.org/ruby. You can
 generate the documentation if you have the source by typing
 
   $ rake rdoc
@@ -104,59 +290,70 @@ Then open the file html/index.html.
 
 See the git log comments.
 
+= Credits
 
-= To Do
+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.
 
-* 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.
+Aman Gupta, aman@tmm1.net
+* Collection#save
 
-* Tests for update and repsert.
+Jon Crosby, jon@joncrosby.me
+* Some code clean-up
 
-* 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.
+John Nunemaker, http://railstips.org
+* Collection#create_index takes symbols as well as strings
+* Fix for Collection#save
 
-* Introduce optional per-database and per-collection PKInjector.
+David James, djames@sunlightfoundation.com
+* Fix dates to return as UTC
 
-* More tests.
+Paul Dlug, paul.dlug@gmail.com
+* Generate _id on the client side if not provided
+* Collection#insert and Collection#save return _id
 
-== Optimizations
+Durran Jordan and Les Hill, durran@gmail.com
+* DB#collections
 
-* 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.
+Cyril Mougel, cyril.mougel@gmail.com
+* Initial logging support
 
-* ensure_index commands should be cached to prevent excessive communication
-  with the database. (Or, the driver user should be informed that ensure_index
-  is not a lightweight operation for the particular driver.)
+Jack Chen, chendo on github
+* Test case + fix for deserializing pre-epoch Time instances
 
+Kyle Banker, banker on github
+* #limit and #skip methods for Cursor instances
 
-= Credits
+Michael Bernstein, mrb on github
+* #sort method for Cursor instances
 
-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.
+Paulo Ahahgon, pahagon on github
+* removed hard limit
+
+Les Hill, leshill on github
+* OrderedHash#each returns self
 
 
 = License
 
-Copyright (C) 2008-2009 10gen Inc.
+ 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
 
-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.
+       http://www.apache.org/licenses/LICENSE-2.0
 
-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.
+   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.
 
-See http://www.gnu.org/licenses for a copy of the GNU Affero General Public
-License.

data/Rakefile

@@ -4,59 +4,27 @@ require 'fileutils'
 require 'rake'
 require 'rake/testtask'
 require 'rake/gempackagetask'
-require 'rake/contrib/rubyforgepublisher'
-
-GEM = "mongo"
-GEM_VERSION = '0.1.0'
-SUMMARY = 'Simple pure-Ruby driver for the 10gen Mongo DB'
-DESCRIPTION = 'This is a simple pure-Ruby driver for the 10gen Mongo DB. For more information about Mongo, see http://www.mongodb.org.'
-AUTHOR = 'Jim Menard'
-EMAIL = 'jimm@io.com'
-HOMEPAGE = 'http://www.mongodb.org'
-RUBYFORGE_USER = 'jimm'
- 
-spec = Gem::Specification.new do |s|
-  s.name = GEM
-  s.version = GEM_VERSION
-  s.platform = Gem::Platform::RUBY
-  s.summary = SUMMARY
-  s.description = DESCRIPTION
-  
-  s.require_paths = ['lib']
-  
-  s.files = FileList['bin/*', 'lib/**/*.rb', 'tests/**/*.rb', '[A-Z]*'].to_a
-  
-  s.bindir = 'bin'
-  s.executables  = %w( mongo_console )
-  s.has_rdoc = true
-
-  s.author = AUTHOR
-  s.email = EMAIL
-  s.homepage = HOMEPAGE
-
-  s.rubyforge_project = GEM # GitHub bug, gem isn't being build when this miss
+begin
+  require 'rake/contrib/rubyforgepublisher'
+rescue LoadError
 end
+require 'rbconfig'
+include Config
+
+gem_command = "gem"
+gem_command = "gem1.9" if $0.match(/1\.9$/) # use gem1.9 if we used rake1.9
 
 # NOTE: some of the tests assume Mongo is running
 Rake::TestTask.new do |t|
-  t.test_files = FileList['tests/test*.rb']
-end
-
-desc "Clone or pull (update) the mongo-qa project used for testing"
-task :mongo_qa do
-  if File.exist?('mongo-qa')
-    Dir.chdir('mongo-qa') do
-      system('git pull')
-    end
-  else
-    system('git clone git://github.com/mongodb/mongo-qa.git')
-  end
+  t.test_files = FileList['test/test*.rb']
 end
 
 desc "Generate documentation"
 task :rdoc do
+  version = eval(File.read("mongo-ruby-driver.gemspec")).version
+  out = File.join('html', version.to_s)
   FileUtils.rm_rf('html')
-  system "rdoc --main README.rdoc --op html --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
+  system "rdoc --main README.rdoc --op #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
 end
 
 desc "Publish documentation to mongo.rubyforge.org"
@@ -65,27 +33,24 @@ task :publish => [:rdoc] do
   Rake::RubyForgePublisher.new(GEM, RUBYFORGE_USER).upload
 end
 
-namespace :gem do 
-
-  Rake::GemPackageTask.new(spec) do |pkg|
-    pkg.gem_spec = spec
-  end
+namespace :gem do
 
   desc "Install the gem locally"
-  task :install => [:package] do
-    sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+  task :install do
+    sh <<EOS
+#{gem_command} build mongo-ruby-driver.gemspec &&
+    sudo #{gem_command} install mongo-*.gem &&
+    rm mongo-*.gem
+EOS
   end
-  
-  desc "Install the gem locally with ruby 1.9"
-  task :'install19' => [:package] do
-    sh %{sudo gem19 install pkg/#{GEM}-#{GEM_VERSION}}
-  end
- 
-  desc "Create a gemspec file"
-  task :make_spec do
-    File.open("#{GEM}.gemspec", "w") do |file|
-      file.puts spec.to_ruby
-    end
+
+  desc "Install the optional c extensions"
+  task :install_extensions do
+    sh <<EOS
+#{gem_command} build mongo-extensions.gemspec &&
+    sudo #{gem_command} install mongo_ext-*.gem &&
+    rm mongo_ext-*.gem
+EOS
   end
 
 end