Add format option for PostgreSQL explain (#295)

Author: pawurb

integration_test/pg/explain_test.exs

@@ -26,4 +26,27 @@ defmodule Ecto.Integration.ExplainTest do
       TestRepo.explain(:all, Post, analyze: "1")
     end)
   end
+
+  test "explain JSON format" do
+    [explain] = TestRepo.explain(:all, Post, analyze: true, verbose: true, timeout: 20000, format: :json) |> Jason.decode!()
+    keys = explain["Plan"] |> Map.keys
+    assert Enum.member?(keys, "Actual Loops")
+    assert Enum.member?(keys, "Actual Rows")
+    assert Enum.member?(keys, "Actual Startup Time")
+  end
+
+  test "explain MAP format" do
+    [explain] = TestRepo.explain(:all, Post, analyze: true, verbose: true, timeout: 20000, format: :map)
+    keys = explain["Plan"] |> Map.keys
+    assert Enum.member?(keys, "Actual Loops")
+    assert Enum.member?(keys, "Actual Rows")
+    assert Enum.member?(keys, "Actual Startup Time")
+  end
+
+  test "explain YAML format" do
+    explain = TestRepo.explain(:all, Post, analyze: true, verbose: true, timeout: 20000, format: :yaml)
+    assert explain =~ ~r/Plan:/
+    assert explain =~ ~r/Node Type:/
+    assert explain =~ ~r/Relation Name:/
+  end
 end

lib/ecto/adapters/postgres/connection.ex

@@ -253,10 +253,21 @@ if Code.ensure_loaded?(Postgrex) do
     @impl true
     def explain_query(conn, query, params, opts) do
       {explain_opts, opts} =
-        Keyword.split(opts, ~w[analyze verbose costs settings buffers timing summary]a)
+        Keyword.split(opts, ~w[analyze verbose costs settings buffers timing summary format]a)
+
+      json_format? = {:format, :json} in explain_opts
+      map_format? = {:format, :map} in explain_opts
 
       case query(conn, build_explain_query(query, explain_opts), params, opts) do
-        {:ok, %Postgrex.Result{rows: rows}} -> {:ok, Enum.map_join(rows, "\n", & &1)}
+        {:ok, %Postgrex.Result{rows: rows}} when json_format? ->
+          case Jason.encode(List.flatten(rows)) do
+            {:ok, json} -> {:ok, json}
+            {:error, error} -> error
+          end
+        {:ok, %Postgrex.Result{rows: rows}} when map_format? ->
+          {:ok, List.flatten(rows)}
+        {:ok, %Postgrex.Result{rows: rows}} ->
+          {:ok, Enum.map_join(rows, "\n", & &1)}
         error -> error
       end
     end
@@ -289,6 +300,9 @@ if Code.ensure_loaded?(Postgrex) do
               {_, nil}, acc ->
                 acc
 
+              {:format, value}, acc ->
+                [String.upcase("#{format_to_sql(value)}") | acc]
+
               {opt, value}, acc ->
                 [String.upcase("#{opt} #{quote_boolean(value)}") | acc]
             end)
@@ -1229,6 +1243,11 @@ if Code.ensure_loaded?(Postgrex) do
     defp quote_boolean(false), do: "FALSE"
     defp quote_boolean(value), do: error!(nil, "bad boolean value #{value}")
 
+    defp format_to_sql(:text), do: "FORMAT TEXT"
+    defp format_to_sql(:json), do: "FORMAT JSON"
+    defp format_to_sql(:map), do: "FORMAT JSON"
+    defp format_to_sql(:yaml), do: "FORMAT YAML"
+
     defp single_quote(value), do: [?', escape_string(value), ?']
 
     defp intersperse_map(list, separator, mapper, acc \\ [])

lib/ecto/adapters/sql.ex

@@ -281,8 +281,7 @@ defmodule Ecto.Adapters.SQL do
 
   Also note that:
 
-    * `FORMAT` isn't supported at the moment and the only possible output
-      is a textual format, so you may want to call `IO.puts/1` to display it;
+    * Currently `:json`, `:map`, `:yaml` and `:text` format options are supported for PostgreSQL
     * Any other value passed to `opts` will be forwarded to the underlying
       adapter query function, including Repo shared options such as `:timeout`;
     * Non built-in adapters may have specific behavior and you should consult