Package org.pjdbc.drivers

Class FederatingDriver

java.lang.Object
org.pjdbc.sql.AbstractDriver
org.pjdbc.drivers.FederatingDriver
All Implemented Interfaces:
Driver
@DriverCapability(prefix="federate", description="Queries multiple databases and merges results", capabilities={"federation","multi-database"}) @DriverParameter(name="mergeStrategy",type=STRING,description="Result merge strategy",defaultValue="concat",enumValues={"concat","union_all","first_non_empty"}) @DriverParameter(name="parallelExecution",type=BOOLEAN,description="Execute queries in parallel",defaultValue="false") @DriverParameter(name="timeout",type=INTEGER,description="Timeout in milliseconds for parallel execution",defaultValue="30000",min=0L) @DriverParameter(name="strictTransactions",type=BOOLEAN,description="Throw exception when transactions are used (no cross-DB coordination). Set to false to allow uncoordinated transactions at your own risk.",defaultValue="true") @DriverParameter(name="tableRouting",type=STRING,description="Optional table-to-database routing. Format: table1:idx1;table2:idx2 where idx is 0-based database index. Unrouted tables broadcast to all.",defaultValue="") @DriverSideEffects(stateful=true) public class FederatingDriver extends AbstractDriver
FederatingDriver queries multiple databases and merges results.

Unlike TeeDriver (write replication) or LoadBalancingDriver (read scaling), FederatingDriver merges query results from all data sources into a unified view.

Operating Modes

Broadcast Mode (default): Executes the same query on all configured databases and concatenates the results. Use for identical schemas across regions/tenants.

Table-Based Routing Mode: Routes queries to specific databases based on the table name. Enable with the tableRouting parameter:

 jdbc:federate[tableRouting=users:0;orders:1]:jdbc:h2:mem:db1;jdbc:h2:mem:db2

This routes users queries to db1 (index 0) and orders queries to db2 (index 1). Tables not in the routing map fall back to broadcast behavior.

Limitations

This driver does NOT provide:

  • Query rewriting for heterogeneous schemas
  • Cross-database JOINs
  • Shard key routing (use table-based routing for simple cases)
  • Distributed query planning

For cross-database JOINs or complex federation: Use a federated query engine (Trino, Presto, Dremio) instead.

Transaction Limitations

This driver does NOT support coordinated transactions across databases. By default, strictTransactions=true causes transactions to fail. If you set strictTransactions=false, be aware that:

  • Commit may succeed on some backends and fail on others (split-brain)
  • Rollback cannot undo commits that already succeeded
  • There is no two-phase commit (2PC) coordination

URL format: jdbc:federate[mergeStrategy=concat,parallelExecution=false]:url1;url2;...

Example URLs: 

 // Broadcast to all databases
 jdbc:federate:jdbc:h2:mem:db1;jdbc:h2:mem:db2

 // Table-based routing: users→db1, orders→db2
 jdbc:federate[tableRouting=users:0;orders:1]:jdbc:h2:mem:db1;jdbc:h2:mem:db2

 // First non-empty result wins
 jdbc:federate[mergeStrategy=first_non_empty]:jdbc:postgresql://db1/sales;jdbc:mysql://db2/inventory