RDB DocumentStore

The RDBDocumentStore is one of the backend implementations for the DocumentNodeStore. It uses relational databases to persist nodes as documents, mainly emulating the native capabilities of MongoDocumentStore.

Note that the API docs for RDBDocumentStore 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):

12:20:20.864 ERROR [main] RDBDocumentStore.java:1014        Unsupported Apache Derby version: 9.14, expected at least 10.11

Initialization

The recommended method to initialize a DocumentNodeStore with an RDBDocumentStore is using an OSGi container and configure the DocumentNodeStoreService. See corresponding Repository OSGi Configuration.

This will also require deploying the Sling DataSource provider and furthermore the associated JDBC driver as OSGi bundle. The details of the latter vary by database:

If the JDBC driver already is an OSGI bundle, it can be deployed as is. This is the case for Apache Derby, H2DB, IBM DB2, Microsoft SQL Server, MySQL, and PostgreSQL. Some of these drivers also implement the OSGi Data Service Specification for JDBC , in which case org.osgi.service.jdbc-1.0.0.jar needs to be deployed as well (this is the case for IBM DB2, Microsoft SQL Server, and PostgreSQL).
Otherwise (e.g., Oracle), an OSGi wrapper needs to be built. See below.

Alternatively an RDB based DocumentNodeStore can be created with the help of a RDBDocumentNodeStoreBuilder.

DataSource dataSource = RDBDataSourceFactory.forJdbcUrl(jdbcurl, user, pw);
DocumentNodeStore store = RDBDocumentNodeStoreBuilder().newRDBDocumentNodeStoreBuilder()
    .setRDBConnection(dataSource).build();
// do something with the store
NodeState root = store.getRoot();

// dispose it when done
store.dispose();

Example: Creating OSGi Bundle for Oracle JDBC driver

Make sure to have a local copy of the JDBC driver, for instance ojdbc8-12.2.0.1.jar.
Get BND command line tool from https://repo1.maven.org/maven2/biz/aQute/bnd/biz.aQute.bnd/4.3.1/biz.aQute.bnd-4.3.1.jar
Create BND ora.bnd below:

 -classpath: ojdbc8-12.2.0.1.jar
 Bundle-SymbolicName: com.oracle.jdbc.ojdbc8
 ver: 12.2.0.1
 -output: ${bsn}-${ver}.jar
 Bundle-Version: ${ver}
 Include-Resource: @ojdbc8-12.2.0.1.jar
 Import-Package: *;resolution:=optional

Then run java -jar biz.aQute.bnd-4.3.1.jar ora.bnd; this should create the OSGi bundle com.oracle.jdbc.ojdbc8-12.2.0.1.jar.

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
BLOBs need to support sizes of ~16MB

The subsections below give examples that have been found to work during the development of RDBDocumentStore.