Global Database (GDB) Automatic Simple Read/Write Splitting Plugin

August 15, 2026 · View on GitHub

The GDB Automatic Simple Read/Write Splitting Plugin (gdbAutoSimpleReadWriteSplitting) is the SQL-routed variant of the GDB Simple Read/Write Splitting Plugin. It combines three behaviors:

  • Two-endpoint routing — connects between the configured read and write endpoints instead of querying cluster topology (from the Simple Read/Write Splitting Plugin).
  • Automatic, SQL-driven routing — decides which endpoint to use per statement by analyzing the SQL, rather than requiring Connection#setReadOnly (from the Automatic Read/Write Splitting Plugin).
  • Global Database region rules — applies the home-region constraints and Global Write Forwarding to the configured write endpoint (from the GDB Read/Write Splitting Plugin).

Routing follows the same rules as the Automatic Read/Write Splitting Plugin: SELECT to the read endpoint; DML/DDL and row-locking SELECTs to the write endpoint; /*@reader*/, /*@writer*/, and /*@keep*/ hints honored; and no re-routing while a transaction is open or autocommit is disabled. Explicit setReadOnly calls are still honored.

Plugin Availability

This plugin is part of the unified read/write splitting plugin family. See the CHANGELOG for the release it first appears in.

Warning

Use exactly one read/write splitting plugin per connection. Do not combine gdbAutoSimpleReadWriteSplitting with any other read/write splitting plugin — readWriteSplitting, autoReadWriteSplitting, srw, autoSimpleReadWriteSplitting, gdbReadWriteSplitting, gdbAutoReadWriteSplitting, or gdbSimpleReadWriteSplitting — for the same connection. They are all read/write splitting plugins and will conflict.

Loading the GDB Automatic Simple Read/Write Splitting Plugin

The plugin is not loaded by default. To load it, include gdbAutoSimpleReadWriteSplitting in the wrapperPlugins connection parameter along with the two required endpoints. Because routing is driven by SQL analysis, the sqlParser plugin must be listed before it, and the com.github.jsqlparser:jsqlparser dependency must be on the classpath (see Required dependency: JSQLParser).

final Properties properties = new Properties();
properties.setProperty(PropertyDefinition.PLUGINS.name, "sqlParser,gdbAutoSimpleReadWriteSplitting");
properties.setProperty("srwWriteEndpoint", "test-db.cluster-XYZ.us-east-2.rds.amazonaws.com");
properties.setProperty("srwReadEndpoint", "test-db.cluster-ro-XYZ.us-east-2.rds.amazonaws.com");
properties.setProperty("gdbRwHomeRegion", "us-east-2");

The driver performs plugin sorting by default (see the autoSortWrapperPluginOrder configuration parameter), which keeps sqlParser ahead of gdbAutoSimpleReadWriteSplitting.

Configuration Parameters

This plugin accepts the same parameters as the GDB Simple Read/Write Splitting Plugin: the endpoint parameters (srwWriteEndpoint, srwReadEndpoint, verifyNewSrwConnections, verifyInitialConnectionType, srwConnectRetryTimeoutMs, srwConnectRetryIntervalMs, cachedReaderKeepAliveTimeoutMs) and the Global Database region parameters (gdbRwHomeRegion, gdbRwRestrictWriterToHomeRegion, gdbRwRestrictReaderToHomeRegion, gdbEnableGlobalWriteForwarding, gdbAccessibleRegions).

It also accepts the family-wide queryLevelLoadBalancing, loadBalancingIncludeWriter, and allowStatementRecreationOnConnectionSwitch parameters — see Query-level load balancing. Because each read statement is a routing point, query-level load balancing rotates reads per query.

Like the other SQL-routing plugins, it accepts assumeWriteTransaction (default false) to route a transaction that was not declared read-only to the writer, including its leading reads. Recommended for Spring/JPA applications; see Transactions and autocommit for the rationale and the recommended setReadOnly/setAutoCommit sequence.

Limitations

All limitations of the Automatic Read/Write Splitting Plugin (including the handling of CallableStatement and unparseable SQL), the Simple Read/Write Splitting Plugin, and the region behavior of the GDB Read/Write Splitting Plugin apply.

Verify plugin compatibility within your driver configuration using the compatibility guide.