couchbase 3.0.0.alpha.1 → 3.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85cb801dc8f7b63d941b79865a732d57ed42bb120cb9e7aedeb5896fcdb9335a
-  data.tar.gz: 83e988d0285aaf16389238afbbf0369aca85394712b8eb492f7f66646b5f4441
+  metadata.gz: 1e71b3d69cab6a09f02460f5b983a908c256a76e12dd68f57fab9173c6a50d0e
+  data.tar.gz: b58766149d745a869828fe7f2f04f56182560de48a3365b95b253313f7f428c4
 SHA512:
-  metadata.gz: 5bf2fe5ef893721de3a7e00ac26d731ed8d00ee47ab8fd2ba72097ae9218a4652618d4677d9899568de2c61d39082b5fdcd747b3f41e1a605abcf7756abc6540
-  data.tar.gz: 654499d9954281e56a5fdcbb8e9c5162e2e97b51331603df37a3910d0595d335a8ea18c2057042c54f22faad9dad5e732860a4c591f05e8f119712bc6b6dd0e7
+  metadata.gz: 12b4ab101a664897933c2ca98841c1d7cd27c6b5a15653eb2b48e59eba69f76f431ce25b316eba392ad8f104cdcde0fa44b38004a341e316141d821a7256c852
+  data.tar.gz: 4a1723022980425bc7b0a907d5487ae72c654d29709f1137a32349a98eab7e11f23d75a95414df60a35097e9eae4cd9ec2414d184877b95c06f62cb97825770a

data/.yardopts

@@ -0,0 +1 @@
+--output-dir doc/couchbase-ruby-client-master lib - README.md

data/Gemfile

@@ -17,7 +17,17 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
 
+gem "rake"
+
 group :development do
-  gem "byebug"
-#  gem "sorbet"
+  gem "yard"
+  platforms :mri do
+    gem "byebug"
+  end
+end
+
+group :test do
+  gem "minitest"
+  gem "minitest-reporters"
+  gem "simplecov-cobertura"
 end

data/README.md

@@ -1,6 +1,61 @@
-# Couchbase Ruby Client
+# Couchbase Ruby Client [![tests](https://github.com/couchbase/couchbase-ruby-client/workflows/tests/badge.svg)](https://github.com/couchbase/couchbase-ruby-client/actions?query=workflow%3Atests)
 
-This repository contains the third generation of the Couchbase SDK for Ruby (aka. SDKv3)
+This repository contains the third generation of the official Couchbase SDK for Ruby (aka. SDKv3)
+
+## Support and Feedback
+
+If you find an issue, please file it in [our JIRA issue tracker](https://couchbase.com/issues/browse/RCBC).
+Also you are always welcome on [our forum](https://forums.couchbase.com/c/ruby-sdk).
+
+Please attach version information to ticket/post. To obtain this information use the following command:
+
+    $ ruby -r couchbase -e 'p Couchbase::VERSION'
+
+## Installation
+
+The library tested with the MRI 2.5, 2.6 and 2.7. Supported platforms are Linux and MacOS.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "couchbase", "3.0.0.beta.1"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install --pre couchbase
+
+For some platforms we precompile binary packages. When, for some reason, binary package cannot be used, pass
+`--platform=ruby` to `gem install` command (or check `specific_platform` and `force_ruby_platform` options of Bundler).
+In latter case, see [Development](#development) section for build dependencies.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+Part of the library is written in C++, and requires both C and C++ compilers installed on the system. To configure build
+environment, it uses `cmake`. When these tools installed, the build process is easy:
+
+    $ rake compile
+
+## Generate Documentation
+
+To generate documentation `yard` library is highly recommended.
+
+    $ gem install yard
+
+The following steps will generate API reference for selected git tag:
+
+    $ rake doc
+
+Now the API reference is accessible using web browser (where `VERSION` is current version of the SDK)
+
+    $ firefox doc/couchbase-ruby-client-VERSION/index.html
 
 ## License
 

data/Rakefile

@@ -27,3 +27,25 @@ task :compile do
     sh "ruby #{File.join(__dir__, "ext", "extconf.rb")}"
   end
 end
+
+task :doc do
+  require "couchbase/version"
+  input_dir = File.join(__dir__, "lib")
+  output_dir = File.join(__dir__, "doc", "couchbase-ruby-client-#{Couchbase::VERSION[:sdk]}")
+  rm_rf output_dir
+  sh "yard doc --hide-api private --output-dir #{output_dir} #{input_dir} --main README.md"
+  puts "#{File.realpath(output_dir)}/index.html"
+end
+
+task :docs => :doc
+
+task :undocumented => :doc do
+  sh "yard stats --list-undoc --compact"
+end
+
+task :render_git_revision do
+  build_version_path = File.join(__dir__, 'ext', 'build_version.hxx.in')
+  File.write(build_version_path, File.read(build_version_path).gsub('@BACKEND_GIT_REVISION@', `git rev-parse HEAD`.strip))
+end
+
+task :build => :render_git_revision

data/couchbase.gemspec

@@ -23,23 +23,56 @@ Gem::Specification.new do |spec|
   spec.email = ["sergey.avseyev@gmail.com"]
   spec.summary = "SDK for Couchbase Server"
   spec.description = "Modern SDK for Couchbase Server"
-  spec.homepage = "https://github.com/couchbase/couchbase.rb"
-  spec.license = "MIT"
+  spec.homepage = "https://www.couchbase.com"
+  spec.license = "Apache-2.0"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/couchbase/couchbase-ruby-client"
-  spec.metadata["changelog_uri"] = "#{spec.metadata["source_code_uri"]}/releases"
+  spec.metadata = {
+      "homepage_uri" => "https://docs.couchbase.com/ruby-sdk/3.0/hello-world/start-using-sdk.html",
+      "bug_tracker_uri" => "https://couchbase.com/issues/browse/RCBC",
+      "mailing_list_uri" => "https://forums.couchbase.com/c/ruby-sdk",
+      "source_code_uri" => "https://github.com/couchbasse/couchbase-ruby-client/tree/#{spec.version}",
+      "changelog_uri" => "https://github.com/couchbase/couchbase-ruby-client/releases/tag/#{spec.version}",
+      "documentation_uri" => "https://docs.couchbase.com/sdk-api/couchbase-ruby-client-#{spec.version}/index.html",
+      "github_repo" => "ssh://github.com/couchbase/couchbase-ruby-client",
+  }
 
   spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
-    `git ls-files --recurse-submodules -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    exclude_paths = %w[
+        .idea
+        .github
+        .gitignore
+        .gitmodules
+        bin
+        test
+        spec
+        features
+        test_data
+        ext/third_party/asio/asio/src/examples
+        ext/third_party/asio/asio/src/tests
+        ext/third_party/asio/asio/src/tools
+        ext/third_party/gsl/tests
+        ext/third_party/http_parser/contrib
+        ext/third_party/http_parser/fuzzers
+        ext/third_party/json/contrib
+        ext/third_party/json/doc
+        ext/third_party/json/src/example
+        ext/third_party/json/src/perf
+        ext/third_party/json/src/test
+        ext/third_party/json/tests
+        ext/third_party/snappy/testdata
+        ext/third_party/spdlog/bench
+        ext/third_party/spdlog/example
+        ext/third_party/spdlog/logos
+        ext/third_party/spdlog/scripts
+        ext/third_party/spdlog/tests
+    ]
+    `git ls-files --recurse-submodules -z`
+        .split("\x0")
+        .reject { |f| f.match(%r{^(#{Regexp.union(exclude_paths)})}) }
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
   spec.extensions = ["ext/extconf.rb"]
-
-  spec.add_development_dependency "bundler", "~> 2.1"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "minitest", "~> 5.14"
-  spec.add_development_dependency "minitest-reporters", "~> 1.4"
+  spec.rdoc_options << "--exclude" << "ext/"
 end

data/examples/analytics.rb

@@ -0,0 +1,221 @@
+require 'couchbase'
+
+include Couchbase
+
+options = Cluster::ClusterOptions.new
+options.authenticate("Administrator", "password")
+cluster = Cluster.connect("couchbase://localhost", options)
+
+
+bucket_name = "tiny_social"
+dataverse_name = "TinySocial"
+
+# Prepare dataset
+begin
+  cluster.buckets.drop_bucket(bucket_name)
+rescue Error::BucketNotFound
+  # ignore
+end
+
+settings = Management::BucketSettings.new
+settings.name = bucket_name
+settings.bucket_type = :couchbase
+settings.ram_quota_mb = 100
+cluster.buckets.create_bucket(settings)
+loop do
+  sleep 1
+  break if cluster.buckets.get_all_buckets.find { |b| b.name == bucket_name }.healthy?
+end
+
+collection = cluster.bucket(bucket_name).default_collection
+
+# Documents for GleambookUsers dataset
+[
+    {
+        "id" => 1,
+        "alias" => "Margarita",
+        "name" => "MargaritaStoddard",
+        "nickname" => "Mags",
+        "userSince" => "2012-08-20T10:10:00",
+        "friendIds" => [2, 3, 6, 10],
+        "employment" => [
+            {
+                "organizationName" => "Codetechno",
+                "start-date" => "2006-08-06"
+            },
+            {
+                "organizationName" => "geomedia",
+                "start-date" => "2010-06-17",
+                "end-date" => "2010-01-26"
+            }
+        ],
+        "gender" => "F"
+    },
+    {
+        "id" => 2,
+        "alias" => "Isbel",
+        "name" => "IsbelDull",
+        "nickname" => "Izzy",
+        "userSince" => "2011-01-22T10:10:00",
+        "friendIds" => [1, 4],
+        "employment" => [
+            {
+                "organizationName" => "Hexviafind",
+                "startDate" => "2010-04-27"
+            }
+        ]
+    },
+    {
+        "id" => 3,
+        "alias" => "Emory",
+        "name" => "EmoryUnk",
+        "userSince" => "2012-07-10T10:10:00",
+        "friendIds" => [1, 5, 8, 9],
+        "employment" => [
+            {
+                "organizationName" => "geomedia",
+                "startDate" => "2010-06-17",
+                "endDate" => "2010-01-26"
+            }
+        ]
+    }
+].each do |document|
+  collection.upsert("user:#{document["id"]}",
+                    document.merge({"type" => "user"}))
+end
+
+# Documents for GleambookMessages dataset
+[
+    {
+        "messageId" => 2,
+        "authorId" => 1,
+        "inResponseTo" => 4,
+        "senderLocation" => [41.66, 80.87],
+        "message" => " dislike x-phone its touch-screen is horrible"
+    },
+    {
+        "messageId" => 3,
+        "authorId" => 2,
+        "inResponseTo" => 4,
+        "senderLocation" => [48.09, 81.01],
+        "message" => " like product-y the plan is amazing"
+    },
+    {
+        "messageId" => 4,
+        "authorId" => 1,
+        "inResponseTo" => 2,
+        "senderLocation" => [37.73, 97.04],
+        "message" => " can't stand acast the network is horrible:("
+    },
+    {
+        "messageId" => 6,
+        "authorId" => 2,
+        "inResponseTo" => 1,
+        "senderLocation" => [31.5, 75.56],
+        "message" => " like product-z its platform is mind-blowing"
+    },
+    {
+        "messageId" => 8,
+        "authorId" => 1,
+        "inResponseTo" => 11,
+        "senderLocation" => [40.33, 80.87],
+        "message" => " like ccast the 3G is awesome:)"
+    },
+    {
+        "messageId" => 10,
+        "authorId" => 1,
+        "inResponseTo" => 12,
+        "senderLocation" => [42.5, 70.01],
+        "message" => " can't stand product-w the touch-screen is terrible"
+    },
+    {
+        "messageId" => 11,
+        "authorId" => 1,
+        "inResponseTo" => 1,
+        "senderLocation" => [38.97, 77.49],
+        "message" => " can't stand acast its plan is terrible"
+    }
+].each do |document|
+  collection.upsert("message:#{document["messageId"]}",
+                    document.merge({"type" => "message"}))
+end
+
+if cluster.analytics_indexes.get_all_datasets.any? {|ds| ds.dataverse_name == dataverse_name}
+  # there are datasets on our dataverse, drop everything and re-create
+  options = Management::AnalyticsIndexManager::DisconnectLinkOptions.new
+  options.dataverse_name = dataverse_name
+  cluster.analytics_indexes.disconnect_link(options)
+  cluster.analytics_indexes.drop_dataverse(dataverse_name)
+end
+
+cluster.analytics_indexes.create_dataverse(dataverse_name)
+
+options = Management::AnalyticsIndexManager::CreateDatasetOptions.new
+options.dataverse_name = dataverse_name
+
+options.condition = '`type` = "user"'
+cluster.analytics_indexes.create_dataset("GleambookUsers", bucket_name, options)
+
+options.condition = '`type` = "message"'
+cluster.analytics_indexes.create_dataset("GleambookMessages", bucket_name, options)
+
+options = Management::AnalyticsIndexManager::ConnectLinkOptions.new
+options.dataverse_name = dataverse_name
+cluster.analytics_indexes.connect_link(options)
+
+sleep(1)
+
+puts "---- inner join"
+res = cluster.analytics_query("SELECT * FROM #{dataverse_name}.GleambookUsers u, #{dataverse_name}.GleambookMessages m WHERE m.authorId = u.id")
+res.rows.each do |row|
+  puts "#{row["u"]["name"]}: #{row["m"]["message"].inspect}"
+end
+
+# The query language supports SQL's notion of left outer join.
+puts "---- left outer join"
+res = cluster.analytics_query("
+  USE #{dataverse_name};
+  SELECT u.name AS uname, m.message AS message
+  FROM GleambookUsers u
+  LEFT OUTER JOIN GleambookMessages m ON m.authorId = u.id
+")
+res.rows.each do |row|
+  puts "#{row["uname"]}: #{row["message"].inspect}"
+end
+
+# Named parameters
+puts "---- named parameters"
+options = Cluster::AnalyticsOptions.new
+options.named_parameters({user_id: 2})
+res = cluster.analytics_query("
+USE #{dataverse_name};
+
+SELECT u.name AS uname
+FROM GleambookUsers u
+WHERE u.id = $user_id
+
+UNION ALL
+
+SELECT VALUE m.message
+FROM GleambookMessages m
+WHERE authorId = $user_id
+", options)
+res.rows.each do |row|
+  p row
+end
+
+# Positional parameters
+puts "---- positional parameters"
+options = Cluster::AnalyticsOptions.new
+options.positional_parameters([2])
+res = cluster.analytics_query("
+USE #{dataverse_name};
+SELECT VALUE user
+FROM GleambookUsers AS user
+WHERE len(user.friendIds) > $1
+", options)
+res.rows.each do |row|
+  puts "#{row["name"]}: #{row["friendIds"].size}"
+end
+
+# More query examples at https://docs.couchbase.com/server/current/analytics/3_query.html

data/examples/crud.rb

@@ -1,4 +1,3 @@
-require 'irb'
 require 'couchbase'
 include Couchbase
 
@@ -12,7 +11,7 @@ res = collection.upsert("foo", {"bar" => 42})
 p res.cas
 
 res = collection.get("foo")
-p res.content_as :json
+p res.content
 p res.cas
 
 res = collection.remove("foo")

data/examples/managing_analytics_indexes.rb

@@ -0,0 +1,72 @@
+require 'couchbase'
+include Couchbase
+
+def measure(msg)
+  start = Time.now
+  yield
+  printf "%s in %.2f seconds\n", msg, Time.now - start
+end
+
+options = Cluster::ClusterOptions.new
+options.authenticate("Administrator", "password")
+cluster = Cluster.connect("couchbase://localhost", options)
+
+manager = cluster.analytics_indexes
+
+options = Management::AnalyticsIndexManager::DropDatasetOptions.new
+options.ignore_if_does_not_exist = true
+options.dataverse_name = "beer-data"
+manager.drop_dataset("beers", options)
+manager.drop_dataset("breweries", options)
+
+options = Management::AnalyticsIndexManager::DropDataverseOptions.new
+options.ignore_if_does_not_exist = true
+manager.drop_dataverse("beer-data", options)
+
+# Creates a dataverse with the name beer-data to be used to manage other metadata entities.
+manager.create_dataverse("beer-data")
+
+# Creates 2 datasets beers and breweries on the beer-sample bucket and filters the content for each dataset by the value
+# of the type field of the record.
+options = Management::AnalyticsIndexManager::CreateDatasetOptions.new
+options.dataverse_name = "beer-data"
+options.condition = '`type` = "beer"'
+manager.create_dataset("beers", "beer-sample", options)
+
+options = Management::AnalyticsIndexManager::CreateDatasetOptions.new
+options.dataverse_name = "beer-data"
+options.condition = '`type` = "brewery"'
+manager.create_dataset("breweries", "beer-sample", options)
+
+# Creates indexes on the identified fields for the specified types.
+options = Management::AnalyticsIndexManager::CreateIndexOptions.new
+options.dataverse_name = "beer-data"
+manager.create_index("beers_name_idx", "beers", {"name" => "string"}, options)
+manager.create_index("breweries_name_idx", "beers", {"name" => "string"}, options)
+manager.create_index("breweries_loc_idx", "beers", {"geo.lon" => "double", "geo.lat" => "double"}, options)
+
+puts "---- Indexes currently defined on the cluster:"
+manager.get_all_indexes.each_with_index do |index, i|
+  puts "#{i}. #{index.dataverse_name}.#{index.dataset_name}.#{index.name} #{"(primary)" if index.primary?}"
+end
+
+# Drops one of the indexes
+options = Management::AnalyticsIndexManager::DropIndexOptions.new
+options.dataverse_name = "beer-data"
+manager.drop_index("breweries_name_idx", "beers", options)
+
+puts "---- Datasets currently defined on the cluster:"
+manager.get_all_datasets.each_with_index do |dataset, i|
+  puts "#{i}. #{dataset.dataverse_name}.#{dataset.name} (link: #{dataset.link_name}, bucket: #{dataset.bucket_name})"
+end
+
+# Connects all datasets to their Data Service buckets and starts shadowing
+options = Management::AnalyticsIndexManager::ConnectLinkOptions.new
+options.dataverse_name = "beer-data"
+manager.connect_link(options)
+
+puts "---- Pending mutations: #{manager.get_pending_mutations.inspect}"
+
+options = Management::AnalyticsIndexManager::DisconnectLinkOptions.new
+options.dataverse_name = "beer-data"
+manager.disconnect_link(options)