add rollback option to explain

Author: greg-rychlewski

integration_test/myxql/explain_test.exs

@@ -42,5 +42,19 @@ defmodule Ecto.Integration.ExplainTest do
       assert Enum.member?(keys, "select_id")
       assert Enum.member?(keys, "table")
     end
+
+    test "explain without rolling back" do
+      TestRepo.insert!(%Post{})
+      assert [%Post{}] = TestRepo.all(Post)
+
+      {:ok, {:ok, explain}} =
+        TestRepo.transaction(fn ->
+          TestRepo.explain(:delete_all, Post, analyze: true, rollback: false, timeout: 20000)
+        end)
+
+      assert explain =~ "DELETE"
+      assert explain =~ "p0"
+      assert TestRepo.all(Post) == []
+    end
   end
 end

integration_test/pg/explain_test.exs

@@ -81,4 +81,18 @@ defmodule Ecto.Integration.ExplainTest do
     assert explain =~ ~r/Node Type:/
     assert explain =~ ~r/Relation Name:/
   end
+
+  test "explain without rolling back" do
+    TestRepo.insert!(%Post{})
+    assert [%Post{}] = TestRepo.all(Post)
+
+    {:ok, {:ok, explain}} =
+      TestRepo.transaction(fn ->
+        TestRepo.explain(:delete_all, Post, analyze: true, rollback: false, timeout: 20000)
+      end)
+
+    assert explain =~ "Delete on posts p0"
+    assert explain =~ "cost="
+    assert TestRepo.all(Post) == []
+  end
 end

lib/ecto/adapters/sql.ex

@@ -434,8 +434,8 @@ defmodule Ecto.Adapters.SQL do
 
   Adapter          | Supported opts
   ---------------- | --------------
-  Postgrex         | `analyze`, `verbose`, `costs`, `settings`, `buffers`, `timing`, `summary`, `format`, `plan`
-  MyXQL            | `format`
+  Postgrex         | `analyze`, `verbose`, `costs`, `settings`, `buffers`, `timing`, `summary`, `format`, `plan`, `rollback`
+  MyXQL            | `format`, `rollback`
 
   All options except `format` are boolean valued and default to `false`.
 
@@ -447,6 +447,10 @@ defmodule Ecto.Adapters.SQL do
     * Postgrex: `:map`, `:yaml` and `:text`
     * MyXQL: `:map` and `:text`
 
+  The `rollback` option is a boolean that controls whether the command is run inside of a transaction
+  that is rolled back. This is useful when, for example, you'd like to use `analyze: true` on an update
+  or delete query without modifying data. Defaults to `true`.
+
   The `:plan` option in Postgrex can take the values `:custom` or `:fallback_generic`. When `:custom`
   is specified, the explain plan generated will consider the specific values of the query parameters
   that are supplied. When using `:fallback_generic`, the specific values of the query parameters will
@@ -508,10 +512,11 @@ defmodule Ecto.Adapters.SQL do
   def explain(repo, operation, queryable, opts \\ [])
 
   def explain(repo, operation, queryable, opts) when is_atom(repo) or is_pid(repo) do
-    explain(Ecto.Adapter.lookup_meta(repo), operation, queryable, opts)
+    rollback? = Keyword.get(opts, :rollback, true)
+    explain(Ecto.Adapter.lookup_meta(repo), operation, queryable, rollback?, opts)
   end
 
-  def explain(%{repo: repo} = adapter_meta, operation, queryable, opts) do
+  def explain(%{repo: repo} = adapter_meta, operation, queryable, true, opts) do
     Ecto.Multi.new()
     |> Ecto.Multi.run(:explain, fn _, _ ->
       {prepared, prepared_params} = to_sql(operation, repo, queryable)
@@ -528,6 +533,11 @@ defmodule Ecto.Adapters.SQL do
     end
   end
 
+  def explain(%{repo: repo} = adapter_meta, operation, queryable, false, opts) do
+    {prepared, prepared_params} = to_sql(operation, repo, queryable)
+    sql_call(adapter_meta, :explain_query, [prepared], prepared_params, opts)
+  end
+
   @doc @disconnect_all_doc
   @spec disconnect_all(
           pid | Ecto.Repo.t() | Ecto.Adapter.adapter_meta(),