update read replica page

Author: rob-bygrave

docs/read-replicas/index.html

@@ -66,6 +66,32 @@ <h1 id="breadcrumb">
   </li>
   <li class="nav1 active">
     <a class="active" href="/docs/read-replicas">Read Replicas</a>
+          <ul class="nav nav-scroll">
+  <li >
+    <a  href="#overview">Overview</a>
+  </li>
+  <li >
+    <a  href="#readOnlyUrl">ReadOnlyUrl</a>
+  </li>
+  <li >
+    <a  href="#readOnlyDataSource">ReadOnlyDataSource</a>
+  </li>
+  <li >
+    <a  href="#aurora">AWS Aurora</a>
+  </li>
+  <li >
+    <a  href="#usingMaster">Using Master</a>
+  </li>
+  <li >
+    <a  href="#queryUseReadReplica">Using Replica</a>
+  </li>
+  <li >
+    <a  href="#transactionReadOnly">@Transaction(readOnly=true)</a>
+  </li>
+  <li >
+    <a  href="#readOnlyDatabase">ReadOnly Database</a>
+  </li>
+          </ul>
   </li>
   <li class="nav1 ">
     <a  href="/docs/database">Database platforms</a>
@@ -117,21 +143,26 @@ <h1 id="breadcrumb">
   </div>
 </form>
 
-<h2 id="transactional">Read Replicas</h2>
+<h2 id="overview">Overview</h2>
 <p>
-  Ebean supports configuring a second DataSource [connection pool] that points to
-  a "Read replica". The DataSource is <em>readOnly = true</em> and <em>autoCommit=true</em>.
+  Ebean supports configuring a second DataSource (connection pool) that points to
+  a "Read replica". The "Read Replica" DataSource is set to be <em>readOnly = true</em>
+  and <em>autoCommit=true</em>.
 </p>
-
-<h2>DataSourceBuilder readOnlyUrl</h2>
 <p>
-  When using DataSourceBuilder we can specify an additional <code>readOnlyUrl</code> which
-  can point to a read replica (e.g. AWS Aurora reader endpoint).
+  When Ebean is configured with 2 DataSources it will use the "Main" DataSource for explicit
+  transactions and writing data, and will use the "Read Only" DataSource for
+  queries that are executed without an explicit transaction - see
+  <a href="#queryUseReadReplica">Using the Read Replica.</a>
 </p>
+
+<h2 id="readOnlyUrl">DataSourceBuilder readOnlyUrl</h2>
 <p>
-  Ebean DataSourceBuilder can support configuration for both a "Master/Writer" DataSource and a
-  "Read Only" DataSource where the difference between these is the connection url. This is
-  the case for AWS Aurora where there are 2 endpoints available (Writer and Reader endpoints).
+  Using DataSourceBuilder we can specify an additional <code>readOnlyUrl</code> which
+  can point to a read replica (e.g. AWS Aurora reader endpoint). When readOnlyUrl is set,
+  the DataSourceBuilder can effectively build 2 DataSources. The difference between these
+  DataSources is the connection url and that the ReadOnly DataSource will have
+  <em>readOnly=true</em> and <em>autoCommit=true</em>.
 </p>
 <div class="syntax java"><div class="highlight"><pre><span></span><span class="k">var</span> <span class="n">dataSourceBuilder</span> <span class="o">=</span>
   <span class="n">DataSourceBuilder</span><span class="o">.</span><span class="na">create</span><span class="o">()</span>
@@ -143,7 +174,7 @@ <h2>DataSourceBuilder readOnlyUrl</h2>
 </pre></div>
 </div>
 
-<h2>DatabaseBuilder readOnlyDataSource</h2>
+<h2 id="readOnlyDataSource">DatabaseBuilder readOnlyDataSource</h2>
 <p>
   If we are not using DataSourceBuilder, we can instead specify a "Read Only" DataSource
   to use. We can create a DataSource (using say Hikari) and specify it as the <em>readOnlyDataSource</em>.
@@ -177,22 +208,19 @@ <h2 id="aurora">Amazon AWS Aurora</h2>
 </ul>
 <img alt="AWS Aurora Endpoints" src="/images/aws-aurora-endpoints.png" class="img-responsive" style="max-width: 700px">
 
-<p>
-
-</p>
-
 
 <h2 id="usingMaster">Using the "Master"</h2>
 <p>
   When we have an explicit transaction via <em>@Transactional</em> on a method or using
   explicitly <code>database.beginTransaction()</code> - then this transaction will use
-  the "Master".
+  the "Master" DataSource.
 </p>
 <p>
   When we use database.save() without an explicit transaction, then a transaction will be
-  used implicitly and this will use the "Master".
+  used implicitly and this will use the "Master" DataSource.
 </p>
 
+
 <h2 id="queryUseMaster">Query.usingMaster()</h2>
 <p>
   If we have a query that is executed outside any explicit transaction, and it will fetch data
@@ -204,7 +232,7 @@ <h2 id="queryUseMaster">Query.usingMaster()</h2>
 <div class="syntax java"><div class="highlight"><pre><span></span><span class="k">var</span> <span class="n">customers</span> <span class="o">=</span>
   <span class="k">new</span> <span class="n">QCustomer</span><span class="o">()</span>
     <span class="o">.</span><span class="na field">status</span><span class="o">.</span><span class="na">eq</span><span class="o">(</span><span class="n">Status</span><span class="o">.</span><span class="na">NEW</span><span class="o">)</span>
-    <span class="o">.</span><span class="na">usingMaster</span><span class="o">()</span> <span class="c1">// Use the &quot;Master/Writer&quot; database</span>
+    <span class="o">.</span><span class="na">usingMaster</span><span class="o">()</span> <span class="c1">// Use the &quot;Master/Writer&quot; dataSource</span>
     <span class="o">.</span><span class="na">findList</span><span class="o">();</span>
 </pre></div>
 </div>
@@ -227,18 +255,38 @@ <h2 id="queryUseReadReplica">Using the Read Replica</h2>
 <h2 id="transactionReadOnly">@Transaction(readOnly=true)</h2>
 <p>
   When a method is annotated with <code>@Transaction(readOnly=true)</code>, then this
-  will create a read only transaction using the "Read Replica".
+  will create a read only transaction using the read only DataSource (which will be
+  pointing to the "Read Replica" instance).
 </p>
 
 <div class="syntax java"><div class="highlight"><pre><span></span><span class="nd">@Transaction</span><span class="o">(</span><span class="nx">readOnly</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span>
 <span class="kt">void</span> <span class="nf">myMethod</span><span class="o">()</span> <span class="o">{</span>
 
-  <span class="c1">// do stuff with a transaction using the Read replica</span>
+  <span class="c1">// do stuff with a transaction using the</span>
+  <span class="c1">// Read replica / read only dataSource</span>
 
 <span class="o">}</span>
 </pre></div>
 </div>
 
+<h2 id="readOnlyDatabase">ReadOnly Database</h2>
+<p>
+  An Ebean Database can be specified as <em>read-only</em> using
+  <code>DatabaseBuilder.readOnlyDatabase(true)</code> to indicate that
+  this Database can only be used in a read only way.
+</p>
+<p>
+  This means that the DataSource and read-only DataSource are expected to be the
+  same and use <em>readOnly=true</em> and <em>autoCommit=true</em>.
+</p>
+<div class="syntax java"><div class="highlight"><pre><span></span><span class="k">var</span> <span class="n">database</span> <span class="o">=</span> <span class="n">Database</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
+  <span class="o">.</span><span class="na">name</span><span class="o">(</span><span class="s">&quot;mydb&quot;</span><span class="o">)</span>
+  <span class="o">.</span><span class="na">readOnlyDatabase</span><span class="o">(</span><span class="kc">true</span><span class="o">)</span>
+  <span class="o">...</span>
+  <span class="o">.</span><span class="na">build</span><span class="o">();</span>
+</pre></div>
+</div>
+
 
   <nav class="next">
     <p class="edit-page">