couchbase-orm 2.0.4 → 2.0.6

data/docusaurus/docs/tutorial-ruby-couchbase-orm/08-views.md

@@ -0,0 +1,158 @@
+# Views (aka Map/Reduce indexes)
+
+Views are a powerful feature in Couchbase that allow you to define map functions to extract and emit specific data from your documents. The Ruby Couchbase ORM provides a convenient way to define and query views within your Ruby application.
+
+## 8.1 Defining Views
+
+To define a view in your Ruby Couchbase ORM model, you can use the `view` method followed by the view name and options. Here's an example:
+
+```ruby
+class Factory < CouchbaseOrm::Base
+  attribute :name, type: String
+  attribute :location, type: String
+  attribute :established_year, type: Integer
+  attribute :active, type: Boolean
+
+  view :by_name, emit_key: :name
+  view :by_location, emit_key: :location
+  view :by_established_year, emit_key: :established_year
+  view :by_active, emit_key: :active
+end
+```
+
+In this example, we define four views for the `Factory` model:
+- `by_name`: Emits the `name` attribute as the key.
+- `by_location`: Emits the `location` attribute as the key.
+- `by_established_year`: Emits the `established_year` attribute as the key.
+- `by_active`: Emits the `active` attribute as the key.
+
+The `emit_key` option specifies the attribute to use as the key for the view.
+
+## 8.2 Custom Map Functions
+
+You can also define custom map functions for your views using the `map` option. This allows you to emit custom keys and values based on your specific requirements. Here's an example:
+
+```ruby
+view :by_name_and_location,
+  map: %{
+    function(doc) {
+      if (doc.type === "factory") {
+        emit([doc.name, doc.location], null);
+      }
+    }
+  }
+```
+
+In this example, we define a view named `by_name_and_location` that emits a composite key consisting of the `name` and `location` attributes.
+
+## 8.3 Querying Views
+
+Once you have defined your views, you can query them using the corresponding view methods. The view methods are automatically generated based on the view names. Here are some examples:
+
+```ruby
+# Query factories by name
+Factory.by_name(key: 'Factory A').each do |factory|
+  puts "- #{factory.name}"
+end
+
+# Query factories by location
+Factory.by_location(key: 'City X').each do |factory|
+  puts "- #{factory.name}"
+end
+
+# Query factories by established year
+Factory.by_established_year(key: 2010).each do |factory|
+  puts "- #{factory.name}"
+end
+
+# Query active factories
+Factory.by_active(key: true).each do |factory|
+  puts "- #{factory.name}"
+end
+```
+
+These examples demonstrate how to query views based on specific keys using the generated view methods.
+
+## 8.4 Indexing Views
+
+In this section, let's explore the `index_view` function and the methods it generates for the `location` attribute.
+
+Here's an updated version of the `Factory` model using `index_view` for the `location` attribute:
+
+```ruby
+class Factory < CouchbaseOrm::Base
+  attribute :name, type: String
+  attribute :location, type: String
+  attribute :established_year, type: Integer
+  attribute :active, type: Boolean
+
+  view :by_name, emit_key: :name
+  index_view :location
+  view :by_established_year, emit_key: :established_year
+  view :by_active, emit_key: :active
+
+  view :by_name_and_location,
+    map: %{
+      function(doc) {
+        if (doc.type === "factory") {
+          emit([doc.name, doc.location], null);
+        }
+      }
+    }
+
+  view :by_established_year_range,
+    map: %{
+      function(doc) {
+        if (doc.type === "factory" && doc.established_year) {
+          emit(doc.established_year, null);
+        }
+      }
+    }
+end
+```
+
+In this updated code, we replaced `view :by_location, emit_key: :location` with `index_view :location`. The `index_view` function generates two methods for querying based on the `location` attribute:
+
+1. `find_by_location(location)`: This method allows you to find factories by a specific location. It returns an array of factories that match the given location.
+
+2. `by_location(key: location)`: This method is similar to `find_by_location` but returns a `CouchbaseOrm::ResultsProxy` object, which provides an enumerable interface to access the view results.
+
+Now, let's see how we can use these generated methods to query factories by location:
+
+```ruby
+# Find factories by location using find_by_location
+factories = Factory.find_by_location('City X')
+factories.each do |factory|
+  puts "- #{factory.name} (#{factory.location})"
+end
+
+# Find factories by location using by_location
+Factory.by_location(key: 'City X').each do |factory|
+  puts "- #{factory.name} (#{factory.location})"
+end
+```
+
+Both `find_by_location` and `by_location` achieve the same result of finding factories by a specific location. The difference is that `find_by_location` returns an array of factories directly, while `by_location` returns a `CouchbaseOrm::ResultsProxy` object that you can further chain or iterate over.
+
+Using `index_view` provides a convenient way to generate commonly used query methods for a specific attribute. It simplifies the process of querying based on that attribute and enhances the readability of your code.
+
+<!-- ## 8.5 Range Queries (Experimental)
+
+You can perform range queries on views by specifying the `startkey` and `endkey` options. Here's an example:
+
+```ruby
+# Query factories established between 2005 and 2015
+Factory.by_established_year_range(startkey: 2005, endkey: 2015).each do |factory|
+  puts "- #{factory.name} (#{factory.established_year})"
+end
+```
+
+In this example, we query the `by_established_year_range` view to retrieve factories established between 2005 and 2015. -->
+
+## 8.5 Conclusion
+
+Views in the Ruby Couchbase ORM provide a powerful way to define and query data based on specific attributes and custom map functions. By defining views, you can easily retrieve subsets of your data and perform efficient queries based on your application's requirements.
+
+Remember to ensure that your design documents are up to date by calling `ensure_design_document!` on your models before running queries.
+
+With the flexibility and ease of use provided by the Ruby Couchbase ORM's view functionality, you can efficiently query and retrieve data from your Couchbase database.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/09-nested-documents.md

@@ -0,0 +1,138 @@
+# Nested Documents
+
+CouchbaseOrm supports nested documents, which allow you to store complex, hierarchical data structures within a single Couchbase document. Nested documents are useful when you have related data that you want to store together with the parent document for performance or consistency reasons.
+
+## 9.1. Defining Nested Documents
+
+To define an nested document, you create a new class that inherits from `CouchbaseOrm::NestedDocument`.
+
+```ruby
+class Part < CouchbaseOrm::NestedDocument
+  attribute :name, :string
+  attribute :manufacturer, :string
+end
+
+# Define the Car model with a nested Part document
+class Car < CouchbaseOrm::Base
+  attribute :make, :string
+  attribute :model, :string
+  attribute :year, :integer
+  attribute :parts, :array, type: Part
+
+  validates :make, presence: true
+  validates :model, presence: true
+  validates :year, presence: true
+end
+
+```
+
+In this example, we define a `Car` model with a nested `Part` document. The `Part` class inherits from `CouchbaseOrm::NestedDocument` and defines attributes for `name` and `manufacturer`. The `Car` model has an `parts` attribute that is an array of `Part` nested documents.
+
+## 9.2. Embedding Documents
+
+To embed a document within a parent document, you can assign an instance of the nested document class to the corresponding attribute.
+
+```ruby
+# Create a new car with nested parts
+car = Car.new(
+  make: 'Toyota',
+  model: 'Corolla',
+  year: 2022,
+  parts: [
+    Part.new(name: 'Engine', manufacturer: 'Toyota Motors'),
+    Part.new(name: 'Transmission', manufacturer: 'Toyota Motors')
+  ]
+)
+car.save
+```
+
+When saving the parent document (`Car`), CouchbaseOrm serializes the nested `Part` documents and stores them within the parent document. This allows you to retrieve the entire data structure with a single query.
+
+## 9.3. Accessing Nested Documents
+
+To access an nested document, you can simply call the corresponding attribute on the parent document.
+
+```ruby
+toyota_cars = Car.where(make: 'Toyota')
+```
+
+CouchbaseOrm automatically deserializes the nested document and returns an instance of the nested document class.
+
+## 9.4. Updating Nested Documents
+
+To update an nested document, you can modify the attributes of the nested document instance and save the parent document.
+
+```ruby
+engine_part = car.parts.find { |part| part.name == 'Engine' }
+engine_part.manufacturer = 'Toyota Industries'
+car.save
+```
+
+CouchbaseOrm will serialize the updated nested document and save it along with the parent document.
+
+## 9.5. Embedding Multiple Documents
+
+You can also embed multiple documents within a parent document using an array attribute.
+
+```ruby
+car = Car.new(
+  make: 'Toyota',
+  model: 'Corolla',
+  year: 2022,
+  parts: [
+    Part.new(name: 'Engine', manufacturer: 'Toyota Motors'),
+    Part.new(name: 'Transmission', manufacturer: 'Toyota Motors')
+  ]
+)
+car.save
+```
+
+In this example, the `Car` model has an `parts` attribute that is an array of `Part` nested documents. You can embed multiple `Part` documents within a single `Car` document, allowing you to store related data together.
+
+## 9.6. Querying Nested Documents
+
+CouchbaseOrm allows you to query nested documents using dot notation and attribute conditions.
+
+```ruby
+cars_by_part_manufacturer = Car.where("ANY part IN parts SATISFIES part.manufacturer = 'Toyota Industries' END")
+```
+
+This query retrieves all the `Car` documents where at least one `Part` document has a `manufacturer` attribute equal to `'Toyota Industries'`. You can use dot notation to access nested document attributes within the query condition.
+
+## 9.7. Validating Nested Documents
+
+CouchbaseOrm allows you to validate nested documents along with the parent document.
+
+```ruby
+class Part < CouchbaseOrm::NestedDocument
+  attribute :name, :string
+  attribute :manufacturer, :string
+
+  validates :name, presence: true
+  validates :manufacturer, presence: true
+end
+
+class Car < CouchbaseOrm::Base
+  attribute :make, :string
+  attribute :model, :string
+  attribute :year, :integer
+  attribute :parts, :array, type: Part
+
+  validates :make, presence: true
+  validates :model, presence: true
+  validates :year, presence: true
+  validates :parts, presence: true
+end
+
+
+```
+
+In this example, we define validations for the `Part` nested document, ensuring that the `name` and `manufacturer` attributes are present. We also add validations to the `Car` model to ensure that the `make`, `model`, `year`, and `parts` attributes are present.
+
+When saving a `Car` document, CouchbaseOrm will validate both the parent document and the nested `Part` documents. If any validation fails, the parent document will not be saved, and validation errors will be added to the parent document.
+
+Nested documents provide a powerful way to model complex data structures and relationships within a single Couchbase document. They allow you to store related data together, improving performance and reducing the need for separate queries to retrieve associated data.
+
+However, it's important to consider the trade-offs when using nested documents. Embedding too much data within a single document can lead to large document sizes and potential performance issues. It's recommended to use nested documents judiciously and to consider the access patterns and data relationships of your application.
+
+In the next section, we'll explore enums in CouchbaseOrm and how they can be used to define a fixed set of values for an attribute.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/10-enums.md

@@ -0,0 +1,91 @@
+# Enums
+
+CouchbaseOrm provides support for enums, which allow you to define a fixed set of values for an attribute. Enums are useful when you have a limited number of possible values for a particular attribute and want to ensure data consistency and validity.
+
+## 10.1. Defining Enums
+
+To define an enum in your model, you can use the `enum` class method provided by CouchbaseOrm.
+
+```ruby
+class User < CouchbaseOrm::Base
+  enum status: [:active, :inactive, :suspended]
+end
+```
+
+In this example, we define an enum named `status` for the `User` model. The enum has three possible values: `:active`, `:inactive`, and `:suspended`.
+
+## 10.2. Using Enums
+
+You can assign enum values to an attribute using the generated methods or by directly assigning the value.
+
+```ruby
+user = User.new
+user.status = :active
+user.save
+
+user.suspended!
+user.save
+
+puts user.status  # Output: "suspended"
+```
+
+In this example, we create a new `User` instance and set the `status` to `:active` using the direct assignment. We then change the `status` to `:suspended` using the generated `suspended!` method.
+
+## 10.3. Querying by Enums
+
+CouchbaseOrm allows you to query records based on their enum values.
+
+```ruby
+active_users = User.where(status: 1)
+suspended_users = User.where(status: 3)
+```
+
+These queries retrieve users with the `status` enum set to `:active` and `:suspended`, respectively.
+
+## 10.4. Enum Mapping
+
+Behind the scenes, CouchbaseOrm maps the enum values to integers for storage in the database. By default, the mapping starts from 0 and increments by 1 for each enum value in the order they are defined.
+
+However, you can customize the mapping by providing a hash of enum values and their corresponding integer values.
+
+```ruby
+class User < CouchbaseOrm::Base
+  enum status: { active: 1, inactive: 2, suspended: 3 }
+end
+```
+
+In this example, we explicitly define the mapping of enum values to integers. The `:active` value is mapped to 1, `:inactive` to 2, and `:suspended` to 3.
+
+## 10.5. Enum Validation
+
+CouchbaseOrm automatically validates that the assigned enum value is one of the defined values for the enum.
+
+```ruby
+user = User.new
+user.status = :invalid
+user.save # Raises an error: "Invalid enum value: :invalid"
+```
+
+If you try to assign an invalid value to an enum attribute, CouchbaseOrm will raise an error indicating that the value is not a valid enum value.
+
+## 10.6. Enum Defaults
+
+You can specify a default value for an enum attribute using the `default` option.
+
+```ruby
+class User < CouchbaseOrm::Base
+  enum status: [:active, :inactive, :suspended], default: :active
+end
+```
+
+In this example, if no value is assigned to the `status` attribute when creating a new `User` instance, the default value of `:active` will be used.
+
+Enums in CouchbaseOrm provide a convenient way to define a fixed set of values for an attribute. They help ensure data consistency, improve code readability, and simplify querying and validation.
+
+When using enums, consider the following:
+
+- Enums are stored as integers in the database, so be cautious when changing the order or removing enum values, as it may affect existing records.
+- Enums are case-sensitive, so `:active` and `:Active` are considered different values.
+- Enums can be used in combination with other attribute types, such as `default` and `validates`, to further customize the behavior of the attribute.
+
+In the next section, we'll explore how to use encryption in CouchbaseOrm to secure sensitive data stored in your Couchbase documents.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/11-encryption.md

@@ -0,0 +1,202 @@
+# Encryption
+
+CouchbaseOrm provides built-in support for storing encrypted data in your Couchbase documents using a structured format. The `:encrypted` type provides a standardized storage format compatible with Couchbase Lite's field-level encryption, but **does not perform encryption/decryption itself**. Your application is responsible for encrypting data before storing it and decrypting it after retrieval.
+
+## 11.1. Encrypted Attributes
+
+To mark an attribute as encrypted, you can use the `:encrypted` type when defining the attribute in your model.
+
+```ruby
+# Define the Bank model with encrypted attributes
+class Bank < CouchbaseOrm::Base
+  attribute :name, :string
+  attribute :account_number, :encrypted
+  attribute :routing_number, :encrypted, alg: "3DES"
+end
+```
+
+In this example, the `account_number` and `routing_number` attributes are marked as encrypted. The `alg` option specifies the encryption algorithm identifier that will be stored in the document metadata (default is `"CB_MOBILE_CUSTOM"`). This identifier is for documentation purposes and Couchbase Lite compatibility - CouchbaseOrm does not use it for actual encryption.
+
+```plaintext
+{
+  "name": "Test Bank",
+  "encrypted$account_number": {
+    "alg": "CB_MOBILE_CUSTOM",
+    "ciphertext": "MTIzNDU2Nzg5"
+  },
+  "encrypted$routing_number": {
+    "alg": "3DES",
+    "ciphertext": "OTg3NjU0MzIx"
+  },
+  "type": "bank"
+}
+```
+
+When a document is saved, CouchbaseOrm stores encrypted attributes in the document with a prefix of `encrypted$`. The values are stored as JSON objects containing the encryption algorithm identifier (`alg`) and the ciphertext (`ciphertext`).
+
+**Important**: You must provide **pre-encrypted** values to encrypted attributes. CouchbaseOrm stores these values as-is in the `ciphertext` field without performing any encryption.
+
+```ruby
+# You must encrypt the data BEFORE assigning it to the attribute
+require 'base64'
+
+# Assuming you have an encryption method (e.g., AES, Tanker, etc.)
+encrypted_account = MyEncryptor.encrypt('123456789')
+encrypted_routing = MyEncryptor.encrypt('987654321')
+
+# Values must be Base64-encoded strings
+bank = Bank.new(
+  name: 'My Bank',
+  account_number: Base64.strict_encode64(encrypted_account),
+  routing_number: Base64.strict_encode64(encrypted_routing)
+)
+```
+
+## 11.2. Complete Example with Encryption
+
+Here's a complete example showing how to handle encryption in your application:
+
+```ruby
+require 'base64'
+require 'openssl'
+
+# Example encryption helper (you should use a proper encryption library)
+class SimpleEncryptor
+  def self.encrypt(plaintext)
+    # This is a simplified example - use a proper encryption library in production
+    cipher = OpenSSL::Cipher.new('AES-256-CBC')
+    cipher.encrypt
+    cipher.key = ENV['ENCRYPTION_KEY'] # Store securely, never commit to git
+    cipher.iv = iv = cipher.random_iv
+
+    encrypted = cipher.update(plaintext) + cipher.final
+    # Prepend IV for decryption (in real implementation, handle this properly)
+    iv + encrypted
+  end
+
+  def self.decrypt(ciphertext_with_iv)
+    cipher = OpenSSL::Cipher.new('AES-256-CBC')
+    cipher.decrypt
+    cipher.key = ENV['ENCRYPTION_KEY']
+
+    # Extract IV and ciphertext
+    iv = ciphertext_with_iv[0..15]
+    ciphertext = ciphertext_with_iv[16..]
+
+    cipher.iv = iv
+    cipher.update(ciphertext) + cipher.final
+  end
+end
+
+# Create a bank record with encrypted attributes
+plaintext_account = "123456789"
+plaintext_routing = "987654321"
+
+# 1. Encrypt the sensitive data
+encrypted_account = SimpleEncryptor.encrypt(plaintext_account)
+encrypted_routing = SimpleEncryptor.encrypt(plaintext_routing)
+
+# 2. Encode as Base64 for storage
+bank = Bank.new(
+  name: "Test Bank",
+  account_number: Base64.strict_encode64(encrypted_account),
+  routing_number: Base64.strict_encode64(encrypted_routing)
+)
+
+# 3. Save to Couchbase
+bank.save!
+
+# 4. Retrieve and decrypt
+found_bank = Bank.find(bank.id)
+
+# 5. Decode Base64 and decrypt
+account_encrypted = Base64.strict_decode64(found_bank.account_number)
+routing_encrypted = Base64.strict_decode64(found_bank.routing_number)
+
+decrypted_account = SimpleEncryptor.decrypt(account_encrypted)
+decrypted_routing = SimpleEncryptor.decrypt(routing_encrypted)
+
+puts "Decrypted account: #{decrypted_account}"  # => "123456789"
+puts "Decrypted routing: #{decrypted_routing}"  # => "987654321"
+```
+
+## 11.3. Storage Format
+
+CouchbaseOrm handles the storage format for encrypted attributes but does not perform encryption/decryption. Here's what happens:
+
+**When saving:**
+1. You assign a Base64-encoded ciphertext to the encrypted attribute
+2. CouchbaseOrm wraps it in the `encrypted$` format with `alg` and `ciphertext` fields
+3. The document is stored in Couchbase with this structure
+
+**When loading:**
+1. CouchbaseOrm reads the document from Couchbase
+2. It unwraps the `encrypted$` format and extracts the `ciphertext` value
+3. The Base64-encoded ciphertext is assigned to the attribute
+4. Your application must decode and decrypt the value
+
+**Key Points:**
+- CouchbaseOrm does **not** require or use any encryption key
+- The `alg` field is purely informational (for compatibility with Couchbase Lite)
+- All actual encryption/decryption is your application's responsibility
+- Values must be valid Base64-encoded strings
+
+## 11.4. Considerations and Best Practices
+
+When using encrypted attributes in CouchbaseOrm, consider the following best practices:
+
+### Security
+- **Encryption is your responsibility**: CouchbaseOrm only provides the storage format. Choose a robust encryption library (e.g., `rbnacl`, `openssl`, or a service like AWS KMS)
+- **Key management**: Store encryption keys securely using environment variables, secret managers (AWS Secrets Manager, HashiCorp Vault), or key management services
+- **Never commit keys**: Keep encryption keys out of version control systems
+- **Key rotation**: Implement a key rotation strategy and maintain the ability to decrypt data encrypted with old keys
+- **Use authenticated encryption**: Prefer AEAD modes (like AES-GCM) that provide both confidentiality and integrity
+
+### Performance and Querying
+- **Cannot query encrypted fields**: Encrypted attributes cannot be used in WHERE clauses or indexed effectively
+- **Consider searchable encryption**: If you need to search encrypted data, investigate specialized solutions like searchable encryption schemes or external encrypted search indexes
+- **Selective encryption**: Only encrypt truly sensitive fields to minimize performance overhead
+
+### Implementation Patterns
+- **Wrap in accessors**: Create getter/setter methods that automatically handle encryption/decryption:
+  ```ruby
+  class Bank < CouchbaseOrm::Base
+    attribute :account_number, :encrypted
+
+    def account_number=(plaintext)
+      encrypted = MyEncryptor.encrypt(plaintext)
+      super(Base64.strict_encode64(encrypted))
+    end
+
+    def account_number
+      encrypted = Base64.strict_decode64(super)
+      MyEncryptor.decrypt(encrypted)
+    end
+  end
+  ```
+
+- **Separate concerns**: Consider using a concern or module to encapsulate encryption logic:
+  ```ruby
+  module EncryptedAttributes
+    def encrypted_attribute(name)
+      define_method("#{name}=") do |plaintext|
+        encrypted = MyEncryptor.encrypt(plaintext)
+        super(Base64.strict_encode64(encrypted))
+      end
+
+      define_method(name) do
+        encrypted = Base64.strict_decode64(super())
+        MyEncryptor.decrypt(encrypted)
+      end
+    end
+  end
+  ```
+
+### Compatibility
+- The `encrypted$` format is compatible with Couchbase Lite's field-level encryption
+- The `alg` field helps document which encryption algorithm was used, aiding in key rotation and auditing
+- Ensure your encryption implementation is compatible across all platforms that access the data (web, mobile, etc.)
+
+Encryption is a powerful tool for protecting sensitive data, but it should be used judiciously. Focus on encrypting the most sensitive and confidential data while balancing the trade-offs between security, performance, and functionality.
+
+In the next section, we'll explore logging in CouchbaseOrm and how you can configure and customize logging to monitor and debug your application.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/12-logging.md

@@ -0,0 +1,48 @@
+# Logging
+
+CouchbaseOrm provides a logging mechanism to help you monitor and debug your application. Logging allows you to capture important events, errors, and information during the execution of your application. CouchbaseOrm integrates with the logging framework used in your Ruby application, such as the built-in `Logger` class or third-party logging libraries.
+
+
+## 12.1. Log Levels
+
+CouchbaseOrm supports different log levels to control the verbosity of the logged messages. The available log levels, in increasing order of severity, are:
+
+- `DEBUG`: Detailed information, typically of interest only when diagnosing problems.
+- `INFO`: Confirmation that things are working as expected.
+- `WARN`: An indication that something unexpected happened or indicative of some problem in the near future.
+- `ERROR`: Due to a more serious problem, the software has not been able to perform some function.
+- `FATAL`: A serious error, indicating that the program itself may be unable to continue running.
+
+By default, CouchbaseOrm logs messages at the `INFO` level and above. You can change the log level by exporting the `COUCHBASE_ORM_DEBUG` environment variable with the desired log level. For example, to set the log level to `DEBUG`, you can run:
+
+```bash
+export COUCHBASE_ORM_DEBUG=Logger::DEBUG
+```
+
+This command sets the log level to `DEBUG`, which will log detailed information for debugging purposes.
+
+```ruby
+require_relative "app"
+
+# Create a new user
+user = User.new(name: 'John Doe', email: 'john@example.com')
+user.save
+
+# Update the user's email
+user.email = 'john.doe@example.com'
+user.save
+
+# Log a custom message
+CouchbaseOrm.logger.info "User #{user.id} updated email to #{user.email}"
+```
+
+In this example, we create a new `User` instance, save it to the database, update the user's email, and log a custom message using the `CouchbaseOrm.logger` object. The log message includes the user's ID and the updated email address.
+
+Output:
+```
+D, [2024-05-24T11:48:00.071104 #234447] DEBUG -- : Initialize model  with {:name=>"John Doe", :email=>"john@example.com"}
+D, [2024-05-24T11:48:00.086972 #234447] DEBUG -- : _create_record - Upsert user-1-vncZNSYZj {"id"=>"user-1-vncZNSYZj", "email"=>"john@example.com", "name"=>"John Doe", "age"=>nil, "height"=>nil, "is_active"=>nil, "birth_date"=>nil, "created_at"=>"2024-05-24T06:18:00Z", "updated_at"=>"2024...
+D, [2024-05-24T11:48:00.113166 #234447] DEBUG -- : _update_record - replace user-1-vncZNSYZj {"id"=>"user-1-vncZNSYZj", "email"=>"john.doe@example.com", "name"=>"John Doe", "age"=>nil, "height"=>nil, "is_active"=>nil, "birth_date"=>nil, "created_at"=>"2024-05-24T06:18:00Z", "updated_at"=>"...
+I, [2024-05-24T11:48:00.115239 #234447]  INFO -- : User user-1-vncZNSYZj updated email to john.doe@example.com
+```
+

data/docusaurus/docs/tutorial-ruby-couchbase-orm/13-troubleshooting.md

@@ -0,0 +1,41 @@
+# Troubleshooting
+
+When working with CouchbaseOrm, you may encounter various issues or errors. In this section, we'll discuss common problems and provide troubleshooting tips to help you identify and resolve these issues effectively.
+
+## 15.1. Common Issues
+
+Here are some common issues you may encounter while using CouchbaseOrm:
+
+1. **Connection Errors**: If you experience connection errors, such as "Failed to connect to Couchbase server," ensure that your Couchbase Server is running and accessible. Verify that the connection details in your configuration file are correct, including the hostname, port, bucket name, username, and password.
+
+2. **Document Not Found**: If you receive a "Document not found" error when retrieving a document, double-check that the document ID is correct and exists in the Couchbase bucket. Make sure you haven't accidentally deleted or modified the document.
+
+3. **N1QL Query Errors**: If your N1QL queries are not returning the expected results or throwing errors, check the syntax of your queries. Ensure that you are using the correct bucket name, index names, and attribute names. Verify that the appropriate indexes are created and available for the queried attributes.
+
+4. **Validation Errors**: If you encounter validation errors when saving a document, review your model's validation rules and make sure the document attributes satisfy those rules. Check for presence, uniqueness, format, and other validation constraints.
+
+5. **Unexpected Behavior**: If you experience unexpected behavior or results, double-check your code logic, query conditions, and attribute assignments. Ensure that you are using the correct methods, parameters, and data types.
+
+## 15.2. Debugging Tips
+
+When troubleshooting issues with CouchbaseOrm, consider the following debugging tips:
+
+1. **Enable Logging**: CouchbaseOrm provides logging functionality to help you track the execution flow and identify issues. Enable logging in your application and set the log level to an appropriate verbosity. Review the log output for any error messages, stacktraces, or unexpected behavior.
+
+2. **Inspect Couchbase Server**: Use the Couchbase Web Console or command-line tools to inspect your Couchbase Server instance. Check the bucket details, document contents, and index definitions to ensure they align with your application's expectations.
+
+3. **Use Debugging Tools**: Utilize debugging tools like `byebug` or `pry` to pause the execution of your code at specific points and inspect variable values, object states, and method invocations. Set breakpoints in your code to step through the execution flow and identify the source of the issue.
+
+4. **Test in Isolation**: Isolate the problematic code or query and test it in a separate environment or script. This allows you to focus on the specific issue without the complexity of the entire application. Create a minimal reproducible example that demonstrates the problem.
+
+5. **Verify Couchbase Server Version**: Ensure that you are using a compatible version of Couchbase Server with CouchbaseOrm. Check the CouchbaseOrm documentation for version compatibility and make sure your server version meets the requirements.
+
+6. **Consult Documentation and Community**: Refer to the CouchbaseOrm documentation, API reference, and guides for detailed information on how to use specific features and resolve common issues. Engage with the CouchbaseOrm community through forums, chat channels, or mailing lists to seek assistance from experienced users and developers.
+
+7. **Reproduce and Report**: If you encounter a bug or an issue that seems to be related to CouchbaseOrm itself, try to reproduce the problem in a isolated environment. If the issue persists, consider reporting it to the CouchbaseOrm maintainers or filing an issue on the project's issue tracker, providing detailed information about the problem, steps to reproduce it, and any relevant code snippets or error messages.
+
+Remember, troubleshooting is an iterative process. Start by isolating the problem, gathering relevant information, and systematically eliminating possible causes. Break down the issue into smaller components and test each component independently to narrow down the root cause.
+
+If you are unable to resolve the issue on your own, don't hesitate to seek help from the CouchbaseOrm community or reach out to the project maintainers for assistance. Providing clear and detailed information about the problem, along with any relevant code snippets and error messages, will help others understand and provide more accurate guidance.
+
+By following these troubleshooting tips and leveraging the available resources, you can effectively diagnose and resolve issues encountered while working with CouchbaseOrm.