rokaki 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e754206bd6927db93fa0977aed409762b9bc9aa2a663c5b0d94977c2d18ba284
-  data.tar.gz: 9df4b1d7d067be43ac1df89f1b5962b2950b91e6bc5e915817cde2ef625f55f0
+  metadata.gz: f6c0197e9af455ef746957b92e5a28a4aa8a34ad35712c2aacae5ad6797f4d18
+  data.tar.gz: 7cc5acc3e65cd850a50de797285c55fdbdab9c47fc2a790a68d6ec23c4064b4d
 SHA512:
-  metadata.gz: bf35a2999e21604de1d4daa615042036b0f16b651e251f569b4a13706d9e0e0c17022d0856303dfa71183b2c77af03631e3cae83e3b4cb790c855d47980ccc1c
-  data.tar.gz: ad6b7c1e51bfee821d54923ccf6447ed91b0633bc084d0cd0adbd6a901d36200025334b3415c53814f62c0cf644bbb8e5a6e1a8418c1c8bac9cdf5add470e8f8
+  metadata.gz: addeae565323de0ce359cd73d01e3c7e31f457849b59fb373942436358561fd085fcf36117a4c8c75279ce549a26473364298067c2b760285eaec1f964423193
+  data.tar.gz: 147a531f6489bc41a102b60b16689c21bc1d852fb18a4d1658115943b35d0d64905d44b81c1ff1d1c4832b5d7739dac4758a436b262c7a6e64aa75db161d92ca

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+### Unreleased
+- Documentation: Added backend auto‑detection feature docs across README and site (index, usage, adapters, configuration). Examples now prefer auto‑detection by default and explain explicit overrides and ambiguity errors.
+- Tests: Added shared examples to exercise auto‑detection behavior under each adapter suite.
+
 ### 0.15.0 — 2025-10-27
 - Add first-class SQLite support: adapter-aware LIKE behavior with OR expansion for arrays.
 - Added SQLite badge in README.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rokaki (0.15.0)
+    rokaki (0.16.0)
       activesupport
 
 GEM

data/README.md

@@ -16,6 +16,7 @@ Rokaki is a small DSL for building safe, composable filters for ActiveRecord que
 - Works with ActiveRecord 7.1 and 8.x
 - LIKE modes: `:prefix`, `:suffix`, `:circumfix` (+ synonyms) and array‑of‑terms
 - Nested filters with auto‑joins and qualified columns
+- Auto‑detects the database backend; specify `db:` only when your app uses multiple adapters or you need an override
 - Block‑form DSL (`filter_map do ... end`) and classic argument form
 - Runtime usage: build an anonymous filter class from a payload (no predeclared class needed)
 

data/docs/adapters.md

@@ -52,6 +52,16 @@ When you pass an array of terms, Rokaki composes adapter‑appropriate SQL that
 - SQL Server: The server/database/column collation determines sensitivity. Rokaki currently defers to your DB’s default. If you need deterministic behavior regardless of DB defaults, consider using a case‑sensitive collation on the column or open an issue to discuss inline `COLLATE` options.
 
 
+## Backend auto-detection
+
+Rokaki auto-detects the adapter from your model’s ActiveRecord connection in typical single-adapter apps. If multiple adapters are detected in the process and you do not specify one, Rokaki raises a helpful error asking you to choose.
+
+- Default: no `db:` needed; the adapter is inferred from the model connection.
+- Multiple adapters present: pass `db:` to `filter_model` (or call `filter_db`) to select one explicitly.
+- Errors you may see:
+  - `Rokaki::Error: Multiple database adapters detected (...). Please declare which backend to use via db: or filter_db.`
+  - `Rokaki::Error: Unable to auto-detect database adapter. Ensure your model is connected or pass db: explicitly.`
+
 ## SQLite
 
 SQLite is embedded and requires no separate server process. Rokaki treats it as a first-class adapter.

data/docs/configuration.md

@@ -42,6 +42,16 @@ Rokaki's test helpers (used in the specs) support environment variable overrides
 ### SQLite
 - `SQLITE_DATABASE` (path to a SQLite file; if unset, tests use an in-memory DB via `":memory:"`)
 
+## Backend auto-detection
+
+By default, Rokaki infers the database adapter from your model’s ActiveRecord connection.
+
+- Single-adapter apps: no `db:` needed.
+- Multiple adapters present: pass `db:` to `filter_model` (or call `filter_db`) to choose explicitly.
+- Errors:
+  - `Rokaki::Error: Multiple database adapters detected (...). Please declare which backend to use via db: or filter_db.`
+  - `Rokaki::Error: Unable to auto-detect database adapter. Ensure your model is connected or pass db: explicitly.`
+
 ## SQL Server notes
 
 - Rokaki uses `LIKE` with proper escaping and OR expansion for arrays of terms.

data/docs/index.md

@@ -10,6 +10,7 @@ Rokaki is a small Ruby library that helps you build safe, composable filters for
 - Supports simple and nested filters
 - LIKE-based matching with prefix/suffix/circumfix modes (circumfix also accepts synonyms: parafix, confix, ambifix)
 - Array-of-terms matching (adapter-aware)
+- Auto-detects the database backend; specify db only when your app uses multiple adapters or you need an override
 
 Get started below or jump to:
 - [Usage](./usage)
@@ -40,8 +41,9 @@ Argument-based form:
 class ArticleQuery
   include Rokaki::FilterModel
 
-  # Tell Rokaki which model to query and which DB adapter semantics to use
-  filter_model :article, db: :postgres # or :mysql, :sqlserver, :oracle, :sqlite
+  # Tell Rokaki which model to query. Adapter is auto-detected from the connection.
+  # If your app uses multiple adapters, pass db: explicitly (e.g., db: :postgres)
+  filter_model :article
 
   # Map a single query key (:q) to multiple LIKE targets on Article
   define_query_key :q
@@ -66,7 +68,9 @@ Block-form DSL (same behavior):
 class ArticleQuery
   include Rokaki::FilterModel
 
-  filter_model :article, db: :postgres # or :mysql, :sqlserver
+  # Adapter is auto-detected from the connection by default.
+  # If your app uses multiple adapters, pass db: explicitly (e.g., db: :postgres)
+  filter_model :article
   define_query_key :q
 
   filter_map do

data/docs/usage.md

@@ -31,8 +31,9 @@ class ArticleQuery
   include Rokaki::FilterModel
   belongs_to :author
 
-  # Choose model and adapter
-  filter_model :article, db: :postgres # or :mysql, :sqlserver, :oracle, :sqlite
+  # Choose model; adapter is auto-detected from the model's connection.
+  # If your app uses multiple adapters, pass db: explicitly (e.g., db: :postgres)
+  filter_model :article
 
   # Map a single query key (:q) to multiple LIKE targets
   define_query_key :q
@@ -112,8 +113,9 @@ Rokaki also supports a block-form DSL that is equivalent to the argument-based f
 class ArticleQuery
   include Rokaki::FilterModel
 
-  # Choose model and adapter
-  filter_model :article, db: :postgres # or :mysql, :sqlserver
+  # Choose model; adapter is auto-detected from the model's connection.
+  # If your app uses multiple adapters, pass db: explicitly (e.g., db: :postgres)
+  filter_model :article
 
   # Declare a single query key used by all LIKE/equality filters below
   define_query_key :q
@@ -188,6 +190,59 @@ Tips:
 - Inside the block, `nested :association` affects all `filters` declared within it.
 
 
+## Backend auto-detection
+
+By default, Rokaki auto-detects which database adapter to use from your model’s ActiveRecord connection. This means you usually don’t need to pass `db:` explicitly.
+
+- Single-adapter apps: No configuration needed — Rokaki infers the adapter from the model connection.
+- Multi-adapter apps: If more than one adapter is detected in the process, Rokaki raises a clear error asking you to declare which backend to use.
+- Explicit override: You can always specify `db:` on `filter_model` or call `filter_db` later.
+
+Examples:
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  # Adapter auto-detected (recommended default)
+  filter_model :article
+  define_query_key :q
+
+  filter_map do
+    like title: :circumfix
+  end
+end
+```
+
+Explicit selection/override:
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  # Option A: choose upfront
+  filter_model :article, db: :postgres
+
+  # Option B: or set it later
+  # filter_model :article
+  # filter_db :sqlite
+end
+```
+
+Ambiguity behavior (apps with multiple adapters):
+
+- If Rokaki sees multiple adapters in use and you haven’t specified one, it raises:
+
+```
+Rokaki::Error: Multiple database adapters detected (...). Please declare which backend to use via db: or filter_db.
+```
+
+- If it cannot detect any adapter at all, it raises:
+
+```
+Rokaki::Error: Unable to auto-detect database adapter. Ensure your model is connected or pass db: explicitly.
+```
+
 ## Dynamic runtime listener (no code changes needed)
 
 You can construct a Rokaki filter class at runtime from a payload (e.g., JSON → Hash) and use it immediately — no prior class is required. Rokaki will compile the tiny class on the fly and generate the methods once.
@@ -197,7 +252,7 @@ You can construct a Rokaki filter class at runtime from a payload (e.g., JSON
 # Example payload (e.g., parsed JSON)
 payload = {
   model: :article,
-  db: :postgres,        # or :mysql, :sqlserver, :oracle
+  db: :postgres,        # optional; or :mysql, :sqlserver, :oracle, :sqlite
   query_key: :q,        # the key in params with search term(s)
   like: {               # like mappings (deeply nested allowed)
     title: :circumfix,

data/lib/rokaki/filter_model.rb

@@ -159,6 +159,89 @@ module Rokaki
         end
       end
 
+      # Map AR adapter names to internal symbols
+      def map_adapter_name(name)
+        n = name.to_s.downcase
+        case n
+        when 'postgresql', 'postgres', 'postgis'
+          :postgres
+        when 'mysql2', 'mysql'
+          :mysql
+        when 'sqlite3', 'sqlite'
+          :sqlite
+        when 'sqlserver'
+          :sqlserver
+        when 'oracle_enhanced', 'oracle'
+          :oracle
+        else
+          nil
+        end
+      end
+
+      # Try to detect adapter from a model's connection
+      def detect_adapter_from_model(model)
+        return nil unless model
+        begin
+          adapter = model.connection_db_config&.adapter
+          return map_adapter_name(adapter) if adapter
+        rescue StandardError
+          # fall through
+        end
+        begin
+          adapter = model.connection&.adapter_name
+          return map_adapter_name(adapter)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Scan known AR models to see how many adapters are in use
+      def adapters_in_use
+        adapters = []
+        begin
+          bases = [::ActiveRecord::Base] + (::ActiveRecord::Base.descendants rescue [])
+          bases.uniq.each do |k|
+            next unless k.respond_to?(:connection_db_config)
+            begin
+              a = k.connection_db_config&.adapter
+              adapters << a if a
+            rescue StandardError
+              # ignore not connected models
+            end
+          end
+        rescue StandardError
+          # ignore
+        end
+        adapters.compact.map { |a| map_adapter_name(a) }.compact.uniq
+      end
+
+      # Determine @_filter_db or raise if ambiguous in multi-adapter apps
+      def resolve_filter_db!(model: @model, explicit: nil)
+        if explicit
+          @_filter_db = explicit
+          return @_filter_db
+        end
+        # Prefer model-specific detection
+        detected = detect_adapter_from_model(model)
+        return (@_filter_db = detected) if detected
+
+        # Fallback to a single global adapter if unambiguous
+        used = adapters_in_use
+        if used.size == 1
+          @_filter_db = used.first
+        elsif used.size > 1
+          raise ::Rokaki::Error, "Multiple database adapters detected (#{used.join(', ')}). Please declare which backend to use via db: or filter_db."
+        else
+          # As a last resort, try ActiveRecord::Base connection
+          begin
+            base_detected = map_adapter_name(::ActiveRecord::Base.connection_db_config&.adapter)
+            return (@_filter_db = base_detected) if base_detected
+          rescue StandardError
+          end
+          raise ::Rokaki::Error, "Unable to auto-detect database adapter. Ensure your model is connected or pass db: explicitly."
+        end
+      end
+
       # Merge two nested like/ilike mappings
       def deep_merge_like(a, b)
         return b if a.nil? || a == {}
@@ -196,7 +279,7 @@ module Rokaki
         if block_given? && args.empty?
           raise ArgumentError, 'define_query_key must be called before block filter_map' unless @filter_map_query_key
           raise ArgumentError, 'filter_model must be called before block filter_map' unless @model
-          @_filter_db ||= :postgres
+          resolve_filter_db!(model: @model)
 
           # Enter block-collection mode
           @__in_filter_map_block = true
@@ -228,22 +311,22 @@ module Rokaki
         filter_model(model)
         @filter_map_query_key = query_key
 
-        @_filter_db = options[:db] || :postgres
-        @_filter_mode = options[:mode] || :and
-        like(options[:like]) if options[:like]
-        ilike(options[:ilike]) if options[:ilike]
-        filters(*options[:match]) if options[:match]
+        resolve_filter_db!(model: @model, explicit: options && options[:db])
+        @_filter_mode = (options && options[:mode]) || :and
+        like(options[:like]) if options && options[:like]
+        ilike(options[:ilike]) if options && options[:ilike]
+        filters(*options[:match]) if options && options[:match]
       end
 
       def filter(model, options)
         filter_model(model)
         @filter_map_query_key = nil
 
-        @_filter_db = options[:db] || :postgres
-        @_filter_mode = options[:mode] || :and
-        like(options[:like]) if options[:like]
-        ilike(options[:ilike]) if options[:ilike]
-        filters(*options[:match]) if options[:match]
+        resolve_filter_db!(model: @model, explicit: options && options[:db])
+        @_filter_mode = (options && options[:mode]) || :and
+        like(options[:like]) if options && options[:like]
+        ilike(options[:ilike]) if options && options[:ilike]
+        filters(*options[:match]) if options && options[:match]
       end
 
       def filters(*filter_keys)
@@ -353,9 +436,10 @@ module Rokaki
       end
 
       def filter_model(model_class, db: nil)
-        @_filter_db = db if db
         @model = (model_class.is_a?(Class) ? model_class : Object.const_get(model_class.capitalize))
         class_eval "def set_model; @model ||= #{@model}; end;"
+        # Only resolve here if an explicit db is provided; otherwise defer to callers
+        resolve_filter_db!(model: @model, explicit: db) if db
       end
 
       def case_sensitive

data/lib/rokaki/version.rb

@@ -1,3 +1,3 @@
 module Rokaki
-  VERSION = "0.15.0"
+  VERSION = "0.16.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Steve Martin