couchbase-orm 1.1.1 → 2.0.2

data/README.md

@@ -1,18 +1,24 @@
 # Couchbase ORM for Rails
 
-[![Build Status](https://secure.travis-ci.org/acaprojects/couchbase-orm.svg)](http://travis-ci.org/acaprojects/couchbase-orm)
+## Documentation
+https://couchbase-ruby-orm.com
 
-## Rails integration
+## Installation
+Add this line to your application's Gemfile:
+```ruby
+gem 'couchbase-orm', git: 'https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm' 
+```
+And then execute:
 
-To generate config you can use `rails generate couchbase_orm:config`:
+    $ bundle install
 
-    $ rails generate couchbase_orm:config dev_bucket dev_user dev_password
-      => create  config/couchbase.yml
+## Rails integration
 
-It will generate this `config/couchbase.yml` for you:
+Create a couchbase-orm config file `config/couchbase.yml`
 
+```yaml
     common: &common
-      hosts: localhost
+      connection_string: couchbase://localhost
       username: dev_user
       password: dev_password
 
@@ -26,10 +32,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 +58,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 +89,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 +138,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 +152,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 +161,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 +176,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 +312,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 = 'Apache-2.0'
+  gem.authors = ['Stephen von Takach', 'Gauthier Monserand', 'Pierre Merlin', 'Julien Burnet-Fauche']
+  gem.homepage = 'https://github.com/Couchbase-Ecosystem/couchbase-ruby-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