Concurrent & remaining docs suggestions#16
Merged
krylosov-aa merged 8 commits intokrylosov-aa:mainfrom Jan 12, 2026
Merged
Conversation
index getting started problem it solves Base docs suggestions as per the commit message. Will open a separate PR for the other stuff I'd suggest in general.
…eferences sections, including the text represnted in code which has been COMMENTED OUT, NOT THE CODE ITSELF
I changed tenses to maintain present tense. The second POV is standard for docs, and it maintains consistency with the rest of your wording. Like "login" (noun) and "log in" (verb) , "rollback" and "rollsback" function as two different kinds of word. "rollback", the function and API call, is a noun. "Rolls back" is the verb, the act of calling a rollback. This is another docs standard thing so the user can tell whether you're describing a thing or telling them that thing is happening. Some of the API calls you named are clear enough not to need to redescribe them as a separate line. (gg!) Under run_in_new_ctx, used the code tag for "callable_func" even if it's an example, so it sticks out and is clear it needs to be an API call. If I made changes to the text about the code but that text was replicated inside code examples, I made those changes there, too. I did NOT touch anything else about your examples and the actual code therein. I tested all my work to make sure that didn't happen, but please feel free to call me on it if I messed that up. "An example of a handle that uses a session in context, but commits manually and even closes the session to release the connection" -> "An example of a handle that uses a session in context, but commits manually and closes the session to release the connection." "And here we closed the session = returned the connection to the pool. This is useful if, for example, at the beginning of the handle a database query is needed, and then there is some other long-term work and you don't want to keep the connection opened" -> "We closed the session and returned the connection to the pool" and "Use if you have more work you need to complete without keeping the connection open." "You don't have to use the context to work with sessions at all" -> "Using the context is option while working with sessions" "In some situations, you need to have multiple sessions running simultaneously" -> "You may need to run multiple sessions simultaneously" "transaction will be automatically rolled back" -> "transactions roll back automatically" "You can manually commit the transaction if you want, but it is not necessary" -> "manually commits the transaction (optional)" "You can close the session if you want, but it is not necessary" -> "manually closes the session (optional)"
Docs Changes to API Reference Section - index.html (API) - api.md Changes made - Tightening sentences - Small formatting changes (made a list toward the top of the section for readability - Small wording changes for the same reason - "rollback" as an API call and "rolling back" or "roll back" as a verb are unfortunately different and while the difference looks petty, it's a standard docs practice (e.g., "login" vs. "log in"). Really think you made a cool thing.
…aster_replica and concurrent_queries
krylosov-aa
approved these changes
Jan 12, 2026
Owner
|
Hi! I've merged your changes and tried to synchronize them into I also changed the text of the section about multiple hosts, as I realized that my thought was not conveyed correctly enough. If you have time, please take a look again that everything is correct now. Thank you so much for your contribution! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
One thing worth mentioning: when you used an ordered list, you closed that list as soon as the first item was done. The list actually stays open until you're done with it unlike paragraphs do. When you have a lot of text for a line item, you can usually reword it, stick it in a table instead to separate all the data cleanly, or you can use a nested list (which also stay open until the nested list ends for the bullet point its a part of):
< p>There are two ways to test:< /p>
<--- and done< ol>
< li>1. separate sessions:<---- note it doesn't close here
< ul>
< li>good for complexity <---you do close this one bc it's the nested list
< li>inspect the database while testing is paused< /li>
< /ul> <--- this is the closing of the next>
< /li> <--- this is the closing of the list item 1
< li>2. shared sessions and transactions <--- keep open again
< ul>
< li>faster < /li> <---like before
< /li>closing of list item 2
I used a nested list to avoid repeating yourself on why both have good use cases and why you use both methods.