feat: enable prepared statement plan caching via adhoc: false in n1ql queries

Add adhoc: false to N1ql.config default so every n1ql-macro query opts into
Couchbase server-side plan caching. The value flows through the reverse_merge
in the generated method, maintaining the same override priority as
scan_consistency: per-call > per-definition > N1ql.config > default.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: pimpin

lib/couchbase-orm/n1ql.rb

@@ -23,7 +23,8 @@ def self.sanitize(value)
         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: false
             }
         end
 
@@ -57,7 +58,10 @@ def n1ql(name, query_fn: nil, emit_key: [], custom_order: nil, **options)
                 @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

spec/n1ql_spec.rb

@@ -196,6 +196,25 @@ class N1QLTest < CouchbaseOrm::Base
         end
     end
 
+    it "should use adhoc: false by default for prepared statement plan caching" do
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: false)).and_call_original
+        N1QLTest.by_rating_reverse()
+    end
+
+    it "should allow overriding adhoc per call" do
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: true)).and_call_original
+        N1QLTest.by_rating_reverse(adhoc: true)
+    end
+
+    it "should respect N1ql.config adhoc setting" do
+        default_config = CouchbaseOrm::N1ql.config
+        CouchbaseOrm::N1ql.config({ adhoc: true })
+        expect(Couchbase::Options::Query).to receive(:new).with(hash_including(adhoc: true)).and_call_original
+        N1QLTest.by_rating_reverse()
+    ensure
+        CouchbaseOrm::N1ql.config(default_config)
+    end
+
     after(:all) do
         N1QLTest.delete_all
     end