docs: internal connection pool for Spring apps #869

sergiyvamz · 2024-02-02T20:50:25Z

Summary

docs: internal connection pool for Spring apps

Additional Reviewers

@karenc-bq
@crystall-bitquill
@aaronchung-bitquill

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

docs/using-the-jdbc-driver/ConfigurationPresets.md

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

karenc-bq · 2024-02-05T18:55:34Z

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md


 When a method with this annotation is hit, Spring calls conn.setReadOnly(true), executes the method, and then calls setReadOnly(false) to restore the connection's initial readOnly value. Consequently, every time the method is called, the plugin switches to the reader, executes the method, and then switches back to the writer. Although the reader connection will be cached after the first setReadOnly call, there is still some overhead when switching between the cached writer/reader connections. This constant switching is not an ideal use of the plugin because it is frequently incurring this overhead. The suggested approach for this scenario is to avoid loading the read/write splitting plugin and instead use the writer cluster URL for your write operations and the reader cluster URL for your read operations. By doing this you avoid the overhead of constantly switching between connections while still spreading load across the database instances in your cluster. 

 #### Internal connection pools

-We recommend that you do not enable internal connection pools when using Spring. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior.
+We recommend that you do not enable internal connection pools when using Spring with default datasource configuration. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior. A Spring application should enable internal connection pool only. That's a recommended configuration.


Should we add a link for default deatasource configuration? Not exactly sure what the default configuration is

I rewrote this part. I hope it's a bit cleaner now.

karenc-bq · 2024-02-05T18:57:43Z

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md


 When a method with this annotation is hit, Spring calls conn.setReadOnly(true), executes the method, and then calls setReadOnly(false) to restore the connection's initial readOnly value. Consequently, every time the method is called, the plugin switches to the reader, executes the method, and then switches back to the writer. Although the reader connection will be cached after the first setReadOnly call, there is still some overhead when switching between the cached writer/reader connections. This constant switching is not an ideal use of the plugin because it is frequently incurring this overhead. The suggested approach for this scenario is to avoid loading the read/write splitting plugin and instead use the writer cluster URL for your write operations and the reader cluster URL for your read operations. By doing this you avoid the overhead of constantly switching between connections while still spreading load across the database instances in your cluster. 

 #### Internal connection pools

-We recommend that you do not enable internal connection pools when using Spring. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior.
+We recommend that you do not enable internal connection pools when using Spring with default datasource configuration. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior. A Spring application should enable internal connection pool only. That's a recommended configuration.


Suggested change

We recommend that you do not enable internal connection pools when using Spring with default datasource configuration. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior. A Spring application should enable internal connection pool only. That's a recommended configuration.

We recommend that you **disable** internal connection pools when using Spring with default datasource configuration. Spring by default uses its own external connection pool. The use of both internal and external pools has not been tested and may result in problematic behaviour. A Spring application should enable internal connection pool only. That's a recommended configuration.

I don't understand the last sentence. A Spring application should enable internal connection pool only. That's a recommended configuration. but the first sentence said to not use internal connection pool when using Spring with default datasource configuration.

I rewrote this part. I hope it's a bit cleaner now.

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

karenc-bq · 2024-02-05T19:04:28Z

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

+## Example
+[ReadWriteSplittingPostgresExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingPostgresExample.java) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver.
+
+[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver. This example application uses a configuration with internal connection pool and provides a load-balanced reader connection according to a specified reader selection strategy. `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` play in collaboration in this example.


Suggested change

[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver. This example application uses a configuration with internal connection pool and provides a load-balanced reader connection according to a specified reader selection strategy. `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` play in collaboration in this example.

[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure Read/Write Splitting plugin with the AWS JDBC Driver. This example application uses a configuration with internal connection pool and provides a load-balanced reader connection according to a specified reader selection strategy. `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` play in collaboration in this example.

Adding on top of Karen's suggestion:

Suggested change

[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver. This example application uses a configuration with internal connection pool and provides a load-balanced reader connection according to a specified reader selection strategy. `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` play in collaboration in this example.

[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure the Read/Write Splitting plugin with the AWS JDBC Driver. This example application uses a configuration with internal connection pooling and provides a load-balanced reader connection according to a specified reader selection strategy. The `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` annotation are both used in this example.

I'm not entirely sure what the last sentence means, does this sound right?

I've changed this sentence. Please take a look.

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

crystall-bitquill · 2024-02-05T20:09:27Z

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

+## Example
+[ReadWriteSplittingPostgresExample.java](../../../examples/AWSDriverExample/src/main/java/software/amazon/ReadWriteSplittingPostgresExample.java) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver.
+
+[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver. This example application uses a configuration with internal connection pool and provides a load-balanced reader connection according to a specified reader selection strategy. `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` play in collaboration in this example.


Adding on top of Karen's suggestion:

Suggested change

[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure read/write splitting with the Aws Advanced JDBC Driver. This example application uses a configuration with internal connection pool and provides a load-balanced reader connection according to a specified reader selection strategy. `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` play in collaboration in this example.

[SpringHibernateBalancedReaderOneDataSourceExample](../../../examples/SpringHibernateBalancedReaderOneDataSourceExample/README.md) demonstrates how to enable and configure the Read/Write Splitting plugin with the AWS JDBC Driver. This example application uses a configuration with internal connection pooling and provides a load-balanced reader connection according to a specified reader selection strategy. The `Read/Write Splitting Plugin` and `@Transactional(readOnly = True)` annotation are both used in this example.

I'm not entirely sure what the last sentence means, does this sound right?

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

docs/using-the-jdbc-driver/ConfigurationPresets.md

crystall-bitquill · 2024-02-06T20:26:25Z

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md


 When a method with this annotation is hit, Spring calls conn.setReadOnly(true), executes the method, and then calls setReadOnly(false) to restore the connection's initial readOnly value. Consequently, every time the method is called, the plugin switches to the reader, executes the method, and then switches back to the writer. Although the reader connection will be cached after the first setReadOnly call, there is still some overhead when switching between the cached writer/reader connections. This constant switching is not an ideal use of the plugin because it is frequently incurring this overhead. The suggested approach for this scenario is to avoid loading the read/write splitting plugin and instead use the writer cluster URL for your write operations and the reader cluster URL for your read operations. By doing this you avoid the overhead of constantly switching between connections while still spreading load across the database instances in your cluster. 

 #### Internal connection pools

-We recommend that you do not enable internal connection pools when using Spring. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior.
+We recommend that you explicitly disable internal connection pools when using Spring. You can check `spring.datasource.type` property to ensure that an external connection pooling is disabled. By default, Spring uses datasource auto-detection, and it may enable external connection pool. The use of both internal and external pools has not been tested and may result in problematic behaviour. A Spring application should enable internal connection pool only. That's a recommended configuration.


Does this paragraph mean that internal connection pooling isn't recommended to use, but if they are used, users should disable Spring's external connection pooling? And that both internal and external connection pooling shouldn't be used together? If that's the case, how does this sound:

Suggested change

We recommend that you explicitly disable internal connection pools when using Spring. You can check `spring.datasource.type` property to ensure that an external connection pooling is disabled. By default, Spring uses datasource auto-detection, and it may enable external connection pool. The use of both internal and external pools has not been tested and may result in problematic behaviour. A Spring application should enable internal connection pool only. That's a recommended configuration.

We recommend that you explicitly disable internal connection pools when using Spring. However, if you do use the driver's internal connection pooling, you can check the `spring.datasource.type` property to ensure that any external connection pooling is disabled. This is necessary because Spring uses datasource auto-detection by default, and it may enable external connection pooling. Using internal and external pools at the same time has not been tested and may result in problematic behaviour. The recommended configuration for a Spring application should either enable internal connection pooling or external connection pooling, but not both at once.

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md

Co-authored-by: crystall-bitquill <[email protected]>

…ttingPlugin.md

…ttingPlugin.md Co-authored-by: crystall-bitquill <[email protected]>

joyc-bq

lgtm

Co-authored-by: crystall-bitquill <[email protected]>

sergiyvamz changed the title ~~[WIP] docs: internal connection pool for Spring apps~~ docs: internal connection pool for Spring apps Feb 2, 2024

karenc-bq reviewed Feb 5, 2024

View reviewed changes

docs/using-the-jdbc-driver/ConfigurationPresets.md Outdated Show resolved Hide resolved

karenc-bq reviewed Feb 5, 2024

View reviewed changes

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md Outdated Show resolved Hide resolved

karenc-bq reviewed Feb 5, 2024

View reviewed changes

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md Outdated Show resolved Hide resolved

karenc-bq reviewed Feb 5, 2024

View reviewed changes

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md Outdated Show resolved Hide resolved

crystall-bitquill reviewed Feb 5, 2024

View reviewed changes

crystall-bitquill reviewed Feb 6, 2024

View reviewed changes

sergiyvamz commented Feb 6, 2024

View reviewed changes

docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSplittingPlugin.md Outdated Show resolved Hide resolved

crystall-bitquill approved these changes Feb 6, 2024

View reviewed changes

sergiyvamz and others added 7 commits February 6, 2024 13:07

docs: internal connection pool for Spring apps

65ef60d

code review

4026f22

code review

2cf9676

Update docs/using-the-jdbc-driver/ConfigurationPresets.md

508cd58

Co-authored-by: crystall-bitquill <[email protected]>

Update docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSpli…

7aa574f

…ttingPlugin.md

Update docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSpli…

6f5ca05

…ttingPlugin.md Co-authored-by: crystall-bitquill <[email protected]>

Update docs/using-the-jdbc-driver/using-plugins/UsingTheReadWriteSpli…

34c0abe

…ttingPlugin.md Co-authored-by: crystall-bitquill <[email protected]>

sergiyvamz force-pushed the rw-splitting-doc branch from 70dec97 to 34c0abe Compare February 6, 2024 21:07

sergiyvamz merged commit aba7e6b into main Feb 6, 2024

sergiyvamz deleted the rw-splitting-doc branch February 6, 2024 21:08

joyc-bq reviewed Feb 7, 2024

View reviewed changes

jasonli-improving pushed a commit to Bit-Quill/aws-advanced-jdbc-wrapper that referenced this pull request Feb 9, 2024

docs: internal connection pool for Spring apps (aws#869)

7e51ce8

Co-authored-by: crystall-bitquill <[email protected]>

	We recommend that you do not enable internal connection pools when using Spring with default datasource configuration. This is because Spring by default uses its own external connection pool. The use of both internal and external pools is not tested and may result in problematic behavior. A Spring application should enable internal connection pool only. That's a recommended configuration.
	We recommend that you disable internal connection pools when using Spring with default datasource configuration. Spring by default uses its own external connection pool. The use of both internal and external pools has not been tested and may result in problematic behaviour. A Spring application should enable internal connection pool only. That's a recommended configuration.

docs: internal connection pool for Spring apps #869

docs: internal connection pool for Spring apps #869

Uh oh!

Conversation

sergiyvamz commented Feb 2, 2024

Summary

Additional Reviewers

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joyc-bq left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!