SQL storage for Gentics Mesh

SQL storage for Gentics Mesh

Description

Despite Gentics Mesh provides an own noSQL graph storage in its bundle, there is now a possibility to use an external SQL database instead of it, either provided by the customer or served along with the main application. As of now the following RDBMSs are supported: MSSQL 2019+, Oracle 19+, PostgreSQL 14.4+, MariaDB 10.3+ (DBs not included).

Documentation

Despite Gentics Mesh being bundled with a noSQL Graph Database as storage, there is an enterprise feature available to use a Relational Database as storage. The used Relational Database has to be provided and is not included or managed by Gentics Mesh.

As of now the following RDBMSs are supported:

  • MSSQL 2019+

  • Oracle 19+

  • PostgreSQL 14.4+

  • MariaDB 10.3+.

Configuration

Most of the configuration options are the same that can be used for Mesh running with OrientDB. There are however extra configuration options that are database-specific.

Environment Variables

The following environment variables will override settings within the mesh.yml.

Variable Description

MESH_JDBC_DATABASE_NAME

Override the default database name.

MESH_FIELD_CONTAINER_CACHE_SIZE

Override the field container cache size.

HIKARI_CP_MAX_POOL_SIZE

This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. Basically this value will determine the maximum number of actual connections to the database backend. A reasonable value for this is best determined by your execution environment. When the pool reaches this size, and no idle connections are available, calls to getConnection() will block for up to connectionTimeout milliseconds before timing out.

MESH_TX_RETRY_DELAY_SECONDS

Override the default transaction retry delay interval.

MESH_DB_SYNC_WRITES_TIMEOUT

Override the database sync write timeout.

LICENSEKEY

The license key

MESH_JDBC_DRIVER_CLASS

Override the default JDBC driver class.

HIKARI_CP_MIN_IDLE_CONNECTION

This property controls the minimum number of idle connections that HikariCP tries to maintain in the pool. If the idle connections dip below this value and total connections in the pool are less than maximumPoolSize, HikariCP will make a best effort to add additional connections quickly and efficiently. However, for maximum performance and responsiveness to spike demands, we recommend not setting this value and instead allowing HikariCP to act as a fixed size connection pool.

MESH_JDBC_CONNECTION_URL_EXTRA_PARAMS

Add the default JDBC connection URL extra params.

MESH_HIBERNATE_GENERATE_STATISTICS

Set whether hibernate should generate statistics.

MESH_JDBC_DRIVER_CLASSPATH

Set the JDBC drivers classpath.

HIKARI_CP_CONNECTION_TIMEOUT

This property controls the maximum number of milliseconds that a client (that's you) will wait for a connection from the pool. If this time is exceeded without a connection becoming available, a SQLException will be thrown. Lowest acceptable connection timeout is 250 ms.

MESH_JDBC_CONNECTION_URL

Override the default JDBC connection URL.

MESH_HIBERNATE_NATIVE_QUERY_FILTERING

Override the configured native query filtering.

MESH_JDBC_CONNECTION_USERNAME

Set the JDBC connection username.

MESH_HIBERNATE_SECOND_LEVEL_CACHE_ENABLED

Set whether second-level cache should be enabled.

MESH_HIBERNATE_JDBC_BATCH_SIZE

Set batch size. Recommended values are between 5 and 30

MESH_HIBERNATE_QUERY_TIMEOUT

Query timeout for hibernate. Default: 0

MESH_JDBC_RETRY_LIMIT

Override the default transaction retry count.

HIKARI_CP_POOL_NAME

This property represents a user-defined name for the connection pool and appears mainly in logging and JMX management consoles to identify pools and pool configurations.

MESH_DB_SYNC_WRITES

Override the database sync writes flag.

HIKARI_CP_MAX_LIFETIME

This property controls the maximum lifetime of a connection in the pool. An in-use connection will never be retired, only when it is closed will it then be removed. On a connection-by-connection basis, minor negative attenuation is applied to avoid mass-extinction in the pool. We strongly recommend setting this value, and it should be several seconds shorter than any database or infrastructure imposed connection time limit. A value of 0 indicates no maximum lifetime (infinite lifetime), subject of course to the idleTimeout setting. The minimum allowed value is 30000ms (30 seconds).

HIKARI_CP_LEAK_DETECTION_THRESHOLD

This property controls the amount of time that a connection can be out of the pool before a message is logged indicating a possible connection leak. A value of 0 means leak detection is disabled. Lowest acceptable value for enabling leak detection is 2000 (2 seconds).

MESH_HIBERNATE_SHOW_SQL

Set whether the driver-specific SQL queries should be logged.

MESH_DB_EXPORT_DIRECTORY

Override the graph database export directory.

MESH_LIST_FIELD_CACHE_SIZE

Override the list field cache size.

HIKARI_CP_REGISTER_MBEANS

This property controls whether or not JMX Management Beans ("MBeans") are registered or not.

HIKARI_CP_TRANSACTION_ISOLATION_LEVEL

This property controls the default transaction isolation level of connections returned from the pool. If this property is not specified, the default transaction isolation level defined by the JDBC driver is used. Only use this property if you have specific isolation requirements that are common for all queries. The value of this property is the constant name from the Connection class such as TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ. Setting it to null defaults to isolation level defined in the JDBC driver.

MESH_HIBERNATE_EXPOSE_JMX_METRICS

Set whether hibernate should expose jmx metrics

MESH_JDBC_CONNECTION_PASSWORD

Set the JDBC connection password.

LICENSEKEY_PATH

Override the default licence key file path.

MESH_JDBC_DIALECT_CLASS

Override the default JDBC dialect class.

MESH_HIBERNATE_FORMAT_SQL

Set whether the driver-specific SQL queries should be formatted while logged.

HIKARI_CP_AUTOCOMMIT

This property controls the default auto-commit behavior of connections returned from the pool. It is a boolean value.

MESH_DB_SQL_PARAMETERS_LIMIT

Limit the number of SQL parameters in selected lookup queries. Can be either `definedByDatabase` or `unlimited` or a custom number (greater than zero). Default is: definedByDatabase

MESH_HIBERNATE_SLOW_SQL_THRESHOLD

Slow SQL query threshold in milliseconds. Default: 60000

MESH_STALE_TX_CHECK_INTERVAL

Overwrite the interval (in ms) for periodic check for stale transactions.

HIKARI_CP_IDLE_TIMEOUT

This property controls the maximum amount of time that a connection is allowed to sit idle in the pool. This setting only applies when minimumIdle is defined to be less than maximumPoolSize. Idle connections will not be retired once the pool reaches minimumIdle connections. Whether a connection is retired as idle or not is subject to a maximum variation of +30 seconds, and average variation of +15 seconds. A connection will never be retired as idle before this timeout. A value of 0 means that idle connections are never removed from the pool. The minimum allowed value is 10000ms (10 seconds).

Examples:

Configuration for PostgreSQL

JDBC Driver

Download postgresql-X.Y.Z.jar from https://jdbc.postgresql.org/download.html , place it at the server into the folder, reachable by Gentics Mesh.

DB configuration

Define the database and Mesh user. This example uses environment variables.

export POSTGRES_DB=mesh
export POSTGRES_USER=meshdbuser
export POSTGRES_PASSWORD=admin

Create the dedicated schema.

CREATE SCHEMA current;
Mesh Configuration
storageOptions:
  retryLimit: 10
  retryDelayMillis: 2000
  driverClass: "org.postgresql.Driver"
  dialectClass: "org.hibernate.dialect.PostgreSQL95Dialect"
  connectionUrl: "jdbc:postgresql://localhost:5432/"
  connectionUrlExtraParams: "?autosave=always&currentSchema=current"
  databaseName: "mesh"
  driverClasspath: "path/to/downloaded/driver/postgresql-X.Y.Z.jar"
  connectionUsername: "meshdbuser"
  connectionPassword: "admin"
  showSql: false
  formatSql: false
  hikariOptions:
    autocommit: false
    connectionTimeout: 10000
    idleTimeout: 600000
    maxLifetime: 1800000
    minimumIdleConnection: 10
    maxPoolSize: 10
    poolName: "MeshHikariCP"
    registerMBeans: false
    transactionIsolationLevel: null
    leakDetectionThreshold: 0
  synchronizeWrites: false
  synchronizeWritesTimeout: 6000

Configuration for MSSQL

This example uses inbuilt "SA" user.

JDBC Driver

Download sqljdbc_X.Y.Z.W_enu.zip from https://docs.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver16 , unpack mssql-jdbc-X.Y.Z.jre11.jar at the server into the folder, reachable by Mesh.

DB configuration

Define the "SA" user password. This example uses environment variables.

export SA_PASSWORD=admin

Create the dedicated database:

CREATE DATABASE mesh;

Alter the isolation level

ALTER DATABASE mesh SET READ_COMMITTED_SNAPSHOT ON;
Mesh Configuration
storageOptions:
  retryLimit: 10
  retryDelayMillis: 2000
  driverClass: "com.microsoft.sqlserver.jdbc.SQLServerDriver"
  dialectClass: "com.gentics.mesh.enterprise.hibernate.dialect.SqlServer2012UnicodeDialect"
  connectionUrl: "jdbc:sqlserver://localhost:1433;databaseName="
  connectionUrlExtraParams: ";encrypt=false"
  databaseName: "mesh"
  driverClasspath: "path/to/extracted/driver/mssql-jdbc-X.Y.Z.jre11.jar"
  connectionUsername: "SA"
  connectionPassword: "admin"
  showSql: false
  formatSql: false
  hikariOptions:
    autocommit: false
    connectionTimeout: 10000
    idleTimeout: 600000
    maxLifetime: 1800000
    minimumIdleConnection: 10
    maxPoolSize: 10
    poolName: "MeshHikariCP"
    registerMBeans: false
    transactionIsolationLevel: null
    leakDetectionThreshold: 0
  synchronizeWrites: false
  synchronizeWritesTimeout: 6000

Configuration for MariaDB

JDBC Driver

Download mariadb-java-client-X.Y.Z.jar from https://mariadb.org/connector-java/all-releases/ , place it at the server into the folder, reachable by Mesh.

DB configuration

Define the database and Mesh user. This example uses environment variables.

export MYSQL_DATABASE=mesh
export MYSQL_USER=meshdbuser
export MYSQL_PASSWORD=admin

Install the isolation level for the database on start with the startup parameter

--transaction-isolation=READ-COMMITTED

Create the dedicated database:

CREATE DATABASE mesh;

Alter the access privileges for the Mesh user

GRANT ALL PRIVILEGES ON mesh.* TO 'meshdbuser'@'%';
Mesh Configuration
storageOptions:
  retryLimit: 10
  retryDelayMillis: 2000
  driverClass: "org.mariadb.jdbc.Driver"
  dialectClass: "com.gentics.mesh.hibernate.dialect.mariadb.uuidbinary.MariaDB103UuidAwareDialect"
  connectionUrl: "jdbc:mariadb://localhost:3306/"
  connectionUrlExtraParams: ""
  databaseName: "mesh"
  driverClasspath: "path/to/downloaded/driver/mariadb-java-client-X.Y.Z.jar"
  connectionUsername: "meshdbuser"
  connectionPassword: "admin"
  showSql: false
  formatSql: false
  hikariOptions:
    autocommit: false
    connectionTimeout: 10000
    idleTimeout: 600000
    maxLifetime: 1800000
    minimumIdleConnection: 10
    maxPoolSize: 10
    poolName: "MeshHikariCP"
    registerMBeans: false
    transactionIsolationLevel: null
    leakDetectionThreshold: 0
  synchronizeWrites: false
  synchronizeWritesTimeout: 6000
JDBC Driver

Download ojdbc11.jar from https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html , place it at the server into the folder, reachable by Mesh.

DB configuration

Define the database and Mesh user. This example uses environment variables.

export ORACLE_DATABASE=mesh

Create the dedicated database:

CREATE DATABASE mesh;

Alter the number of simultaneously open cursors

ALTER SYSTEM SET OPEN_CURSORS=4444 SID='*' SCOPE=BOTH;

Create the dedicated user

CREATE USER meshdbuser IDENTIFIED BY "admin";
GRANT ALL PRIVILEGES TO meshdbuser;
Mesh Configuration
storageOptions:
  retryLimit: 10
  retryDelayMillis: 2000
  driverClass: "oracle.jdbc.driver.OracleDriver"
  dialectClass: "com.gentics.mesh.enterprise.hibernate.dialect.Oracle12cLongTextDialect"
  connectionUrl: "jdbc:oracle:thin:@localhost:1521/"
  connectionUrlExtraParams: ""
  databaseName: "mesh"
  driverClasspath: "path/to/downloaded/driver/ojdbc11.jar"
  connectionUsername: "meshdbuser"
  connectionPassword: "admin"
  showSql: false
  formatSql: false
  hikariOptions:
    autocommit: false
    connectionTimeout: 10000
    idleTimeout: 600000
    maxLifetime: 1800000
    minimumIdleConnection: 10
    maxPoolSize: 10
    poolName: "MeshHikariCP"
    registerMBeans: false
    transactionIsolationLevel: null
    leakDetectionThreshold: 0
  synchronizeWrites: false
  synchronizeWritesTimeout: 6000

Plugin Details

Gentics Mesh provides a feature of using one of the mainstream SQL RDBMSs as a storage for Mesh, to allow more control over the data being served.

Interested?

Version

1.9.x

License

commercial

Authors

Gentics