couchbase-orm 2.0.4 → 2.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f70a9e7ebdde5781a23268a9d400a917fcea2d9432a61f0b374280c2d534325
-  data.tar.gz: a3cb52d01386be648eecce010f96399325771b0b50c32f92dec3f91b41fdb628
+  metadata.gz: f52bb1912f8b6e060c4daffc1b9ef0bd0922b7dc4035c774743839ea54abcab4
+  data.tar.gz: ba9cf86a6014a14a671c9a209f2c8ba58bd2acd8b1d54720af8c9237c4812cbc
 SHA512:
-  metadata.gz: 7bb46f6fe815f3378e39421453b3a0b901fe81cd35f49ec10505a9d6e12d11d201d58ce02a436adb8b569adc2e01aec7b5c07bdd264bc50a68ff1074d0f574f8
-  data.tar.gz: 5f542c3227c7587c1ad14c43f64d35e2a072bc4d39165fd9c6983bf86f3061c220360ce86393cbc67e61c537833bfb6679ed5ad3b3edebc7c2a00065e02997b3
+  metadata.gz: 1c3dc0311028fb1edf5612632f9b8bbadd89bd540416f08989331075ee052d915f58481b2879b15f946810c0e4c735b8130d994c0f796c9cae4d50bf0a0e50ea
+  data.tar.gz: '013937e07a05ec6386be0c65ef72dba41c67aa902680d5cb5f0bd936eaf592a1d5b024d7d4c6bcd06d5bc7195bb4bb44f8afc99beb010288f1be9807e117e207'

data/.github/workflows/deploy.yml

@@ -0,0 +1,45 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: |
+            cd docusaurus
+            yarn install
+
+      - name: Build website
+        run: |
+            cd docusaurus
+            yarn build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docusaurus/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

data/.github/workflows/test.yml

@@ -11,27 +11,32 @@ jobs:
     strategy:
       matrix:
         include:
+          - ruby: '3.4'
+            active-model: '8.0.2'
+            couchbase: '7.2.3'
+          - ruby: '3.3'
+            active-model: '8.0.0'
+            couchbase: '7.2.3'
           - ruby: '3.3'
-            gemfile: '7.1.0'
+            active-model: '7.2'
             couchbase: '7.2.3'
           - ruby: '3.2'
-            gemfile: '7.1.0'
+            active-model: '7.2.0'
             couchbase: '7.1.1'
-          - ruby: '3.0'
-            gemfile: '7.0.0'
+          - ruby: '3.2'
+            active-model: '7.1.0'
             couchbase: '6.6.5'
-          - ruby: '3.0'
-            gemfile: '7.0.0'
-            couchbase: '7.1.0'
-          - ruby: '2.7'
-            gemfile: '7.0.0'
+          - ruby: '3.1'
+            active-model: '7.1.0'
             couchbase: '7.1.0'
       fail-fast: false
-    runs-on: ubuntu-20.04
-    name: ${{ matrix.ruby }} rails-${{ matrix.gemfile }}  couchbase-${{ matrix.couchbase }}
+    runs-on: ubuntu-24.04
+    name: ${{ matrix.ruby }} rails-${{ matrix.active-model }}  couchbase-${{ matrix.couchbase }}
     steps:
     - uses: actions/checkout@v3
-    - run: sudo apt-get update && sudo apt-get install libevent-dev libev-dev python-httplib2
+    - run: sudo apt-get update && sudo apt-get install libevent-dev libev-dev python3-httplib2
+    - run: wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2ubuntu0.1_amd64.deb
+    - run: sudo apt install ./libtinfo5_6.3-2ubuntu0.1_amd64.deb
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
@@ -39,7 +44,7 @@ jobs:
     - run: sudo ./ci/run_couchbase.sh $COUCHBASE_VERSION $COUCHBASE_BUCKET $COUCHBASE_USER $COUCHBASE_PASSWORD
     - run: bundle exec rspec
     env:
-      ACTIVE_MODEL_VERSION: ${{ matrix.gemfile }}
+      ACTIVE_MODEL_VERSION: ${{ matrix.active-model }}
       BUNDLE_JOBS: 4
       BUNDLE_PATH: vendor/bundle
       COUCHBASE_BUCKET: default

data/README.md

@@ -393,3 +393,15 @@ The request above pulls the same database document each time and returns it. A s
 |Response time|0.88 secs|0.34 secs|
 |Transaction rate|204.25 trans/sec|366.57 trans/sec|
 |Request Code|[ruby-model-app](https://github.com/QuayPay/coauth/blob/95bbf5e5c3b3340e5af2da494b90c91c5e3d6eaa/app/controllers/auth/authorities_controller.rb#L6)|[couch-orm-app](https://github.com/QuayPay/coauth/blob/87f6fdeaab784ba252a5d38bbcf9e6b0477bb504/app/controllers/auth/authorities_controller.rb#L8)|
+
+---
+
+## 📢 Support Policy
+
+We truly appreciate your interest in this project!  
+This project is **community-maintained**, which means it's **not officially supported** by our support team.
+
+If you need help, have found a bug, or want to contribute improvements, the best place to do that is right here — by [opening a GitHub issue](https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm/issues).  
+Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.
+
+Your collaboration helps us all move forward together — thank you!

data/couchbase-orm.gemspec

@@ -15,10 +15,10 @@ Gem::Specification.new do |gem|
   gem.summary = 'Couchbase ORM for Rails'
   gem.description = 'A Couchbase ORM for Rails'
 
-  gem.required_ruby_version = '>= 2.7.0'
+  gem.required_ruby_version = '>= 3.1.0'
   gem.require_paths = ['lib']
 
-  gem.add_runtime_dependency 'activemodel', ENV['ACTIVE_MODEL_VERSION'] || '>= 5.2'
+  gem.add_runtime_dependency 'activemodel', ENV['ACTIVE_MODEL_VERSION'] || '>= 7.1'
 
   gem.add_runtime_dependency     'couchbase',    '>= 3.4.2'
   gem.add_runtime_dependency     'radix',        '~> 2.2' # converting numbers to and from any base

data/docusaurus/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

data/docusaurus/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

data/docusaurus/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

data/docusaurus/docs/tutorial-ruby-couchbase-orm/01-introduction.md

@@ -0,0 +1,49 @@
+# Introduction
+
+Welcome to the documentation for Couchbase ORM, an Object-Relational Mapping (ORM) library for Ruby that simplifies interactions with Couchbase Server. This guide will walk you through the features and usage of Couchbase ORM, helping you build efficient and scalable Ruby applications with Couchbase.
+
+## 1.1. What is Couchbase ORM?
+
+Couchbase ORM is a Ruby library that provides an ActiveRecord-like interface for working with Couchbase Server, a highly scalable and performant NoSQL database. It allows you to define your application's data models as Ruby classes and interact with the database using a familiar and intuitive API.
+
+With Couchbase ORM, you can:
+
+- Define your data models and their relationships
+- Perform CRUD (Create, Read, Update, Delete) operations on your models
+- Query your data using a flexible and expressive query language
+- Use Couchbase-specific features like N1QL queries and views
+- Implement advanced features such as data validation, callbacks, and associations
+
+Couchbase ORM abstracts away the low-level details of interacting with Couchbase Server, enabling you to focus on writing business logic and building great applications.
+
+## 1.2. Key Features
+
+Couchbase ORM offers a wide range of features to make working with Couchbase Server a breeze. Some of the key features include:
+
+1. **ActiveModel Compliance**: Couchbase ORM follows the ActiveModel API, providing a familiar interface for developers who have worked with ActiveRecord or other ActiveModel-compliant libraries.
+
+2. **Attribute Definition**: Easily define your model's attributes and their types using a simple and intuitive DSL.
+
+3. **Querying**: Use a powerful and expressive query language to retrieve data from Couchbase Server. Couchbase ORM supports a wide range of query options, including filtering, ordering, limiting, and more.
+
+4. **Persistence**: Perform CRUD operations on your models with simple and intuitive methods like `save`, `create`, `update`, and `destroy`.
+
+5. **Associations**: Define relationships between your models, such as one-to-many and many-to-many, using simple declarations.
+
+6. **Validations**: Validate your model's data before persisting it to the database using a variety of built-in validators or custom validation methods.
+
+7. **Callbacks**: Define callbacks to execute code before or after certain events, such as saving or updating a model.
+
+8. **N1QL Queries**: Execute N1QL queries directly from your Ruby code and map the results to your models.
+
+9. **Views**: Create and query Couchbase views to efficiently retrieve data based on specific criteria.
+
+10. **Nested Documents**: Embed related documents within a parent document for denormalized data modeling.
+
+These are just a few of the many features offered by Couchbase ORM. Throughout this documentation, we'll explore these features in-depth and provide examples of how to use them in your Ruby applications.
+
+## 1.3. Getting Started
+
+To get started with Couchbase ORM, you'll need to have Ruby and Couchbase Server installed on your system. Once you have the prerequisites in place, you can install the Couchbase ORM gem and start building your application.
+
+In the next section, we'll walk through the installation process and show you how to configure Couchbase ORM to connect to your Couchbase Server instance.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/02-installation.md

@@ -0,0 +1,108 @@
+# Installation
+
+Installing Couchbase ORM is a straightforward process. In this section, we'll guide you through the prerequisites and the step-by-step installation procedure.
+
+## 2.1. Prerequisites
+
+Before installing Couchbase ORM, ensure that you have the following prerequisites in place:
+
+1. **Ruby**: Couchbase ORM requires Ruby version 2.7 or higher. You can check your Ruby version by running the following command in your terminal:
+
+   ```sh
+   ruby -v
+   ```
+
+   If you don't have Ruby installed or your version is older than 2.7, you can install the latest version from the official Ruby website: [https://www.ruby-lang.org](https://www.ruby-lang.org)
+
+2. **Couchbase Server**: Couchbase ORM works with Couchbase Server, a NoSQL database. Make sure you have Couchbase Server installed and running on your system. You can download Couchbase Server from the official website: [https://www.couchbase.com/downloads](https://www.couchbase.com/downloads)
+
+   Follow the installation instructions specific to your operating system to set up Couchbase Server.
+
+3. **Bundler** (optional): Bundler is a dependency management tool for Ruby. While not strictly required, it is recommended to use Bundler to manage your Ruby project's dependencies. You can install Bundler by running the following command:
+
+   ```sh
+   gem install bundler
+   ```
+
+With these prerequisites in place, you're ready to install Couchbase ORM.
+
+## 2.2. Installing Couchbase ORM
+
+To install Couchbase ORM, you have a couple of options:
+
+1. **Using Bundler** (recommended): If you're using Bundler to manage your project's dependencies, add the following line to your `Gemfile`:
+
+   ```ruby
+   gem 'couchbase-orm', git: 'https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm'
+   ```
+
+   Then, run the following command to install the gem:
+
+   ```sh
+   bundle install
+   ```
+
+   Bundler will take care of installing Couchbase ORM and its dependencies.
+
+2. **Using RubyGems**: If you're not using Bundler, you can install Couchbase ORM directly using RubyGems. Run the following command in your terminal:
+
+   ```sh
+   gem install couchbase-orm
+   ```
+
+   This command will download and install the Couchbase ORM gem along with its dependencies.
+
+After the installation is complete, you're ready to configure Couchbase ORM to connect to your Couchbase Server instance.
+
+## 2.3. Configuring Couchbase Connection
+
+To use Couchbase ORM in your Ruby application, you need to configure the connection settings for your Couchbase Server instance. Couchbase ORM provides a simple way to configure the connection.
+
+1. **Rails Applications**:
+
+   If you're using Couchbase ORM in a Rails application, create a new configuration file named `couchbase.yml` in the `config` directory of your Rails project. Add the following content to the file:
+
+   ```yaml
+   development:
+     connection_string: couchbase://localhost
+     bucket: my_app_development
+     username: my_username
+     password: my_password
+
+   test:
+     connection_string: couchbase://localhost
+     bucket: my_app_test
+     username: my_username
+     password: my_password
+
+    production:
+      connection_string: <%= ENV['COUCHBASE_CONNECTION_STRING'] %>
+      bucket: <%= ENV['COUCHBASE_BUCKET'] %>
+      username: <%= ENV['COUCHBASE_USER'] %>
+      password: <%= ENV['COUCHBASE_PASSWORD'] %>
+   ```
+
+   Replace the values for `connection_string`, `bucket`, `username`, and `password` with your actual Couchbase Server connection details.
+
+   Couchbase ORM will automatically load the configuration based on the current Rails environment.
+
+   You can also set the connection details using environment variables in the production environment to avoid storing sensitive information in the source code.
+
+2. **Non-Rails Applications**:
+
+   For non-Rails applications, you can configure the connection settings programmatically. Add the following code to your application's initialization file or before you start using Couchbase ORM:
+
+   ```ruby
+   Couchbase ORM.configure do |config|
+     config.connection_string = 'couchbase://localhost'
+     config.bucket = 'travel-sample'
+     config.username = 'Administrator'
+     config.password = 'password'
+   end
+   ```
+
+   Replace the values for `connection_string`, `bucket`, `username`, and `password` with your actual Couchbase Server connection details.
+
+With the connection configured, you're now ready to start defining your models and interacting with Couchbase Server using Couchbase ORM.
+
+In the next section, we'll explore how to define models in Couchbase ORM and work with the basic CRUD operations.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/03-defining-models.md

@@ -0,0 +1,239 @@
+# Defining Models
+
+In CouchbaseOrm, models are defined as Ruby classes that inherit from `CouchbaseOrm::Base`. Each model represents a document type in Couchbase Server and encapsulates the data and behavior of the objects in your application.
+
+## 3.1. Creating a Model
+
+To create a model, define a new class that inherits from `CouchbaseOrm::Base`. For example, let's create a `User` model:
+
+```ruby
+class User < CouchbaseOrm::Base
+end
+```
+
+By convention, CouchbaseOrm uses the underscored, pluralized name of the class as the document type in Couchbase Server. In this case, the document type for the `User` model would be `users`.
+
+## 3.2. Attribute Types
+
+CouchbaseOrm supports various attribute types to define the structure and types of your model's data. You can specify the attributes of your model using the `attribute` method.
+
+Here's an example of defining attributes in the `User` model:
+
+```ruby
+class User < CouchbaseOrm::Base
+  attribute :email, :string
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :height, :float
+  attribute :is_active, :boolean
+  attribute :birth_date, :date
+  attribute :created_at, :datetime
+  attribute :updated_at, :datetime
+  attribute :appointment_time, :time
+  attribute :hobbies, :array, type: :string
+  attribute :metadata, type: Hash
+  attribute :avatar, :binary
+
+  attribute :created_at, :datetime
+  attribute :updated_at, :datetime
+end
+```
+
+In this example, we define several attributes for the `User` model, each with a specific type. The supported attribute types in CouchbaseOrm include:
+
+- `:string`: Represents a string value.
+- `:integer`: Represents an integer value.
+- `:float`: Represents a floating-point value.
+- `:boolean`: Represents a boolean value.
+- `:date`: Represents a date value.
+- `:datetime`: Represents a date and time value.
+- `:time`: Represents a time value.
+- `:array`: Represents an array of values.
+- `:binary`: Represents a binary data value.
+
+- `Hash`: Represents a hash (dictionary) of key-value pairs.
+
+CouchbaseOrm automatically handles the serialization and deserialization of these attribute types when storing and retrieving documents from Couchbase Server.
+
+## 3.3. Attribute Options
+
+In addition to specifying the attribute type, you can also provide additional options to customize the behavior of the attributes. Some commonly used options include:
+
+- `default`: Specifies a default value for the attribute if no value is provided.
+
+
+Here's an example of using attribute options:
+
+```ruby
+class User < CouchbaseOrm::Base
+  attribute :name, :string, default: 'Unknown'
+end
+```
+
+In this example, the `name` attribute has a default value of `'Unknown'`.
+ <!-- the `email` attribute is aliased as `contact_email` in the document, and the `age` attribute is marked as read-only. -->
+
+## 3.4. Timestamps
+
+CouchbaseOrm provides built-in support for timestamp attributes. By default, if you define attributes named `created_at` and `updated_at` with the `:datetime` type, CouchbaseOrm will automatically populate these attributes with the current date and time when a document is created or updated. To enable this feature, add the `created_at` and `updated_at` attributes to your model.The fields are automatically updated when the document is saved.`document.save`
+
+```ruby
+class User < CouchbaseOrm::Base
+  attribute :created_at, :datetime
+  attribute :updated_at, :datetime
+end
+```
+
+With these timestamp attributes defined, CouchbaseOrm will manage them automatically whenever a document is persisted or updated.
+
+## 3.5. Callbacks
+
+CouchbaseOrm supports lifecycle callbacks that allow you to execute code at certain points in a document's lifecycle. Callbacks can be used to perform actions before or after specific events, such as saving or updating a document.
+
+Here are some commonly used callbacks:
+
+- `before_create`: Runs before a new document is created.
+- `after_create`: Runs after a new document is created.
+- `before_save`: Runs before a document is saved (either created or updated).
+- `after_save`: Runs after a document is saved (either created or updated).
+- `before_update`: Runs before an existing document is updated.
+- `after_update`: Runs after an existing document is updated.
+- `before_destroy`: Runs before a document is destroyed.
+- `after_destroy`: Runs after a document is destroyed.
+
+To define a callback, use the corresponding callback method and provide a block or method name to be executed. For example:
+
+```ruby
+class Document < CouchbaseOrm::Base
+  attribute :title, :string
+  attribute :content, :string
+
+  before_create :before_create_callback
+  after_create :after_create_callback
+  before_save :before_save_callback
+  after_save :after_save_callback
+  before_update :before_update_callback
+  after_update :after_update_callback
+  before_destroy :before_destroy_callback
+  after_destroy :after_destroy_callback
+
+  private
+
+  def before_create_callback
+    puts "Running before_create callback for #{title}"
+  end
+
+  def after_create_callback
+    puts "Running after_create callback for #{title}"
+  end
+
+  def before_save_callback
+    puts "Running before_save callback for #{title}"
+  end
+
+  def after_save_callback
+    puts "Running after_save callback for #{title}"
+  end
+
+  def before_update_callback
+    puts "Running before_update callback for #{title}"
+  end
+
+  def after_update_callback
+    puts "Running after_update callback for #{title}"
+  end
+
+  def before_destroy_callback
+    puts "Running before_destroy callback for #{title}"
+  end
+
+  def after_destroy_callback
+    puts "Running after_destroy callback for #{title}"
+  end
+end
+```
+
+In this example, the `Document` model defines several callbacks that are triggered at different points in the document's lifecycle. The callback methods are implemented as private instance methods within the model class.
+
+Callbacks allow you to encapsulate logic related to the document lifecycle and maintain a clean and organized codebase.
+
+## 3.6. Validations
+
+CouchbaseOrm includes built-in validation capabilities to ensure the integrity and validity of your data before persisting it to Couchbase Server. Validations help you enforce business rules and constraints on your models.
+
+To define validations, use the `validates` method followed by the attribute name and the desired validation rules. For example:
+
+```ruby
+class Book < CouchbaseOrm::Base
+  attribute :title, :string
+  attribute :author, :string
+  attribute :pages, :integer
+  attribute :genre, :string
+  attribute :email, :string
+
+  validates_presence_of :title
+  validates :author, presence: true
+  validates :pages, numericality: { greater_than: 0 }
+  validates :genre, inclusion: { in: %w[Fiction Non-Fiction] }
+  validates :author, format: { with: /\A[a-zA-Z]+\z/, message: 'only allows letters' }
+  validates :pages, length: { maximum: 500 }
+  validates :genre, exclusion: { in: %w[Science-Fiction] }
+  validates :email, format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
+
+  validate :custom_validation
+
+  private
+
+  ...
+end
+```
+
+In this example, we define several validations for the `User` model:
+
+- The `name` attribute must be present.
+- The `email` attribute must match a specific format (a valid email address).
+- The `age` attribute must be a number greater than or equal to 18.
+
+CouchbaseOrm provides a wide range of built-in validation helpers, such as:
+
+- `presence`: Ensures that the attribute is not blank.
+- `validates_presence_of`: An alias for `presence`.
+<!-- - `uniqueness`: Ensures that the attribute value is unique among all documents. -->
+- `format`: Validates the attribute value against a regular expression.
+- `length`: Validates the length of the attribute value.
+- `numericality`: Validates that the attribute value is a valid number.
+- `inclusion`: Ensures that the attribute value is included in a given set.
+- `exclusion`: Ensures that the attribute value is not included in a given set.
+
+
+You can also define custom validation methods by adding methods to your model class and using the `validate` method to trigger them. For example:
+
+```ruby
+class Book < CouchbaseOrm::Base
+  attribute :title, :string
+  ...
+
+  validate :custom_validation
+
+  private
+
+  def custom_validation
+    puts 'Running custom validation...'
+    if title&.include?('Funny')
+      errors.add(:title, 'should not contain the word "Funny"')
+    else
+      # print the title
+      puts "Title: #{title}"
+      puts 'Custom validation passed'
+    end
+  end
+end
+```
+
+In this example, the `custom_validation` method is called during the validation process, and if `some_condition` is met, an error is added to the model's `errors` collection.
+
+Validations are automatically run when saving a document. If any validations fail, the save operation will be aborted, and the model's `errors` collection will contain the validation error messages.
+
+By leveraging validations, you can ensure the quality and consistency of your data before it is persisted to Couchbase Server.
+
+With the model definition covered, including attributes, callbacks, and validations, you're ready to start querying and persisting data using CouchbaseOrm. In the next section, we'll explore the querying capabilities of CouchbaseOrm and how to retrieve data from Couchbase Server efficiently.