Feature explain query support

.beads/last-touched

@@ -1 +1 @@
-el-4ha
+el-ffc

CHANGELOG.md

@@ -97,6 +97,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ```
   - 9 new CTE tests covering simple, recursive, and edge cases
 
+- **EXPLAIN QUERY PLAN Support**
+  - Full support for SQLite's `EXPLAIN QUERY PLAN` via Ecto's `Repo.explain/2` and `Repo.explain/3`
+  - **Query detection**: Rust NIF `should_use_query()` now detects EXPLAIN statements for proper query/execute routing
+  - **Ecto.Multi compatibility**: `explain_query/4` callback returns `{:ok, maps}` tuple format required by Ecto.Multi
+  - **Output format**: Returns list of maps with `id`, `parent`, `notused`, and `detail` keys matching SQLite's output
+  - **Usage examples**:
+    ```elixir
+    # Basic EXPLAIN QUERY PLAN
+    {:ok, plan} = Repo.explain(:all, from(u in User, where: u.active == true))
+    # Returns: [%{"id" => 2, "parent" => 0, "notused" => 0, "detail" => "SCAN users"}]
+
+    # With options
+    {:ok, plan} = Repo.explain(:all, query, analyze: true)
+
+    # Direct SQL execution
+    {:ok, _, result, _state} = EctoLibSql.handle_execute(
+      "EXPLAIN QUERY PLAN SELECT * FROM users WHERE id = ?",
+      [1],
+      [],
+      state
+    )
+    ```
+  - **Implementation**: Query detection in `utils.rs:should_use_query()`, SQL generation in `connection.ex:explain_query/4`
+  - **Test coverage**: 12 tests across `explain_simple_test.exs` and `explain_query_test.exs`
+
 ## [0.8.3] - 2025-12-29
 
 ### Added

SECURITY.md

@@ -0,0 +1,112 @@
+# Security
+
+## Vulnerability Mitigation
+
+### CVE-2025-47736: libsql-sqlite3-parser UTF-8 Crash
+
+**Status:** MITIGATED
+**Severity:** Low
+**Affected Component:** `libsql-sqlite3-parser` ≤ 0.13.0 (transitive dependency via `libsql`)
+
+#### Vulnerability Description
+
+The `libsql-sqlite3-parser` crate through version 0.13.0 can crash when processing invalid UTF-8 input in SQL queries. This vulnerability is documented in [CVE-2025-47736](https://advisories.gitlab.com/pkg/cargo/libsql-sqlite3-parser/CVE-2025-47736/).
+
+#### Our Mitigation Strategy
+
+**ecto_libsql is NOT vulnerable** to this CVE due to multiple layers of defence:
+
+##### 1. **Type System Protection (Primary Defence)**
+- All SQL strings in our Rust NIF code use Rust's `&str` type
+- Rust's type system guarantees that `&str` contains valid UTF-8
+- Any attempt to create invalid UTF-8 in Rust would fail at compile time
+
+##### 2. **Rustler Validation (Secondary Defence)**
+- Rustler (our NIF bridge) validates UTF-8 when converting Elixir binaries to Rust strings
+- Invalid UTF-8 from Elixir would cause NIF conversion errors before reaching our code
+- These errors are caught and returned to Elixir as error tuples
+
+##### 3. **Explicit Validation (Defence-in-Depth)**
+- We've added explicit UTF-8 validation at all SQL entry points:
+  - `prepare_statement/2` in `statement.rs`
+  - `declare_cursor/3` in `cursor.rs`
+  - `execute_batch_native/3` in `batch.rs`
+- This validation provides:
+  - Explicit documentation of security guarantees
+  - Additional safety layer against future changes
+  - Clear audit trail for security reviews
+
+#### Implementation Details
+
+The `validate_utf8_sql/1` function in `native/ecto_libsql/src/utils.rs` (lines 13-60) performs the validation:
+
+```rust
+pub fn validate_utf8_sql(sql: &str) -> Result<(), rustler::Error> {
+    // Validates UTF-8 boundaries and character indices
+    // Returns descriptive errors for any invalid sequences
+}
+```
+
+This validation is called at the start of every NIF function that accepts SQL, before the SQL reaches `libsql-sqlite3-parser`.
+
+#### Why This Vulnerability Doesn't Affect Us
+
+Even without our explicit validation (layer 3), the vulnerability cannot be triggered because:
+
+1. **Elixir strings are UTF-8:** Elixir enforces UTF-8 for all string literals and string operations
+2. **Rustler enforces UTF-8:** Converting from Elixir to Rust `&str` validates UTF-8
+3. **Type safety:** Rust's `&str` cannot contain invalid UTF-8 by definition
+
+The explicit validation we've added serves as **defence-in-depth** and **documentation** of our security posture.
+
+#### Upstream Fix Status
+
+The vulnerability is fixed in commit `14f422a` of `libsql-sqlite3-parser`, but this fix has not been released to crates.io yet. Once a new version is published, we will:
+
+1. Update our `libsql` dependency (which will pull in the fixed parser)
+2. Continue to maintain our explicit validation as defence-in-depth
+3. Update this document with the new version information
+
+#### Testing
+
+Our test suite includes UTF-8 validation coverage:
+- All named parameter tests exercise the validation code paths
+- Invalid UTF-8 would be caught by Rustler before reaching our code
+- Our validation function is called on every SQL query
+
+#### Reporting Security Issues
+
+If you discover a security vulnerability in ecto_libsql, please email the maintainers directly rather than opening a public issue. See our [CONTRIBUTING.md](CONTRIBUTING.md) for contact information.
+
+## Security Best Practices
+
+When using ecto_libsql in your applications:
+
+1. **Use parameterised queries:** Always use Ecto's parameter binding (`?` or `:param`) instead of string interpolation
+2. **Validate input:** Validate user input at application boundaries before passing to database queries
+3. **Keep dependencies updated:** Regularly update ecto_libsql and Ecto to get security fixes
+4. **Use encryption:** Enable encryption for sensitive data using the `:encryption_key` option
+5. **Secure credentials:** Store Turso auth tokens in environment variables, not in source code
+
+## Dependency Security
+
+We use the following tools to monitor dependency security:
+
+- **Dependabot:** Automated vulnerability scanning on GitHub
+- **cargo audit:** Rust dependency vulnerability checking
+- **mix audit:** Elixir dependency vulnerability checking
+
+Run security audits locally:
+
+```bash
+# Rust dependencies
+cd native/ecto_libsql && cargo audit
+
+# Elixir dependencies (requires mix_audit)
+mix deps.audit
+```
+
+## Changelog
+
+- **2026-01-07:** Added explicit UTF-8 validation as defence against CVE-2025-47736
+- **2025-12-30:** v0.5.0 - Eliminated all `.unwrap()` calls in production code (CVE-prevention)

lib/ecto/adapters/libsql/connection.ex

@@ -694,9 +694,25 @@ defmodule Ecto.Adapters.LibSql.Connection do
 
   @impl true
   def explain_query(conn, query, params, opts) do
-    sql = all(query)
-    explain_sql = IO.iodata_to_binary(["EXPLAIN QUERY PLAN " | sql])
-    execute(conn, explain_sql, params, opts)
+    # The query parameter is the prepared SQL string generated by Ecto
+    # Prepend "EXPLAIN QUERY PLAN" to get the optimiser plan
+    sql = IO.iodata_to_binary(["EXPLAIN QUERY PLAN " | query])
+
+    # EXPLAIN QUERY PLAN returns rows, so use query() path not execute()
+    case query(conn, sql, params, opts) do
+      {:ok, result} ->
+        # Convert result to list of maps for Ecto's explain consumption
+        # Return {:ok, maps} - Ecto.Multi requires this format
+        maps =
+          Enum.map(result.rows, fn row ->
+            Enum.zip(result.columns, row) |> Enum.into(%{})
+          end)
+
+        {:ok, maps}
+
+      error ->
+        error
+    end
   end
 
   @impl true

lib/ecto_libsql.ex

@@ -152,11 +152,154 @@ defmodule EctoLibSql do
         query when is_binary(query) -> %EctoLibSql.Query{statement: query}
       end
 
-    if trx_id do
-      EctoLibSql.Native.execute_with_trx(state, query_struct, args)
-    else
-      EctoLibSql.Native.execute_non_trx(query_struct, state, args)
+    # Check if query returns rows (SELECT, EXPLAIN, WITH, RETURNING clauses).
+    # If so, route through query path instead of execute path.
+    sql = query_struct.statement
+
+    case EctoLibSql.Native.should_use_query_path(sql) do
+      true ->
+        # Query returns rows, use the query path.
+        # Convert map arguments to list if needed (NIFs expect lists).
+        normalised_args = normalise_args_for_query(sql, args)
+
+        if trx_id do
+          EctoLibSql.Native.query_with_trx_args(trx_id, state.conn_id, sql, normalised_args)
+          |> format_query_result(state)
+        else
+          EctoLibSql.Native.query_args(
+            state.conn_id,
+            state.mode,
+            state.sync,
+            sql,
+            normalised_args
+          )
+          |> format_query_result(state)
+        end
+
+      false ->
+        # Query doesn't return rows, use the execute path (INSERT/UPDATE/DELETE).
+        # Note: execute_with_trx and execute_non_trx handle argument normalisation internally.
+        if trx_id do
+          EctoLibSql.Native.execute_with_trx(state, query_struct, args)
+        else
+          EctoLibSql.Native.execute_non_trx(query_struct, state, args)
+        end
+    end
+  end
+
+  # Helper to format raw query results for return
+  defp format_query_result(%{"columns" => columns, "rows" => rows, "num_rows" => num_rows}, state) do
+    result = %EctoLibSql.Result{
+      columns: columns,
+      rows: rows,
+      num_rows: num_rows
+    }
+
+    {:ok, %EctoLibSql.Query{}, result, state}
+  end
+
+  defp format_query_result({:error, reason}, state) do
+    error = build_error(reason)
+    {:error, error, state}
+  end
+
+  # Build an EctoLibSql.Error from various reason formats.
+  defp build_error(%EctoLibSql.Error{} = error), do: error
+
+  defp build_error(reason) when is_binary(reason) do
+    %EctoLibSql.Error{message: reason, sqlite: %{code: :error, message: reason}}
+  end
+
+  defp build_error(reason) when is_map(reason) do
+    message = Map.get(reason, :message) || Map.get(reason, "message") || inspect(reason)
+    %EctoLibSql.Error{message: message, sqlite: %{code: :error, message: message}}
+  end
+
+  defp build_error(reason) do
+    message = inspect(reason)
+    %EctoLibSql.Error{message: message, sqlite: %{code: :error, message: message}}
+  end
+
+  # Convert map arguments to a list by extracting named parameters from SQL.
+  # If args is already a list, return it unchanged.
+  defp normalise_args_for_query(_sql, args) when is_list(args), do: args
+
+  defp normalise_args_for_query(sql, args) when is_map(args) do
+    # Extract named parameters from SQL in order of appearance.
+    # Supports :name, $name, and @name formats.
+    param_names = extract_named_params(sql)
+
+    # Validate that all parameters exist in the map and collect missing ones.
+    missing_params =
+      Enum.filter(param_names, fn name ->
+        not has_param?(args, name)
+      end)
+
+    # Raise error if any parameters are missing.
+    if missing_params != [] do
+      missing_list = Enum.map_join(missing_params, ", ", &":#{&1}")
+
+      raise ArgumentError,
+            "Missing required parameters: #{missing_list}. " <>
+              "SQL requires: #{Enum.map_join(param_names, ", ", &":#{&1}")}"
     end
+
+    # Convert map values to list in parameter order.
+    Enum.map(param_names, fn name ->
+      get_param_value(args, name)
+    end)
+  end
+
+  # Check if a parameter exists in the map (supports both atom and string keys).
+  # Uses String.to_existing_atom/1 to avoid atom table exhaustion from dynamic SQL.
+  defp has_param?(map, name) when is_binary(name) do
+    # Try existing atom key first (common case), then string key.
+    try do
+      atom_key = String.to_existing_atom(name)
+      Map.has_key?(map, atom_key) or Map.has_key?(map, name)
+    rescue
+      ArgumentError ->
+        # Atom doesn't exist, check string key only.
+        Map.has_key?(map, name)
+    end
+  end
+
+  # Get a parameter value from a map, supporting both atom and string keys.
+  # Uses String.to_existing_atom/1 to avoid atom table exhaustion from dynamic SQL.
+  # This assumes the parameter exists (validated by has_param?).
+  defp get_param_value(map, name) when is_binary(name) do
+    # Try existing atom key first (common case), then string key.
+    atom_key = String.to_existing_atom(name)
+    Map.get(map, atom_key, Map.get(map, name))
+  rescue
+    ArgumentError ->
+      # Atom doesn't exist, try string key only.
+      Map.get(map, name)
+  end
+
+  # Extract named parameter names from SQL in order of appearance.
+  # Returns a list of strings to avoid atom table exhaustion from dynamic SQL.
+  #
+  # LIMITATION: This regex-based approach cannot distinguish between parameter-like
+  # patterns in SQL string literals or comments and actual parameters. For example:
+  #
+  #   SELECT ':not_a_param', name FROM users WHERE id = :actual_param
+  #
+  # Would extract both "not_a_param" and "actual_param", even though the first
+  # appears in a string literal. This is an edge case that would require a full
+  # SQL parser to handle correctly (tracking quoted strings, escaped characters,
+  # and comment blocks). In practice, this limitation rarely causes issues because:
+  # 1. SQL string literals containing parameter-like patterns are uncommon
+  # 2. The validation will catch truly missing parameters
+  # 3. Extra entries in the parameter list are ignored during binding
+  #
+  # If this becomes problematic, consider using a proper SQL parser or the
+  # prepared statement introspection approach used in lib/ecto_libsql/native.ex.
+  defp extract_named_params(sql) do
+    # Match :name, $name, or @name patterns.
+    ~r/[:$@]([a-zA-Z_][a-zA-Z0-9_]*)/
+    |> Regex.scan(sql)
+    |> Enum.map(fn [_full, name] -> name end)
   end
 
   @impl true