couch-db

Ruby CouchDB

Ruby gem to connect to a CouchDB database in Ruby, focusing on bulk requests. Make sure to watch Tim Anglade's excellent talk CouchDB & Ruby: You're Doing It Wrong.

Installation

Add this line to your application's Gemfile:

gem 'couch-db'

And then execute:

$ bundle

Or install it yourself as:

$ gem install couch-db

Usage

    require 'couch'
    
    # Subclass Couch::Server for application-specific logic
    class MyCouch < Couch::Server
      DB_NAME = 'my-db'
    
      def initialize
        super(
            'https://user.couchprovider.com/', # The library automatically detects whether to use SSL
            {
                name: 'user',
                password: 'supersecretpassword' # May be nil for public databases 

                max_array_length: 50, # Number of documents queued before an automatic write to the database occurs. Defaults to 250.
                flush_size_mb: 15, # Size of documents queued before an automatic write to the database occurs. Defaults to 10.
                open_timeout: 5*60, # HTTP timeout for opening connections, defaults to 5*30
                read_timeout: 5*60, # HTTP timeout for opening connections, defaults to 5*30
            }
        )
        @queue = []
      end
    
      def add_to_queue(doc)
        @queue << doc
        flushed = post_bulk_if_big_enough(DB_NAME, @queue)
        puts "Added #{doc[:_id]} to queue. Flushed: #{flushed}"
      end
    
      def flush_queue
        length = @queue.length
        post_bulk_throttled(DB_NAME, @queue) do |res|
          puts "Flushed bulk, response code #{res.code}"
        end
        length
      end
    end
    
    #####################
    # Script starts here
    #####################
    
    # Initialize couch interface
    couch = MyCouch.new
    couch.put("/#{MyCouch::DB_NAME}", '') # Create database
    
    # Add some documents to our database, triggering a bulk post after every 3 docs
    couch.options[:max_array_length] = 3
    (1..11).each do |i|
      couch.add_to_queue({_id: "document-#{i}"})
    end
    
    # Get single document.
    puts couch.get_doc(
             MyCouch::DB_NAME,
             'document-7',
             {stale: 'ok'} # Pass URL parameters in a hash
         )
    
    # Flush remaining docs
    l = couch.flush_queue
    puts "Flushed remaining #{l} docs in queue"
    
    # Access docs
    couch.all_docs(MyCouch::DB_NAME, 4) do |slice|
      puts "> Next #{slice.length} docs:"
      slice.each do |doc|
        puts doc
      end
    end
    
    # Delete database
    couch.delete("/#{MyCouch::DB_NAME}") 

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake false to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/digitalheir/ruby-couch-db. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.