feat: Add validation for incompatible R*Tree table options

ocean · ocean · commit 5e9894881b93 · 2026-01-08T10:16:00.000+11:00
- Add validate_rtree_options!/1 to explicitly reject incompatible options
- R*Tree virtual tables do not support :strict, :random_rowid, :without_rowid
- Add comprehensive tests for single and multiple incompatible options
- Update AGENTS.md to document incompatible options
- Update CHANGELOG.md to document validation behavior

Addresses feedback about options being silently ignored - now raises
clear ArgumentError with specific incompatible options listed.
diff --git a/AGENTS.md b/AGENTS.md
@@ -1107,7 +1107,7 @@ distance_sql = EctoLibSql.Native.vector_distance_cos("description_embedding", qu
 
 ### R*Tree Spatial Indexing
 
-R*Tree is a specialized spatial index for efficient multi-dimensional range queries. Perfect for geospatial data, collision detection, and time-series queries.
+R*Tree is a specialised spatial index for efficient multi-dimensional range queries. Perfect for geospatial data, collision detection, and time-series queries.
 
 #### Creating R*Tree Tables
 
@@ -1134,6 +1134,7 @@ end
 - Remaining columns come in min/max pairs (2D, 3D, 4D, or 5D)
 - Total columns must be odd (3, 5, 7, 9, or 11)
 - Minimum 3 columns (id + 1 dimension), maximum 11 columns (id + 5 dimensions)
+- R*Tree tables are virtual tables and do not support standard table options like `:strict`, `:random_rowid`, or `:without_rowid`
 
 #### 2D Example: Geographic Boundaries
 
@@ -1210,7 +1211,7 @@ result = Ecto.Adapters.SQL.query!(
   SELECT id FROM events
   WHERE max_x >= 90 AND min_x <= 110
     AND max_y >= 190 AND min_y <= 210
-    AND max_time >= #{query_start} AND min_time <= #{end_time}
+    AND max_time >= #{query_start} AND min_time <= #{query_end}
   """
 )
 ```
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,7 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Table creation**: Use `:rtree => true` option in Ecto migrations
   - **Dimensions supported**: 1D to 5D (3 to 11 columns total including ID)
   - **Column structure**: First column must be `id` (integer primary key), followed by min/max coordinate pairs
-  - **Validation**: Automatic validation of column count (odd numbers only), first-column requirements (must be 'id'), and dimensional constraints
+  - **Validation**: Automatic validation of column count (odd numbers only), first-column requirements (must be 'id'), dimensional constraints, and incompatible table options
+  - **Table options**: R*Tree virtual tables reject standard table options (`:strict`, `:random_rowid`, `:without_rowid`) with clear error messages
   - **Use cases**: Geographic bounding boxes, collision detection, time-range queries, spatial indexing
   - **Migration example**:
     ```elixir
@@ -28,7 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ```
   - **Query patterns**: Point containment, bounding box intersection, range queries
   - **Virtual table syntax**: Generates `CREATE VIRTUAL TABLE ... USING rtree(...)` DDL
-  - **Implementation**: New `create_rtree_table/3` and `validate_rtree_columns!/1` helpers in `connection.ex`
+  - **Implementation**: New `create_rtree_table/3`, `validate_rtree_options!/1`, and `validate_rtree_columns!/1` helpers in `connection.ex`
   - **Comprehensive test coverage** in `test/rtree_test.exs` covering 2D/3D tables, validation, queries, and CRUD operations
   - **Documentation**: Full guide in AGENTS.md with examples for geographic data, time-series, and hybrid vector+spatial search
   - **Comparison guide**: R*Tree vs Vector Search decision matrix in documentation
diff --git a/lib/ecto/adapters/libsql/connection.ex b/lib/ecto/adapters/libsql/connection.ex
@@ -186,6 +186,8 @@ defmodule Ecto.Adapters.LibSql.Connection do
 
     # Check if this is an R*Tree virtual table
     if table.options && Keyword.get(table.options, :rtree, false) do
+      # Validate that no incompatible options are set with :rtree
+      validate_rtree_options!(table.options)
       create_rtree_table(table_name, if_not_exists, columns)
     else
       # Standard table creation
@@ -502,6 +504,25 @@ defmodule Ecto.Adapters.LibSql.Connection do
     ]
   end
 
+  defp validate_rtree_options!(options) do
+    # R*Tree virtual tables are incompatible with standard table options
+    # Check for any non-:rtree options that would be silently ignored
+    incompatible_options =
+      Keyword.keys(options)
+      |> Enum.reject(&(&1 == :rtree))
+
+    unless Enum.empty?(incompatible_options) do
+      options_str = Enum.map_join(incompatible_options, ", ", &inspect/1)
+
+      raise ArgumentError,
+            "R*Tree virtual tables do not support standard table options. " <>
+              "Found incompatible options: #{options_str}. " <>
+              "R*Tree tables can only use the :rtree option."
+    end
+
+    :ok
+  end
+
   defp validate_rtree_columns!(columns) do
     # R*Tree requires odd number of columns (3 to 11)
     # First column is ID, then min/max pairs
diff --git a/test/rtree_test.exs b/test/rtree_test.exs
@@ -208,6 +208,51 @@ defmodule Ecto.RTreeTest do
         execute_ddl({:create, table, columns})
       end
     end
+
+    test "rejects R*Tree table with incompatible options" do
+      import Ecto.Adapters.LibSql.Connection
+
+      # Test with :strict option
+      table = %Ecto.Migration.Table{
+        name: :invalid_rtree,
+        prefix: nil,
+        options: [rtree: true, strict: true]
+      }
+
+      columns = [
+        {:add, :id, :integer, [primary_key: true]},
+        {:add, :min_lat, :float, []},
+        {:add, :max_lat, :float, []},
+        {:add, :min_lng, :float, []},
+        {:add, :max_lng, :float, []}
+      ]
+
+      assert_raise ArgumentError, ~r/do not support standard table options/, fn ->
+        execute_ddl({:create, table, columns})
+      end
+
+      # Test with :random_rowid option
+      table = %Ecto.Migration.Table{
+        name: :invalid_rtree,
+        prefix: nil,
+        options: [rtree: true, random_rowid: true]
+      }
+
+      assert_raise ArgumentError, ~r/Found incompatible options: :random_rowid/, fn ->
+        execute_ddl({:create, table, columns})
+      end
+
+      # Test with multiple incompatible options
+      table = %Ecto.Migration.Table{
+        name: :invalid_rtree,
+        prefix: nil,
+        options: [rtree: true, strict: true, random_rowid: true]
+      }
+
+      assert_raise ArgumentError, ~r/do not support standard table options/, fn ->
+        execute_ddl({:create, table, columns})
+      end
+    end
   end
 
   describe "R*Tree queries" do
