Using a Database Target with MicroStream CDI Integration

The CDI integration of MicroStream allows you to work with the Storage Manager and the object root in a declarative way. The StorageManager is configured using configuration values that are retrieved through MicroProfile Config and the integration provides the MicroStream concepts as CDI beans and makes use of the interceptor mechanism to store changes.

Besides the filesystem, the CDI integration can also make use of other targets like storing the serialised content into a database as a BLOB or cloud storage. This blog describes how you can use a PostgreSQL database instance to store your object instances with the CDI integration version 7.0. In a future version, the procedure will be slightly updated (made easier) and the changes will be updated in this blog at the time of the release.

Dependencies

Besides the CDI integration artefact itself, you also need an additional dependency that supports the MicroStream’s Abstract File System (AFS) for a database (See the user guide)

The following dependencies are added to the Maven project file for our example.

<dependency>
   <groupId>one.microstream</groupId>
   <artifactId>microstream-integrations-cdi</artifactId>
   <version>${microstream.version}</version>
</dependency>

<!-- Support for databases in MicroStream -->
<dependency>
   <groupId>one.microstream</groupId>
   <artifactId>microstream-afs-sql</artifactId>
   <version>${microstream.version}</version>
</dependency>

<!-- JDBC driver -->
<dependency>
   <groupId>org.postgresql</groupId>
   <artifactId>postgresql</artifactId>
   <version>42.3.6</version>
</dependency>

The `microstream-afs-sql` artefact is all that is needed to allow MicroStream to make use of the PostgreSQL database.

The PostgreSQL dependency itself is added to have the JDBC driver available within the application and the runtime. An alternative is that the driver is made available through the runtime directly and not provided through the application. Look at the documentation of the runtime you are using to provide the JDBC drivers.

Configuration

The configuration values for the database connection like the JDBC URL, username and password will be retrieved using MicroProfile config. The following set of configuration values are the minimum set of configuration keys that is needed to configure the PostgreSQL database integration:

one.microstream.property.storage-filesystem.sql.postgres.data-source-provider=be.rubus.microstream.cdi.database.config.MyDataSourceProvider
one.microstream.property.storage-filesystem.sql.postgres.password=mysecretpassword
one.microstream.property.storage-filesystem.sql.postgres.user=postgres
one.microstream.property.storage-filesystem.sql.postgres.url=jdbc:postgresql://localhost:5432/postgres

The URL, username, and password values are self-explanatory. The data-source-provider Class provides the MicroStream system with the database connection that will be used to read and write the serialised data of the java instances that make up your data. More on that in the next section.

Important remarks about the key values for a successful configuration.

The key values need to start with `one.microstream.property.` and the remainder of the key needs to follow the MicroStream convention. So it is required to use `storage-filesystem` (and not `storage.filesystem`) which means that, for example, the configuration keys can’t be specified as environment variables since it contains an ‘-‘ character. This will be improved in the next version of the integration.

Other properties, like the number of channels that are used to read and write the data, can be specified using the standard keys like

Providing the Database Connection

The database connection must be provided by an implementation of the interface `one.microstream.afs.sql.types.SqlDataSourceProvider` that is implemented by the developer and the fully qualified class name is specified as a configuration value. The method `provideDataSource()` has a `Configuration` parameter that gives you access to configuration values for the target.

It is up to the developer to determine how he provides the connection, using the capabilities of the runtime like a connection pool or simply providing the DataSource instance directory from the JDBC driver.

@Override
public DataSource provideDataSource(Configuration configuration) {
    PGSimpleDataSource dataSource = new PGSimpleDataSource();
    dataSource.setUrl(configuration.get("url"));
    dataSource.setUser(configuration.get("user"));
    dataSource.setPassword(configuration.get("password"));

    return dataSource;
}

And that is all that is needed to configure the MicroStream Storage Manager with a database using the CDI integration.

An example project can be found in this GitHub repository.