couchbase 0.9.8 → 1.0.0

data/.gitignore

@@ -1,4 +1,12 @@
 *.gem
+*.so
 .bundle
+.yardoc
 Gemfile.lock
+core*
+doc/
+ext/couchbase/Makefile
+ext/couchbase/mkmf.log
 pkg/*
+test/CouchbaseMock.jar
+tmp

data/.yardopts

@@ -0,0 +1,5 @@
+--protected
+--no-private
+-
+README.markdown
+HISTORY.markdown

data/HISTORY.markdown

@@ -1,15 +1,20 @@
-=== 0.9.8 / 2011-12-16
+## 1.0.0 / 2011-12-23
+
+* Implement all operations using libcouchbase as backend
+* Remove views code. It will be re-added in 1.1 version
+
+## 0.9.8 / 2011-12-16
 
 * Fix RCBC-10: It was impossible to store data in non-default buckets
 
-=== 0.9.7 / 2011-10-04
+## 0.9.7 / 2011-10-04
 
 * Fix design doc removing
 * Fix 'set' method signature: add missing options argument
 * Rename gem to 'couchbase' for easy of use. The github project still
   is 'couchbase-ruby-client'
 
-=== 0.9.6 / 2011-10-04
+## 0.9.6 / 2011-10-04
 
 * Fix bug with decoding multiget result
 * Allow create design documents from IO and String
@@ -18,11 +23,11 @@
 * Remove dependency on libyajl library: it bundled with yaji now
 * Update rake tasks: create zip- and tar-balls
 
-=== 0.9.5 / 2011-08-24
+## 0.9.5 / 2011-08-24
 
 * Update installation notes in README
 
-=== 0.9.4 / 2011-08-24
+## 0.9.4 / 2011-08-24
 
 * Use streaming json parser to iterate over view results
 * Update memcached gem dependency to v1.3
@@ -32,23 +37,22 @@
 * Fix bug with unicode parsing in config listener
 * Add more unit tests
 
-=== 0.9.3 / 2011-07-29
+## 0.9.3 / 2011-07-29
 
 * Use Latch (via Mutex and ConditionVariable) to wait until initial
   setup will be finished.
 * Update prefix for development views (from '$dev_' to 'dev_')
 
-=== 0.9.2 / 2011-07-29
+## 0.9.2 / 2011-07-29
 
 * Use zero TTL by default to store records forever
 * Update documentation
 * Sleep if setup isn't done
 
-
-=== 0.9.1 / 2011-07-25
+## 0.9.1 / 2011-07-25
 
 * Minor bugfix for RestClient initialization
 
-=== 0.9.0 / 2011-07-25
+## 0.9.0 / 2011-07-25
 
 * Initial public release

data/README.markdown

@@ -1,135 +1,330 @@
-Couchbase Ruby Client
-=====================
+# Couchbase Ruby Client
 
 This is the official client library for use with Couchbase Server.
 
-INSTALL
-=======
+## INSTALL
 
 This gem depends on a couple of external libraries to work with JSON and
-HTTP. For JSON it uses [yajl-ruby][1] and [yaji][2] which are built atop
-of [yajl][3]. For HTTP iteraction it uses [curb][4], the curl bindings for
-ruby. To install it use your package manager. On debian you can install
-it, use `aptitude`:
+Couchbase Server. For JSON it uses [yajl-ruby][1] which is built atop
+[yajl][2]. For Couchbase iteraction it uses [libcouchbase][3]. The first
+dependency shouldn't cause any issues because it will bundle yajl in the c
+extensions. To install yajl-ruby use following command:
 
-    $ sudo aptitude install libcurl3-dev
+    $ gem install yajl-ruby
 
-After that you can install the gem via rubygems:
+In most cases installing libcouchbase is just as simple.
+
+### MacOS (Homebrew)
+
+    $ brew install libcouchbase
+
+Or if our pull request isn't yet merged:
+
+    $ brew install http://packages.couchbase.com/clients/c/homebrew/libvbucket.rb
+    $ brew install http://packages.couchbase.com/clients/c/homebrew/libcouchbase.rb
+
+### Debian (Ubuntu)
+
+Download packages depending on your architecture:
+
+    $ wget http://packages.couchbase.com/clients/c/libvbucket{1,1-dbg,-dev}_1.8.0.1-1_amd64.deb
+    $ wget http://packages.couchbase.com/clients/c/libcouchbase{1,1-dbg,-dev}_1.0.0-1_amd64.deb
+
+or
+
+    $ wget http://packages.couchbase.com/clients/c/libvbucket{1,1-dbg,-dev}_1.8.0.1-1_i386.deb
+    $ wget http://packages.couchbase.com/clients/c/libcouchbase{1,1-dbg,-dev}_1.0.0-1_i386.deb
+
+Then install them using dpkg tool
+
+    $ sudo dpkg -i lib{vbucket,couchbase}*.deb
+
+### Centos (Redhat and rpm-based systems)
+
+Download packages depending on your architecture:
+
+    $ wget http://packages.couchbase.com/clients/c/libvbucket{1,-debuginfo,-devel}-1.8.0.1-1.x86_64.rpm
+    $ wget http://packages.couchbase.com/clients/c/libcouchbase{1,-debuginfo,-devel}-1.0.0-1.x86_64.rpm
+
+or
+
+    $ wget http://packages.couchbase.com/clients/c/libvbucket{1,-debuginfo,-devel}-1.8.0.1-1.i386.rpm
+    $ wget http://packages.couchbase.com/clients/c/libcouchbase{1,-debuginfo,-devel}-1.0.0-1.i386.rpm
+
+Then install them using rpm tool
+
+    $ sudo rpm -ivh lib{vbucket,couchbase}*.rpm
+
+### Couchbase gem
+
+Now install the couchbase gem itself
 
     $ gem install couchbase
 
-USAGE
-=====
+
+## USAGE
 
 First of all you need to load library:
 
     require 'couchbase'
 
-To establish connection with couchbase you need to specify at least pool
-URI. Also you can choose custom bucket name and memcached SASL
-authentication and Couchbase REST API.
+There are several ways to establish new connection to Couchbase Server.
+By default it uses the `http://localhost:8091/pools/default/buckets/default`
+as the endpoint. The client will automatically adjust configuration when
+the cluster will rebalance its nodes when nodes are added or deleted
+therefore this client is "smart".
+
+    c = Couchbase.new
 
+This is equivalent to following forms:
+
+    c = Couchbase.new("http://localhost:8091/pools/default/buckets/default")
     c = Couchbase.new("http://localhost:8091/pools/default")
-    c = Couchbase.new("http://localhost:8091/pools/default", :bucket_name => 'blog')
-    c = Couchbase.new("http://localhost:8091/pools/default",
-                      :bucket_name => 'blog', :bucket_password => 'secret')
-
-This gem supports memcached API accessible for [memcached][5] client
-with a bit syntax sugar:
-
-    c.set('password', 'secret')
-    c.get('password')             #=> "secret"
-    c['password'] = 'secret'
-    c['password']                 #=> "secret"
-    c['counter'] = 1              #=> 1
-    c['counter'] += 1             #=> 2
-    c['counter']                  #=> 2
-    c.increment('counter', 10)
-    c.flush
+    c = Couchbase.new("http://localhost:8091")
+    c = Couchbase.new(:host => "localhost")
+    c = Couchbase.new(:host => "localhost", :port => 8091)
+    c = Couchbase.new(:pool => "default", :bucket => "default")
 
-But if you store structured data, they will be treated as documents and
-you can handle them in map/reduce function from CouchDB views. For
-example, store a couple of posts using memcached API:
+The hash parameters take precedence on string URL.
 
-    c['biking'] = {:title => 'Biking',
-                   :body => 'I went to the the pet store earlier and brought home a little kitty...',
-                   :date => '2009/01/30 18:04:11'}
-    c['bought-a-cat'] = {:title => 'Biking',
-                         :body => 'My biggest hobby is mountainbiking. The other day...',
-                         :date => '2009/01/30 18:04:11'}
-    c['hello-world'] = {:title => 'Hello World',
-                        :body => 'Well hello and welcome to my new blog...',
-                        :date => '2009/01/15 15:52:20'}
-    c.all_docs.count    #=> 3
+The library supports both synchronous and asynchronous mode. You can
+choose either using the `:async` option or attribute.
 
-Now let's create design doc with sample view and save it in file
-'blog.json':
+    c = Couchbase.new(:async => true)
+    # ... asynchronous mode
+    c.async = false
+    # ... synchronous mode
 
-    {
-      "_id": "_design/blog",
-      "language": "javascript",
-      "views": {
-        "recent_posts": {
-          "map": "function(doc){if(doc.date && doc.title){emit(doc.date, doc.title);}}"
-        }
-      }
-    }
+In asynchronous mode all operations will return control to caller
+without blocking current thread. You can pass the block to method and it
+will be called with result when the operation will be completed. You
+need to run event loop when you scheduled your operations:
 
-This design document could be loaded into the database like this (also you can
-pass the ruby Hash or String with JSON encoded document):
+    c = Couchbase.new(:async => true)
+    c.run do |conn|
+      conn.get("foo") {|ret| puts ret.value}
+      conn.set("bar", "baz")
+    end
 
-    c.save_design_doc(File.open('blog.json'))
+The handlers could be nested
 
-To execute view you need to fetch it from design document `_design/blog`:
+    c.run do |conn|
+      conn.get("foo") do |ret|
+        conn.incr(ret.value, :initial => 0)
+      end
+    end
 
-    blog = c.design_docs['blog']
-    blog.views                    #=> ["recent_posts"]
-    blog.recent_posts             #=> [#<Couchbase::Document:14244860 {"id"=>"hello-world", "key"=>"2009/01/15 15:52:20", "value"=>"Hello World"}>,...]
+The asynchronous callback receives instance of `Couchbase::Result` which
+responds to several methods to figure out what was happened:
 
-Gem uses streaming parser to access view results so you can iterate them
-easily and if your code won't keep links to the documents GC might free
-them as soon as it decide they are unreachable, because parser doesn't
-store global JSON tree.
+  * `success?`. Returns `true` if operation succed.
 
-    posts = blog.recent_posts.each do |doc|
-      # do something
-      # with doc object
-    end
+  * `error`. Returns `nil` or exception object (subclass of
+    `Couchbase::Error::Base`) if something went wrong.
 
-You can also use Enumerator to iterate view results
+  * `key`
 
-    require 'date'
-    posts_by_date = Hash.new{|h,k| h[k] = []}
-    enum = c.all_docs.each  # request hasn't issued yet
-    enum.inject(posts_by_date) do |acc, doc|
-      acc[date] = Date.strptime(doc['date'], '%Y/%m/%d')
-      acc
-    end
+  * `value`
 
-The Couchbase server could generate errors during view execution with
-`200 OK` and partial results. By default the library raises exception as
-soon as errors detected in the result stream, but you can define the
-callback `on_error` to intercept these errors and do something more
-useful.
+  * `flags`
 
-    view = blog.recent_posts
-    logger = Logger.new(STDOUT)
+  * `cas`. The CAS version tag.
+
+  * `node`. Node address. It is used in flush and stats commands.
+
+  * `operation`. The symbol, representing an operation.
 
-    view.on_error do |from, reason|
-      logger.warn("#{view.inspect} received the error '#{reason}' from #{from}")
-    end
 
-    posts = view.each do |doc|
-      # do something
-      # with doc object
+To handle global errors in async mode `#on_error` callback should be
+used. It can be set in following fashions:
+
+    c.on_error do |opcode, key, exc|
+      ...
     end
 
-Note that errors object in view results usually goes *after* the rows,
-so you will likely receive a number of view results successfully before
-the error is detected.
+    handler = lambda {|opcode, key, exc| ...}
+    c.on_error = handler
+
+By default connection uses `:quiet` mode. This mean it won't raise
+exceptions when the given key is not exists:
+
+    c.get("missing-key")            #=> nil
+
+It could be useful when you are trying to make you code a bit efficient
+by avoiding exception handling. (See `#add` and `#replace` operations).
+You can turn on these exception by passing `:quiet => false` when you
+are instantiating the connection or change corresponding attribute:
+
+    c.quiet = false
+    c.get("missing-key")            #=> raise Couchbase::Error::NotFound
+    c.get("missing-key", :quiet => true)    #=> nil
+
+The library supports three different formats for representing values:
+
+* `:document` (default) format supports most of ruby types which could
+  be mapped to JSON data (hashes, arrays, string, numbers). A future
+  version will be able to run map/reduce queries on the values in the
+  document form (hashes)
+
+* `:marshal` This format avoids any conversions to be applied to your
+  data, but your data should be passed as String. This is useful for
+  building custom algorithms or formats. For example to implement a set:
+  http://dustin.github.com/2011/02/17/memcached-set.html
+
+* `:plain` Use this format if you'd like to transparently serialize your
+  ruby object with standard `Marshal.dump` and `Marshal.load` methods
+
+The couchbase API is the superset of [Memcached binary protocol][4], so
+you can use its operations.
+
+### Get
+
+    val = c.get("foo")
+    val, flags, cas = c.get("foo", :extended => true)
+
+Get and touch
+
+    val = c.get("foo", :ttl => 10)
+
+Get multiple values. In quiet mode will put `nil` values on missing
+positions:
+
+    vals = c.get("foo", "bar", "baz")
+    c.get("foo"){|val, key| ... }
+    c.get("foo", :extended => true){|val, key, flags, cas| ... }
+
+Get multiple values with extended information. The result will
+represented by hash with tuples `[value, flags, cas]` as a value.
+
+    vals = c.get("foo", "bar", "baz", :extended => true)
+    vals.inspect    #=> {"baz"=>["3", 0, 4784582192793125888],
+                         "foo"=>["1", 0, 8835713818674332672],
+                         "bar"=>["2", 0, 10805929834096100352]}
+
+Hash-like syntax
+
+    c["foo"]
+    c["foo", "bar", "baz"]
+    c["foo", {:extended => true}]
+    c["foo", :extended => true]         # for ruby 1.9.x only
+
+### Touch
+
+    c.touch("foo")                      # use :default_ttl
+    c.touch("foo", 10)
+    c.touch("foo", :ttl => 10)
+    c.touch("foo" => 10, "bar" => 20)
+    c.touch("foo" => 10, "bar" => 20){|key, success| ... }
+
+### Set
+
+    c.set("foo", "bar")
+    c.set("foo", "bar", :flags => 0x1000, :ttl => 30, :format => :plain)
+    c["foo"] = "bar"
+    c["foo", {:flags => 0x1000, :format => :plain}] = "bar"
+    c["foo", :flags => 0x1000] = "bar"  # for ruby 1.9.x only
+    c.set("foo", "bar", :cas => 8835713818674332672)
+    c.set("foo", "bar"){|cas, key, operation| ... }
+
+### Add
+
+Add command will fail if the key already exists. It accepts the same
+options as set command above.
+
+    c.add("foo", "bar")
+    c.add("foo", "bar", :flags => 0x1000, :ttl => 30, :format => :plain)
+
+### Replace
+
+The replace command will fail if the key already exists. It accepts the same
+options as set command above.
+
+    c.replace("foo", "bar")
+
+### Prepend/Append
+
+These commands are meaningful when you are using the `:plain` value format,
+because the concatenation is performed by server which has no idea how
+to merge to JSON values or values in ruby Marshal format. You may receive
+an `Couchbase::Error::ValueFormat` error.
+
+    c.set("foo", "world")
+    c.append("foo", "!")
+    c.prepend("foo", "Hello, ")
+    c.get("foo")                    #=> "Hello, world!"
+
+### Increment/Decrement
+
+These commands increment the value assigned to the key. It will raise
+Couchbase::Error::DeltaBadval if the delta or value is not a number.
+
+    c.set("foo", 1)
+    c.incr("foo")                   #=> 2
+    c.incr("foo", :delta => 2)      #=> 4
+    c.incr("foo", 4)                #=> 8
+    c.incr("foo", -1)               #=> 7
+    c.incr("foo", -100)             #=> 0
+    c.incr("foo"){|val, cas| ... }
+
+    c.set("foo", 10)
+    c.decr("foo", 1)                #=> 9
+    c.decr("foo", 100)              #=> 0
+    c.decr("foo"){|val, cas| ... }
+
+    c.incr("missing1", :initial => 10)      #=> 10
+    c.incr("missing1", :initial => 10)      #=> 11
+    c.incr("missing2", :create => true)     #=> 0
+    c.incr("missing2", :create => true)     #=> 1
+
+Note that it isn't the same as increment/decrement in ruby, which is
+performed on client side with following `set` operation:
+
+    c["foo"] = 10
+    c["foo"] -= 20                  #=> -10
+
+### Delete
+
+    c.delete("foo")
+    c.delete("foo", :cas => 8835713818674332672)
+    c.delete("foo", 8835713818674332672)
+    c.delete{|key, success| ... }
+
+### Flush
+
+Flush the items in the cluster.
+
+    c.flush
+    c.flush{|node, success| ... }
+
+### Stats
+
+Return statistics from each node in the cluster
+
+    c.stats
+    c.stats{|node, key, value| ... }
+
+The result is represented as a hash with the server node address as
+the key and stats as key-value pairs.
+
+    {
+      "172.16.16.76:12008"=>
+        {
+          "threads"=>"4",
+          "connection_structures"=>"22",
+          "ep_max_txn_size"=>"10000",
+          ...
+        },
+      "172.16.16.76:12000"=>
+        {
+          "threads"=>"4",
+          "connection_structures"=>"447",
+          "ep_max_txn_size"=>"10000",
+          ...
+        },
+      ...
+    }
 
 [1]: https://github.com/brianmario/yajl-ruby/
-[2]: https://github.com/avsej/yaji/
-[3]: http://lloyd.github.com/yajl/
-[4]: https://rubygems.org/gems/curb/
-[5]: https://github.com/fauna/memcached/
+[2]: http://lloyd.github.com/yajl/
+[3]: http://www.couchbase.com/develop/c/current
+[4]: http://code.google.com/p/memcached/wiki/BinaryProtocolRevamped