pahagon-mongo-abd 0.14.1

data/README.rdoc

@@ -0,0 +1,353 @@
+= Introduction
+
+This is a Ruby driver for MongoDB[http://www.mongodb.org].
+
+Here is a quick code sample. See the files in the "examples" subdirectory for
+many more.
+
+  require 'mongo'
+
+  include Mongo
+
+  db = Connection.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
+
+Install the "mongo" gem by typing
+
+  $ gem sources -a http://gems.github.com
+  $ sudo gem install mongodb-mongo
+
+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 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
+
+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.
+
+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 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
+strings be UTF-8 (http://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 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
+
+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 (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, 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 http://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, http://railstips.org
+* Collection#create_index takes symbols as well as strings
+* Fix for Collection#save
+
+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
+
+Durran Jordan and Les Hill, durran@gmail.com
+* DB#collections
+
+Cyril Mougel, cyril.mougel@gmail.com
+* Initial logging support
+
+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
+
+Michael Bernstein, mrb on github
+* #sort method for Cursor instances
+
+= 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.
+

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+require 'rubygems/specification'
+require 'fileutils'
+require 'rake'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+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['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 #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
+end
+
+desc "Publish documentation to mongo.rubyforge.org"
+task :publish => [:rdoc] do
+  # Assumes docs are in ./html
+  Rake::RubyForgePublisher.new(GEM, RUBYFORGE_USER).upload
+end
+
+namespace :gem do
+
+  desc "Install the gem locally"
+  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 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
+
+task :default => :list
+
+task :list do
+  system 'rake -T'
+end

data/bin/bson_benchmark.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include Mongo
+
+TRIALS = 100000
+
+def encode(doc)
+  t0 = Time.new
+  b = BSON.new
+  TRIALS.times { |i|
+    b = BSON.new
+    b.serialize doc
+  }
+  print "took: #{Time.now.to_f - t0.to_f}\n"
+  return b
+end
+
+def decode(bson)
+  t0 = Time.new
+  doc = nil
+  TRIALS.times { |i|
+    doc = bson.deserialize
+  }
+  print "took: #{Time.now.to_f - t0.to_f}\n"
+  return doc
+end
+
+TEST_CASES = [{},
+              {
+                "hello" => "world"
+              },
+              {
+                "hello" => "world",
+                "mike" => "something",
+                "here's" => "another"
+              },
+              {
+                "int" => 200,
+                "bool" => true,
+                "an int" => 20,
+                "a bool" => false
+              },
+              {
+                "this" => 5,
+                "is" => {"a" => true},
+                "big" => [true, 5.5],
+                "object" => nil
+              }]
+
+TEST_CASES.each { |doc|
+  print "case #{doc.inspect}\n"
+  print "enc bson\n"
+  enc_bson = encode(doc)
+  print "dec bson\n"
+  raise "FAIL" unless doc == decode(enc_bson)
+}