-
Notifications
You must be signed in to change notification settings - Fork 161
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation proposal: Insert Returning example #636
Comments
This is a good idea. It's a common question. I will take care of it next time I'm working on doc. Thanks! |
Yes, I second this request. I just spent a ton of time figuring out how to do this before finding the solution in 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 |
Thirded. It's not easily discoverable from the docs as is. |
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.
The text was updated successfully, but these errors were encountered: