Improve docs and error for Ecto.Repo.delete_all/2 (#4211)

lib/ecto/query/planner.ex

@@ -1995,6 +1995,10 @@ defmodule Ecto.Query.Planner do
                   havings: [], preloads: [], assocs: [], distinct: nil, lock: nil,
                   windows: [], combinations: []} ->
         query
+      _ when operation == :delete_all ->
+        error! query, "`#{operation}` allows only `with_cte`, `where`, `select`, and `join` expressions. " <>
+                      "You can exclude unwanted expressions from a query by using " <>
+                      "Ecto.Query.exclude/2. Error found"
       _ ->
         error! query, "`#{operation}` allows only `with_cte`, `where` and `join` expressions. " <>
                       "You can exclude unwanted expressions from a query by using " <>

lib/ecto/repo.ex

@@ -1202,7 +1202,11 @@ defmodule Ecto.Repo do
 
       MyRepo.delete_all(Post)
 
-      from(p in Post, where: p.id < 10) |> MyRepo.delete_all
+      from(p in Post, where: p.id < 10) |> MyRepo.delete_all()
+
+      # With returning results, if supported by the database.
+      {_count, posts} = from(p in Post, where: p.id < 10, select: p) |> MyRepo.delete_all()
+
   """
   @doc group: "Query API"
   @callback delete_all(queryable :: Ecto.Queryable.t(), opts :: Keyword.t()) ::

test/ecto/query/planner_test.exs

@@ -1760,7 +1760,7 @@ defmodule Ecto.Query.PlannerTest do
       from(p in Post, update: [set: [name: "foo"]]) |> normalize(:delete_all)
     end
 
-    message = ~r"`delete_all` allows only `with_cte`, `where` and `join` expressions"
+    message = ~r"`delete_all` allows only `with_cte`, `where`, `select`, and `join` expressions"
     assert_raise Ecto.QueryError, message, fn ->
       from(p in Post, order_by: p.title) |> normalize(:delete_all)
     end