couchbase-orm 3.0.3 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87ca9e5d5883671444a8c9d6a9fec5191da2d44818b8f95e0511cb379715d4d3
-  data.tar.gz: ea7e8e4fe8586958f478a0ac004719b1c4d2c873fa1168974900cd33859e1479
+  metadata.gz: 253e0ee05a3522f641294d615724214c6b03ebfd189f008544e9a41f0e671916
+  data.tar.gz: 7628e1f89db8f7649dd6795145b238a06af87cb1901e30337670c3f15b87378c
 SHA512:
-  metadata.gz: 11e6a97c5f7b08549ce024a0a406d131fab9934efffa9bd410a7328f23bd39d55620b5e6ddc81c257bb78295804c3abaabd80cee41395e35b87d3b2cf902af34
-  data.tar.gz: be34bdf6a52ade5558ec6fb50c07570f694731bd422c34d135a0560ae2f14f86c10a5e4bd7226964636d9a6f04ccd7a763d68e231042f6750df390079f3b5b31
+  metadata.gz: af199f51fb0fd808ac4920ca8eb16d50b8d6afa89a23cd311d5e39e92df87f93914368267afd373e7d8d282e50e517b892039008f3a2d234ef5bf1ea2b63bb83
+  data.tar.gz: b0703729ad90b504026467377aecdeaed17434010f044ede50d0645ef1e51d9dadef595c31ad1f1990d7366ba7f4101c934c716f4f8cb2152a70d0f846ad7e88

data/.github/workflows/test.yml

@@ -20,23 +20,15 @@ jobs:
           - ruby: '3.3'
             active-model: '7.2'
             couchbase: '7.2.3'
-          - ruby: '3.2'
-            active-model: '7.2.0'
-            couchbase: '7.1.1'
-          - ruby: '3.2'
-            active-model: '7.1.0'
-            couchbase: '6.6.5'
-          - ruby: '3.1'
-            active-model: '7.1.0'
-            couchbase: '7.1.0'
       fail-fast: false
     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 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
+    - run: |
+        sudo apt-get update
+        sudo apt-get install -y libevent-dev libev-dev python3-httplib2
+        sudo apt-get install -y libtinfo5 || sudo apt-get install -y libtinfo6
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}

data/couchbase-orm.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |gem|
   gem.summary = 'Couchbase ORM for Rails'
   gem.description = 'A Couchbase ORM for Rails'
 
-  gem.required_ruby_version = '>= 3.1.0'
+  gem.required_ruby_version = '>= 3.3.0'
   gem.require_paths = ['lib']
 
   gem.add_runtime_dependency 'activemodel', ENV['ACTIVE_MODEL_VERSION'] || '>= 7.1'

data/docusaurus/docs/tutorial-ruby-couchbase-orm/07-sqlpp-queries.md

@@ -147,6 +147,47 @@ docs = N1QLTest.by_custom_rating_values(key: [[1, 2]]).collect { |ob| ob.name }
 
 In the above examples, the `collect` method is used to extract the `name` attribute from each document in the result set.
 
+## 7.8 Prepared Statement Plan Caching
+
+Couchbase Server can cache the query execution plan for a SQL++ query so that subsequent executions skip the planning step. This is controlled by the `adhoc` query option: `adhoc: false` tells the server to prepare and cache the plan on first execution and reuse it on subsequent ones.
+
+### Default behaviour
+
+By default CouchbaseOrm runs queries with `adhoc: true` (the Couchbase SDK default), meaning no plan caching. This preserves the existing behaviour — you opt into plan caching explicitly.
+
+### Enabling caching for a specific call
+
+Pass `adhoc: false` directly to the query method to prepare and cache the plan (useful for frequently repeated queries):
+
+```ruby
+# Cache the plan for this query
+N1QLTest.by_rating(key: 1, adhoc: false)
+
+# Relation query with plan caching
+User.where(country: 'FR').with(adhoc: false).to_a
+```
+
+### Enabling caching for a specific `n1ql` definition
+
+Set `adhoc: false` in the macro options to always cache the plan for that particular query:
+
+```ruby
+n1ql :by_stable_filter, emit_key: [:name], adhoc: false
+```
+
+### Changing the global default
+
+Override the thread-local config to change the default for all queries in the current thread:
+
+```ruby
+# Enable plan caching for all queries in this thread
+CouchbaseOrm::N1ql.config(adhoc: false)
+```
+
+### Override priority
+
+From highest to lowest: **per-call kwarg** > **per-`n1ql`-definition option** > **`N1ql.config`** > **default (`true`)**.
+
 ## 7.7 Indexing for SQL++
 
 To optimize the performance of SQL++ queries, it's important to create appropriate indexes on the fields used in the query conditions. Couchbase Server provides a way to create indexes using the Index service.

data/lib/couchbase-orm/n1ql.rb

@@ -9,6 +9,7 @@ module CouchbaseOrm
         extend ActiveSupport::Concern
         NO_VALUE = :no_value_specified
         DEFAULT_SCAN_CONSISTENCY = :request_plus
+        DEFAULT_ADHOC = true
         # sanitize for injection query
         def self.sanitize(value)
             if value.is_a?(String)
@@ -22,9 +23,10 @@ module CouchbaseOrm
 
         def self.config(new_config = nil)
             Thread.current['__couchbaseorm_n1ql_config__'] = new_config if new_config
-            Thread.current['__couchbaseorm_n1ql_config__'] || {
-                scan_consistency: DEFAULT_SCAN_CONSISTENCY
-            }
+            {
+                scan_consistency: DEFAULT_SCAN_CONSISTENCY,
+                adhoc: DEFAULT_ADHOC
+            }.merge(Thread.current['__couchbaseorm_n1ql_config__'] || {})
         end
 
         module ClassMethods
@@ -57,7 +59,10 @@ module CouchbaseOrm
                 @indexes[name] = method_opts
 
                 singleton_class.__send__(:define_method, name) do |key: NO_VALUE, **opts, &result_modifier|
-                    opts = options.merge(opts).reverse_merge(scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency])
+                    opts = options.merge(opts).reverse_merge(
+                        scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency],
+                        adhoc: CouchbaseOrm::N1ql.config[:adhoc]
+                    )
                     values = key == NO_VALUE ? NO_VALUE : convert_values(method_opts[:emit_key], key)
                     current_query = run_query(method_opts[:emit_key], values, query_fn, custom_order: custom_order, **opts.except(:include_docs, :key))
                     if result_modifier
@@ -95,10 +100,10 @@ module CouchbaseOrm
                 end
             end
 
-            def build_where(keys, values)
+            def build_where(keys, values, params: nil)
                 where = values == NO_VALUE ? '' : keys.zip(Array.wrap(values))
                             .reject { |key, value| key.nil? && value.nil? }
-                            .map { |key, value| build_match(key, value) }
+                            .map { |key, value| build_match(key, value, params: params) }
                             .join(" AND ")
                 "type=\"#{design_document}\" #{"AND " + where unless where.blank?}"
             end
@@ -119,12 +124,17 @@ module CouchbaseOrm
                     N1qlProxy.new(query_fn.call(bucket, values, Couchbase::Options::Query.new(**options)))
                 else
                     bucket_name = bucket.name
-                    where = build_where(keys, values)
+                    params = []
+                    where = build_where(keys, values, params: params)
                     order = custom_order || build_order(keys, descending)
                     limit = build_limit(limit)
                     n1ql_query = "select raw meta().id from `#{bucket_name}` where #{where} order by #{order} #{limit}"
-                    result = cluster.query(n1ql_query, Couchbase::Options::Query.new(**options))
-                    CouchbaseOrm.logger.debug  "N1QL query: #{n1ql_query} return #{result.rows.to_a.length} rows with scan_consistency : #{options[:scan_consistency]}"
+
+                    query_options = options.merge(positional_parameters: params)
+                    result = cluster.query(n1ql_query, Couchbase::Options::Query.new(**query_options))
+                    CouchbaseOrm.logger.debug {
+                        "N1QL query: #{n1ql_query} params: #{params.inspect} return #{result.rows.to_a.length} rows with scan_consistency: #{options[:scan_consistency]}"
+                    }
                     N1qlProxy.new(result)
                 end
             end

data/lib/couchbase-orm/relation.rb

@@ -3,7 +3,7 @@ module CouchbaseOrm
         extend ActiveSupport::Concern
 
         class CouchbaseOrm_Relation
-            def initialize(model:, where: where = nil, order: order = nil, limit: limit = nil, _not: _not = false, strict_loading: strict_loading = false)
+            def initialize(model:, where: where = nil, order: order = nil, limit: limit = nil, _not: _not = false, strict_loading: strict_loading = false, query_options: query_options = {})
                 CouchbaseOrm::logger.debug "CouchbaseOrm_Relation init: #{model} where:#{where.inspect} not:#{_not.inspect} order:#{order.inspect} limit: #{limit} strict_loading: #{strict_loading}"
                 @model = model
                 @limit = limit
@@ -12,6 +12,7 @@ module CouchbaseOrm
                 @order = merge_order(**order) if order
                 @where = merge_where(where, _not) if where
                 @strict_loading = strict_loading
+                @query_options = query_options || {}
                 CouchbaseOrm::logger.debug "- #{to_s}"
             end
 
@@ -21,31 +22,41 @@ module CouchbaseOrm
 
             def to_n1ql
                 bucket_name = @model.bucket.name
-                where = build_where
+                where = build_where_with_params(nil)
                 order = build_order
                 limit = build_limit
                 "select raw meta().id from `#{bucket_name}` where #{where} order by #{order} #{limit}"
             end
 
-            def execute(n1ql_query)
-                result = @model.cluster.query(n1ql_query, Couchbase::Options::Query.new(scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency]))
-                CouchbaseOrm.logger.debug { "Relation query: #{n1ql_query} return #{result.rows.to_a.length} rows with scan_consistency : #{CouchbaseOrm::N1ql.config[:scan_consistency]}" }
+            def to_n1ql_with_params
+                bucket_name = @model.bucket.name
+                params = []
+                where = build_where_with_params(params)
+                order = build_order
+                limit = build_limit
+                ["select raw meta().id from `#{bucket_name}` where #{where} order by #{order} #{limit}", params]
+            end
+
+            def execute(n1ql_query, params = [])
+                result = @model.cluster.query(n1ql_query, build_query_options(positional_parameters: params))
+                CouchbaseOrm.logger.debug { "Relation query: #{n1ql_query} params: #{params.inspect} return #{result.rows.to_a.length} rows" }
                 N1qlProxy.new(result)
             end
 
             def query
                 CouchbaseOrm::logger.debug("Query: #{self}")
-                n1ql_query = to_n1ql
-                execute(n1ql_query)
+                n1ql_query, params = to_n1ql_with_params
+                execute(n1ql_query, params)
             end
-            
+
             def update_all(**cond)
                 bucket_name = @model.bucket.name
-                where = build_where
+                params = []
+                where = build_where_with_params(params)
                 limit = build_limit
-                update = build_update(**cond)
+                update = build_update_with_params(params, **cond)
                 n1ql_query = "update `#{bucket_name}` set #{update} where #{where} #{limit}"
-                execute(n1ql_query)
+                execute(n1ql_query, params)
             end
 
             def ids
@@ -60,15 +71,21 @@ module CouchbaseOrm
                 !!@strict_loading
             end
 
+            def with(opts = {})
+                CouchbaseOrm_Relation.new(**initializer_arguments.merge(query_options: @query_options.merge(opts)))
+            end
+
             def first
-                result = @model.cluster.query(self.limit(1).to_n1ql, Couchbase::Options::Query.new(scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency]))
+                n1ql_query, params = self.limit(1).to_n1ql_with_params
+                result = @model.cluster.query(n1ql_query, build_query_options(positional_parameters: params))
                 return unless (first_id = result.rows.to_a.first)
 
                 @model.find(first_id, with_strict_loading: @strict_loading)
             end
 
             def last
-                result = @model.cluster.query(to_n1ql, Couchbase::Options::Query.new(scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency]))
+                n1ql_query, params = to_n1ql_with_params
+                result = @model.cluster.query(n1ql_query, build_query_options(positional_parameters: params))
                 last_id = result.rows.to_a.last
                 @model.find(last_id, with_strict_loading: @strict_loading) if last_id
             end
@@ -156,7 +173,7 @@ module CouchbaseOrm
             end
 
             def initializer_arguments
-                { model: @model, order: @order, where: @where, limit: @limit, strict_loading: @strict_loading }
+                { model: @model, order: @order, where: @where, limit: @limit, strict_loading: @strict_loading, query_options: @query_options }
             end
 
             def merge_order(*lorder, **horder)
@@ -166,7 +183,7 @@ module CouchbaseOrm
                     .merge(Array.wrap(lorder).map{ |o| [o, :asc] }.to_h)
                     .merge(horder)
             end
-     
+
             def merge_where(conds, _not = false)
                 @where + (_not ? conds.to_a.map{|k,v|[k,v,:not]} : conds.to_a)
             end
@@ -183,48 +200,54 @@ module CouchbaseOrm
                 end.join(", ")
                 order.empty? ? "meta().id" : order
             end
-            
-            def build_where
-                build_conds([[:type, @model.design_document]] + @where)
+
+            def build_where_with_params(params)
+                build_conds_with_params([[nil, "type = #{@model.quote(@model.design_document)}"]] + @where, params)
             end
 
-            def build_conds(conds)
+            def build_conds_with_params(conds, params)
                 conds.map do |key, value, opt|
                     if key
-                        opt == :not ? 
-                            @model.build_not_match(key, value) : 
-                            @model.build_match(key, value)
+                        opt == :not ?
+                            @model.build_not_match(key, value, params: params) :
+                            @model.build_match(key, value, params: params)
                     else
                         value
                     end
                 end.join(" AND ")
             end
 
-            def build_update(**cond)
+            def build_update_with_params(params, **cond)
                 cond.map do |key, value|
-                    for_clause=""
+                    for_clause = ""
                     if value.is_a?(Hash) && value[:_for]
                         path_clause = value.delete(:_for)
                         var_clause = path_clause.to_s.split(".").last.singularize
-                        
+
                         _when = value.delete(:_when)
-                        when_clause = _when ? build_conds(_when.to_a) : ""
-                        
-                        _set = value.delete(:_set)                       
+                        when_clause = _when ? build_conds_with_params(_when.to_a, params) : ""
+
+                        _set = value.delete(:_set)
                         value = _set if _set
 
                         for_clause = " for #{var_clause} in #{path_clause} when #{when_clause} end"
                     end
                     if value.is_a?(Hash)
                         value.map do |k, v|
-                            "#{key}.#{k} = #{@model.quote(v) || 'NULL'}"
+                            "#{key}.#{k} = #{v.nil? ? 'NULL' : @model.bind(v, params)}"
                         end.join(", ") + for_clause
                     else
-                        "#{key} = #{@model.quote(value)}#{for_clause}"
+                        "#{key} = #{value.nil? ? 'NULL' : @model.bind(value, params)}#{for_clause}"
                     end
                 end.join(", ")
             end
 
+            def build_query_options(positional_parameters: [])
+                opts = CouchbaseOrm::N1ql.config.merge(@query_options)
+                opts[:positional_parameters] = positional_parameters unless positional_parameters.empty?
+                Couchbase::Options::Query.new(**opts)
+            end
+
             def method_missing(method, *args, &block)
                 if @model.respond_to?(method)
                     scoping {
@@ -243,7 +266,7 @@ module CouchbaseOrm
 
             delegate :ids, :update_all, :delete_all, :count, :empty?, :filter, :reduce, :find_by, to: :all
 
-            delegate :where, :not, :order, :limit, :all, :strict_loading, :strict_loading?, to: :relation
+            delegate :where, :not, :order, :limit, :all, :strict_loading, :strict_loading?, :with, to: :relation
         end
     end
 end

data/lib/couchbase-orm/utilities/has_many.rb

@@ -96,7 +96,9 @@ module CouchbaseOrm
                 klass.class_eval do
                   n1ql remote_method, emit_key: 'id', query_fn: proc { |bucket, values, options|
                     raise ArgumentError, "values[0] must not be blank" if values[0].blank?
-                    cluster.query("SELECT raw #{through_key} FROM `#{bucket.name}` where type = \"#{design_document}\" and #{foreign_key} = #{quote(values[0])}", options)
+                    n1ql_query = "SELECT raw #{through_key} FROM `#{bucket.name}` where type = \"#{design_document}\" and #{foreign_key} = $1"
+                    options.positional_parameters([values[0]])
+                    cluster.query(n1ql_query, options)
                   }
                 end
             else

data/lib/couchbase-orm/utilities/query_helper.rb

@@ -4,7 +4,34 @@ module CouchbaseOrm
 
         module ClassMethods
 
-            def build_match(key, value)
+            def serialize_for_binding(value)
+                if value.is_a?(Array)
+                    value.map { |v| serialize_for_binding(v) }
+                elsif [DateTime, Time].any? { |clazz| value.is_a?(clazz) } || (value.respond_to?(:acts_like?) && value.acts_like?(:time))
+                    value.iso8601(@precision || 0)
+                elsif value.is_a?(Date)
+                    value.to_s
+                else
+                    value
+                end
+            end
+
+            def bind(value, params)
+                if value.nil?
+                    nil
+                else
+                    params << serialize_for_binding(value)
+                    "$#{params.length}"
+                end
+            end
+
+            # Renders a value either as a positional parameter (when +params+ is
+            # provided) or as an inline quoted literal (when it is nil).
+            def resolve_value(value, params)
+                params ? bind(value, params) : quote(value)
+            end
+
+            def build_match(key, value, params: nil)
                 use_is_null = self.properties_always_exists_in_document
                 key = "meta().id" if key.to_s == "id"
                 case
@@ -13,35 +40,35 @@ module CouchbaseOrm
                 when value.nil? && !use_is_null
                     "#{key} IS NOT VALUED"
                 when value.is_a?(Hash) && attribute_types[key.to_s].is_a?(CouchbaseOrm::Types::Array)
-                    "any #{key.to_s.singularize} in #{key} satisfies (#{build_match_hash("#{key.to_s.singularize}", value)}) end"
+                    "any #{key.to_s.singularize} in #{key} satisfies (#{build_match_hash("#{key.to_s.singularize}", value, params: params)}) end"
                 when value.is_a?(Hash) && !attribute_types[key.to_s].is_a?(CouchbaseOrm::Types::Array)
-                    build_match_hash(key, value)
+                    build_match_hash(key, value, params: params)
                 when value.is_a?(Array) && value.include?(nil)
-                    "(#{build_match(key, nil)} OR #{build_match(key, value.compact)})"
+                    "(#{build_match(key, nil, params: params)} OR #{build_match(key, value.compact, params: params)})"
                 when value.is_a?(Array)
-                    "#{key} IN #{quote(value)}"
+                    "#{key} IN #{resolve_value(value, params)}"
                 when value.is_a?(Range)
-                    build_match_range(key, value)
+                    build_match_range(key, value, params: params)
                 else
-                    "#{key} = #{quote(value)}"
+                    "#{key} = #{resolve_value(value, params)}"
                 end
             end
 
-            def build_match_hash(key, value)
+            def build_match_hash(key, value, params: nil)
                 matches = []
                 value.each do |k, v|
                     case k
                     when :_gt
-                        matches << "#{key} > #{quote(v)}"
+                        matches << "#{key} > #{resolve_value(v, params)}"
                     when :_gte
-                        matches << "#{key} >= #{quote(v)}"
+                        matches << "#{key} >= #{resolve_value(v, params)}"
                     when :_lt
-                        matches << "#{key} < #{quote(v)}"
+                        matches << "#{key} < #{resolve_value(v, params)}"
                     when :_lte
-                        matches << "#{key} <= #{quote(v)}"
+                        matches << "#{key} <= #{resolve_value(v, params)}"
                     when :_ne
-                        matches << "#{key} != #{quote(v)}"
-                    
+                        matches << "#{key} != #{resolve_value(v, params)}"
+
                     # TODO v2
                     # when :_in
                     #     matches << "#{key} IN #{quote(v)}"
@@ -65,7 +92,7 @@ module CouchbaseOrm
                     #     matches << "#{key} MATCH #{quote(v)}"
                     # when :_nmatch
                     #     matches << "#{key} NOT MATCH #{quote(v)}"
-                    
+
                     # TODO v3
                     # when :_any
                     #     matches << "#{key} ANY #{quote(v)}"
@@ -80,26 +107,26 @@ module CouchbaseOrm
                     #when :_nwithin
                     #    matches << "#{key} NOT WITHIN #{quote(v)}"
                     else
-                        matches << build_match("#{key}.#{k}", v)
+                        matches << build_match("#{key}.#{k}", v, params: params)
                     end
                 end
-                
+
                 matches.join(" AND ")
             end
 
-            def build_match_range(key, value)
+            def build_match_range(key, value, params: nil)
                 matches = []
-                matches << "#{key} >= #{quote(value.begin)}"
+                matches << "#{key} >= #{resolve_value(value.begin, params)}"
                 if value.exclude_end?
-                    matches << "#{key} < #{quote(value.end)}"
+                    matches << "#{key} < #{resolve_value(value.end, params)}"
                 else
-                    matches << "#{key} <= #{quote(value.end)}"
+                    matches << "#{key} <= #{resolve_value(value.end, params)}"
                 end
                 matches.join(" AND ")
             end
 
 
-            def build_not_match(key, value)
+            def build_not_match(key, value, params: nil)
                 use_is_null = self.properties_always_exists_in_document
                 key = "meta().id" if key.to_s == "id"
                 case
@@ -108,11 +135,11 @@ module CouchbaseOrm
                 when value.nil? && !use_is_null
                     "#{key} IS VALUED"
                 when value.is_a?(Array) && value.include?(nil)
-                    "(#{build_not_match(key, nil)} AND #{build_not_match(key, value.compact)})"
+                    "(#{build_not_match(key, nil, params: params)} AND #{build_not_match(key, value.compact, params: params)})"
                 when value.is_a?(Array)
-                    "#{key} NOT IN #{quote(value)}"
+                    "#{key} NOT IN #{resolve_value(value, params)}"
                 else
-                    "#{key} != #{quote(value)}"
+                    "#{key} != #{resolve_value(value, params)}"
                 end
             end
 

data/lib/couchbase-orm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true, encoding: ASCII-8BIT
 
 module CouchbaseOrm
-  VERSION = '3.0.3'
+  VERSION = '3.2.0'
 end

data/spec/n1ql_spec.rb

@@ -172,7 +172,10 @@ describe CouchbaseOrm::N1ql do
     it "should log the default scan_consistency when n1ql query is executed" do
         allow(CouchbaseOrm.logger).to receive(:debug)
         N1QLTest.by_rating_reverse()
-        expect(CouchbaseOrm.logger).to have_received(:debug).at_least(:once).with("N1QL query: select raw meta().id from `#{CouchbaseOrm::Connection.bucket.name}` where type=\"n1_ql_test\"  order by name DESC  return 0 rows with scan_consistency : #{described_class::DEFAULT_SCAN_CONSISTENCY}")
+        expect(CouchbaseOrm.logger).to have_received(:debug).at_least(:once) do |&block|
+            msg = block ? block.call : nil
+            msg == "N1QL query: select raw meta().id from `#{CouchbaseOrm::Connection.bucket.name}` where type=\"n1_ql_test\"  order by name DESC  params: [] return 0 rows with scan_consistency: #{described_class::DEFAULT_SCAN_CONSISTENCY}"
+        end
     end
 
     it "should log the set scan_consistency when n1ql query is executed with a specific scan_consistency" do
@@ -180,11 +183,36 @@ describe CouchbaseOrm::N1ql do
         default_n1ql_config = CouchbaseOrm::N1ql.config
         CouchbaseOrm::N1ql.config({ scan_consistency: :not_bounded })
         N1QLTest.by_rating_reverse()
-        expect(CouchbaseOrm.logger).to have_received(:debug).at_least(:once).with("N1QL query: select raw meta().id from `#{CouchbaseOrm::Connection.bucket.name}` where type=\"n1_ql_test\"  order by name DESC  return 0 rows with scan_consistency : not_bounded")
+        expect(CouchbaseOrm.logger).to have_received(:debug).at_least(:once) do |&block|
+            msg = block ? block.call : nil
+            msg == "N1QL query: select raw meta().id from `#{CouchbaseOrm::Connection.bucket.name}` where type=\"n1_ql_test\"  order by name DESC  params: [] return 0 rows with scan_consistency: not_bounded"
+        end
 
         CouchbaseOrm::N1ql.config(default_n1ql_config)
         N1QLTest.by_rating_reverse()
-        expect(CouchbaseOrm.logger).to have_received(:debug).at_least(:once).with("N1QL query: select raw meta().id from `#{CouchbaseOrm::Connection.bucket.name}` where type=\"n1_ql_test\"  order by name DESC  return 0 rows with scan_consistency : #{described_class::DEFAULT_SCAN_CONSISTENCY}")
+        expect(CouchbaseOrm.logger).to have_received(:debug).at_least(:once) do |&block|
+            msg = block ? block.call : nil
+            msg == "N1QL query: select raw meta().id from `#{CouchbaseOrm::Connection.bucket.name}` where type=\"n1_ql_test\"  order by name DESC  params: [] return 0 rows with scan_consistency: #{described_class::DEFAULT_SCAN_CONSISTENCY}"
+        end
+    end
+
+    it "should use adhoc: true by default (no prepared statement plan caching)" do
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: true)).and_call_original
+        N1QLTest.by_rating_reverse()
+    end
+
+    it "should allow overriding adhoc per call to enable plan caching" do
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: false)).and_call_original
+        N1QLTest.by_rating_reverse(adhoc: false)
+    end
+
+    it "should respect N1ql.config adhoc setting" do
+        default_config = CouchbaseOrm::N1ql.config
+        CouchbaseOrm::N1ql.config({ adhoc: false })
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: false)).and_call_original
+        N1QLTest.by_rating_reverse()
+    ensure
+        CouchbaseOrm::N1ql.config(default_config)
     end
 
     after(:all) do

data/spec/relation_spec.rb

@@ -310,6 +310,55 @@ describe CouchbaseOrm::Relation do
         expect(RelationModel.empty?).to eq(false)
     end
 
+    describe "parameterized queries" do
+        it "should return parameterized query with to_n1ql_with_params" do
+            relation = RelationModel.where(active: true, name: "Jane")
+            n1ql, params = relation.send(:to_n1ql_with_params)
+            expect(n1ql).to include("type = 'relation_model'")
+            expect(n1ql).to include("active = $1")
+            expect(n1ql).to include("name = $2")
+            expect(n1ql).not_to include("'Jane'")
+            expect(params).to eq([true, "Jane"])
+        end
+
+        it "should parameterize NOT conditions" do
+            relation = RelationModel.not(active: true)
+            n1ql, params = relation.send(:to_n1ql_with_params)
+            expect(n1ql).to include("active != $1")
+            expect(params).to eq([true])
+        end
+
+        it "should parameterize range conditions" do
+            relation = RelationModel.where(age: 10..30)
+            n1ql, params = relation.send(:to_n1ql_with_params)
+            expect(n1ql).to include("age >= $1")
+            expect(n1ql).to include("age <= $2")
+            expect(params).to eq([10, 30])
+        end
+
+        it "should parameterize hash operator conditions" do
+            relation = RelationModel.where(age: { _gte: 18, _lt: 65 })
+            n1ql, params = relation.send(:to_n1ql_with_params)
+            expect(n1ql).to include("age >= $1")
+            expect(n1ql).to include("age < $2")
+            expect(params).to eq([18, 65])
+        end
+
+        it "should pass through string conditions without parameterization" do
+            relation = RelationModel.where("active = true")
+            n1ql, params = relation.send(:to_n1ql_with_params)
+            expect(n1ql).to include("(active = true)")
+            expect(params).to eq([])
+        end
+
+        it "should parameterize array IN conditions" do
+            relation = RelationModel.where(name: ["Alice", "Bob"])
+            n1ql, params = relation.send(:to_n1ql_with_params)
+            expect(n1ql).to include("name IN $1")
+            expect(params).to eq([["Alice", "Bob"]])
+        end
+    end
+
     describe "operators" do
         it "should query by gte and lte" do
             _m1 = RelationModel.create!(age: 10)
@@ -452,5 +501,38 @@ describe CouchbaseOrm::Relation do
             end
         end
     end
+
+    it "should use adhoc: true by default (no prepared statement plan caching)" do
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: true)).and_call_original
+        RelationModel.where(active: true).ids
+    end
+
+    describe "adhoc option via with" do
+        it "should return a relation when calling with(adhoc:)" do
+            expect(RelationModel.all.with(adhoc: false)).to be_a(CouchbaseOrm::Relation::CouchbaseOrm_Relation)
+        end
+
+        it "should pass adhoc: false to query options when set on the relation" do
+            expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: false)).and_call_original
+            RelationModel.where(active: true).with(adhoc: false).ids
+        end
+
+        it "should override N1ql.config adhoc when set on the relation" do
+            default_config = CouchbaseOrm::N1ql.config
+            CouchbaseOrm::N1ql.config(adhoc: false)
+            expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: true)).and_call_original
+            RelationModel.where(active: true).with(adhoc: true).ids
+        ensure
+            CouchbaseOrm::N1ql.config(default_config)
+        end
+
+        it "should be chainable with other relation methods" do
+            m1 = RelationModel.create!(active: true, age: 10)
+            _m2 = RelationModel.create!(active: false, age: 20)
+            expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: false)).and_call_original
+            result = RelationModel.where(active: true).order(:age).with(adhoc: false).to_a
+            expect(result).to match_array([m1])
+        end
+    end
 end
 

metadata

@@ -1,17 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: couchbase-orm
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: 3.2.0
 platform: ruby
 authors:
 - Stephen von Takach
 - Gauthier Monserand
 - Pierre Merlin
 - Julien Burnet-Fauche
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -210,7 +209,6 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: A Couchbase ORM for Rails
-email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -354,7 +352,6 @@ metadata:
   bug_tracker_uri: https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm/issues
   documentation_uri: https://www.couchbase-ruby-orm.com/
   homepage_uri: https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -362,15 +359,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Couchbase ORM for Rails
 test_files: