mongo 1.0 → 1.1.5

data/Rakefile

@@ -13,36 +13,72 @@ require 'rbconfig'
 include Config
 ENV['TEST_MODE'] = 'TRUE'
 
+task :java do
+  Rake::Task['build:java'].invoke
+  Rake::Task['test:ruby'].invoke
+end
+
+namespace :build do
+  desc "Build the java extensions."
+  task :java do
+    puts "Building Java extensions..."
+    java_dir  = File.join(File.dirname(__FILE__), 'ext', 'java')
+    jar_dir   = File.join(java_dir, 'jar')
+
+    jruby_jar = File.join(jar_dir, 'jruby.jar')
+    mongo_jar = File.join(jar_dir, 'mongo-2.2.jar')
+    bson_jar = File.join(jar_dir, 'bson-2.2.jar')
+
+    src_base   = File.join(java_dir, 'src')
+
+    system("javac -Xlint:unchecked -classpath #{jruby_jar}:#{mongo_jar}:#{bson_jar} #{File.join(src_base, 'org', 'jbson', '*.java')}")
+    system("cd #{src_base} && jar cf #{File.join(jar_dir, 'jbson.jar')} #{File.join('.', 'org', 'jbson', '*.class')}")
+  end
+end
+
 desc "Test the MongoDB Ruby driver."
 task :test do
-  puts "\nThis option has changed."
-  puts "\nTo test the driver with the c-extensions:\nrake test:c\n"
-  puts "To test the pure ruby driver: \nrake test:ruby"
+  puts "\nTo test the driver with the C-extensions:\nrake test:c\n\n"
+  puts "To test the pure ruby driver: \nrake test:ruby\n\n"
 end
 
 namespace :test do
 
-  desc "Test the driver with the c extension enabled."
+  desc "Test the driver with the C extension enabled."
   task :c do
     ENV['C_EXT'] = 'TRUE'
-    Rake::Task['test:unit'].invoke
-    Rake::Task['test:functional'].invoke
-    Rake::Task['test:bson'].invoke
-    Rake::Task['test:pooled_threading'].invoke
-    Rake::Task['test:drop_databases'].invoke
+    if ENV['TEST']
+      Rake::Task['test:functional'].invoke
+    else
+      Rake::Task['test:unit'].invoke
+      Rake::Task['test:functional'].invoke
+      Rake::Task['test:bson'].invoke
+      Rake::Task['test:pooled_threading'].invoke
+      Rake::Task['test:drop_databases'].invoke
+    end
     ENV['C_EXT'] = nil
   end
 
-  desc "Test the driver using pure ruby (no c extension)"
+  desc "Test the driver using pure ruby (no C extension)"
   task :ruby do
     ENV['C_EXT'] = nil
-    Rake::Task['test:unit'].invoke
-    Rake::Task['test:functional'].invoke
-    Rake::Task['test:bson'].invoke
-    Rake::Task['test:pooled_threading'].invoke
-    Rake::Task['test:drop_databases'].invoke
+    if ENV['TEST']
+      Rake::Task['test:functional'].invoke
+    else
+      Rake::Task['test:unit'].invoke
+      Rake::Task['test:functional'].invoke
+      Rake::Task['test:bson'].invoke
+      Rake::Task['test:pooled_threading'].invoke
+      Rake::Task['test:drop_databases'].invoke
+    end
+  end
+
+  desc "Run the replica set test suite"
+  Rake::TestTask.new(:rs) do |t|
+    t.test_files = FileList['test/replica_sets/*_test.rb']
+    t.verbose    = true
   end
-  
+
   Rake::TestTask.new(:unit) do |t|
     t.test_files = FileList['test/unit/*_test.rb']
     t.verbose    = true
@@ -54,27 +90,7 @@ namespace :test do
   end
 
   Rake::TestTask.new(:pooled_threading) do |t|
-    t.test_files = FileList['test/threading/*.rb']
-    t.verbose    = true
-  end
-
-  Rake::TestTask.new(:pair_count) do |t|
-    t.test_files = FileList['test/replica/count_test.rb']
-    t.verbose    = true
-  end
-
-  Rake::TestTask.new(:pair_insert) do |t|
-    t.test_files = FileList['test/replica/insert_test.rb']
-    t.verbose    = true
-  end
-
-  Rake::TestTask.new(:pooled_pair_insert) do |t|
-    t.test_files = FileList['test/replica/pooled_insert_test.rb']
-    t.verbose    = true
-  end
-
-  Rake::TestTask.new(:pair_query) do |t|
-    t.test_files = FileList['test/replica/query_test.rb']
+    t.test_files = FileList['test/threading/*_test.rb']
     t.verbose    = true
   end
 
@@ -94,26 +110,27 @@ namespace :test do
   end
 
   Rake::TestTask.new(:bson) do |t|
-    t.test_files = FileList['test/mongo_bson/*_test.rb']
+    t.test_files = FileList['test/bson/*_test.rb']
     t.verbose    = true
   end
 
   task :drop_databases do |t|
-    puts "Dropping test database..."
-    require File.join(File.dirname(__FILE__), 'test', 'test_helper')
-    include Mongo
-    con = Connection.new(ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost',
-      ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT)
-    con.drop_database(MONGO_TEST_DB)
+    puts "Dropping test databases..."
+    require './lib/mongo'
+    con = Mongo::Connection.new(ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost',
+      ENV['MONGO_RUBY_DRIVER_PORT'] || Mongo::Connection::DEFAULT_PORT)
+    con.database_names.each do |name|
+      con.drop_database(name) if name =~ /^ruby-test/
+    end
   end
 end
 
-desc "Generate documentation"
+desc "Generate RDOC documentation"
 task :rdoc do
-  version = eval(File.read("mongo-ruby-driver.gemspec")).version
+  version = eval(File.read("mongo.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'`"
+  system "rdoc --main README.md --op #{out} --inline-source --quiet README.md `find lib -name '*.rb'`"
 end
 
 desc "Generate YARD documentation"
@@ -121,36 +138,55 @@ task :ydoc do
   require File.join(File.dirname(__FILE__), 'lib', 'mongo')
   out = File.join('ydoc', Mongo::VERSION)
   FileUtils.rm_rf('ydoc')
-  system "yardoc lib/**/*.rb lib/mongo/**/*.rb -e docs/yard_ext.rb -p docs/templates -o #{out} --title MongoRuby-#{Mongo::VERSION}"
+  system "yardoc lib/**/*.rb lib/mongo/**/*.rb lib/bson/**/*.rb -e yard/yard_ext.rb -p yard/templates -o #{out} --title MongoRuby-#{Mongo::VERSION} --files docs/TUTORIAL.md,docs/GridFS.md,docs/FAQ.md,docs/REPLICA_SETS.md,docs/WRITE_CONCERN.md,docs/HISTORY.md,docs/CREDITS.md,docs/1.0_UPGRADE.md"
 end
 
-desc "Publish documentation to mongo.rubyforge.org"
-task :publish => [:rdoc] do
-  # Assumes docs are in ./html
-  Rake::RubyForgePublisher.new(GEM, RUBYFORGE_USER).upload
+namespace :bamboo do
+  namespace :test do
+    task :ruby do
+      Rake::Task['test:ruby'].invoke
+    end
+
+    task :c do
+      Rake::Task['gem:install_extensions'].invoke
+      Rake::Task['test:c'].invoke
+    end
+  end
 end
 
 namespace :gem do
 
   desc "Install the gem locally"
   task :install do
-    sh "gem build mongo-ruby-driver.gemspec"
-    sh "gem install mongo-*.gem"
+    sh "gem build bson.gemspec"
+    sh "gem install --no-rdoc --no-ri bson-*.gem"
+
+    sh "gem build mongo.gemspec"
+    sh "gem install --no-rdoc --no-ri mongo-*.gem"
+
     sh "rm mongo-*.gem"
+    sh "rm bson-*.gem"
   end
 
   desc "Install the optional c extensions"
   task :install_extensions do
-    sh "gem build bson.gemspec"
     sh "gem build bson_ext.gemspec"
-    sh "gem install bson-*.gem"
-    sh "gem install bson_ext-*.gem"
-    sh "rm bson-*.gem"
+    sh "gem install --no-rdoc --no-ri bson_ext-*.gem"
     sh "rm bson_ext-*.gem"
   end
 
 end
 
+namespace :ci do
+  namespace :test do
+    task :c do
+      Rake::Task['gem:install'].invoke
+      Rake::Task['gem:install_extensions'].invoke
+      Rake::Task['test:c'].invoke
+    end
+  end
+end
+
 task :default => :list
 
 task :list do

data/bin/mongo_console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+org_argv = ARGV.dup
+ARGV.clear
+
+require 'irb'
+
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include Mongo
+
+host = org_argv[0] || ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = org_argv[1] || ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT
+dbnm = org_argv[2] || ENV['MONGO_RUBY_DRIVER_DB']   || 'ruby-mongo-console'
+
+puts "Connecting to #{host}:#{port} (CONN) on with database #{dbnm} (DB)"
+CONN = Connection.new(host, port)
+DB = CONN.db(dbnm)
+
+puts "Starting IRB session..."
+IRB.start(__FILE__)

data/docs/1.0_UPGRADE.md

@@ -0,0 +1,21 @@
+You can upgrade freely from v0.20 to v1.0.
+
+However, if you're running a version < 0.20, upgrade to 0.20
+before upgrading to 1.0.
+
+The upgrade to 0.20 requires some minor code upgrades.
+
+1. Note the exception changes in HISTORY. Certain exceptions are now scoped under the BSON
+module; if you're catching these, you will need to modify your code.
+
+2. The BSON types are now scoped under the BSON module.
+
+3. Note that mongo_ext no longer exists. The new gems are bson and bson_ext.
+
+4. Indexes on GridFS chunks collections should be unique. If you have existing GridFS
+collections, you should drop the current index and replace with a unique one. Before you do this,
+make sure that index doesn't exist; no need to go through process unnecessarily.
+If you do need to create the index, once you have the chunks collection, here are the commands you can run:
+
+    @chunks.drop_index('files_id_1_n_1')
+    @chunks.create_index([['files_id', Mongo::ASCENDING], ['n', Mongo::ASCENDING]], :unique => true)

data/docs/CREDITS.md

@@ -0,0 +1,123 @@
+# 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
+* Noted bug in returning query batch size.
+
+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
+* Add logger convenience methods to connection and database
+
+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, durran@gmail.com
+
+* DB#collections
+* Support for specifying sort order as array of [key, direction] pairs
+* OrderedHash#update aliases to merge!
+
+Cyril Mougel, cyril.mougel@gmail.com
+
+* Initial logging support
+* Test case
+
+Jack Chen, chendo on github
+
+* Test case + fix for deserializing pre-epoch Time instances
+
+Michael Bernstein, mrb on github
+
+* Cursor#sort
+
+Paulo Ahahgon, pahagon on github
+
+* removed hard limit
+
+Les Hill, leshill on github
+
+* OrderedHash#each returns self
+
+Sean Cribbs, seancribbs on github
+
+* Modified standard_benchmark to allow profiling
+* C ext for faster ObjectID creation
+
+Sunny Hirai
+
+* Suggested hashcode fix for Mongo::ObjectID
+* Noted index ordering bug.
+* GridFS performance boost
+
+Christos Trochalakis
+
+* Added map/reduce helper
+
+Blythe Dunham
+
+* Added finalize option to map/reduce
+
+Matt Powell (fauxparse)
+
+* Added GridStore#mv
+
+Patrick Collison
+
+* Added safe mode for Collection#remove
+
+Chuck Remes
+
+* Extraction of BSON into separate gems
+* Extensions compile on Rubinius
+* Performance improvements for INT in C extensions
+* Performance improvements for JRuby BSON encoder and callback classes
+
+Dmitrii Golub (Houdini) and Jacques Crocker (railsjedi)
+
+* Support open to exclude fields on query
+
+dfitzgibbon
+
+* patch for ensuring bson_ext compatibility with early release of Ruby 1.8.5
+
+Matt Taylor
+
+* Noticed excessive calls to ObjectId#to_s. As a result, stopped creating
+log messages when no logger was passed to Mongo::Connection. Resulted in a significant
+performance improvement.
+
+Hongli Lai (Phusion)
+
+* Significant performance improvements. See commits.
+
+Mislav Marohnić
+
+* Replaced returning with each_with_object
+
+Alex Stupka
+
+* Replica set port bug

data/docs/FAQ.md

@@ -0,0 +1,112 @@
+# Ruby MongoDB FAQ
+
+This is a list of frequently asked questions about using Ruby with MongoDB. If you have a question you'd like to have answered here, please post your question to the [mongodb-user list](http://groups.google.com/group/mongodb-user).
+
+#### Can I run (insert command name here) from the Ruby driver?
+
+Yes. You can run any of the [available database commands|List of Database Commands] from the driver using the DB#command method. The only trick is to use an OrderedHash when specifying the command. For example, here's how you'd run an asynchronous fsync from the driver:
+
+
+    # This command is run on the admin database.
+    @db = Mongo::Connection.new.db('admin')  
+
+    # Build the command.
+    cmd = OrderedHash.new
+    cmd['fsync'] = 1
+    cmd['async'] = true
+
+    # Run it.
+    @db.command(cmd)
+
+
+It's important to keep in mind that some commands, like `fsync`, must be run on the `admin` database, while other commands can be run on any database. If you're having trouble, check the [command reference|List of Database Commands] to make sure you're using the command correctly.
+
+#### Does the Ruby driver support an EXPLAIN command?
+
+Yes. `explain` is, technically speaking, an option sent to a query that tells MongoDB to return an explain plan rather than the query's results. You can use `explain` by constructing a query and calling explain at the end:
+
+
+    @collection = @db['users']
+    result = @collection.find({:name => "jones"}).explain
+
+
+The resulting explain plan might look something like this:
+
+
+    {"cursor"=>"BtreeCursor name_1", 
+     "startKey"=>{"name"=>"Jones"}, 
+     "endKey"=>{"name"=>"Jones"}, 
+     "nscanned"=>1.0, 
+     "n"=>1, 
+     "millis"=>0, 
+     "oldPlan"=>{"cursor"=>"BtreeCursor name_1", 
+                   "startKey"=>{"name"=>"Jones"}, 
+                   "endKey"=>{"name"=>"Jones"}
+     },
+     "allPlans"=>[{"cursor"=>"BtreeCursor name_1", 
+                     "startKey"=>{"name"=>"Jones"}, 
+                     "endKey"=>{"name"=>"Jones"`]
+     }
+
+
+Because this collection has an index on the "name" field, the query uses that index, only having to scan a single record. "n" is the number of records the query will return. "millis" is the time the query takes, in milliseconds. "oldPlan" indicates that the query optimizer has already seen this kind of query and has, therefore, saved an efficient query plan. "allPlans" shows all the plans considered for this query.
+
+#### I see that BSON supports a symbol type. Does this mean that I can store Ruby symbols in MongoDB?
+
+You can store Ruby symbols in MongoDB, but only as values. BSON specifies that document keys must be strings. So, for instance, you can do this:
+
+
+    @collection = @db['test']
+
+    boat_id = @collection.save({:vehicle  => :boat})
+    car_id  = @collection.save({"vehicle" => "car"})
+
+    @collection.find_one('_id' => boat_id)
+    {"_id" => ObjectID('4bb372a8238d3b5c8c000001'), "vehicle" => :boat}
+
+
+    @collection.find_one('_id' => car_id)
+    {"_id" => ObjectID('4bb372a8238d3b5c8c000002'), "vehicle" => "car"}
+
+
+Notice that the symbol values are returned as expected, but that symbol keys are treated as strings.
+
+#### Why can't I access random elements within a cursor?
+
+MongoDB cursors are designed for sequentially iterating over a result set, and all the drivers, including the Ruby driver, stick closely to this directive. Internally, a Ruby cursor fetches results in batches by running a MongoDB `getmore` operation. The results are buffered for efficient iteration on the client-side.
+
+What this means is that a cursor is nothing more than a device for returning a result set on a query that's been initiated on the server. Cursors are not containers for result sets. If we allow a cursor to be randomly accessed, then we run into issues regarding the freshness of the data. For instance, if I iterate over a cursor and then want to retrieve the cursor's first element, should a stored copy be returned, or should the cursor re-run the query? If we returned a stored copy, it may not be fresh. And if the the query is re-run, then we're technically dealing with a new cursor.
+
+To avoid those issues, we're saying that anyone who needs flexible access to the results of a query should store those results in an array and then access the data as needed.
+
+#### Why can't I save an instance of TimeWithZone?
+
+MongoDB stores times in UTC as the number of milliseconds since the epoch. This means that the Ruby driver serializes Ruby Time objects only. While it would certainly be possible to serialize a TimeWithZone, this isn't preferable since the driver would still deserialize to a Time object.
+
+All that said, if necessary, it'd be easy to write a thin wrapper over the driver that would store an extra time zone attribute and handle the serialization/deserialization of TimeWithZone transparently.
+
+#### I keep getting CURSOR_NOT_FOUND exceptions. What's happening?
+
+The most likely culprit here is that the cursor is timing out on the server. Whenever you issue a query, a cursor is created on the server. Cursor naturally time out after ten minutes, which means that if you happen to be iterating over a cursor for more than ten minutes, you risk a CURSOR_NOT_FOUND exception.
+
+There are two solutions to this problem. You can either:
+
+1. Limit your query. Use some combination of `limit` and `skip` to reduce the total number of query results. This will, obviously, bring down the time it takes to iterate.
+
+2. Turn off the cursor timeout. To do that, invoke `find` with a block, and pass `:timeout => true`:
+
+        @collection.find({}, :timeout => false) do |cursor|
+          cursor.each do |document
+            # Process documents here
+          end
+        end
+
+#### I periodically see connection failures between the driver and MongoDB. Why can't the driver retry the operation automatically?
+
+A connection failure can indicate any number of failure scenarios. Has the server crashed? Are we experiencing a temporary network partition? Is there a bug in our ssh tunnel?
+
+Without further investigation, it's impossible to know exactly what has caused the connection failure. Furthermore, when we do see a connection failure, it's impossible to  know how many operations prior to the failure succeeded. Imagine, for instance, that we're using safe mode and we send an `$inc` operation to the server. It's entirely possible that the server has received the `$inc` but failed on the call to `getLastError`. In that case, retrying the operation would result in a double-increment.
+
+Because of the indeterminacy involved, the MongoDB drivers will not retry operations on connection failure. How connection failures should be handled is entirely dependent on the application. Therefore, we leave it to the application developers to make the best decision in this case.
+
+The drivers will reconnect on the subsequent operation.

data/docs/GridFS.md

@@ -0,0 +1,158 @@
+# GridFS in Ruby
+
+GridFS, which stands for "Grid File Store," is a specification for storing large files in MongoDB. It works by dividing a file into manageable chunks and storing each of those chunks as a separate document. GridFS requires two collections to achieve this: one collection stores each file's metadata (e.g., name, size, etc.) and another stores the chunks themselves. If you're interested in more details, check out the [GridFS Specification](http://www.mongodb.org/display/DOCS/GridFS+Specification).
+
+### The Grid class
+
+The [Grid class](Mongo/Grid.html) represents the core GridFS implementation. Grid gives you a simple file store, keyed on a unique ID. This means that duplicate filenames aren't a problem. To use the Grid class, first make sure you have a database, and then instantiate a Grid:
+
+
+    @db = Mongo::Connection.new.db('social_site')
+    @grid = Grid.new(@db)
+
+#### Saving files
+Once you have a Grid object, you can start saving data to it. The data can be either a string or an IO-like object that responds to a #read method:
+
+
+    # Saving string data
+    id = @grid.put("here's some string / binary data")
+
+    # Saving IO data and including the optional filename
+    image = File.open("me.jpg")
+    id2   = @grid.put(image, :filename => "me.jpg")
+
+
+Grid#put returns an object id, which you can use to retrieve the file:
+
+
+    # Get the string we saved
+    file = @grid.get(id)
+
+    # Get the file we saved
+    image = @grid.get(id2)
+
+
+#### File metadata
+
+There are accessors for the various file attributes:
+
+
+    image.filename
+    # => "me.jpg"
+
+    image.content_type
+    # => "image/jpg"
+
+    image.file_length
+    # => 502357
+
+    image.upload_date
+    # => Mon Mar 01 16:18:30 UTC 2010
+
+    # Read all the image's data at once
+    image.read
+
+    # Read the first 100k bytes of the image
+    image.read(100 * 1024)
+
+
+When putting a file, you can set many of these attributes and write arbitrary metadata:
+
+
+    # Saving IO data
+    file = File.open("me.jpg")
+    id2  = @grid.put(file, 
+             :filename     => "my-avatar.jpg" 
+             :content_type => "application/jpg", 
+             :_id          => 'a-unique-id-to-use-in-lieu-of-a-random-one',
+             :chunk_size   => 100 * 1024,
+             :metadata     => {'description' => "taken after a game of ultimate"})
+
+
+#### Safe mode
+
+A kind of safe mode is built into the GridFS specification. When you save a file, and MD5 hash is created on the server. If you save the file in safe mode, an MD5 will be created on the client for comparison with the server version. If the two hashes don't match, an exception will be raised.
+
+
+    image = File.open("me.jpg")
+    id2   = @grid.put(image, "my-avatar.jpg", :safe => true) 
+
+
+#### Deleting files
+
+Deleting a file is as simple as providing the id:
+
+
+    @grid.delete(id2)
+
+
+### The GridFileSystem class
+
+[GridFileSystem](http://api.mongodb.org/ruby/current/Mongo/GridFileSystem.html) is a light emulation of a file system and therefore has a couple of unique properties. The first is that filenames are assumed to be unique. The second, a consequence of the first, is that files are versioned. To see what this means, let's create a GridFileSystem instance:
+
+#### Saving files
+
+    @db = Mongo::Connection.new.db("social_site")
+    @fs = GridFileSystem.new(@db)
+
+Now suppose we want to save the file 'me.jpg.' This is easily done using a filesystem-like API:
+
+
+    image = File.open("me.jpg")
+    @fs.open("me.jpg", "w") do |f|
+      f.write image
+    end 
+
+
+We can then retrieve the file by filename:
+
+
+    image = @fs.open("me.jpg", "r") {|f| f.read }
+
+
+No problems there. But what if we need to replace the file? That too is straightforward:
+
+
+    image = File.open("me-dancing.jpg")
+    @fs.open("me.jpg", "w") do |f|
+      f.write image
+    end 
+
+
+But a couple things need to be kept in mind. First is that the original 'me.jpg' will be available until the new 'me.jpg' saves. From then on, calls to the #open method will always return the most recently saved version of a file. But, and this the second point, old versions of the file won't be deleted. So if you're going to be rewriting files often, you could end up with a lot of old versions piling up. One solution to this is to use the :delete_old options when writing a file:
+
+
+    image = File.open("me-dancing.jpg")
+    @fs.open("me.jpg", "w", :delete_old => true) do |f|
+      f.write image
+    end 
+
+
+This will delete all but the latest version of the file.
+
+
+#### Deleting files
+
+When you delete a file by name, you delete all versions of that file:
+
+
+    @fs.delete("me.jpg")
+
+
+#### Metadata and safe mode
+
+All of the options for storing metadata and saving in safe mode are available for the GridFileSystem class:
+
+
+    image = File.open("me.jpg")
+    @fs.open('my-avatar.jpg', w,  
+               :content_type => "application/jpg", 
+               :metadata     => {'description' => "taken on 3/1/2010 after a game of ultimate"},
+               :_id          => 'a-unique-id-to-use-instead-of-the-automatically-generated-one',
+               :safe         => true) { |f| f.write image }
+
+
+### Advanced Users
+
+Astute code readers will notice that the Grid and GridFileSystem classes are merely thin wrappers around an underlying [GridIO class](http://api.mongodb.org/ruby/current/Mongo/GridIO.html). This means that it's easy to customize the GridFS implementation presented here; just use GridIO for all the low-level work, and build the API you need in an external manager class similar to Grid or GridFileSystem.
+