Documentation proposal: Insert Returning example

[hibikir]

In my experience, it's a common question for new devs on DB libraries is how to handle inserts that return ids: Do you handle them as commands or queries, and similar things. In fact, I've had this question asked in company slacks a few times regarding skunk. As far as I can tell, the documentation doesn't seem to mention "Insert returning" at all, and the only time it's used in tests, it's in a case where it's supposed to exception out, so it's not even the greatest of examples.

I think that we can make onboarding easier, and cut down on questions, by putting an example of insert returning in the main documentation. I'd even be happy to write it if it'd take too much of a maintainers time.

Given the current shape of the documentation, If I was making the decision, I'd consider some the following edits:
-A single sentence addition on the Queries section, to indicate that we should use query whenever there's an expected return value, regardless of whether the operation is a pure select, or an insert.
-An actual example of an insert returning inside of query, possibly as its own section
-A mention in the command section that if one wants to insert while returning some of the values, to used query instead.

But since I am not really owning the documentation, and only volunteering some time, I'd be happy to make any/all of the three changes, or any others that might be recommended. Or you could just close this, or make the changes without me. I just don't want to go through the work if it's not in a shape that would merge.

[tpolecat]

This is a good idea. It's a common question. I will take care of it next time I'm working on doc. Thanks!

[porcinity]

Yes, I second this request. I just spent a ton of time figuring out how to do this before finding the solution in Session.scala.

It's surprising to me that you have to use query even if you're issuing a command in the same statement.

This is made even more confusing when you consider how Gabriel Volpe uses .as(id) at the end a few commands in his book. See, for instance, pages 154 and 159 of Practical FP in Scala.

[wonk1132]

Thirded. It's not easily discoverable from the docs as is.