svn commit: r1852528 - in /jackrabbit/oak/trunk/oak-doc/src/site: markdown/nodestore/document/rdb-document-store.md markdown/nodestore/documentmk.md site.xml

[re...@apache.org]

Author: reschke
Date: Wed Jan 30 14:52:26 2019
New Revision: 1852528

URL: http://svn.apache.org/viewvc?rev=1852528&view=rev
Log:
OAK-7960: RDB: add to Oak documentationRDB: add to Oak documentation (work in progress)

Added:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md   (with props)
Modified:
    jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md
    jackrabbit/oak/trunk/oak-doc/src/site/site.xml

Added: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md?rev=1852528&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md (added)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md Wed Jan 30 14:52:26 2019
@@ -0,0 +1,94 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+  -->
+# RDB DocumentStore
+
+The `RDBDocumentStore` is one of the backend implementations for the
+[DocumentNodeStore](../documentmk.html). It uses relational databases to
+persist nodes as documents, mainly emulating the native capabilities of
+[MongoDocumentStore](mongo-document-store.html).
+
+Note that the [API docs for RDBDocumentStore](/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/document/rdb/RDBDocumentStore.html)
+contain more implementation details.
+
+## Supported Databases
+
+The code was written to be as database-agnostic as possible. That said, there 
+are vendor-specific code paths. Adding support for a new database type
+however should be relatively straighforward. Most of the database-specific
+code resides in the `RDBDocumentStoreDB` class.
+
+The following databases are supported in the sense that they are recognized
+and have been tested with:
+
+For testing purposes:
+
+- Apache Derby
+- H2DB
+
+For production use:
+
+- IBM DB2 (LUW)
+- Microsoft SQL Server
+- MySQL (MariaDB)
+- Oracle
+- PostgreSQL
+
+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).
+
+
+## Database Creation
+
+`RDBDocumentStore` relies on JDBC, and thus, in general, can not create
+database instances (that said, certain DBs such as Apache Derby or H2DB can create the
+database automatically when it's not there yet - consult the DB documentation
+in general and the JDBC URL syntax specifically).
+
+So in general, the administrator will have to take care of creating the database.
+There are only a few requirements for the database, but these are critical for
+the correct operation:
+
+- character fields must be able to store any Unicode code point - UTF-8 encoding is recommended
+- the collation for character fields needs to sort by Unicode code points
+
+## Table Creation
+
+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
+diagnostics in the log file.
+
+Administrators who want to create tables upfront can do so. The DDL statements
+for the supported databases can be dumped using [RDBHelper](/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/document/rdb/RDBHelper.html).
+
+
+## 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)
+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.
+
+
+
+

Propchange: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md
------------------------------------------------------------------------------
    svn:executable = *

Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md?rev=1852528&r1=1852527&r2=1852528&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md Wed Jan 30 14:52:26 2019
@@ -77,7 +77,7 @@ The DocumentNodeStore supports a number
 called `DocumentStore`:
 
 * [`MongoDocumentStore`](document/mongo-document-store.html): 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 remaining part of the document will focus on the `MongoDocumentStore` to

Modified: jackrabbit/oak/trunk/oak-doc/src/site/site.xml
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/site.xml?rev=1852528&r1=1852527&r2=1852528&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/site.xml (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/site.xml Wed Jan 30 14:52:26 2019
@@ -43,6 +43,7 @@ under the License.
       <item href="nodestore/overview.html" name="Node Storage" collapse="false">
         <item href="nodestore/documentmk.html" name="Document NodeStore" collapse="false">
           <item href="nodestore/document/mongo-document-store.html" name="MongoDB DocumentStore" />
+          <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" />