Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Default values are used only if repository is in embedded mode, otherwise configuration validation fails.

Option

Description

Default

databaseSimplified option for repository setup. Possible values are h2, mysql, oracle, sqlserver, postgresql. This option will set defaults for other options, for example embedded, hibernateHbm2ddl, hibernateDialect and driverClassName based on selected database. These defaults can be overridden by specifying custom values in configuration.h2

dropIfExists

Drops database files if they exist during start. Useful for tests.

false

baseDir

Directory where H2 files will be saved if we're running in embedded mode.

<baseDir>${midpoint.home}</baseDir> can be used if we want to store H2 db files in midpoint.home directory

current folder "."

fileName

Database filename. Name for H2 files if we're running in embedded mode.

midpoint

embedded

Embedded H2 mode.

true

asServer

This option can be used if we're running in H2 embedded mode. If the server mode is turned on, H2 runs with TCP server. Other applications/services can connect to H2 server. If false, H2 runs in file mode.

false

tcpSSL

Embedded H2 server mode SSL.

false

port

Embedded H2 server mode port.

5437

hibernateHbm2ddl

Automatically validates or exports schema DDL to the database when the SessionFactory is created. E.g. validateupdatecreatecreate-drop | none.

With create-drop, the database schema will be dropped when the SessionFactory is closed explicitly.

For production environments, validate should be used (before midPoint 3.9) or none (3.9 and later). Please see Schema creation and updating section later.

for H2: update

otherwise: validate (before 3.9), none (3.9 and later)

hibernateDialect

SQL dialect based on choosen DB Supported hibernate dialects.

org.hibernate.dialect.H2Dialect

dataSource

Uses JNDI DataSource loading, when this option is defined in configuration, then jdbcUsername, jdbcPassword, jdbcUrl and driverClassName don't need to be present. E.g. <dataSource>java:comp/env/jdbc/midpoint</dataSource>


jdbcUsername

Username for JDBC connection.

sa (if embedded=true)

jdbcPassword

Password for JDBC connection.

empty string (if embedded=true)

jdbcUrl

URL for JDBC conection.

if embedded=true url is computed from previous parameters

driverClassName

Driver class name for JDBC connection.

org.h2.Driver (if embedded=true)

useZipProperty provides optional compression for full XML column.false
minPoolSizeMinimal # of connections in connection pool, if connection pool is not provided through dataSource.8
maxPoolSizeMaximum # of connections in connection pool, if connection pool is not provided through dataSource.20
cacheMaxTTLOption which can enable caching of selected object types (ConnectorType, ObjectTemplateType, SecurityPolicyType, SystemConfigurationType and ValuePolicyType). Objects are cached and reloaded only if object version doesn't match. Version check happens only after time to live (TTL) period has passed. Value in seconds.0
initializationFailTimeoutHikari pool initialization failure timeout, in milliseconds. It is there to allow midPoint to wait until the repository is up and running and therefore to avoid failing prematurely. Introduced in midPoint 3.9.1 ms (effectively keeping the behavior as it was before midPoint 3.9)

Anchor
schemaValidation
schemaValidation
Schema creation and updating

...

Schema validation and maintenance is the driven by these configuration options:

OptionDescriptionDefault
skipExplicitSchemaValidationWhether to skip this process of explicit schema validation.
  • true (i.e. "skip") if hibernateHbm2ddl is validateupdatecreate, or create-drop;
  • false (i.e. "do not skip") otherwise (e.g. if it is none which is the default for non-H2 databases)
missingSchemaAction

What to do if the database schema is not present:

  • stop: midPoint startup process is stopped with an appropriate explanation message;
  • warn: midPoint startup process continues (with a warning message); very probably to be crashed soon because of a repository access failure. This option is therefore not recommended;
  • create: midPoint tries to create the schema using appropriate SQL script. Then it checks the schema for validity again and stops if it's (still) invalid.
stop
upgradeableSchemaAction

What to do if the database schema is present but it is outdated and it seems to be upgradeable:

  • stop: midPoint startup process is stopped with an appropriate explanation message;
  • warn: midPoint startup process continues (with a warning message); very probably to be crashed sooner or later because of a repository access failure. This option is therefore not recommended;
  • upgrade:
    • if possible, midPoint tries to upgrade the schema by running appropriate SQL script. Then it checks the schema for validity again and stops if it's (still) invalid;
    • if not possible, midPoint acts as in stop case: outputs a message and stops.

Note that currently (as of 3.9) the only supported automated upgrade is from 3.8 to 3.9.

Please consider carefully whether you want to run this automatic upgrade also for the production environment. It is perhaps better to still run the upgrade manually in such situation.

stop 
incompatibleSchemaAction

What to do if the database schema is present, is not compatible and not upgradeable. A typical example is when the schema is newer than the current version of midPoint.

  • stop: midPoint startup process is stopped with an appropriate explanation message;
  • warn: midPoint startup process continues (with a warning message); very probably to be crashed sooner or later because of a repository access failure. This option is therefore not recommended;
 stop
schemaVersionIfMissingIf the schema version cannot be determined from m_global_metadata table e.g. because the table does not exist, it is possible to specify it using this parameter. It applies only if the version is missing in the database.(none)
schemaVersionOverrideOverrides any schema version information in the m_global_metadata table.(none)
schemaVariant

Used to specify what schema variant is to be used for automated creation or upgrade of the database schema. Currently the only known variant is utf8mb4 for MySQL/MariaDB.

Beware: it is the administrator's responsibility to choose the correct variant! Currently midPoint does not try to determine the variant present in the database. So be sure to avoid applying e.g. mysql-upgrade-3.8-3.9-utf8mb4.sql if the database is not in utf8mb4 character set, or vice versa.

(none)

Schema creation and updating (before 3.9)

...

  1. First step is DB resource configuration in application server. Here is example for Tomcat 7. This XML part is located in <tomcat-location>/conf/server.xml, resource will be available for all applications in container.

    Code Block
    languagehtml/xml
    linenumberstrue
    <GlobalNamingResources>
    	<Resource name="jdbc/mysql" auth="Container" type="javax.sql.DataSource"
    		username="MYSQL_USER" password="MYSQL_USER_PASSWORD"
    		url="jdbc:mysql://localhost:3306/midpoint-big"
    		driverClassName="com.mysql.jdbc.Driver" 
    		accessToUnderlyingConnectionAllowed="true"
    		initialSize="5" maxWait="5000"
    		maxActive="30" maxIdle="5"
    		validationQuery="select 1"
    		poolPreparedStatements="true"/>
    </GlobalNamingResources>

    Also configure <tomcat-location>/conf/context.xml file:

    Code Block
    languagehtml/xml
     <?xml version='1.0' encoding='utf-8'?>
    <Context>
        <WatchedResource>WEB-INF/web.xml</WatchedResource>
        <ResourceLink name="jdbc/mysql"
                      global="jdbc/mysql"
                      type="javax.sql.DataSource"/>
    </Context>


  2. Next step is configuration in file config.xml located in midpoint.home folder. hibernateDialect depends on your DB choice, dataSource is based on resource name.

    Code Block
    languagehtml/xml
    linenumberstrue
    <configuration>
    	<midpoint>
    		<repository>
    			<repositoryServiceFactoryClass>com.evolveum.midpoint.repo.sql.SqlRepositoryFactory</repositoryServiceFactoryClass>
    			<embedded>false</embedded>
    			<hibernateDialect>com.evolveum.midpoint.repo.sql.util.MidPointMySQLDialect</hibernateDialect>
    			<hibernateHbm2ddl>validate</hibernateHbm2ddl>
    			<dataSource>java:comp/env/jdbc/mysql</dataSource>
    		</repository>
    	</midpoint>
    </configuration>


Warning
Note
titleMissing/incomplete feature

It is currently not possible to set up data sources with standalone configuration (i.e. when using embedded Tomcat). We are perfectly capable to implement, fix and finish the feature, just the funding for the work is needed. Please consider the possibility for supporting development of this feature by means of midPoint Platform subscription. If you already are midPoint Platform subscriber and this feature is within the goals of your deployment you may be able to use your subscription to endorse implementation of this feature.

...