|
1 | 1 | ## Read-Write Splitting Plugin |
2 | 2 |
|
3 | | -The read-write splitting plugin adds functionality to switch between writer/reader instances via calls to the `Connection#setReadOnly` method. Upon calling `setReadOnly(true)`, the plugin will establish a connection to a random reader instance and direct subsequent queries to this instance. Future calls to `setReadOnly` will switch between the established writer and reader connections according to the boolean argument you supply to the `setReadOnly` method. |
| 3 | +The read-write splitting plugin adds functionality to switch between writer/reader instances via calls to the `Connection#setReadOnly` method. Upon calling `setReadOnly(true)`, the plugin will establish a connection to a reader instance and direct subsequent queries to this instance. Future calls to `setReadOnly` will switch between the established writer and reader connections according to the boolean argument you supply to the `setReadOnly` method. |
4 | 4 |
|
5 | 5 | ### Loading the Read-Write Splitting Plugin |
6 | 6 |
|
7 | | -The 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 read-write splitting plugin alongside the failover and host monitoring plugins, the read-write splitting plugin must be placed 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 read-write splitting plugin alongside these plugins. |
| 7 | +The 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 read-write splitting plugin alongside the failover and host monitoring plugins, the 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 read-write splitting plugin with these plugins. |
8 | 8 |
|
9 | 9 | ``` |
10 | 10 | final Properties properties = new Properties(); |
11 | 11 | properties.setProperty(PropertyDefinition.PLUGINS.name, "readWriteSplitting,failover,efm"); |
12 | 12 | ``` |
13 | 13 |
|
14 | | -If you would like to use the read-write splitting plugin without the failover plugin against an Aurora cluster, you will need to include the Aurora host list plugin before the read-write splitting plugin. This informs the driver that it should query for Aurora's topology. |
| 14 | +If you would like to use the read-write splitting plugin without the failover plugin, the Aurora host list plugin must be included before the read-write splitting plugin. This informs the driver that it should query for Aurora's topology. |
15 | 15 |
|
16 | 16 | ``` |
17 | 17 | final Properties properties = new Properties(); |
18 | 18 | properties.setProperty(PropertyDefinition.PLUGINS.name, "auroraHostList,readWriteSplitting"); |
19 | 19 | ``` |
20 | 20 |
|
21 | | -### Using the Read-Write Splitting Plugin against RDS/Aurora clusters |
| 21 | +### Supplying the connection string |
22 | 22 |
|
23 | | -When using the read-write splitting plugin against RDS or Aurora clusters, you do not have to supply multiple instance URLs in the connection string. Instead, supply just the URL for the initial instance to which you're connecting. You must also include either the failover plugin or the Aurora host list plugin in your plugin chain so that the driver knows to query Aurora for its topology. See the section on [loading the read-write splitting plugin](#loading-the-read-write-splitting-plugin) for more info. |
| 23 | +When using the read-write splitting plugin against Aurora clusters, you do not have to supply multiple instance URLs in the connection string. Instead, supply just the URL for the initial instance to which you're connecting. You must also include either the failover plugin or the Aurora host list plugin in your plugin chain so that the driver knows to query Aurora for its topology. See the section on [loading the read-write splitting plugin](#loading-the-read-write-splitting-plugin) for more info. |
24 | 24 |
|
25 | | -### Using the Read-Write Splitting Plugin against non-RDS clusters |
| 25 | +### Using the Read-Write Splitting Plugin against non-Aurora clusters |
26 | 26 |
|
27 | | -If you are using the read-write splitting plugin against a cluster that is not hosted on RDS or Aurora, the plugin will not be able to automatically acquire the cluster topology. Instead, you must supply the topology information in the connection string as a comma-delimited list of multiple instance URLs. If you are using a single writer instance, the first instance in the list must be the writer instance and you must enable the `singleWriterConnectionString` property: |
28 | | - |
29 | | -``` |
30 | | -properties.setProperty(ConnectionStringHostListProvider.SINGLE_WRITER_CONNECTION_STRING.name, "true"); |
31 | | -String connectionUrl = "jdbc:aws-wrapper:mysql://writer-instance-1.com,reader-instance-1.com,reader-instance-2.com/database-name" |
32 | | -``` |
33 | | - |
34 | | -Additionally, you should avoid using the Aurora host list plugin and the failover plugin in this scenario, as they are designed to specifically operate against Aurora databases. |
| 27 | +The read-write splitting plugin is not currently supported for non-Aurora clusters. |
35 | 28 |
|
36 | 29 | ### Internal connection pooling |
37 | 30 |
|
|
0 commit comments