From 888c6e22d6d1b7af71acc6ce4fe76f0897f81e2f Mon Sep 17 00:00:00 2001 From: Zhen Li Date: Mon, 2 Oct 2017 15:29:52 +0200 Subject: [PATCH 1/6] Conn Pool management and load balancing strategy New sections in Config for introducing settings for connection pool management and load balancing strategy --- src/main/asciidoc/client-applications.adoc | 95 ++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/src/main/asciidoc/client-applications.adoc b/src/main/asciidoc/client-applications.adoc index 1fc60095..9216d33c 100644 --- a/src/main/asciidoc/client-applications.adoc +++ b/src/main/asciidoc/client-applications.adoc @@ -363,6 +363,101 @@ include::{python-examples}/config_trust_example.py[tags=config-trust] ==== +[[driver-config-connection-pool-management]] +=== Connection pool management + +The driver maintains a pool of connections. The pooled connections are reused by sessions and transaction to avoid overhead added by establishing new connections every time to run a query. +The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled connections are then reused by new sessions and transactions to execute queries. + +Three connection pool related configuration settings are exposed via driver configuration, namely `maxConnectionLifetime`, `maxConnectionPoolSize` and `connectionAcquisitionTimeout`. +Application users could tune these settings to fit the driver into application adoption based on appliation's performace requirement and resourse consumption limit on remote servers. + +The detailed description of the available connection pool settings are listed bellow: + +* `maxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. + +* `maxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver (with “bolt” uri scheme) this sets the max amount of connections towards a single database. While for routing driver (with “bolt+routing” uri scheme) this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. + +* `connectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. + +[.tabbed-example] +.Connection pool management +==== +[.include-with-dotnet] +====== +[source, csharp] +---- +include::{dotnet-examples}/Examples.cs[tags=config-connection-pool] +---- +====== + +[.include-with-java] +====== +[source, java] +---- +include::{java-examples}/ConfigConnectionPoolExample.java[tags=config-connection-pool] +---- +====== + +[.include-with-javascript] +====== +[source, javascript] +---- +include::{javascript-examples}/examples.test.js[tags=config-connection-pool] +---- +====== + +[.include-with-python] +====== +[source, python] +---- +include::{python-examples}/config_connection_pool_example.py[tags=config-connection-pool] +---- +====== +==== + + +[[driver-load-balancing-strategy]] +=== Load balancing strategy +For the routing driver, the driver contains a simple load balancer to route queries evenly among many cluster members. The built-in load balancer provides two strategies: `Least-connected` (Default) and `round-robin`. The `least-connection` strategy in general gives a better performance as it takes query execution time and server load into consideration when distrbuting queries among the cluster memebers. The 1.5 drivers adopt `least-connected` as default load balancing strategy. + +[.tabbed-example] +.Load balancing strategy +==== +[.include-with-dotnet] +====== +[source, csharp] +---- +include::{dotnet-examples}/Examples.cs[tags=config-load-balancing-strategy] +---- +====== + +[.include-with-java] +====== +[source, java] +---- +include::{java-examples}/ConfigLoadBalancingStrategyExample.java[tags=config-load-balancing-strategy] +---- +====== + +[.include-with-javascript] +====== +[source, javascript] +---- +include::{javascript-examples}/examples.test.js[tags=config-load-balancing-strategy] +---- +====== + +[.include-with-python] +====== +[source, python] +---- +include::{python-examples}/config_load_balancing_strategy_example.py[tags=config-load-balancing-strategy] +---- +====== +==== + + [[driver-configuration-connection-timeout]] === Connection timeout From 45aced7f78f33f57063b5948c6fc5ea094427b11 Mon Sep 17 00:00:00 2001 From: Zhen Date: Mon, 2 Oct 2017 17:40:33 +0200 Subject: [PATCH 2/6] Adds a new config `MaxIdleConnectionPoolSize` --- src/main/asciidoc/client-applications.adoc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/main/asciidoc/client-applications.adoc b/src/main/asciidoc/client-applications.adoc index 9216d33c..95677d4b 100644 --- a/src/main/asciidoc/client-applications.adoc +++ b/src/main/asciidoc/client-applications.adoc @@ -367,18 +367,21 @@ include::{python-examples}/config_trust_example.py[tags=config-trust] === Connection pool management The driver maintains a pool of connections. The pooled connections are reused by sessions and transaction to avoid overhead added by establishing new connections every time to run a query. -The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled connections are then reused by new sessions and transactions to execute queries. +The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled idle connections are then reused by new sessions and transactions to execute queries. -Three connection pool related configuration settings are exposed via driver configuration, namely `maxConnectionLifetime`, `maxConnectionPoolSize` and `connectionAcquisitionTimeout`. -Application users could tune these settings to fit the driver into application adoption based on appliation's performace requirement and resourse consumption limit on remote servers. +The driver exposes a few connection pool related configuration settings, which client builders could adjust when adopting the driver based on client performace requirement and resourse consumption limit of remote servers. The detailed description of the available connection pool settings are listed bellow: -* `maxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. +* `MaxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. + +* `MaxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. The total pool size includes both the connections that are used by sessions and/or transactions and idle connections buffered by the pool. For direct driver, this sets the max amount of connections towards a single database. While for routing driver, this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is returned to the pool or the request to acquire a new connection times out (where an `ClientException` will be thrown). The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. + +* `MaxIdleConnectionPoolSize` - This setting configures the maximum amount of idle connections buffered by the pool per host. When the pool has reached its max idle connection pool size, the connections that are ready to be returned to the pool will be closed directly rather than buffered by the pool. Configure this value higher for greater concurrency for spike demamds, or lower to reduce the pressure on remote server for maintaining unactive resources. For most usecases, we recommend setting this value to be the same as `MaxConnectionPoolSize` so that let the pool act as a fixed size connection pool. + +* `ConnectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. -* `maxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver (with “bolt” uri scheme) this sets the max amount of connections towards a single database. While for routing driver (with “bolt+routing” uri scheme) this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. -* `connectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. [.tabbed-example] .Connection pool management From 933be6a268531a7c617a16ae61b5da473ab2308d Mon Sep 17 00:00:00 2001 From: Zhen Date: Tue, 3 Oct 2017 14:31:54 +0200 Subject: [PATCH 3/6] Revert "Adds a new config `MaxIdleConnectionPoolSize`" This reverts commit 45aced7f78f33f57063b5948c6fc5ea094427b11. --- src/main/asciidoc/client-applications.adoc | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/main/asciidoc/client-applications.adoc b/src/main/asciidoc/client-applications.adoc index 95677d4b..9216d33c 100644 --- a/src/main/asciidoc/client-applications.adoc +++ b/src/main/asciidoc/client-applications.adoc @@ -367,21 +367,18 @@ include::{python-examples}/config_trust_example.py[tags=config-trust] === Connection pool management The driver maintains a pool of connections. The pooled connections are reused by sessions and transaction to avoid overhead added by establishing new connections every time to run a query. -The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled idle connections are then reused by new sessions and transactions to execute queries. +The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled connections are then reused by new sessions and transactions to execute queries. -The driver exposes a few connection pool related configuration settings, which client builders could adjust when adopting the driver based on client performace requirement and resourse consumption limit of remote servers. +Three connection pool related configuration settings are exposed via driver configuration, namely `maxConnectionLifetime`, `maxConnectionPoolSize` and `connectionAcquisitionTimeout`. +Application users could tune these settings to fit the driver into application adoption based on appliation's performace requirement and resourse consumption limit on remote servers. The detailed description of the available connection pool settings are listed bellow: -* `MaxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. - -* `MaxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. The total pool size includes both the connections that are used by sessions and/or transactions and idle connections buffered by the pool. For direct driver, this sets the max amount of connections towards a single database. While for routing driver, this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is returned to the pool or the request to acquire a new connection times out (where an `ClientException` will be thrown). The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. - -* `MaxIdleConnectionPoolSize` - This setting configures the maximum amount of idle connections buffered by the pool per host. When the pool has reached its max idle connection pool size, the connections that are ready to be returned to the pool will be closed directly rather than buffered by the pool. Configure this value higher for greater concurrency for spike demamds, or lower to reduce the pressure on remote server for maintaining unactive resources. For most usecases, we recommend setting this value to be the same as `MaxConnectionPoolSize` so that let the pool act as a fixed size connection pool. - -* `ConnectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. +* `maxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. +* `maxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver (with “bolt” uri scheme) this sets the max amount of connections towards a single database. While for routing driver (with “bolt+routing” uri scheme) this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. +* `connectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. [.tabbed-example] .Connection pool management From 3969d79f93e1d49ca81d0d771b97005349fa49f3 Mon Sep 17 00:00:00 2001 From: Zhen Date: Tue, 3 Oct 2017 15:00:58 +0200 Subject: [PATCH 4/6] Pending for default value of MaxConnPoolSize --- src/main/asciidoc/client-applications.adoc | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/main/asciidoc/client-applications.adoc b/src/main/asciidoc/client-applications.adoc index 9216d33c..af68e656 100644 --- a/src/main/asciidoc/client-applications.adoc +++ b/src/main/asciidoc/client-applications.adoc @@ -367,18 +367,17 @@ include::{python-examples}/config_trust_example.py[tags=config-trust] === Connection pool management The driver maintains a pool of connections. The pooled connections are reused by sessions and transaction to avoid overhead added by establishing new connections every time to run a query. -The connections in the pool are created on demand. The connection pool always start with no pooled connection. New connections are created on demand by sessions and/or transactions. When sessions and/or transactions finished using connections, healthy ones are returned to the pool. These pooled connections are then reused by new sessions and transactions to execute queries. +The connection pool always start with an empty pool. New connections are created on demand by sessions and transactions to run queries. When a sessions or a transaction has done query execution with a connection, the connection will be returned to the pool to be reused. -Three connection pool related configuration settings are exposed via driver configuration, namely `maxConnectionLifetime`, `maxConnectionPoolSize` and `connectionAcquisitionTimeout`. -Application users could tune these settings to fit the driver into application adoption based on appliation's performace requirement and resourse consumption limit on remote servers. +Application users could tune connection pool settings to fit the driver for different usecases based on client performace requirement and database resourse consumption limit. -The detailed description of the available connection pool settings are listed bellow: +The detailed description of the available connection pool settings via driver configuratoin are listed bellow: -* `maxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. +* `MaxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. -* `maxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver (with “bolt” uri scheme) this sets the max amount of connections towards a single database. While for routing driver (with “bolt+routing” uri scheme) this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. +* `MaxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver this sets the max amount of connections towards a single database. While for routing driver this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. -* `connectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. +* `ConnectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. [.tabbed-example] .Connection pool management From 619bb428b3ec6b36b84baec330059b6e4d193d6c Mon Sep 17 00:00:00 2001 From: Zhen Date: Thu, 5 Oct 2017 11:45:23 +0200 Subject: [PATCH 5/6] Final final change to default value of new settings!!! --- src/main/asciidoc/client-applications.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/asciidoc/client-applications.adoc b/src/main/asciidoc/client-applications.adoc index af68e656..63fb0225 100644 --- a/src/main/asciidoc/client-applications.adoc +++ b/src/main/asciidoc/client-applications.adoc @@ -373,9 +373,9 @@ Application users could tune connection pool settings to fit the driver for diff The detailed description of the available connection pool settings via driver configuratoin are listed bellow: -* `MaxConnectionLifetime` - Default value: Infinite. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its adopted application network infrastructure (such as router, load balancer, proxy, firewall, etc.). No maximum lifetime limit is imposed by default. Zero and negative values result in lifetime not being checked. +* `MaxConnectionLifetime` - Default value: 1h. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its application system infrastructure (such as operation system, router, load balancer, proxy, firewall, etc.). Negative values result in lifetime not being checked. -* `MaxConnectionPoolSize` - Default value: Infinite. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver this sets the max amount of connections towards a single database. While for routing driver this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. +* `MaxConnectionPoolSize` - Default value: a large number such as 100 but vary in drivers. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver this sets the max amount of connections towards a single database. While for routing driver this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. * `ConnectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. From a397a8071340c75add10d522ca780c7f19efef1b Mon Sep 17 00:00:00 2001 From: mariascharin Date: Wed, 11 Oct 2017 13:40:10 +0200 Subject: [PATCH 6/6] Editorial changes --- src/main/asciidoc/client-applications.adoc | 80 ++++++++++++------- .../asciidoc/sessions-and-transactions.adoc | 1 - 2 files changed, 52 insertions(+), 29 deletions(-) diff --git a/src/main/asciidoc/client-applications.adoc b/src/main/asciidoc/client-applications.adoc index 63fb0225..38b8ed79 100644 --- a/src/main/asciidoc/client-applications.adoc +++ b/src/main/asciidoc/client-applications.adoc @@ -366,18 +366,38 @@ include::{python-examples}/config_trust_example.py[tags=config-trust] [[driver-config-connection-pool-management]] === Connection pool management -The driver maintains a pool of connections. The pooled connections are reused by sessions and transaction to avoid overhead added by establishing new connections every time to run a query. -The connection pool always start with an empty pool. New connections are created on demand by sessions and transactions to run queries. When a sessions or a transaction has done query execution with a connection, the connection will be returned to the pool to be reused. +The driver maintains a pool of connections. +The pooled connections are reused by sessions and transactions to avoid the overhead added by establishing new connections for every query. +The connection pool always starts up empty. +New connections are created on demand by sessions and transactions. +When a session or a transaction is done with its execution, the connection will be returned to the pool to be reused. + +Application users can tune connection pool settings to configure the driver for different use cases based on client performance requirements and database resource consumption limits. + +Detailed descriptions of connection pool settings available via driver configuration are listed below: + +`MaxConnectionLifetime`:: +Pooled connections older than this threshold will be closed and removed from the pool. +Such removal happens during connection acquisition so that new session is never backed by an old connection. +Setting this option to a low value will cause a high connection churn and might result in a performance drop. +It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its application system infrastructure (such as operation system, router, load balancer, proxy and firewall). +Negative values result in lifetime not being checked. +Default value: 1h. + +`MaxConnectionPoolSize`:: +This setting defines the maximum total number of connections allowed to be managed by the connection pool on each host. +In other words, for a direct driver, this sets the maximum amount of connections towards a single database. +For a routing driver this sets the maximum amount of connections towards each cluster member. +If a session or transaction tries to acquire a connection at a time when the pool size is at its full capacity, it must wait until a free connection is available in the pool or the request to acquire a new connection times out. +The connection acquiring timeout is configured via `ConnectionAcquisitionTimeout`. +Default value: This is different for different drivers, but is a number in the order of 100. + +`ConnectionAcquisitionTimeout`:: +This setting limits the amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. +The exception thrown in this case is `ClientException`. +Timeout only applies when connection pool is at its max capacity. +Default value: 1m. -Application users could tune connection pool settings to fit the driver for different usecases based on client performace requirement and database resourse consumption limit. - -The detailed description of the available connection pool settings via driver configuratoin are listed bellow: - -* `MaxConnectionLifetime` - Default value: 1h. Pooled connections older than this threshold will be closed and removed from the pool. Such removal happens during connection acquisition so that new session is never backed by an old connection. Setting this option to a low value will cause a high connection churn and might result in a performance drop. It is recommended to set driver's maximum lifetime to a value smaller than the maximum lifetime configured in its application system infrastructure (such as operation system, router, load balancer, proxy, firewall, etc.). Negative values result in lifetime not being checked. - -* `MaxConnectionPoolSize` - Default value: a large number such as 100 but vary in drivers. It defines the maximum total number of connections allowed to be managed by the connection pool per host. In other words, for direct driver this sets the max amount of connections towards a single database. While for routing driver this sets the max amount of connections towards each cluster member. When a session or transaction tries to acquire connection and pool is at its full capacity, then the session or transaction has to wait until a free connection is availble in the pool or the request to acquire a new connection times out. The connection acquiring timeout is configured via `connectionAcquisitionTimeout`. - -* `ConnectionAcquisitionTimeout` - Default value: 1m. This setting limits amount of time a session or transaction can spend waiting for a free connection to appear in the pool before throwing an exception. Exception in this case is `ClientException`. Timeout only applies when connection pool is at its max capacity. [.tabbed-example] .Connection pool management @@ -416,18 +436,20 @@ include::{python-examples}/config_connection_pool_example.py[tags=config-connect ==== -[[driver-load-balancing-strategy]] -=== Load balancing strategy -For the routing driver, the driver contains a simple load balancer to route queries evenly among many cluster members. The built-in load balancer provides two strategies: `Least-connected` (Default) and `round-robin`. The `least-connection` strategy in general gives a better performance as it takes query execution time and server load into consideration when distrbuting queries among the cluster memebers. The 1.5 drivers adopt `least-connected` as default load balancing strategy. +[[driver-configuration-connection-timeout]] +=== Connection timeout + +To configure the maximum time allowed to establish a connection, pass a duration value to the driver configuration. +For example: [.tabbed-example] -.Load balancing strategy +.Connection timeout ==== [.include-with-dotnet] ====== [source, csharp] ---- -include::{dotnet-examples}/Examples.cs[tags=config-load-balancing-strategy] +include::{dotnet-examples}/Examples.cs[tags=config-connection-timeout] ---- ====== @@ -435,7 +457,7 @@ include::{dotnet-examples}/Examples.cs[tags=config-load-balancing-strategy] ====== [source, java] ---- -include::{java-examples}/ConfigLoadBalancingStrategyExample.java[tags=config-load-balancing-strategy] +include::{java-examples}/ConfigConnectionTimeoutExample.java[tags=config-connection-timeout] ---- ====== @@ -443,7 +465,7 @@ include::{java-examples}/ConfigLoadBalancingStrategyExample.java[tags=config-loa ====== [source, javascript] ---- -include::{javascript-examples}/examples.test.js[tags=config-load-balancing-strategy] +This feature is not available in the Javascript driver. ---- ====== @@ -451,26 +473,28 @@ include::{javascript-examples}/examples.test.js[tags=config-load-balancing-strat ====== [source, python] ---- -include::{python-examples}/config_load_balancing_strategy_example.py[tags=config-load-balancing-strategy] +include::{python-examples}/config_connection_timeout_example.py[tags=config-connection-timeout] ---- ====== ==== -[[driver-configuration-connection-timeout]] -=== Connection timeout +[[driver-load-balancing-strategy]] +=== Load balancing strategy -To configure the maximum time allowed to establish a connection, pass a duration value to the driver configuration. -For example: +A routing driver contains a load balancer to route queries evenly among many cluster members. +The built-in load balancer provides two strategies: `least-connected` and `round-robin`. +The `least-connected` strategy in general gives a better performance as it takes query execution time and server load into consideration when distributing queries among the cluster members. +Default value: `least-connected`. [.tabbed-example] -.Connection timeout +.Load balancing strategy ==== [.include-with-dotnet] ====== [source, csharp] ---- -include::{dotnet-examples}/Examples.cs[tags=config-connection-timeout] +include::{dotnet-examples}/Examples.cs[tags=config-load-balancing-strategy] ---- ====== @@ -478,7 +502,7 @@ include::{dotnet-examples}/Examples.cs[tags=config-connection-timeout] ====== [source, java] ---- -include::{java-examples}/ConfigConnectionTimeoutExample.java[tags=config-connection-timeout] +include::{java-examples}/ConfigLoadBalancingStrategyExample.java[tags=config-load-balancing-strategy] ---- ====== @@ -486,7 +510,7 @@ include::{java-examples}/ConfigConnectionTimeoutExample.java[tags=config-connect ====== [source, javascript] ---- -This feature is not available in the Javascript driver. +include::{javascript-examples}/examples.test.js[tags=config-load-balancing-strategy] ---- ====== @@ -494,7 +518,7 @@ This feature is not available in the Javascript driver. ====== [source, python] ---- -include::{python-examples}/config_connection_timeout_example.py[tags=config-connection-timeout] +include::{python-examples}/config_load_balancing_strategy_example.py[tags=config-load-balancing-strategy] ---- ====== ==== diff --git a/src/main/asciidoc/sessions-and-transactions.adoc b/src/main/asciidoc/sessions-and-transactions.adoc index 6cf0d452..6e204a00 100644 --- a/src/main/asciidoc/sessions-and-transactions.adoc +++ b/src/main/asciidoc/sessions-and-transactions.adoc @@ -288,7 +288,6 @@ include::{python-examples}/read_write_transaction_example.py[tags=read-write-tra ====== ==== --- == Asynchronous programming