Add query.usingMaster() to explicitly choose master data source

When we have a read replica with potential for replication lag, and config a read only DataSource to use that read replica, by default a query executed without a current transaction will use the read replica.

We specify usingMaster() when we explicitly want to execute a query and use the master data source.

ebean-api/src/main/java/io/ebean/DtoQuery.java

@@ -205,4 +205,16 @@ public interface DtoQuery<T> extends CancelableQuery {
    * Use the explicit transaction to execute the query.
    */
   DtoQuery<T> usingTransaction(Transaction transaction);
+
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link io.ebean.config.DatabaseConfig#setReadOnlyDataSource(DataSource)} then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We we use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  DtoQuery<T> usingMaster();
 }

ebean-api/src/main/java/io/ebean/Query.java

@@ -4,6 +4,7 @@ import io.avaje.lang.NonNullApi;
 import io.avaje.lang.Nullable;
 
 import javax.persistence.NonUniqueResultException;
+import javax.sql.DataSource;
 import java.sql.Connection;
 import java.sql.Timestamp;
 import java.util.List;
@@ -685,6 +686,18 @@ public interface Query<T> extends CancelableQuery {
    */
   Query<T> usingDatabase(Database database);
 
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link io.ebean.config.DatabaseConfig#setReadOnlyDataSource(DataSource)} then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We we use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  Query<T> usingMaster();
+
   /**
    * Execute the query returning the list of Id's.
    * <p>

ebean-api/src/main/java/io/ebean/SqlQuery.java

@@ -45,6 +45,18 @@ public interface SqlQuery extends Serializable, CancelableQuery {
    */
   SqlQuery usingTransaction(Transaction transaction);
 
+  /**
+   * Ensure that the master DataSource is used if there is a read only data source
+   * being used (that is using a read replica database potentially with replication lag).
+   * <p>
+   * When the database is configured with a read-only DataSource via
+   * say {@link io.ebean.config.DatabaseConfig#setReadOnlyDataSource(DataSource)} then
+   * by default when a query is run without an active transaction, it uses the read-only data
+   * source. We we use {@code usingMaster()} to instead ensure that the query is executed
+   * against the master data source.
+   */
+  SqlQuery usingMaster();
+
   /**
    * Execute the query returning a list.
    */