couchbase-orm 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d5a44e4dcc24a7d2e0d4dfdac8ea6cf2657cbf8cd2edf6499ab8ac002b82192
-  data.tar.gz: ff4554e430770fc9d69f83247e6089ed8ec2874afd2f5cc3543bd21ef7c9ae5c
+  metadata.gz: 65b1d614fe648dace9781d689ac5583108b6acfcf216f6da479a66d710608048
+  data.tar.gz: 4cbb6ff2c0e59445ae03d908c07b2d21bbc12f34f3cf02d68248390b66bea3c6
 SHA512:
-  metadata.gz: 50bf631a6df22796e99a6fc7a6d1c49b1a00dd19fbbab58e4035286b2388fb597168b2cdbfd335f8a6f89028526ac7f47c005d30d49aac19064b6d7bd67d87b4
-  data.tar.gz: 1b2c61ce24033f54779fa56e5ef51e3c12a9f8c3e603fa8b00c4b7837db5289d032a2041b4e72d45dc032383fe6d8d710c822a1814bac75ad3be03269c36dc87
+  metadata.gz: b12fc3d20ac1acc47bac8b784b9f5de3b5113e916c4b68c3181684bc58cffa143202d122177b62821afea4d3af9e54d9a0c26d5a16a441b757cefcd4a3465435
+  data.tar.gz: e1a99aeaa12090047188a5f93b652e29d5e173e6a0f12422e1f42a252bda3229651cc9f550ac33dbeb0784f564e71b620a50c6967b375e882db3d005e2b0358d

data/.github/workflows/test.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        include:
+          - ruby: '3.2'
+            gemfile: '7.1.0'
+            couchbase: '7.1.1'
+          - ruby: '3.0'
+            gemfile: '7.0.0'
+            couchbase: '6.6.5'
+          - ruby: '3.0'
+            gemfile: '7.0.0'
+            couchbase: '7.1.0'
+          - ruby: '2.7'
+            gemfile: '7.0.0'
+            couchbase: '7.1.0'
+      fail-fast: false
+    runs-on: ubuntu-20.04
+    name: ${{ matrix.ruby }} rails-${{ matrix.gemfile }}  couchbase-${{ matrix.couchbase }}
+    steps:
+    - uses: actions/checkout@v3
+    - run: sudo apt-get update && sudo apt-get install libevent-dev libev-dev python-httplib2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: sudo ./ci/run_couchbase.sh $COUCHBASE_VERSION $COUCHBASE_BUCKET $COUCHBASE_USER $COUCHBASE_PASSWORD
+    - run: bundle exec rspec
+    env:
+      ACTIVE_MODEL_VERSION: ${{ matrix.gemfile }}
+      BUNDLE_JOBS: 4
+      BUNDLE_PATH: vendor/bundle
+      COUCHBASE_BUCKET: default
+      COUCHBASE_USER: tester
+      COUCHBASE_PASSWORD: password123
+      COUCHBASE_VERSION: ${{ matrix.couchbase }}

data/.gitignore

@@ -1,5 +1,6 @@
 *.sw?
 .DS_Store
+.rbenv-vars
 coverage
 rdoc
 html
@@ -14,5 +15,6 @@ Gemfile.lock
 .yardoc
 bin
 Gemfile-custom
+vendor
 
 *.gem

data/.travis.yml

@@ -1,9 +1,9 @@
 language: ruby
 rvm:
   - ruby-2.4.2
-  - ruby-2.3.5
+  - ruby-2.5.7
   - ruby-head
-  - jruby-9.1.13.0
+  - jruby-9.2.9.0
   - jruby-head
   - rubinius
   - rubinius-3.86
@@ -24,6 +24,7 @@ before_install:
   - /opt/couchbase/bin/couchbase-cli bucket-create -c 127.0.0.1:8091 -u admin -p password --bucket=default --bucket-type=couchbase --bucket-ramsize=160 --bucket-replica=0 --wait
   - sleep 1
   - /opt/couchbase/bin/couchbase-cli user-manage   -c 127.0.0.1:8091 -u admin -p password --set --rbac-username tester --rbac-password password123 --rbac-name "Auto Tester" --roles admin --auth-domain local
+  - curl http://admin:password@localhost:8093/query/service -d 'statement=CREATE INDEX `default_type` ON `default`(`type`)'
   - export TRAVIS_TEST=true
 matrix:
   allow_failures:

data/CODEOWNERS

@@ -0,0 +1 @@
+* @doctolib/couchbase-guild

data/Gemfile

@@ -1,4 +1,6 @@
+git_source(:github) do |repo_name|
+  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?('/')
+  "https://github.com/#{repo_name}.git"
+end
 source "https://rubygems.org"
-gemspec
-
-gem "rubysl", :platform => :rbx
+gemspec

data/README.md

@@ -1,7 +1,5 @@
 # Couchbase ORM for Rails
 
-[![Build Status](https://secure.travis-ci.org/acaprojects/couchbase-orm.svg)](http://travis-ci.org/acaprojects/couchbase-orm)
-
 ## Rails integration
 
 To generate config you can use `rails generate couchbase_orm:config`:
@@ -11,8 +9,9 @@ To generate config you can use `rails generate couchbase_orm:config`:
 
 It will generate this `config/couchbase.yml` for you:
 
+```yaml
     common: &common
-      hosts: localhost
+      connection_string: couchbase://localhost
       username: dev_user
       password: dev_password
 
@@ -26,10 +25,25 @@ It will generate this `config/couchbase.yml` for you:
 
     # set these environment variables on your production server
     production:
-    hosts: <%= ENV['COUCHBASE_HOST'] || ENV['COUCHBASE_HOSTS'] %>
-    bucket: <%= ENV['COUCHBASE_BUCKET'] %>
-    username: <%= ENV['COUCHBASE_USER'] %>
-    password: <%= ENV['COUCHBASE_PASSWORD'] %>
+      connection_string: <%= ENV['COUCHBASE_CONNECTION_STRING'] %>
+      bucket: <%= ENV['COUCHBASE_BUCKET'] %>
+      username: <%= ENV['COUCHBASE_USER'] %>
+      password: <%= ENV['COUCHBASE_PASSWORD'] %>
+```
+
+## Setup without Rails
+
+If you are not using Rails, you can configure couchbase-orm with an initializer:
+
+```ruby
+# config/initializers/couchbase_orm.rb
+CouchbaseOrm::Connection.config = {
+  connection_string: "couchbase://localhost"
+  username: "dev_user"
+  password: "dev_password"
+  bucket: "dev_bucket"
+}
+```
 
 Views are generated on application load if they don't exist or mismatch.
 This works fine in production however by default in development models are lazy loaded.
@@ -37,16 +51,15 @@ This works fine in production however by default in development models are lazy
     # config/environments/development.rb
     config.eager_load = true
 
-
 ## Examples
 
 ```ruby
     require 'couchbase-orm'
 
     class Post < CouchbaseOrm::Base
-      attribute :title, type: String
-      attribute :body,  type: String
-      attribute :draft, type: Boolean
+      attribute :title, :string
+      attribute :body,  :string
+      attribute :draft, :boolean
     end
 
     p = Post.new(id: 'hello-world',
@@ -69,16 +82,45 @@ You can also let the library generate the unique identifier for you:
     p.id        #=> "post-abcDE34"
 ```
 
-You can define connection options on per model basis:
+<!-- You can define connection options on per model basis:
 
 ```ruby
     class Post < CouchbaseOrm::Base
-      attribute :title, type: String
-      attribute :body,  type: String
-      attribute :draft, type: Boolean
+      attribute :title, :string
+      attribute :body,  :string
+      attribute :draft, :boolean
 
       connect bucket: 'blog', password: ENV['BLOG_BUCKET_PASSWORD']
     end
+``` -->
+
+## Typing
+
+The following types have been tested :
+
+- :string
+- :integer
+- :float
+- :boolean
+- :date
+- :datetime (stored as iso8601, use precision: n to store more decimal precision)
+- :timestamp (stored as integer)
+- :encrypted
+  - see <https://docs.couchbase.com/couchbase-lite/current/c/field-level-encryption.html>
+  - You must store a string that can be encoded in json (not binary data), use base64 if needed
+- :array (see below)
+- :nested (see below)
+
+You can register other types in ActiveModel registry :
+
+```ruby
+    class DateTimeWith3Decimal < CouchbaseOrm::Types::DateTime
+      def serialize(value)
+        value&.iso8601(3)
+      end
+    end
+
+    ActiveModel::Type.register(:datetime3decimal, DateTimeWith3Decimal)
 ```
 
 ## Validations
@@ -89,7 +131,8 @@ context of rails application. You can also enforce types using ruby
 
 ```ruby
     class Comment < Couchbase::Model
-      attribute :author, :body, type: String
+      attribute :author, :string
+      attribute :body, :string
 
       validates_presence_of :author, :body
     end
@@ -102,7 +145,8 @@ can then be used for filtering results or ordering.
 
 ```ruby
     class Comment < CouchbaseOrm::Base
-      attribute :author, :body, type: String
+      attribute :author :string
+      attribute :body, :string
       view :all # => emits :id and will return all comments
       view :by_author, emit_key: :author
 
@@ -110,15 +154,12 @@ can then be used for filtering results or ordering.
       # * the by_author view above
       # * def find_by_author(author); end
       index_view :author
-      
+
       # You can make compound keys by passing an array to :emit_key
       # this allow to query by read/unread comments
       view :by_read, emit_key: [:user_id, :read]
       # this allow to query by view_count
       view :by_view_count, emit_key: [:user_id, :view_count]
-       
-      
-      
 
       validates_presence_of :author, :body
     end
@@ -128,20 +169,129 @@ You can use `Comment.find_by_author('name')` to obtain all the comments by
 a particular author. The same thing, using the view directly would be:
 `Comment.by_author(key: 'name')`
 
-When using a compound key, the usage is the same, you just give the full key : 
+When using a compound key, the usage is the same, you just give the full key :
 
 ```ruby
    Comment.by_read(key: '["'+user_id+'",false]') # gives all unread comments for one particular user
-   
+
    # or even a range !
+
+   Comment.by_view_count(startkey: '["'+user_id+'",10]', endkey: '["'+user_id+'",20]') 
    
-   Comment.by_view_count(startkey: '["'+user_id+'",10]', endkey: '["'+user_id+'",20]') # gives all comments that have been seen more than 10 times but less than 20
+   # gives all comments that have been seen more than 10 times but less than 20
 ```
-
-Check this couchbase help page to learn more on what's possible with compound keys : https://developer.couchbase.com/documentation/server/3.x/admin/Views/views-translateSQL.html
+Check this couchbase help page to learn more on what's possible with compound keys : <https://developer.couchbase.com/documentation/server/3.x/admin/Views/views-translateSQL.html>
 
 Ex : Compound keys allows to decide the order of the results, and you can reverse it by passing `descending: true`
 
+```ruby
+    class Comment < CouchbaseOrm::Base19
+      self.ignored_properties = [:old_name] # ignore old_name property in the model
+      self.properties_always_exists_in_document = true # use is null for nil value instead of not valued for performance purpose, only possible if all properties always exists in document
+    end
+```      
+You can specify `properties_always_exists_in_document` to true if all properties always exists in document, this will allow to use `is null` instead of `not valued` for nil value, this will improve performance. 
+
+WARNING: If a document exists without a property, the query will failed! So you must be sure that all documents have all properties.
+
+
+## N1ql
+
+Like views, it's possible to use N1QL to process some requests used for filtering results or ordering.
+
+```ruby
+    class Comment < CouchbaseOrm::Base
+      attribute :author, :string
+      attribute :body, :string
+      n1ql :by_author, emit_key: :author
+
+      # Generates two functions:
+      # * the by_author view above
+      # * def find_by_author(author); end
+      index_n1ql :author
+
+      # You can make compound keys by passing an array to :emit_key
+      # this allow to query by read/unread comments
+      n1ql :by_read, emit_key: [:user_id, :read]
+      # this allow to query by view_count
+      n1ql :by_view_count, emit_key: [:user_id, :view_count]
+
+      validates_presence_of :author, :body
+    end
+```
+
+## Basic Active Record like query engine
+
+```ruby
+class Comment < CouchbaseOrm::Base
+      attribute :title, :string
+      attribute :author, :string
+      attribute :category, :string
+      attribute :ratings, :number
+end
+
+Comment.where(author: "Anne McCaffrey", category: ['S-F', 'Fantasy']).not(ratings: 0).order(:title).limit(10)
+
+# Relation can be composed as in AR:
+
+amc_comments = Comment.where(author: "Anne McCaffrey")
+
+amc_comments.count
+
+amc_sf_comments = amc_comments.where(category: 'S-F')
+
+# pluck is available, but will query all object fields first
+
+Comment.pluck(:title, :ratings)
+
+# To load the ids without loading the models
+
+Comment.where(author: "David Eddings").ids
+
+# To delete all the models of a relation
+
+Comment.where(ratings: 0).delete_all
+```
+
+## scopes
+
+Scopes can be written as class method, scope method is not implemented yet.
+They can be chained as in AR or mixed with relation methods.
+
+```ruby
+class Comment < CouchbaseOrm::Base
+      attribute :title, :string
+      attribute :author, :string
+      attribute :category, :string
+      attribute :ratings, :number
+
+      def self.by_author(author)
+        where(author: author)
+      end
+end
+
+Comment.by_author("Anne McCaffrey").where(category: 'S-F').not(ratings: 0).order(:title).limit(10)
+```
+
+## Operators
+
+Several operators are available to filter numerical results : \_gt, \_lt, \_gte, \_lte, \_ne
+  
+  ```ruby
+  Comment.where(ratings: {_gt: 3})
+  ```
+
+## Range in the where
+
+You can specify a Range of date or intger in the where clause
+
+  ```ruby
+  Person.where(birth_date: DateTime.new(1980, 1, 1)..DateTime.new(1990, 1, 1))
+  Person.where(age: 10..20)
+
+  Person.where(age: 10...20) # to exclude the upper bound
+  ```
+
 ## Associations and Indexes
 
 There are common active record helpers available for use `belongs_to` and `has_many`
@@ -155,21 +305,77 @@ There are common active record helpers available for use `belongs_to` and `has_m
         has_many :comments, dependent: :destroy
 
         # You can ensure an attribute is unique for this model
-        attribute :email, type: String
+        attribute :email, :string
         ensure_unique :email
     end
 ```
 
+By default, `has_many` uses a view for association,
+but you can define a `type` option to specify an association using N1QL instead:
+
+  ```ruby
+  class Comment < CouchbaseOrm::Base
+      belongs_to :author
+  end
+
+  class Author < CouchbaseOrm::Base
+      has_many :comments, type: :n1ql, dependent: :destroy
+  end
+  ```
+
+## Nested
+
+Attributes can be of type nested, they must specify a type of NestedDocument.
+The NestedValidation triggers nested validation on parent validation.
+
+```ruby
+    class Address < CouchbaseOrm::NestedDocument
+      attribute :road, :string
+      attribute :city, :string
+      validates :road, :city, presence: true
+    end
+
+    class Author < CouchbaseOrm::Base
+        attribute :address, :nested, type: Address
+        validates :address, nested: true
+    end
+```
+
+Model can be queried using the nested attributes
+
+```ruby
+    Author.where(address: {road: '1 rue de la paix', city: 'Paris'})
+```
+
+## Array
+
+Attributes can be of type array, they must contain something that can be serialized and deserialized to/from JSON.
+You can enforce the type of array elements. The type can be a NestedDocument
+
+```ruby
+    class Book < CouchbaseOrm::NestedDocument
+      attribute :name, :string
+      validates :name, presence: true
+    end 
+
+    class Author < CouchbaseOrm::Base
+        attribute things, :array
+        attribute flags, :array, type: :string
+        attribute books, :array, type: Book
+
+        validates :books, nested: true
+    end
+```
 
 ## Performance Comparison with Couchbase-Ruby-Model
 
 Basically we migrated an application from [Couchbase Ruby Model](https://github.com/couchbase/couchbase-ruby-model)
 to [Couchbase-ORM](https://github.com/acaprojects/couchbase-orm) (this project)
 
-* Rails 5 production
-* Puma as the webserver
-* Running on a 2015 Macbook Pro
-* Performance test: `siege -c250 -r10  http://localhost:3000/auth/authority`
+- Rails 5 production
+- Puma as the webserver
+- Running on a 2015 Macbook Pro
+- Performance test: `siege -c250 -r10  http://localhost:3000/auth/authority`
 
 The request above pulls the same database document each time and returns it. A simple O(1) operation.
 

data/ci/run_couchbase.sh

@@ -0,0 +1,22 @@
+set -x
+set -e
+
+VERSION=$1
+BUCKET=$2
+USER=$3
+PASSWORD=$4
+
+
+wget https://packages.couchbase.com/releases/$VERSION/couchbase-server-enterprise_$VERSION-ubuntu20.04_amd64.deb
+dpkg -i couchbase-server-enterprise_$VERSION-ubuntu20.04_amd64.deb
+sleep 8
+sudo service couchbase-server status
+/opt/couchbase/bin/couchbase-cli cluster-init -c 127.0.0.1:8091 --cluster-username=admin --cluster-password=password --cluster-ramsize=320 --cluster-index-ramsize=256 --cluster-fts-ramsize=256 --services=data,index,query,fts
+sleep 5
+/opt/couchbase/bin/couchbase-cli server-info   -c 127.0.0.1:8091 -u admin -p password
+/opt/couchbase/bin/couchbase-cli bucket-create -c 127.0.0.1:8091 -u admin -p password --bucket=$BUCKET --bucket-type=couchbase --bucket-ramsize=160 --bucket-replica=0 --wait
+sleep 1
+/opt/couchbase/bin/couchbase-cli user-manage   -c 127.0.0.1:8091 -u admin -p password --set --rbac-username $USER --rbac-password $PASSWORD --rbac-name "Auto Tester" --roles admin --auth-domain local
+curl http://admin:password@localhost:8093/query/service -d "statement=CREATE INDEX \`default_type\` ON \`$BUCKET\`(\`type\`)"
+curl http://admin:password@localhost:8093/query/service -d "statement=CREATE INDEX \`default_rating\` ON \`$BUCKET\`(\`rating\`)"
+curl http://admin:password@localhost:8093/query/service -d "statement=CREATE INDEX \`default_name\` ON \`$BUCKET\`(\`name\`)"

data/couchbase-orm.gemspec

@@ -1,27 +1,33 @@
-require File.expand_path("../lib/couchbase-orm/version", __FILE__)
+require File.expand_path('../lib/couchbase-orm/version', __FILE__)
 
 Gem::Specification.new do |gem|
-    gem.name          = "couchbase-orm"
-    gem.version       = CouchbaseOrm::VERSION
-    gem.license       = 'MIT'
-    gem.authors       = ["Stephen von Takach"]
-    gem.email         = ["steve@cotag.me"]
-    gem.homepage      = "https://github.com/cotag/couchbase-orm"
-    gem.summary       = "Couchbase ORM for Rails"
-    gem.description   = "A Couchbase ORM for Rails"
+  gem.name = 'couchbase-orm'
+  gem.version = CouchbaseOrm::VERSION
+  gem.license = 'MIT'
+  gem.authors = ['Stephen von Takach', 'Gauthier Monserand', 'Pierre Merlin', 'Julien Burnet-Fauche']
+  gem.homepage = 'https://github.com/doctolib/couchbase-orm'
+  gem.summary = 'Couchbase ORM for Rails'
+  gem.description = 'A Couchbase ORM for Rails'
 
-    gem.required_ruby_version = '>= 2.1.0'
-    gem.require_paths = ["lib"]
+  gem.required_ruby_version = '>= 2.7.0'
+  gem.require_paths = ['lib']
 
-    gem.add_runtime_dependency     'libcouchbase', '~> 1.2'
-    gem.add_runtime_dependency     'activemodel',  '>= 4.0', '< 6.0'
-    gem.add_runtime_dependency     'radix',        '~> 2.2' # converting numbers to and from any base
+  gem.add_runtime_dependency 'activemodel', ENV['ACTIVE_MODEL_VERSION'] || '>= 5.2'
 
-    gem.add_development_dependency 'rake',         '~> 12.2'
-    gem.add_development_dependency 'rspec',        '~> 3.7'
-    gem.add_development_dependency 'yard',         '~> 0.9'
-    gem.add_development_dependency 'minitest',     '~> 5.10'
+  gem.add_runtime_dependency     'couchbase',    '>= 3.4.2'
+  gem.add_runtime_dependency     'radix',        '~> 2.2' # converting numbers to and from any base
+  gem.add_runtime_dependency     'json-schema',  '>= 3' # validating JSON against a schema
 
-    gem.files         = `git ls-files`.split("\n")
-    gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.add_development_dependency 'rake', '~> 12.2'
+  gem.add_development_dependency 'rspec', '~> 3.7'
+  gem.add_development_dependency 'yard', '~> 0.9'
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'pry-stack_explorer'
+  gem.add_development_dependency 'simplecov'
+  gem.add_development_dependency 'actionpack'
+  gem.add_development_dependency 'timecop'
+  gem.add_development_dependency 'base64'
+
+  gem.files = `git ls-files`.split("\n")
+  gem.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
 end

data/lib/couchbase-orm/active_record_compat.rb

@@ -0,0 +1,92 @@
+require 'active_support/concern'
+require 'active_model'
+require 'active_support/hash_with_indifferent_access'
+
+module CouchbaseOrm
+
+  # Set of methods defined in ActiveRecord and needed for CouchbaseOrm
+  # try to avoid dependencies on too many active record classes
+  # by exemple we don't want to go down to the concept of tables
+  module ActiveRecordCompat
+
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      def primary_key
+        'id'
+      end
+
+      def base_class?
+        true
+      end
+
+      def column_names # can't be an alias for now
+        attribute_names
+      end
+
+      def abstract_class?
+        false
+      end
+
+      def connected?
+        true
+      end
+
+      def table_exists?
+        true
+      end
+
+      def _reflect_on_association(_attribute)
+        false
+      end
+
+      def type_for_attribute(attribute)
+        attribute_types[attribute]
+      end
+
+      if ActiveModel::VERSION::MAJOR < 6
+        def attribute_names
+          attribute_types.keys
+        end
+      end
+    end
+
+    def slice(*methods)
+      HashWithIndifferentAccess.new(methods.flatten.to_h { |method| [method, public_send(method)] })
+    end
+
+    def values_at(*methods)
+      methods.flatten.map! { |method| public_send(method) }
+    end
+
+    def _has_attribute?(attr_name)
+      attribute_names.include?(attr_name.to_s)
+    end
+
+    def attribute_for_inspect(attr_name)
+      value = send(attr_name)
+      value.inspect
+    end
+
+    if ActiveModel::VERSION::MAJOR < 6
+      def attribute_names
+        self.class.attribute_names
+      end
+
+      def has_attribute?(attr_name)
+        @attributes.key?(attr_name.to_s)
+      end
+
+      def attribute_present?(attribute)
+        value = send(attribute)
+        !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+      end
+
+      def _write_attribute(attr_name, value)
+        @attributes.write_from_user(attr_name.to_s, value)
+        value
+      end
+    end
+  end
+end