diff --git a/docs/source/connecting/connecting.md b/docs/source/connecting/connecting.md index 1522cb2571..0e53e4859e 100644 --- a/docs/source/connecting/connecting.md +++ b/docs/source/connecting/connecting.md @@ -35,6 +35,12 @@ async fn main() -> Result<(), Box> { 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` - 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.