The GDB Read/Write Splitting Plugin extends the functionality of the Read/Write Splitting Plugin and adopts some additional settings to improve support for Global Databases.
The GDB Read/Write Splitting Plugin adds the notion of a home region and allows users to constrain new connections to this region. Such restrictions may be helpful to prevent opening new connections in environments where remote AWS regions add substantial latency that cannot be tolerated.
Unless otherwise stated, all recommendations, configurations and code examples made for the Read/Write Splitting Plugin are applicable to the current GDB Read/Write Splitting Plugin.
The plugin is available since version 3.2.0.
The GDB Read/Write Splitting Plugin is not loaded by default. To load the plugin, include it in the wrapperPlugins connection parameter. If you would like to load the GDB Read/Write Splitting Plugin alongside the failover and host monitoring plugins, the GDB Read/Write Splitting Plugin must be listed before these plugins in the plugin chain. If it is not, failover exceptions will not be properly processed by the plugin. See the example below to properly load the GDB Read/Write Splitting Plugin with these plugins. Although the driver performs proper plugin sorting by default (see autoSortWrapperPluginOrder configuration parameter), this note remains important.
final Properties properties = new Properties();
properties.setProperty(PropertyDefinition.PLUGINS.name, "gdbReadWriteSplitting,failover2,efm2");
If you would like to use the GDB Read/Write Splitting Plugin without the failover plugin, make sure you have the gdbReadWriteSplitting plugin in the wrapperPlugins property, and that the failover plugin is not part of it.
final Properties properties = new Properties();
properties.setProperty(PropertyDefinition.PLUGINS.name, "gdbReadWriteSplitting");
Warning
Do not use the readWriteSplitting, srw and/or gdbReadWriteSplitting plugins (or their combination) at the same time for the same connection!
The GDB Read/Write Splitting Plugin can be used against Aurora clusters and RDS clusters. However, since these cluster types are single-region clusters, setting a home region does not make much sense.
Verify plugin compatibility within your driver configuration using the compatibility guide.
| Parameter | Value | Required | Description | Default Value |
|---|---|---|---|---|
readerHostSelectorStrategy |
String | No | The name of the strategy that should be used to select a new reader host. For more information on the available reader selection strategies, see this table. | random |
cachedReaderKeepAliveTimeoutMs |
Integer | No | The time in milliseconds to keep a reader connection alive in the cache. Default value 0 means the plugin will keep reusing the same cached reader connection. | 0 |
gdbRwHomeRegion |
String | If connecting using an IP address, a custom domain URL, Global Database endpoint or other endpoint with no region: Yes Otherwise: No |
Defines a home region. Examples: us-west-2, us-east-1. If this parameter is omitted, the value is parsed from the connection URL. For regional cluster endpoints and instance endpoints, it's set to the region of the provided endpoint. If the provided endpoint has no region (for example, a Global Database endpoint or IP address), the configuration parameter is mandatory. |
For regional cluster endpoints and instance endpoints, it's set to the region of the provided endpoint. Otherwise: null |
gdbRwRestrictWriterToHomeRegion |
Boolean | No | If set to true, prevents following and connecting to a writer node outside the defined home region. An exception will be raised when such a connection to a writer outside the home region is requested. |
true |
gdbRwRestrictReaderToHomeRegion |
Boolean | No | If set to true, prevents connecting to a reader node outside the defined home region. If no reader nodes in the home region are available, an exception will be raised. |
true |
gdbEnableGlobalWriteForwarding |
Boolean | No | If set to true, allows connections in the secondary region to forward write queries to the primary global region. This is useful if your home region is the secondary global region. This functionality requires Global Write Forwarding to be enabled. |
false |
Please refer to the original Read/Write Splitting Plugin for more details about error codes, configurations, connection pooling and sample codes.