rokaki 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e754206bd6927db93fa0977aed409762b9bc9aa2a663c5b0d94977c2d18ba284
-  data.tar.gz: 9df4b1d7d067be43ac1df89f1b5962b2950b91e6bc5e915817cde2ef625f55f0
+  metadata.gz: 52ffc6e9a926824c6730632c566d42570997aa5e2a2674ea07e79d0722a628fc
+  data.tar.gz: 248ecf8294fe48488f0b8a8990f1602ab7cd3c10af95731be2a8e3f0933905c8
 SHA512:
-  metadata.gz: bf35a2999e21604de1d4daa615042036b0f16b651e251f569b4a13706d9e0e0c17022d0856303dfa71183b2c77af03631e3cae83e3b4cb790c855d47980ccc1c
-  data.tar.gz: ad6b7c1e51bfee821d54923ccf6447ed91b0633bc084d0cd0adbd6a901d36200025334b3415c53814f62c0cf644bbb8e5a6e1a8418c1c8bac9cdf5add470e8f8
+  metadata.gz: ff1071aaa8e6a151fa0382ec294df042a4afb5d8c8e00bd5a25fe2ffdc67ba54971b649edc5cfd3019895a44c64ee2b0ce352032f8f24d2a525a3cd2ef6dadd0
+  data.tar.gz: 99dcd53ddb3c068522a7a2eba6b262c8f5bfb9bc78433596e4d15a8ea1363e31895be3b2c39270276955a802fe2198ae2d74ddba4d60a063519903ace4f71263

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+### Unreleased
+- (no changes yet)
+
+### 0.17.0 — 2025-10-28
+- Version bump to 0.17.0.
+- Documentation: Updated installation snippets to `~> 0.17`.
+- Documentation: Added comprehensive Range/BETWEEN/MIN/MAX filter docs across README and site (usage, adapters). Clarified sub-key aliases (`between`, `from`/`since`/`after`/`start`/`min`, `to`/`until`/`before`/`end`/`max`), accepted value shapes (Range, 2‑element Array, Hash), nested examples, and equality array semantics (`IN` vs `BETWEEN`).
+- Added Range/BETWEEN/MIN/MAX filters
+
+### 0.16.0 — 2025-10-27
+- 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.17.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)
 
@@ -37,6 +38,25 @@ Docs
 
 Tip: For a dynamic runtime listener (build a filter class from a JSON/hash payload at runtime), see “Dynamic runtime listener” in the Usage docs.
 
+## Range filters (between/min/max)
+
+Use the field name as the key and the filter type as a sub-key, or pass a `Range` directly. Aliases are supported.
+
+```ruby
+# Top-level
+Article.filter(published: { from: Date.new(2024,1,1), to: Date.new(2024,12,31) })
+Article.filter(published: (Date.new(2024,1,1)..Date.new(2024,12,31)))
+
+# Nested
+Article.filter(reviews_published: { max: Time.utc(2024,6,30) })
+```
+
+- Lower bound aliases (>=): `from`, `since`, `after`, `start`, `min`
+- Upper bound aliases (<=): `to`, `until`, `before`, `end`, `max`
+- Arrays always mean `IN (?)` for equality. Use a `Range` or `{ between: [from, to] }` for range filtering
+
+See full docs: https://tevio.github.io/rokaki/usage#range-between-min-and-max-filters
+
 ---
 
 ## Further reading

data/docs/adapters.md

@@ -22,6 +22,7 @@ Rokaki generates adapter‑aware SQL for PostgreSQL, MySQL, SQL Server, Oracle,
   - Case sensitivity follows DB collation by default; future versions may add inline `COLLATE` options
 - Oracle
   - Uses `LIKE`; arrays of terms are OR‑chained; case‑insensitive paths use `UPPER(column) LIKE UPPER(:q)`
+  - See the dedicated page: [Oracle connections](/adapters/oracle) for connection strings, NLS settings, and common errors.
 - SQLite
   - Embedded (no separate server needed)
   - Uses `LIKE`; arrays of terms are OR‑chained across predicates
@@ -52,6 +53,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.
@@ -68,3 +79,20 @@ database: ":memory:"
 ```
 
 To persist a database file locally, set `SQLITE_DATABASE` to a path (e.g., `tmp/test.sqlite3`).
+
+
+## Range/BETWEEN filters
+
+Rokaki’s range filters (`between`, lower-bound aliases like `from`/`min`, and upper-bound aliases like `to`/`max`) are adapter‑agnostic. The library always generates parameterized predicates using `BETWEEN`, `>=`, and `<=` on the target column.
+
+Adapter notes:
+- PostgreSQL: Uses regular `WHERE column BETWEEN $1 AND $2` (or `>=`/`<=`). No special handling is required.
+- MySQL/MariaDB: Uses `BETWEEN ? AND ?` (or `>=`/`<=`). Datetime values are compared with the column precision configured by your schema.
+- SQLite: Uses `BETWEEN ? AND ?` (or `>=`/`<=`).
+- SQL Server: Uses `BETWEEN @from AND @to` (or `>=`/`<=`). Parameters are bound via ActiveRecord.
+- Oracle: Uses `BETWEEN :from AND :to` (or `>=`/`<=`). If your column type is `DATE`, be aware it has second precision; `TIMESTAMP` supports fractional seconds.
+
+Tips:
+- For date-only upper bounds (e.g., `2024-12-31`), Rokaki treats them inclusively and, when applicable, will extend to the end of day in basic filters to match expectations. If you need precise control, pass explicit `Time` values.
+- Arrays are treated as equality lists (`IN (?)`) across all adapters. Use a `Range` or `{ between: [from, to] }` for range filtering.
+- `nil` bounds are ignored: only the provided side is applied.

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/dsl_syntax.md

@@ -0,0 +1,196 @@
+---
+layout: page
+title: Rokaki's DSL Syntax
+permalink: /dsl-syntax
+---
+
+This page describes Rokaki’s domain-specific language (DSL) for declaring mappings and how incoming payloads are interpreted, with a focus on the difference between join-structure keys and leaf-level field keys.
+
+The same concepts apply to both DSL entry points:
+- FilterModel (querying a specific ActiveRecord model)
+- Filterable (key mapping only)
+
+See also: Usage, Adapters, and Configuration pages linked from the site index.
+
+## Key ideas
+
+- You declare the shape of your filterable graph in code. This defines which associations (joins) are traversed and which fields are addressable (leaves).
+- At runtime, the payload mirrors only the declared structure. Values at leaves drive the operator semantics (equality, LIKE, range). The structure of joins does not change at runtime.
+
+## Join-structure keys vs leaf-level field keys
+
+- Join-structure keys represent associations. They appear only in the mapping you write (and mirrored by the payload). They do not carry operators by themselves. Examples: `author`, `reviews`, `articles`.
+- Leaf-level field keys represent actual database columns on the current model or on a joined association. Examples: `title`, `content`, `published`, `first_name`.
+- The mapping defines where a key is treated as a join (non-leaf) vs a field (leaf). At a declared leaf, the value can be a scalar, array, range, or an operator-hash (see below). Rokaki will not traverse deeper than the declared leaf.
+
+## Declaring mappings
+
+Two equivalent styles are supported:
+
+### Argument-based form (classic)
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  filter_model :article               # Adapter auto-detected; pass db: if needed
+  define_query_key :q                 # Map a single query key to many fields
+
+  like title: :circumfix, content: :circumfix # LIKE mappings (no modes: option)
+
+  # Nested LIKEs and filters via association-shaped hashes
+  like author: { first_name: :prefix, last_name: :suffix }
+
+  # Declare equality/range-capable fields (leafs)
+  filters :published                  # enables :published in payload
+  filters reviews: :published         # enables nested reviews.published
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+```
+
+### Block-form DSL
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  filter_model :article
+  define_query_key :q
+
+  filter_map do
+    like title: :circumfix, content: :circumfix
+
+    nested :author do
+      like first_name: :prefix, last_name: :suffix
+      filters :id         # leaf field under author
+    end
+
+    nested :reviews do
+      filters :published  # leaf field under reviews
+    end
+  end
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+```
+
+## Payload rules (what values mean at a leaf)
+
+At a leaf field (e.g., `published` or `reviews.published`):
+
+- Scalar value → equality on the column
+  - Example: `{ published: Time.utc(2024,1,1) }` → `WHERE published = :v`
+
+- Array value → equality `IN` list
+  - Arrays always mean `IN` across adapters.
+  - Example: `{ published: [t1, t2, t3] }` → `WHERE published IN (?, ?, ?)`
+
+- Range (`a..b`) → between
+  - Example: `{ published: (t1..t2) }` → `WHERE published BETWEEN :from AND :to`
+
+- Operator-hash (range-style keys) → between or open-ended bounds
+  - Reserved keys at the leaf indicate operator semantics:
+    - `between`
+    - Lower-bound aliases (>=): `from`, `since`, `after`, `start`, `min`
+    - Upper-bound aliases (<=): `to`, `until`, `before`, `end`, `max`
+  - Examples:
+    - `{ published: { from: t1, to: t2 } }`
+    - `{ published: { between: [t1, t2] } }`
+    - `{ published: { min: t1 } }` → `published >= t1`
+    - `{ published: { max: t2 } }` → `published <= t2`
+
+Notes:
+- Only the leaf level interprets these reserved keys. Join-structure keys do not carry operators.
+- Arrays never imply range; to express a range with an array, use `{ published: { between: [from, to] } }`.
+- Nil bounds are ignored: `{ published: { from: t1 } }` applies only the lower bound.
+
+## LIKE mappings and payloads
+
+- You declare LIKE semantics in code via the `like` mapping; the payload provides the terms.
+- Modes:
+  - `:prefix` → `%term`
+  - `:suffix` → `term%`
+  - `:circumfix` (synonyms: `:parafix`, `:confix`, `:ambifix`) → `%term%`
+- Payload values for LIKE can be a string or an array of strings. Arrays are matched with adapter-aware OR semantics.
+
+Examples:
+```ruby
+like title: :circumfix
+like author: { first_name: :prefix }
+
+# Payload examples
+{ q: "First" }
+{ author: { first_name: ["Ada", "Al"] } }
+```
+
+## Nested examples
+
+Top-level field range:
+```ruby
+ArticleQuery.new(filters: { published: { since: Time.utc(2024,1,1), until: Time.utc(2024,6,30) } }).results
+```
+
+Nested association field range:
+```ruby
+ArticleQuery.new(filters: { reviews: { published: (Time.utc(2024,1,1)..Time.utc(2024,6,30)) } }).results
+```
+
+Deep nested example (author → articles → reviews.published):
+```ruby
+class AuthorQuery
+  include Rokaki::FilterModel
+  filter_model :author
+  filter_map do
+    nested :articles do
+      nested :reviews do
+        filters :published
+      end
+    end
+  end
+  attr_accessor :filters
+  def initialize(filters: {}) ; @filters = filters ; end
+end
+
+AuthorQuery.new(filters: { articles: { reviews: { published: { max: Time.utc(2024,6,30) } } } }).results
+```
+
+## Dynamic runtime listener
+
+You can build a filter class at runtime from a payload (see Usage → Dynamic runtime listener). The same rules apply: the mapping fixes the join structure; leaf values drive operators.
+
+```ruby
+payload = {
+  model: :article, db: :postgres, query_key: :q,
+  like: { title: :circumfix, author: { first_name: :prefix } }
+}
+listener = Class.new do
+  include Rokaki::FilterModel
+  filter_model payload[:model], db: payload[:db]
+  define_query_key payload[:query_key]
+  filter_map { like payload[:like] }
+  attr_accessor :filters
+  def initialize(filters: {}) ; @filters = filters ; end
+end
+
+listener.new(filters: { q: "First" }).results
+```
+
+## Adapter behavior
+
+- Range/bounds predicates (`BETWEEN`, `>=`, `<=`) are adapter-agnostic; Rokaki binds parameters appropriately for PostgreSQL, MySQL, SQL Server, Oracle, and SQLite.
+- LIKE behavior is adapter-aware (e.g., Postgres `ANY(ARRAY[..])`, SQL Server `ESCAPE` clause, Oracle `UPPER()` for case-insensitive paths). See the Adapters page for details.
+
+## Quick reference
+
+- Join-structure keys: associations, declared in code, mirrored in payload structure; never carry operators.
+- Leaf-level keys: columns/fields, declared in code with `filters`, accept values that determine semantics.
+- Reserved leaf operator keys: `between`, `from`/`since`/`after`/`start`/`min`, `to`/`until`/`before`/`end`/`max`.
+- Arrays: always equality `IN`.
+- Ranges or operator-hash: range filtering.

data/docs/index.md

@@ -10,9 +10,11 @@ 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)
+- [Rokaki's DSL Syntax](./dsl-syntax)
 - [Database adapters](./adapters)
 - [Configuration](./configuration)
 
@@ -21,7 +23,7 @@ Get started below or jump to:
 Add to your application's Gemfile:
 
 ```ruby
-gem "rokaki", "~> 0.15"
+gem "rokaki", "~> 0.17"
 ```
 
 Then:
@@ -40,8 +42,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 +69,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/oracle.md

@@ -0,0 +1,138 @@
+---
+layout: page
+title: Oracle connections
+permalink: /adapters/oracle
+---
+
+This page collects Oracle‑specific connection tips for Rokaki (and ActiveRecord in general), including environment variables, client library notes, and how to avoid common errors during local development and CI runs.
+
+Rokaki uses ActiveRecord’s `oracle_enhanced` adapter and ruby‑oci8 under the hood. All examples below assume ActiveRecord 7.1–8.x as used by Rokaki.
+
+## Quick start: commands that work
+
+- Preferred full descriptor (stable across environments):
+
+```bash
+RBENV_VERSION=3.3.0 \
+ORACLE_USERNAME=system ORACLE_PASSWORD=oracle \
+NLS_LANG=AMERICAN_AMERICA.AL32UTF8 \
+ORACLE_DATABASE='(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=FREEPDB1)))' \
+bundle exec rspec spec/lib/04_oracle_aware_spec.rb --format documentation
+```
+
+- EZCONNECT (be sure to include the double slash prefix):
+
+```bash
+RBENV_VERSION=3.3.0 \
+ORACLE_DATABASE=//127.0.0.1:1521/FREEPDB1 \
+ORACLE_USERNAME=system ORACLE_PASSWORD=oracle \
+NLS_LANG=AMERICAN_AMERICA.AL32UTF8 \
+bundle exec rspec spec/lib/04_oracle_aware_spec.rb
+```
+
+Notes:
+- Oracle Free images typically expose a pluggable database (PDB) service named `FREEPDB1`.
+- Oracle XE images typically use `XEPDB1` instead.
+- If you hit listener errors (ORA‑12514/12521), verify the exact service via `lsnrctl status` inside your container and confirm host port mapping.
+
+## Environment variables Rokaki tests understand
+
+The spec helper accepts overrides which are passed to ActiveRecord’s connection config (see `spec/support/database_manager.rb`):
+
+- `ORACLE_HOST` — defaults to `localhost`
+- `ORACLE_PORT` — defaults to `1521`
+- `ORACLE_USERNAME` — database username
+- `ORACLE_PASSWORD` — database password
+- `ORACLE_DATABASE` — EZCONNECT or TNS/descriptor, takes precedence over `ORACLE_SERVICE_NAME`
+- `ORACLE_SERVICE_NAME` — service name (e.g., `FREEPDB1` or `XEPDB1`)
+- `NLS_LANG` — recommended: `AMERICAN_AMERICA.AL32UTF8`
+
+If only `ORACLE_SERVICE_NAME` is provided, Rokaki’s test helper composes a full descriptor automatically. If `ORACLE_DATABASE` is provided, it is used as‑is (recommended for EZCONNECT or explicit descriptors).
+
+## ruby‑oci8 and Instant Client
+
+- Build‑time (already set in this repo’s `.bundle/config`):
+
+```yaml
+BUNDLE_BUILD__RUBY___OCI8: "--with-instant-client-dir=/opt/oracle/instantclient_23_3 \
+  --with-instant-client-include=/opt/oracle/instantclient_23_3/sdk/include \
+  --with-instant-client-lib=/opt/oracle/instantclient_23_3"
+```
+
+- Runtime (set these if the client libraries aren’t found or you see NLS errors):
+
+macOS:
+```bash
+export DYLD_LIBRARY_PATH=/opt/oracle/instantclient_23_3:$DYLD_LIBRARY_PATH
+```
+Linux:
+```bash
+export LD_LIBRARY_PATH=/opt/oracle/instantclient_23_3:$LD_LIBRARY_PATH
+```
+Optional (explicit NLS data path):
+```bash
+export OCI_NLS10=/opt/oracle/instantclient_23_3/nls/data
+```
+
+## Common errors and fixes
+
+- ORA‑12705: Cannot access NLS data files or invalid environment specified
+  - Cause: invalid/missing NLS settings or client libraries not found.
+  - Fix: set `NLS_LANG=AMERICAN_AMERICA.AL32UTF8` (or leave unset), ensure Instant Client libraries are on `DYLD_LIBRARY_PATH` (macOS) or `LD_LIBRARY_PATH` (Linux). Optionally set `OCI_NLS10`.
+
+- ORA‑12514 / ORA‑12521: TNS:listener does not currently know of service requested in connect descriptor / service not registered
+  - Cause: wrong `SERVICE_NAME`, wrong host/port, container not exposing the service.
+  - Fix: run `lsnrctl status` inside the container; use the exact `SERVICE_NAME` (e.g., `FREEPDB1`), confirm host port mapping. For EZCONNECT, remember the `//` prefix: `//HOST:PORT/SERVICE`.
+
+- ORA‑01017: invalid username/password; logon denied
+  - Cause: wrong credentials for the target service/PDB.
+  - Fix: double‑check username/password; for tests you can connect as `SYSTEM` to bootstrap schema, or create a dedicated test user (see below).
+
+## Creating a dedicated test schema user
+
+From `SYSTEM` (connected to the target PDB service):
+
+```sql
+CREATE USER ROKAKI IDENTIFIED BY rokaki;
+GRANT CONNECT, RESOURCE, CREATE TABLE, CREATE SEQUENCE TO ROKAKI;
+ALTER USER ROKAKI QUOTA UNLIMITED ON USERS;
+```
+
+Then connect with:
+
+```bash
+ORACLE_USERNAME=ROKAKI ORACLE_PASSWORD=rokaki \
+ORACLE_DATABASE=//127.0.0.1:1521/FREEPDB1 \
+NLS_LANG=AMERICAN_AMERICA.AL32UTF8 \
+bundle exec rspec spec/lib/04_oracle_aware_spec.rb
+```
+
+## Rails `database.yml` examples
+
+Using `oracle_enhanced` with service name:
+
+```yaml
+production:
+  adapter: oracle_enhanced
+  host: <%= ENV["ORACLE_HOST"] || "localhost" %>
+  port: <%= (ENV["ORACLE_PORT"] || 1521).to_i %>
+  username: <%= ENV["ORACLE_USERNAME"] %>
+  password: <%= ENV["ORACLE_PASSWORD"] %>
+  service_name: <%= ENV["ORACLE_SERVICE_NAME"] || "FREEPDB1" %>
+```
+
+Using EZCONNECT/descriptor directly:
+
+```yaml
+production:
+  adapter: oracle_enhanced
+  username: <%= ENV["ORACLE_USERNAME"] %>
+  password: <%= ENV["ORACLE_PASSWORD"] %>
+  database: <%= ENV["ORACLE_DATABASE"] %> # e.g., //127.0.0.1:1521/FREEPDB1
+```
+
+## CI and local tips
+
+- Prefer the full `(DESCRIPTION=...)` form in CI to avoid resolver quirks.
+- On Oracle Free containers the default service is `FREEPDB1`; on XE it’s `XEPDB1`.
+- If your tests need to create tables, use a user with `CREATE TABLE` and `CREATE SEQUENCE` privileges (our specs do this automatically).

data/docs/usage.md

@@ -5,13 +5,14 @@ permalink: /usage
 ---
 
 This page shows how to use Rokaki to define filters and apply them to ActiveRecord relations.
+For a formal description of the mapping DSL and how payloads are interpreted (join structure vs leaf-level keys), see Rokaki's DSL Syntax: [/dsl-syntax](/dsl-syntax).
 
 ## Installation
 
 Add the gem to your Gemfile and bundle:
 
 ```ruby
-gem "rokaki", "~> 0.15"
+gem "rokaki", "~> 0.17"
 ```
 
 ```bash
@@ -31,8 +32,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
@@ -79,6 +81,83 @@ Each accepts a single string or an array of strings. Rokaki generates adapter‑
 - MySQL: `LIKE`/`LIKE BINARY` and, in nested-like contexts, `REGEXP` where designed
 - SQL Server: `LIKE` with safe escaping; arrays expand into OR chains of parameterized `LIKE` predicates
 
+## Range, BETWEEN, MIN, and MAX filters
+
+Rokaki supports range-style filters as normal filters (not aggregates) across all adapters. You don’t have to declare special operators per field — the value shape (and optional sub-keys) drive the behavior.
+
+Preferred syntax: use the field name as the key and the filter type as a sub-key. Aliases are supported.
+
+- Sub-keys:
+  - `between` → interpret the value as a range and generate `BETWEEN`/`>=`/`<=` as appropriate
+  - Lower bound aliases → `>=`: `from`, `since`, `after`, `start`, `min`
+  - Upper bound aliases → `<=`: `to`, `until`, `before`, `end`, `max`
+
+Accepted value shapes for `between` (also works when you pass a range directly as the field value):
+- Ruby `Range`: `1..10`, `Time.utc(2024,1,1)..Time.utc(2024,12,31)`
+- Two-element `Array`: `[from, to]` (only when wrapped with `{ between: [...] }`)
+- Hash with aliases: `{ from:, to: }`, `{ since:, until: }`, `{ after:, before: }`, `{ start:, end: }`
+
+Examples (top-level field):
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+  filter_model :article
+
+  # equality filters (existing)
+  filters :author_id, :published
+
+  # LIKEs (existing)
+  define_query_key :q
+  like title: :circumfix
+end
+
+# Between with a Range
+Article.filter(published: Date.new(2024,1,1)..Date.new(2024,12,31))
+
+# Between with a Hash + aliases
+Article.filter(published: { from: Date.new(2024,1,1), to: Date.new(2024,12,31) })
+Article.filter(published: { since: Date.new(2024,1,1), until: Date.new(2024,6,30) })
+
+# Open-ended bounds
+Article.filter(published: { min: Date.new(2024,1,1) })   # >= 2024-01-01
+Article.filter(published: { max: Date.new(2024,12,31) }) # <= 2024-12-31
+
+# Between with a two-element Array
+Article.filter(published: [Date.new(2024,5,1), Date.new(2024,12,1)])
+```
+
+Nested fields use the same sub-keys and value shapes:
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+  filter_model :article
+
+  filter_map do
+    nested :author do
+      # Range filters are value-driven; declaring the field enables the param key
+      filters :created_at   # enables :author_created_at
+    end
+
+    nested :reviews do
+      filters :published    # enables :reviews_published
+    end
+  end
+end
+
+# Params examples
+Article.filter(author_created_at: { from: Time.utc(2024,1,1), to: Time.utc(2024,6,30) })
+Article.filter(reviews_published: (Time.utc(2024,1,1)..Time.utc(2024,6,30)))
+```
+
+Behavior notes:
+- `min`/`max` are interpreted as lower/upper bounds, not aggregate functions.
+- Passing a `Range` or two-element `Array` directly as the field value is treated as a between filter automatically.
+- Arrays with more than two elements are treated as equality lists (`IN (?)`) — use `{ between: [...] }` if you intend a range.
+- `nil` bounds are ignored: only the provided side is applied (e.g., `{ from: t }` becomes `>= t`).
+- All generated predicates are parameterized and adapter‑agnostic (`BETWEEN`, `>=`, `<=`).
+
 ## Nested filters
 
 Use `nested :association` to scope filters to joined tables. Rokaki handles the necessary joins and qualified columns.
@@ -112,8 +191,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 +268,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 +330,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/basic_filter.rb

@@ -3,13 +3,16 @@
 module Rokaki
   module FilterModel
     class BasicFilter
-      def initialize(keys:, prefix:, infix:, like_semantics:, i_like_semantics:, db:)
+      def initialize(keys:, prefix:, infix:, like_semantics:, i_like_semantics:, db:, between_keys: nil, min_keys: nil, max_keys: nil)
         @keys = keys
         @prefix = prefix
         @infix = infix
         @like_semantics = like_semantics
         @i_like_semantics = i_like_semantics
         @db = db
+        @between_keys = Array(between_keys).compact
+        @min_keys = Array(min_keys).compact
+        @max_keys = Array(max_keys).compact
         @filter_query = nil
       end
       attr_reader :keys, :prefix, :infix, :like_semantics, :i_like_semantics, :db, :filter_query
@@ -83,12 +86,114 @@ module Rokaki
             key: key
           )
         else
-          query = "@model.where(#{key}: #{filter})"
+          # New preferred style: field => { between:/from:/to:/min:/max: }
+          # Also accept direct Range/Array/Hash with from/to aliases.
+          query = <<-RUBY
+            begin
+              _val = #{filter}
+              if _val.is_a?(Hash)
+                # Support wrapper keys like :between as well as bound aliases/min/max
+                _inner = _val
+                if _val.key?(:between) || _val.key?('between')
+                  _inner = _val[:between] || _val['between']
+                end
+                _from = _inner[:from] || _inner['from'] || _inner[:since] || _inner['since'] || _inner[:after] || _inner['after'] || _inner[:start] || _inner['start'] || _inner[:min] || _inner['min']
+                _to   = _inner[:to]   || _inner['to']   || _inner[:until] || _inner['until'] || _inner[:before] || _inner['before'] || _inner[:end]   || _inner['end']   || _inner[:max] || _inner['max']
+
+                if _from.nil? && _to.nil?
+                  # If hash contains range-like but with different container (e.g., { between: range })
+                  if _inner.is_a?(Range)
+                    _from = _inner.begin; _to = _inner.end
+                  elsif _inner.is_a?(Array)
+                    _from, _to = _inner[0], _inner[1]
+                  end
+                end
+
+                # Adjust inclusive end-of-day behavior if upper bound appears to be a date or midnight time
+                if !_to.nil? && (_to.is_a?(Date) && !_to.is_a?(DateTime) || (_to.respond_to?(:hour) && _to.hour == 0 && _to.min == 0 && _to.sec == 0))
+                  _to = (_to.respond_to?(:to_time) ? _to.to_time : _to) + 86399
+                end
+                if !_from.nil? && !_to.nil?
+                  @model.where("#{key} BETWEEN :from AND :to", from: _from, to: _to)
+                elsif !_from.nil?
+                  @model.where("#{key} >= :from", from: _from)
+                elsif !_to.nil?
+                  @model.where("#{key} <= :to", to: _to)
+                else
+                  # Fall back to equality with the original hash
+                  @model.where(#{key}: _val)
+                end
+              elsif _val.is_a?(Range)
+                #{build_between_query(filter: filter, key: key)}
+              else
+                # Equality and IN semantics for arrays and scalars (Arrays are always IN lists)
+                @model.where(#{key}: _val)
+              end
+            end
+          RUBY
         end
 
         @filter_query = query
       end
 
+      def build_between_query(filter:, key:)
+        # Accept [from, to], Range, or {from:, to:}
+        # Build appropriate where conditions with bound params
+        <<-RUBY
+          begin
+            _val = #{filter}
+            _from = _to = nil
+            if _val.is_a?(Range)
+              _from = _val.begin
+              _to = _val.end
+            elsif _val.is_a?(Array)
+              _from, _to = _val[0], _val[1]
+            elsif _val.is_a?(Hash)
+              # allow aliases for from/to
+              _from = _val[:from] || _val['from'] || _val[:since] || _val['since'] || _val[:after] || _val['after'] || _val[:start] || _val['start']
+              _to   = _val[:to]   || _val['to']   || _val[:until] || _val['until'] || _val[:before] || _val['before'] || _val[:end]   || _val['end']
+            else
+              # single value → equality
+              return @model.where(#{key}: _val)
+            end
+
+            if !_from.nil? && !_to.nil?
+              @model.where("#{key} BETWEEN :from AND :to", from: _from, to: _to)
+            elsif !_from.nil?
+              @model.where("#{key} >= :from", from: _from)
+            elsif !_to.nil?
+              @model.where("#{key} <= :to", to: _to)
+            else
+              @model
+            end
+          end
+        RUBY
+      end
+
+      def parse_range_semantics(key)
+        k = key.to_s
+        %w[_between _min _max _from _to _after _before _since _until _start _end].each do |suf|
+          if k.end_with?(suf)
+            base = k.sub(/#{Regexp.escape(suf)}\z/, '')
+            op = case suf
+                 when '_between' then :between
+                 when '_min' then :min
+                 when '_max' then :max
+                 when '_from','_after','_since','_start' then :from
+                 when '_to','_before','_until','_end' then :to
+                 else nil
+                 end
+            return [base, op]
+          end
+        end
+        [nil, nil]
+      end
+
+      def build_compare_query(op:, filter:, column:)
+        operator = (op == :'>=') ? '>=' : '<='
+        %Q{@model.where("#{column} #{operator} :v", v: #{filter})}
+      end
+
       # # @model.where('`authors`.`first_name` LIKE BINARY :query', query: "%teev%").or(@model.where('`authors`.`first_name` LIKE BINARY :query', query: "%imi%"))
       # if Array == filter
       #     first_term = filter.unshift

data/lib/rokaki/filter_model/nested_filter.rb

@@ -129,21 +129,17 @@ module Rokaki
           where_after.push(" }")
         end
 
-        joins = joins_before + joins_after
+        joins_arr = joins_before + joins_after
+        joins_str = joins_arr.join
 
         name += "#{leaf}"
-        where_middle = ["{ #{leaf}: #{prefix}#{name} }"]
-
-        where = where_before + where_middle + where_after
-        joins = joins.join
-        where = where.join
 
         if search_mode
           if db == :sqlserver || db == :oracle
             key_leaf = "#{keys.last.to_s.pluralize}.#{leaf}"
             helper = db == :sqlserver ? 'sqlserver_like' : 'oracle_like'
             @filter_methods << "def #{prefix}filter#{infix}#{name};"\
-              "#{helper}(@model.joins(#{joins}), \"#{key_leaf}\", \"#{type}\", #{prefix}#{name}, :#{search_mode}); end;"
+              "#{helper}(@model.joins(#{joins_str}), \"#{key_leaf}\", \"#{type}\", #{prefix}#{name}, :#{search_mode}); end;"
 
             @filter_templates << "@model = #{prefix}filter#{infix}#{name} if #{prefix}#{name};"
           else
@@ -157,14 +153,51 @@ module Rokaki
             )
 
             @filter_methods << "def #{prefix}filter#{infix}#{name};"\
-              "@model.joins(#{joins}).#{query}; end;"
+              "@model.joins(#{joins_str}).#{query}; end;"
 
             @filter_templates << "@model = #{prefix}filter#{infix}#{name} if #{prefix}#{name};"
           end
         else
-          @filter_methods << "def #{prefix}filter#{infix}#{name};"\
-            "@model.joins(#{joins}).where(#{where}); end;"
-
+          # Preferred: value Hash with sub-keys between/from/to/min/max; also accept Range/Array directly
+          qualified_col = "#{keys.last.to_s.pluralize}.#{leaf}"
+          body = <<-RUBY
+            begin
+              _val = #{prefix}#{name}
+              rel = @model.joins(#{joins_str})
+              if _val.is_a?(Hash)
+                _inner = _val
+                if _val.key?(:between) || _val.key?('between')
+                  _inner = _val[:between] || _val['between']
+                end
+                _from = _inner[:from] || _inner['from'] || _inner[:since] || _inner['since'] || _inner[:after] || _inner['after'] || _inner[:start] || _inner['start'] || _inner[:min] || _inner['min']
+                _to   = _inner[:to]   || _inner['to']   || _inner[:until] || _inner['until'] || _inner[:before] || _inner['before'] || _inner[:end]   || _inner['end']   || _inner[:max] || _inner['max']
+                if _from.nil? && _to.nil?
+                  if _inner.is_a?(Range)
+                    _from = _inner.begin; _to = _inner.end
+                  elsif _inner.is_a?(Array)
+                    _from, _to = _inner[0], _inner[1]
+                  end
+                end
+                if !_from.nil? && !_to.nil?
+                  rel.where("#{qualified_col} BETWEEN :from AND :to", from: _from, to: _to)
+                elsif !_from.nil?
+                  rel.where("#{qualified_col} >= :from", from: _from)
+                elsif !_to.nil?
+                  rel.where("#{qualified_col} <= :to", to: _to)
+                else
+                  rel.where("#{qualified_col} = :v", v: _val)
+                end
+              elsif _val.is_a?(Range)
+                rel.where("#{qualified_col} BETWEEN :from AND :to", from: _val.begin, to: _val.end)
+              elsif _val.is_a?(Array)
+                # Arrays represent IN semantics for equality; use BETWEEN only when explicitly wrapped via :between
+                rel.where("#{qualified_col} IN (?)", _val)
+              else
+                rel.where("#{qualified_col} = :v", v: _val)
+              end
+            end
+          RUBY
+          @filter_methods << "def #{prefix}filter#{infix}#{name};#{body}; end;"
           @filter_templates << "@model = #{prefix}filter#{infix}#{name} if #{prefix}#{name};"
         end
       end
@@ -182,6 +215,25 @@ module Rokaki
         query
       end
 
+      def parse_range_semantics(key)
+        k = key.to_s
+        %w[_between _min _max _from _to _after _before _since _until _start _end].each do |suf|
+          if k.end_with?(suf)
+            base = k.sub(/#{Regexp.escape(suf)}\z/, '')
+            op = case suf
+                 when '_between' then :between
+                 when '_min' then :from   # min → lower bound
+                 when '_max' then :to     # max → upper bound
+                 when '_from','_after','_since','_start' then :from
+                 when '_to','_before','_until','_end' then :to
+                 else nil
+                 end
+            return [base, op]
+          end
+        end
+        [nil, nil]
+      end
+
     end
   end
 end

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.17.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Steve Martin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-27 00:00:00.000000000 Z
+date: 2025-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -296,7 +296,9 @@ files:
 - docs/_config.yml
 - docs/adapters.md
 - docs/configuration.md
+- docs/dsl_syntax.md
 - docs/index.md
+- docs/oracle.md
 - docs/usage.md
 - lib/rokaki.rb
 - lib/rokaki/filter_model.rb