Docs: Add recommendations about Session usage. #914
Conversation
docs/source/connecting/connecting.md
Outdated
| @@ -35,6 +35,12 @@ async fn main() -> Result<(), Box<dyn Error>> { | |||
| After successfully connecting to some specified node the driver will fetch topology information about | |||
| other nodes in this cluster and connect to them as well. | |||
|
|
|||
| Driver maintains this pool of connections and each connection is capable of handling multiple requests in parallel. Driver will also route the request to node / shard that actually owns the data (unless load balancing policy that you use doesn't support it). | |||
| For those reasons, we recommend to use one instance of `Session` per application. | |||
| Creating short-lived `Session`'s (e.g. `Session` per request) is extremely discouraged and will result in great performance penalties because creating a `Session` is a costly process - it requires estabilishing a lot of TCP connections. | |||
There was a problem hiding this comment.
IMO "extremely" is too strong of a word here. There are cases where short sessions make sense, e.g. an administrative tool that connects only to execute a single statement. Of course, creating multiple sessions over the course of the application is wasteful.
There was a problem hiding this comment.
I change to strongly, if that's also too strong I'll rewrite this sentence differently
There was a problem hiding this comment.
"Strongly" sounds better to me as well. I was mostly concerned about the "short-lived" sessions given the use cases for them I mentioned in my previous comment, but with the added warning about using only one session per application I think it looks OK now.
Lorak-mmk
changed the title
Lorak-mmk
force-pushed
the
session-usage-recommendations
branch
from
2fc8656 to
95330ed
Compare
|
v2:
|
|
v3: Fixed typo in preprocessor script |
This will make it easier to add new functionalities to it.
Lorak-mmk
force-pushed
the
session-usage-recommendations
branch
from
85cac1f to
f359ed1
Compare
#216 showed that best practices of
Sessionusage are not obvious and should be stated in documentation.This PR adds the relevant section that explains how to use it in order to not decrease performance.
Fixes: #216
Pre-review checklist
./docs/source/.Fixes:annotations to PR description.