Cross plugin compatibility

September 21, 2026 · View on GitHub

This document is part of the Compatibility Guide and explains compatibility between various plugins. While combining plugins in a single driver configuration is common, some plugins may not work properly together. Such incompatibilities can arise from either plugin design constraints or logical conflicts.

For example, the failover plugin is incompatible with failover2. Both plugins support database cluster failover but implement this functionality differently. Combining them in a single configuration causes interference between their operations, leading to instability.

Similarly, the limitless plugin and customEndpoint plugin are incompatible because Limitless Database does not support custom endpoints.

Plugin codes / Plugin codesefm / efm2failover / failover2gdbFailover
failover / failover2✓
gdbFailover✓✗ 1
iam / awsSecretsManager / awsSecretsManager2 / federatedAuth / okta✓✓✓
readWriteSplitting / autoReadWriteSplitting✓✓✓
srw / autoSimpleReadWriteSplitting✓✓✓
gdbReadWriteSplitting / gdbAutoReadWriteSplitting✓✓✓
gdbSimpleReadWriteSplitting / gdbAutoSimpleReadWriteSplitting✓✓✓
customEndpoint✓✓✗ 2
auroraConnectionTracker✓✓✓
initialConnection✓✓✓
auroraStaleDns✓✓✓
connectTime✓✓✓
fastestResponseStrategy✓✓✓
limitless✓✗ 3✗ 3
bg✓✓✗ 4

Plugin codes / Plugin codesiam / awsSecretsManager / awsSecretsManager2 / federatedAuth / okta
readWriteSplitting / autoReadWriteSplitting✓
srw / autoSimpleReadWriteSplitting✓
gdbReadWriteSplitting / gdbAutoReadWriteSplitting✓
gdbSimpleReadWriteSplitting / gdbAutoSimpleReadWriteSplitting✓
customEndpoint✓
auroraConnectionTracker✓
initialConnection✓
auroraStaleDns✓
connectTime✓
fastestResponseStrategy✓
limitless✓
bg✓

Plugin codes / Plugin codesreadWriteSplitting / autoReadWriteSplittingsrw / autoSimpleReadWriteSplittinggdbReadWriteSplitting / gdbAutoReadWriteSplittinggdbSimpleReadWriteSplitting / gdbAutoSimpleReadWriteSplitting
srw / autoSimpleReadWriteSplitting✗ 5
gdbReadWriteSplitting / gdbAutoReadWriteSplitting✗ 5✗ 5
gdbSimpleReadWriteSplitting / gdbAutoSimpleReadWriteSplitting✗ 5✗ 5✗ 5
customEndpoint✓✓✗ 2✗ 2
auroraConnectionTracker✓✓✓✓
initialConnection✓✗ 6✓✗ 6
auroraStaleDns✓✗ 6✓✗ 6
connectTime✓✓✓✓
fastestResponseStrategy✓✓✓✓
limitless✗ 3✗ 3✗ 3✗ 3
bg✓✓✗ 4✗ 4

Plugin codes / Plugin codescustomEndpointauroraConnectionTrackerinitialConnectionauroraStaleDns
auroraConnectionTracker✓
initialConnection✓✓
auroraStaleDns✓✓✗ 7
connectTime✓✓✗ 8✓
fastestResponseStrategy✓✓✓✓
limitless✗ 3✗ 3✗ 3✗ 3
bg✗ 9✓✓✓

Plugin codes / Plugin codesconnectTimefastestResponseStrategylimitlessbg
fastestResponseStrategy✓
limitless✓✗ 10
bg✓✓✗ 3

Notes

Footnotes

  1. Use only one failover plugin (gdbFailover/failover/failover2) at a time. ↩

  2. A custom endpoint is a single-region Aurora construct and does not apply to global databases, should not be combined with the gdb plugins. ↩ ↩2 ↩3

  3. The limitless plugin manages its own routing and is incompatible with this plugin. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11

  4. Blue/Green is not supported on Aurora global databases, should not be combined with the gdb plugins. ↩ ↩2 ↩3

  5. Use only one read/write-splitting plugin at a time. ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  6. The simple read/write splitting plugins (srw, autoSimpleReadWriteSplitting, gdbSimpleReadWriteSplitting, gdbAutoSimpleReadWriteSplitting) manage their own connections between two fixed endpoints and are incompatible with plugins that resolve or re-point connections. ↩ ↩2 ↩3 ↩4

  7. auroraStaleDns and the initial connection plugin both act on the initial cluster connection and conflict. ↩

  8. The initial connection plugin opens and verifies candidate connections in a retry loop with openConnectionRetryIntervalMs delays before returning, so the time connectTime records would include those retries and waits rather than the true connection latency. ↩

  9. A Blue/Green switchover replaces the whole deployment, so a custom endpoint's hand-picked instance subset does not carry over. ↩

  10. fastestResponseStrategy and limitless use conflicting host-selection mechanisms. ↩