You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by re...@apache.org on 2019/02/19 16:56:17 UTC
svn commit: r1853897 - in /jackrabbit/oak/branches/1.8: ./ oak-doc/src/site/
oak-doc/src/site/markdown/nodestore/
oak-doc/src/site/markdown/nodestore/document/
oak-store-document/src/main/java/org/apache/jackrabbit/oak/plugins/document/rdb/
Author: reschke
Date: Tue Feb 19 16:56:16 2019
New Revision: 1853897
URL: http://svn.apache.org/viewvc?rev=1853897&view=rev
Log:
OAK-7960: RDB: add to Oak documentationRDB: add to Oak documentation (ported to 1.8)
Added:
jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md
- copied, changed from r1852528, jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md
Modified:
jackrabbit/oak/branches/1.8/ (props changed)
jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/documentmk.md
jackrabbit/oak/branches/1.8/oak-doc/src/site/site.xml
jackrabbit/oak/branches/1.8/oak-store-document/src/main/java/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.java
Propchange: jackrabbit/oak/branches/1.8/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Tue Feb 19 16:56:16 2019
@@ -1,3 +1,3 @@
/jackrabbit/oak/branches/1.0:1665962
-/jackrabbit/oak/trunk:1820660-1820661,1820729,1820734,1820859,1820861,1820878,1820888,1820947,1821027,1821130,1821140-1821141,1821178,1821237,1821240,1821249,1821258,1821325,1821358,1821361-1821362,1821370,1821375,1821393,1821477,1821487,1821516,1821617,1821663,1821665,1821668,1821681,1821847,1821975-1821983,1822121,1822201,1822207,1822527,1822642,1822723,1822808,1822850,1822934,1823135,1823163,1823169,1823172,1823655,1823669,1824196,1824198,1824253,1824255,1824896,1824962,1825065,1825362,1825381,1825442,1825448,1825466,1825470-1825471,1825475,1825523,1825525,1825561,1825619-1825621,1825651,1825654,1825992,1826079,1826090,1826096,1826216,1826237,1826338,1826516,1826532,1826551,1826560,1826638,1826640,1826730,1826833,1826932,1826957,1827423,1827472,1827486,1827816,1827977,1828349,1828439,1828502,1828529,1828948,1829527,1829534,1829546,1829569,1829587,1829665,1829854,1829864,1829978,1829985,1829987,1829998,1830019,1830048,1830160,1830171,1830197,1830209,1830239,1830347,1830748,1830911
,1830923,1831157-1831158,1831163,1831190,1831374,1831560,1831689,1832258,1832376,1832379,1832535,1833308,1833347,1833833,1834112,1834117,1834287,1834291,1834302,1834326,1834328,1834336,1834428,1834468,1834483,1834610,1834648-1834649,1834681,1834823,1834857-1834858,1835060,1835518,1835521,1835635,1835642,1835780,1835819,1836082,1836121,1836167-1836168,1836170-1836187,1836189-1836196,1836206,1836487,1836493,1836548,1837057,1837274,1837296,1837326,1837475,1837503,1837547,1837569,1837600,1837657,1837718,1837998,1838076,1838637,1839549,1839570,1839637,1839746,1840019,1840024,1840031,1840226,1840455,1840462,1840574,1840769,1841314,1841352,1842089,1842677,1843175,1843222,1843231,1843398,1843618,1843652,1843911,1844325,1844549,1844625,1844627,1844642,1844728,1844775,1844932,1845135,1845336,1845405,1845415,1845730-1845731,1845863,1845865,1846057,1846396,1846429,1846617,1848073,1848181-1848182,1848191,1848217,1848822-1848823,1850837,1851533-1851535,1851619,1852120,1852451,1852492,1853393,1853
429,1853433
+/jackrabbit/oak/trunk:1820660-1820661,1820729,1820734,1820859,1820861,1820878,1820888,1820947,1821027,1821130,1821140-1821141,1821178,1821237,1821240,1821249,1821258,1821325,1821358,1821361-1821362,1821370,1821375,1821393,1821477,1821487,1821516,1821617,1821663,1821665,1821668,1821681,1821847,1821975-1821983,1822121,1822201,1822207,1822527,1822642,1822723,1822808,1822850,1822934,1823135,1823163,1823169,1823172,1823655,1823669,1824196,1824198,1824253,1824255,1824896,1824962,1825065,1825362,1825381,1825442,1825448,1825466,1825470-1825471,1825475,1825523,1825525,1825561,1825619-1825621,1825651,1825654,1825992,1826079,1826090,1826096,1826216,1826237,1826338,1826516,1826532,1826551,1826560,1826638,1826640,1826730,1826833,1826932,1826957,1827423,1827472,1827486,1827816,1827977,1828349,1828439,1828502,1828529,1828948,1829527,1829534,1829546,1829569,1829587,1829665,1829854,1829864,1829978,1829985,1829987,1829998,1830019,1830048,1830160,1830171,1830197,1830209,1830239,1830347,1830748,1830911
,1830923,1831157-1831158,1831163,1831190,1831374,1831560,1831689,1832258,1832376,1832379,1832535,1833308,1833347,1833833,1834112,1834117,1834287,1834291,1834302,1834326,1834328,1834336,1834428,1834468,1834483,1834610,1834648-1834649,1834681,1834823,1834857-1834858,1835060,1835518,1835521,1835635,1835642,1835780,1835819,1836082,1836121,1836167-1836168,1836170-1836187,1836189-1836196,1836206,1836487,1836493,1836548,1837057,1837274,1837296,1837326,1837475,1837503,1837547,1837569,1837600,1837657,1837718,1837998,1838076,1838637,1839549,1839570,1839637,1839746,1840019,1840024,1840031,1840226,1840455,1840462,1840574,1840769,1841314,1841352,1842089,1842677,1843175,1843222,1843231,1843398,1843618,1843652,1843911,1844325,1844549,1844625,1844627,1844642,1844728,1844775,1844932,1845135,1845336,1845405,1845415,1845730-1845731,1845863,1845865,1846057,1846396,1846429,1846617,1848073,1848181-1848182,1848191,1848217,1848822-1848823,1850837,1851533-1851535,1851619,1852120,1852451,1852492,1852528,1852
582,1852584,1853393,1853429,1853433,1853893
/jackrabbit/trunk:1345480
Copied: jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md (from r1852528, jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md)
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md?p2=jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md&p1=jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md&r1=1852528&r2=1853897&rev=1853897&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md (original)
+++ jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md Tue Feb 19 16:56:16 2019
@@ -50,7 +50,11 @@ For production use:
For supported databases, `RDBDocumentStoreDB` has knowledge about supported
versions (and likewise supported JDBC drivers). Watch out for log messages
during system startup which might warn about outdated versions (the system
-will attempt to start anyway).
+will attempt to start anyway):
+
+~~~
+12:20:20.864 ERROR [main] RDBDocumentStore.java:1014 Unsupported Apache Derby version: 9.14, expected at least 10.11
+~~~
## Database Creation
@@ -71,7 +75,14 @@ the correct operation:
The implementation will try to create all tables and indices when they are not present
yet. Of course this requires that the configured database user actually has
-permission to do so. If it does not, the system will not start up and provide
+permission to do so. Example from system log:
+
+~~~
+12:20:22.705 INFO [main] RDBDocumentStore.java:1063 RDBDocumentStore (SNAPSHOT) instantiated for database Apache Derby 10.14.2.0 - (1828579) (10.14), using driver: Apache Derby Embedded JDBC Driver 10.14.2.0 - (1828579) (10.14), connecting to: jdbc:derby:./target/derby-ds-test, transaction isolation level: TRANSACTION_READ_COMMITTED (2), SA.NODES: ID VARCHAR(512), MODIFIED BIGINT, HASBINARY SMALLINT, DELETEDONCE SMALLINT, MODCOUNT BIGINT, CMODCOUNT BIGINT, DSIZE BIGINT, VERSION SMALLINT, SDTYPE SMALLINT, SDMAXREVTIME BIGINT, DATA VARCHAR(16384), BDATA BLOB(1073741824) /* {BIGINT=-5, BLOB=2004, SMALLINT=5, VARCHAR=12} */ /* index NODES_MOD on SA.NODES (MODIFIED ASC) other (#0, p0), index NODES_SDM on SA.NODES (SDMAXREVTIME ASC) other (#0, p0), index NODES_SDT on SA.NODES (SDTYPE ASC) other (#0, p0), index NODES_VSN on SA.NODES (VERSION ASC) other (#0, p0), unique index SQL190131122022490 on SA.NODES (ID ASC) other (#0, p0) */
+12:20:22.705 INFO [main] RDBDocumentStore.java:1070 Tables created upon startup: [CLUSTERNODES, NODES, SETTINGS, JOURNAL]
+~~~
+
+If it does not, the system will not start up and provide
diagnostics in the log file.
Administrators who want to create tables upfront can do so. The DDL statements
@@ -81,13 +92,35 @@ for the supported databases can be dumpe
## Upgrade from earlier versions
As of Oak 1.8, the database layout has been slightly extended (see
-[API docs for RDBDocumentStore](/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.html)
+[API docs for RDBDocumentStore](/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.html#apidocs.versioning)
for details).
Upon startup on an "old" database instance, `RDBDocumentStore` will try to
-upgrade the tables. If this fails, it will continue using the "old" layout,
-and log diagnostics about the failed upgrade. The upgrade can then be done
-at a later point of time by executing the required DDL statements.
+upgrade the tables. Example (for `NODES`):
+
+~~~
+12:05:54.146 INFO [main] RDBDocumentStore.java:1369 Upgraded NODES to DB level 1 using 'alter table NODES add VERSION smallint'
+
+12:05:54.166 INFO [main] RDBDocumentStore.java:1369 Upgraded NODES to DB level 2 using 'alter table NODES add SDMAXREVTIME bigint'
+12:05:54.167 INFO [main] RDBDocumentStore.java:1369 Upgraded NODES to DB level 2 using 'create index NODES_VSN on NODES (VERSION)'
+12:05:54.167 INFO [main] RDBDocumentStore.java:1369 Upgraded NODES to DB level 2 using 'create index NODES_SDT on NODES (SDTYPE)'
+12:05:54.167 INFO [main] RDBDocumentStore.java:1369 Upgraded NODES to DB level 2 using 'create index NODES_SDM on NODES (SDMAXREVTIME)'
+~~~
+
+If this fails, it will continue using the "old" layout,
+and log diagnostics about the failed upgrade:
+
+~~~
+12:05:56.746 INFO [main] RDBDocumentStore.java:1379 Attempted to upgrade NODES to DB level 1 using 'alter table NODES add VERSION smallint', but failed with SQLException 'table alter statement rejected: alter table NODES add VERSION smallint' (code: 17/state: ABCDE) - will continue without.
+
+12:05:56.955 INFO [main] RDBDocumentStore.java:1379 Attempted to upgrade NODES to DB level 2 using 'alter table NODES add SDTYPE smallint', but failed with SQLException 'table alter statement rejected: alter table NODES add SDTYPE smallint' (code: 17/state: ABCDE) - will continue without.
+12:05:56.955 INFO [main] RDBDocumentStore.java:1379 Attempted to upgrade NODES to DB level 2 using 'alter table NODES add SDMAXREVTIME bigint', but failed with SQLException 'table alter statement rejected: alter table NODES add SDMAXREVTIME bigint' (code: 17/state: ABCDE) - will continue without.
+12:05:56.964 INFO [main] RDBDocumentStore.java:1379 Attempted to upgrade NODES to DB level 2 using 'create index NODES_SDT on NODES (SDTYPE)', but failed with SQLException ''SDTYPE' is not a column in table or VTI 'NODES'.' (code: 20000/state: 42X14) - will continue without.
+12:05:56.964 INFO [main] RDBDocumentStore.java:1379 Attempted to upgrade NODES to DB level 2 using 'create index NODES_SDM on NODES (SDMAXREVTIME)', but failed with SQLException ''SDMAXREVTIME' is not a column in table or VTI 'NODES'.' (code: 20000/state: 42X14) - will continue without.
+~~~
+
+The upgrade can then be done
+at a later point of time by executing the required DDL statements.
Modified: jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/documentmk.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/documentmk.md?rev=1853897&r1=1853896&r2=1853897&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/documentmk.md (original)
+++ jackrabbit/oak/branches/1.8/oak-doc/src/site/markdown/nodestore/documentmk.md Tue Feb 19 16:56:16 2019
@@ -61,7 +61,7 @@ The DocumentNodeStore supports a number
called `DocumentStore`:
* `MongoDocumentStore`: stores documents in a MongoDB.
-* `RDBDocumentStore`: stores documents in a relational data base.
+* [`RDBDocumentStore`](document/rdb-document-store.html): stores documents in a relational data base.
* `MemoryDocumentStore`: keeps documents in memory. This implementation should only be used for testing purposes.
The recommended MongoDB version depends on the Oak release. Below table lists
Modified: jackrabbit/oak/branches/1.8/oak-doc/src/site/site.xml
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.8/oak-doc/src/site/site.xml?rev=1853897&r1=1853896&r2=1853897&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.8/oak-doc/src/site/site.xml (original)
+++ jackrabbit/oak/branches/1.8/oak-doc/src/site/site.xml Tue Feb 19 16:56:16 2019
@@ -41,6 +41,7 @@ under the License.
<menu name="Features and Plugins">
<item href="nodestore/overview.html" name="Node Storage" collapse="false">
<item href="nodestore/documentmk.html" name="Document NodeStore" collapse="false">
+ <item href="nodestore/document/rdb-document-store.html" name="RDB DocumentStore" />
<item href="nodestore/document/node-bundling.html" name="Node Bundling" />
<item href="nodestore/document/secondary-store.html" name="Secondary Store" />
<item href="nodestore/persistent-cache.html" name="Persistent Cache" />
Modified: jackrabbit/oak/branches/1.8/oak-store-document/src/main/java/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.8/oak-store-document/src/main/java/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.java?rev=1853897&r1=1853896&r2=1853897&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.8/oak-store-document/src/main/java/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.java (original)
+++ jackrabbit/oak/branches/1.8/oak-store-document/src/main/java/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.java Tue Feb 19 16:56:16 2019
@@ -98,7 +98,7 @@ import com.google.common.collect.Sets;
/**
* Implementation of {@link DocumentStore} for relational databases.
*
- * <h3>Supported Databases</h3>
+ * <h3 id="apidocs.supported-databases">Supported Databases</h3>
* <p>
* The code is supposed to be sufficiently generic to run with a variety of
* database implementations. However, the tables are created when required to
@@ -114,7 +114,7 @@ import com.google.common.collect.Sets;
* <li>Oracle</li>
* </ul>
*
- * <h3>Table Layout</h3>
+ * <h3 id="apidocs.table-layout">Table Layout</h3>
* <p>
* Data for each of the DocumentStore's {@link Collection}s is stored in its own
* database table (with a name matching the collection).
@@ -200,7 +200,7 @@ import com.google.common.collect.Sets;
* testing, as tables can also be dropped automatically when the store is
* disposed (this only happens for those tables that have been created on
* demand).
- * <h4>Versioning</h4>
+ * <h4 id="apidocs.versioning">Versioning</h4>
* <p>
* The initial database layout used in OAK 1.0 through 1.6 is version 0.
* <p>
@@ -223,14 +223,15 @@ import com.google.common.collect.Sets;
* <em>For MySQL, the database parameter "max_allowed_packet" needs to be
* increased to support ~16M blobs.</em>
*
- * <h3>Table Creation</h3>
+ * <h3 id="apidocs.table-creation">Table Creation</h3>
* <p>
* The code tries to create the tables when they are not present. Likewise, it
* tries to upgrade to a newer schema when needed.
* <p>
* Users/Administrators who prefer to stay in control over table generation can
- * create them "manually". {@link RDBHelper} can be used to print out the DDL
- * statements that would have been used for auto-creation.
+ * create them "manually". The oak-run "<a href="https://jackrabbit.apache.org/oak/docs/nodestore/document/rdb-document-store.html#oak-run_rdbddldump"><code>rdbddldump</code></a>"
+ * command can be used to print out the DDL statements that would have been used for auto-creation
+ * and/or automatic schema updates.
*
* <h3>Caching</h3>
* <p>