Add {:unsafe_fragment, ...} support to RETURNING clause

[henryzhan013]

Summary

This lets you pass raw SQL fragments to the RETURNING clause, just like you already can with conflict_target.

Why

PostgreSQL supports expressions in RETURNING — things like:

RETURNING id, (price != EXCLUDED.price) AS was_updated

But Ecto only accepts column names for :returning, which all get quoted as identifiers. If you try passing a string with an expression, it becomes "(price != EXCLUDED.price) AS was_updated" which is invalid.

I ran into this working on ash_postgres where we need to detect whether an upsert actually updated a row or was skipped due to conflict conditions. Right now that requires an extra query. With this change, we can do it in one shot by returning a computed expression.

Changes

One new function clause in returning/1:

defp returning({:unsafe_fragment, fragment}),
  do: [" RETURNING ", fragment]

This is the same pattern conflict_target/1 already uses (line 284), so there's precedent for it. Existing code using lists of column names works exactly as before.

[josevalim]

Can you please add this to tds as well? It has a similar defp returning clause.

Also please send a PR to elixir-ecto/ecto itself that updates the docs!