mongodb-mongo 0.5.3 → 0.6.1

data/README.rdoc

@@ -3,10 +3,6 @@
 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.
@@ -35,7 +31,7 @@ a separate project.
 Install the "mongo" gem by typing
 
   $ gem sources -a http://gems.github.com
-  $ sudo gem install mongodb-mongo-ruby-driver
+  $ sudo gem install mongodb-mongo
 
 The first line tells RubyGems to add the GitHub gem repository. You only need
 to run this command once.
@@ -49,6 +45,9 @@ 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.
+
 
 = Examples
 
@@ -89,7 +88,8 @@ Here is some simple example code:
 
 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.
+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'.

data/bin/run_test_script

@@ -5,6 +5,10 @@
 
 HERE=`dirname $0`
 
+if [ ! -f $HERE/../tests/mongo-qa/$1 ] ; then
+    exit 0
+fi
+
 begintime=`date`
 ruby $HERE/../tests/mongo-qa/$1 >> $2
 exitval=$?

data/bin/standard_benchmark

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+#
+# Note: Ruby 1.9 is faster than 1.8, as expected.
+
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include XGen::Mongo::Driver
+
+N = 30_000
+
+def report(str, t0, t1, n)
+  dt = t1.to_f - t0.to_f
+  printf("%16s: %03.8f\n", str, dt)
+end
+
+def benchmark(str, n, db, after_proc=nil)
+  coll = db.collection('benchmark')
+  t0 = Time.new
+  n.times { |i| yield coll, i }
+  after_proc.call if after_proc
+  report(str, t0, Time.new, n)
+end
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+db = Mongo.new(host, port).db('ruby-benchmark')
+db.drop_collection('benchmark')
+coll = db.collection('benchmark')
+
+coll.create_index('foo', 'i')
+
+# Call to db.error forces inserts to finish
+benchmark('insert', N, db, Proc.new{db.error}) { |coll, i|
+  coll.insert('i' => i)
+}
+benchmark('find_first', N, db) { |coll, i|
+  coll.find_first
+}
+benchmark('find', N, db) { |coll, i|
+  coll.find('i' => 3).each { }
+  coll.find('i' => 234).each { }
+  coll.find('i' => 9876).each { }
+}
+benchmark('find gt/lt', N, db) { |coll, i|
+  h = {'i' => {'$gt' => 200, '$lt' => 200}}
+  coll.find(h).each {}
+}

data/examples/admin.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+require 'pp'
+
+include XGen::Mongo::Driver
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+coll = db.create_collection('test')
+
+# Erase all records from collection, if any
+coll.clear
+
+admin = db.admin
+
+# Profiling level set/get
+p admin.profiling_level
+
+# Start profiling everything
+admin.profiling_level = :all
+
+# Read records, creating a profiling event
+coll.find().to_a
+
+# Stop profiling
+admin.profiling_level = :off
+
+# Print all profiling info
+pp admin.profiling_info
+
+# Validate returns a hash if all is well or raises an exception if there is a
+# problem.
+info = admin.validate_collection(coll.name)
+puts "valid = #{info['ok']}"
+puts info['result']
+
+# Destroy the collection
+coll.drop

data/examples/benchmarks.rb

@@ -1,4 +1,3 @@
-require "rubygems"
 require "benchmark"
   
 $LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
@@ -17,7 +16,7 @@ TEST_COUNT = 100
 
 puts "Generating benchmark data"
 msgs = %w{hola hello aloha ciao}
-arr = OBJS_COUNT.times.map {|x| { :number => x, :rndm => (rand(5)+1), :msg => msgs[rand(4)] }}
+arr = (0..OBJS_COUNT).collect {|x| { :number => x, :rndm => (rand(5)+1), :msg => msgs[rand(4)] }}
 
 puts "Running benchmark"
 Benchmark.bmbm do |results|
@@ -33,6 +32,11 @@ Benchmark.bmbm do |results|
       coll.insert(arr)
     }
   }
+  results.report("find_first: ") {
+    TEST_COUNT.times {
+      coll.find_first(:number => 0)
+    }
+  }
 end
 
 coll.clear

data/examples/capped.rb

@@ -0,0 +1,23 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include XGen::Mongo::Driver
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+db.drop_collection('test')
+
+# A capped collection has a max size and optionally a max number of records.
+# Old records get pushed out by new ones once the size or max num records is
+# reached.
+coll = db.create_collection('test', :capped => true, :size => 1024, :max => 12)
+
+100.times { |i| coll.insert('a' => i+1) }
+
+# We will only see the last 12 records
+coll.find().each { |row| p row }
+
+coll.drop

data/examples/cursor.rb

@@ -0,0 +1,47 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+require 'pp'
+
+include XGen::Mongo::Driver
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+coll = db.collection('test')
+
+# Erase all records from collection, if any
+coll.clear
+
+# Insert 3 records
+3.times { |i| coll.insert({'a' => i+1}) }
+
+# Cursors don't run their queries until you actually attempt to retrieve data
+# from them.
+
+# Find returns a Cursor, which is Enumerable. You can iterate:
+coll.find().each { |row| pp row }
+
+# You can turn it into an array
+array = coll.find().to_a
+
+# You can iterate after turning it into an array (the cursor will iterate over
+# the copy of the array that it saves internally.)
+cursor = coll.find()
+array = cursor.to_a
+cursor.each { |row| pp row }
+
+# You can get the next object
+first_object = coll.find().next_object
+
+# next_object returns nil if there are no more objects that match
+cursor = coll.find()
+obj = cursor.next_object
+while obj
+  pp obj
+  obj = cursor.next_object
+end
+
+# Destroy the collection
+coll.drop

data/examples/gridfs.rb

@@ -0,0 +1,87 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+require 'mongo/gridfs'
+
+include XGen::Mongo::Driver
+include XGen::Mongo::GridFS
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+
+def dump(db, fname)
+  GridStore.open(db, fname, 'r') { |f| puts f.read }
+end
+
+# Write a new file
+GridStore.open(db, 'foobar', 'w') { |f| f.write("hello, world!") }
+
+# Read it and print out the contents
+dump(db, 'foobar')                 # defined above
+
+# Append more data
+GridStore.open(db, 'foobar', 'w+') { |f| f.write("\n"); f.puts "line two" }
+dump(db, 'foobar')
+
+# Overwrite
+GridStore.open(db, 'foobar', 'w') { |f| f.puts "hello, sailor!" }
+dump(db, 'foobar')
+
+# File existence tests
+puts "File 'foobar' exists: #{GridStore.exist?(db, 'foobar')}"
+puts "File 'does-not-exist' exists: #{GridStore.exist?(db, 'does-not-exist')}"
+
+# Read with offset (uses seek)
+puts GridStore.read(db, 'foobar', 6, 7)
+
+# Rewind/seek/tell
+GridStore.open(db, 'foobar', 'w') { |f|
+  f.write "hello, world!"
+  f.rewind
+  f.write "xyzzz"
+  puts f.tell                   # => 5
+  f.seek(4)
+  f.write('y')
+}
+dump(db, 'foobar')              # => 'xyzzy'
+
+# Unlink (delete)
+GridStore.unlink(db, 'foobar')
+puts "File 'foobar' exists after delete: #{GridStore.exist?(db, 'foobar')}"
+
+# Metadata
+GridStore.open(db, 'foobar', 'w') { |f| f.write("hello, world!") }
+GridStore.open(db, 'foobar', 'r') { |f|
+  puts f.content_type
+  puts f.upload_date
+  puts f.chunk_size
+  puts f.metadata.inspect
+}
+
+# Add some metadata; change content type
+GridStore.open(db, 'foobar', 'w+') { |f|
+  f.content_type = 'text/xml'
+  f.metadata = {'a' => 1}
+}
+# Print it
+GridStore.open(db, 'foobar', 'r') { |f|
+  puts f.content_type
+  puts f.upload_date
+  puts f.chunk_size
+  puts f.metadata.inspect
+}
+
+# You can also set metadata when initially writing the file. Setting :root
+# means that the file and its chunks are stored in a different root
+# collection: instead of gridfs.files and gridfs.chunks, here we use
+# my_files.files and my_files.chunks.
+GridStore.open(db, 'foobar', 'w',
+               :content_type => 'text/plain',
+               :metadata => {'a' => 1},
+               :chunk_size => 1024 * 4,
+               :root => 'my_files') { |f|
+  f.puts 'hello, world'
+}
+

data/examples/info.rb

@@ -0,0 +1,30 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include XGen::Mongo::Driver
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+coll = db.collection('test')
+
+# Erase all records from collection, if any
+coll.clear
+
+# Insert 3 records
+3.times { |i| coll.insert({'a' => i+1}) }
+
+# Collection names in database
+p db.collection_names
+
+# More information about each collection
+p db.collections_info
+
+# Index information
+db.create_index('test', 'index_name', ['a'])
+p db.index_information('test')
+
+# Destroy the collection
+coll.drop

data/examples/queries.rb

@@ -0,0 +1,69 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+require 'pp'
+
+include XGen::Mongo::Driver
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+coll = db.collection('test')
+
+# Remove all records, if any
+coll.clear
+
+# Insert three records
+coll.insert('a' => 1)
+coll.insert('a' => 2)
+coll.insert('b' => 3)
+
+# Count.
+puts "There are #{coll.count()} records."
+
+# Find all records. find() returns a Cursor.
+cursor = coll.find()
+
+# Print them. Note that all records have an _id automatically added by the
+# database. See pk.rb for an example of how to use a primary key factory to
+# generate your own values for _id.
+cursor.each { |row| pp row }
+
+# Cursor has a to_a method that slurps all records into memory.
+rows = coll.find().to_a
+rows.each { |row| pp row }
+
+# See Collection#find. From now on in this file, we won't be printing the
+# records we find.
+coll.find('a' => 1)
+
+# Find records sort by 'a', offset 1, limit 2 records.
+# Sort can be single name, array, or hash.
+coll.find({}, {:offset => 1, :limit => 2, :sort => 'a'})
+
+# Find all records with 'a' > 1. There is also $lt, $gte, and $lte.
+coll.find({'a' => {'$gt' => 1}})
+coll.find({'a' => {'$gt' => 1, '$lte' => 3}})
+
+# Find all records with 'a' in a set of values.
+coll.find('a' => {'$in' => [1,2]})
+
+# Find by regexp
+coll.find('a' => /[1|2]/)
+
+# Print query explanation
+pp coll.find('a' => /[1|2]/).explain()
+
+# Use a hint with a query. Need an index. Hints can be stored with the
+# collection, in which case they will be used with all queries, or they can be
+# specified per query, in which case that hint overrides the hint associated
+# with the collection if any.
+coll.create_index('test_a_index', 'a')
+coll.hint = 'a'
+
+# You will see a different explanation now that the hint is in place
+pp coll.find('a' => /[1|2]/).explain()
+
+# Override hint for single query
+coll.find({'a' => 1}, :hint => 'b')

data/examples/strict.rb

@@ -0,0 +1,34 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include XGen::Mongo::Driver
+
+host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+
+puts "Connecting to #{host}:#{port}"
+db = Mongo.new(host, port).db('ruby-mongo-examples')
+
+db.drop_collection('does-not-exist')
+db.create_collection('test')
+
+db.strict = true
+
+begin
+  # Can't reference collection that does not exist
+  db.collection('does-not-exist')
+  puts "error: expected exception"
+rescue => ex
+  puts "expected exception: #{ex}"
+end
+
+begin
+  # Can't create collection that already exists
+  db.create_collection('test')
+  puts "error: expected exception"
+rescue => ex
+  puts "expected exception: #{ex}"
+end
+
+db.strict = false
+db.drop_collection('test')