Skip to content

Commit

Permalink
Docs: Add recommendations about Sessions usage.
Browse files Browse the repository at this point in the history
  • Loading branch information
Lorak-mmk committed Jan 14, 2024
1 parent e86823b commit 2fc8656
Showing 1 changed file with 6 additions and 0 deletions.
6 changes: 6 additions & 0 deletions docs/source/connecting/connecting.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Creating many `Session`'s in one application (e.g. `Session` per thread / per Tokio taks) is also discouraged, because it wastes resources - as mentioned before, `Session` maintains connection pool itself and can handle parallel queries, so you would be holding a lot of connections unnecessarily.
If you need to share `Session` to different threads / Tokio tasks etc. use `Arc<Session>` - all methods of `Session` take `&self`, so it doesn't hinder the functionality in any way. In order to avoid cost of `Arc`'s atomic operations, you can estabilish all your `Arc`'s in the beggining as the atomic operations only happend when cloning `Arc`, not when using it's inner object.

The driver refreshes the cluster metadata periodically, which contains information about cluster topology as well as the cluster schema. By default, the driver refreshes the cluster metadata every 60 seconds.
However, you can set the `cluster_metadata_refresh_interval` to a non-negative value to periodically refresh the cluster metadata. This is useful when you do not have unexpected amount of traffic or when you have an extra traffic causing topology to change frequently.

Expand Down

0 comments on commit 2fc8656

Please sign in to comment.