read-write-splitting-plugin.md

Read/Write Splitting Plugin for the AWS Advanced ODBC Wrapper

The Read/Write Splitting Plugin adds functionality to switch between writer and reader instances via calls to set the connection's read-only attribute. Upon setting the connection to read-only, the plugin will connect to a reader instance according to a host selection strategy and direct subsequent queries to this instance. Future changes to the read-only attribute will switch between the established writer and reader connections.

Plugin Availability

The Read/Write Splitting Plugin is designed for use with Amazon Aurora clusters. The plugin relies on the cluster topology to identify available reader instances and switch connections.

Enabling the Read/Write Splitting Plugin

The Read/Write Splitting Plugin is not enabled by default. To enable the plugin, set the ENABLE_RW_SPLIT connection parameter to 1 in your DSN or connection string.

Configuration Parameters

Field	Connection Option Key	Value	Default Value	Sample Value
Enable Read/Write Splitting	ENABLE_RW_SPLIT	Set to 1 to enable the Read/Write Splitting Plugin. When enabled, the plugin will switch between writer and reader connections based on the connection's read-only attribute.	0	1
Reader Host Selector Strategy	RW_HOST_SELECTOR_STRATEGY	The strategy used to select a reader host when switching to a read-only connection. Currently supported strategies are: RANDOM_HOST, ROUND_ROBIN, HIGHEST_WEIGHT.	RANDOM_HOST	ROUND_ROBIN
Cached Reader Keep-Alive Timeout	CACHED_READER_KEEP_ALIVE_TIMEOUT_MS	The time in milliseconds to keep a cached reader connection alive. When the connection to read-only is first established, the reader connection is cached. By default, this cached connection will never expire (value of 0), meaning all subsequent read-only switches on the same connection will reuse the same reader. Setting a non-zero value will cause the cached reader connection to expire after the specified time, and the next read-only switch will create a new reader connection using the configured host selection strategy.	0	600000

Reader Selection

To indicate which selection strategy to use, the HOST_SELECTOR_STRATEGY configuration parameter can be set to one of the following values:

Strategy	Connection Option Value	Description
Random	RANDOM_HOST	Selects a reader instance at random from the available readers.
Round Robin	ROUND_ROBIN	Cycles through available reader instances in order.
Highest Weight	HIGHEST_WEIGHT	Selects the reader instance with the highest weight in the cluster topology.

Reader Keep-Alive Timeout

If no connection pool is used, reader connections created by switching to read-only mode will be cached for the entire lifetime of the connection. This may have a negative performance impact if your application frequently switches to read-only mode on the same connection, as all read traffic for that connection will be directed to a single reader instance.

To improve performance, you can specify a timeout for the cached reader connection using CACHED_READER_KEEP_ALIVE_TIMEOUT_MS. Once the reader has expired, the next switch to read-only mode will create a new reader connection determined by the reader host selection strategy. The default value of 0 means the wrapper will keep reusing the same cached reader connection. If connection pooling is enabled, this setting is ignored.

Using the Read/Write Splitting Plugin Against Non-Aurora Clusters

The Read/Write Splitting Plugin is not currently supported for non-Aurora clusters.