--- title: Repository configuration files description: Configuration files for all supported repositories are located in the /path/to/openidm/db/database/conf directory. For JDBC repositories, the configuration is defined in two files: component: pingidm version: 8.1 page_id: pingidm:objects-guide:repo-config canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/repo-config.html keywords: ["Data Object Model", "Repository", "JDBC"] section_ids: datasource-jdbc-json: JDBC connection configuration repo-jdbc-json: JDBC database table configuration repo-ds-json: DS repository configuration --- # Repository configuration files Configuration files for all supported repositories are located in the `/path/to/openidm/db/database/conf` directory. For JDBC repositories, the configuration is defined in two files: * `datasource.jdbc-default.json` specifies the connection to the database. * `repo.jdbc.json` specifies the mapping between IDM resources and database tables. For a DS repository, the `repo.ds.json` file specifies the resource mapping and, in the case of an external repository, the connection details to the LDAP server. For both DS and JDBC, the `conf/repo.init.json` file specifies IDM's initial [internal roles and users](../auth-guide/authorization-and-roles.html#idm-authorization). Copy the configuration files for your specific database type to your project's `conf/` directory. ## JDBC connection configuration The default database connection configuration file for a MySQL database follows: ```json { "driverClass" : "com.mysql.cj.jdbc.Driver", "jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8&serverTimezone=UTC", "databaseName" : "openidm", "username" : "openidm", "password" : "openidm", "connectionTimeout" : 30000, "connectionPool" : { "type" : "hikari", "minimumIdle" : 20, "maximumPoolSize" : 50 } } ``` The configuration file includes the following properties: * `driverClass` `"driverClass" : string` To use the JDBC driver manager to acquire a data source, set this property, as well as `jdbcUrl`, `username`, and `password`. The driver class must be the fully-qualified class name of the database driver to use for your database. Using the JDBC driver manager to acquire a data source is the most likely option, and the only one supported "out of the box". The remaining options in the sample repository configuration file assume that you are using a JDBC driver manager. Example: `"driverClass" : "com.mysql.cj.jdbc.Driver"` * `jdbcUrl` The connection URL to the JDBC database. The URL should include all parameters required by your database. For example, to specify the encoding in MySQL use `'characterEncoding=utf8'`. Specify the values for `openidm.repo.host` and `openidm.repo.port` in one of the following ways: * Set the values in `resolver/boot.properties` or your project's `conf/system.properties` file, for example: ```properties openidm.repo.host = localhost openidm.repo.port = 3306 ``` * Set the properties in the `OPENIDM_OPTS` environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example: ``` export OPENIDM_OPTS="-Xmx2048m -Xms2048m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=3306" /path/to/openidm/startup.sh Executing ./startup.sh... Using OPENIDM_HOME: /path/to/openidm Using PROJECT_HOME: /path/to/openidm Using OPENIDM_OPTS: -Xmx2048m -Xms2048m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=3306 ... Using boot properties at /path/to/openidm/resolver/boot.properties -> OpenIDM version "8.1.0" OpenIDM ready ``` * `databaseName` The name of the database, used in SQL queries. For example: ```sql select * from databaseName.managedobjects ``` In addition to the SQL queries that are generated by IDM, any queries defined in the `repo.jdbc.json` file replace `{_dbSchema}` with the value of the `databaseName` property. For example, the following query in the `repo.jdbc.json` file replaces the `{_dbSchema}` with the value of the `databaseName`: ```json "delete-mapping-links" : "DELETE FROM ${_dbSchema}.${_table} WHERE linktype = ${mapping}", ``` * `username` The username with which to access the JDBC database. * `password` The password with which to access the JDBC database. IDM automatically encrypts clear string passwords. To replace an existing encrypted value, replace the whole `crypto-object` value, including the brackets, with a string of the new password. * `connectionTimeout` The period of time, in milliseconds, after which IDM should consider an attempted connection to the database to have failed. The default period is 30000 milliseconds (30 seconds). * `connectionPool` Database connection pooling configuration. The default connection pool library is HikariCP: ```json "connectionPool" : { "type" : "hikari" } ``` IDM uses the default HikariCP configuration, except for the following parameters. You might need to adjust these parameters, according to your database workload: * `minimumIdle` This property controls the minimum number of idle connections that HikariCP maintains in the connection pool. If the number of idle connections drops below this value, HikariCP attempts to add additional connections. By default, HikariCP runs as a fixed-sized connection pool, that is, this property is not set. The connection configuration files provided with IDM set the minimum number of idle connections to `20`. * `maximumPoolSize` This property controls the maximum number of connections to the database, including idle connections and connections that are being used. By default, HikariCP sets the maximum number of connections to `10`. The connection configuration files provided with IDM set the maximum number of connections to `50`. For information about the HikariCP configuration parameters, refer to the [HikariCP Project Page](https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby). ## JDBC database table configuration An excerpt of a MySQL database table configuration file follows: ```json { "dbType" : "MYSQL", "useDataSource" : "default", "maxBatchSize" : 100, "maxTxRetry" : 5, "queries" : {...}, "commands" : {...}, "resourceMapping" : {...} } ``` The configuration file includes the following properties: * `dbType` : string, optional The type of database. The database type might affect the queries used and other optimizations. Supported database types include the following:\ `DB2`\ `SQLSERVER` (for Microsoft SQL Server)\ `MYSQL`\ `ORACLE`\ `POSTGRESQL` * `useDataSource` : string, optional This option refers to the connection details that are defined in the configuration file, described previously. The default configuration file is named `datasource.jdbc-default.json`. This is the file that is used by default (and the value of the `"useDataSource"` is therefore `"default"`). You might want to specify a different connection configuration file, instead of overwriting the details in the default file. In this case, set your connection configuration file `datasource.jdbc-name.json` and set the value of `"useDataSource"` to whatever name you have used. * `maxBatchSize` The maximum number of SQL statements that will be batched together. This parameter lets you optimize the time taken to execute multiple queries. Certain databases do not support batching, or limit how many statements can be batched. A value of `1` disables batching. * `maxTxRetry` The maximum number of times that a specific transaction should be attempted before that transaction is aborted. * `queries` Any custom [queries](queries.html#parameterized-queries) that can be referenced from the configuration. Options supported for query parameters include the following: * A default string parameter, for example: ```javascript openidm.query("managed/user", { "_queryId": "for-userName", "uid": "jdoe" }); ``` For more information about the query function, refer to [openidm.query](../scripting-guide/scripting-func-ref.html#function-query). * A list parameter (`${list:propName}`). Use this parameter to specify a set of indeterminate size as part of your query. For example: ```sql WHERE targetObjectId IN (${list:filteredIds}) ``` * A boolean parameter (`${bool:propName}`). Use this parameter to query boolean values in the database. * Numeric parameters for integers (`${int:propName}`), large integers (`${long:propName}`), and decimal values (`${num:propName}`). Use these parameters to query numeric values in the database, corresponding to the column data type in your repository. * `commands` Specific commands configured to manage the database over the REST interface. Currently, the following default commands are included in the configuration: * `purge-by-recon-expired` * `purge-by-recon-number-of` * `delete-mapping-links` * `delete-target-ids-for-recon` These commands assist with removing stale reconciliation audit information from the repository, and preventing the repository from growing too large. The commands work by executing a query filter, then performing the specified operation on each result set. Currently the only supported operation is `DELETE`, which removes all entries that match the filter. * `resourceMapping` Defines the mapping between IDM resource URIs (for example, `managed/user`) and JDBC tables. The structure of the resource mapping is as follows: ```json "resourceMapping" : { "default" : { "mainTable" : "genericobjects", "propertiesTable" : "genericobjectproperties", "searchableDefault" : true }, "genericMapping" : {...}, "explicitMapping" : {...} } ``` The default mapping object represents a default generic table in which any resource that does not have a more specific mapping is stored. The generic and explicit mapping objects are described in the following section. ## DS repository configuration An excerpt of a DS repository configuration file follows: ```json { "embedded" : false, "maxConnectionAttempts" : 5, "security" : {...}, "ldapConnectionFactories" : {...}, "queries" : {...}, "commands" : {...}, "rest2LdapOptions" : {...}, "indices" : {...}, "schemaProviders" : {...}, "resourceMapping" : {...} } ``` The configuration file includes the following properties: * `embedded` : boolean Specifies an embedded or external DS instance. As of IDM 8.0, the embedded instance is no longer included or supported. * `maxConnectionAttempts` : integer Specifies the number of times IDM should attempt to connect to the DS instance. On startup, IDM will attempt to connect to DS indefinitely. The `maxConnectionAttempts` parameter controls the number of reconnection attempts in the event of a failure during normal operation, for example, if an attempt to access the DS repository times out. By default, IDM will attempt to reconnect to the DS instance `5` times. * `security` Specifies the keystore and truststore for secure connections to DS. ```json "security": { "trustManager": "file", "fileBasedTrustManagerType": "JKS", "fileBasedTrustManagerFile": "&{idm.install.dir}/security/truststore", "fileBasedTrustManagerPasswordFile": "&{idm.install.dir}/security/storepass" } ``` In the default case, where DS servers use TLS key pairs generated using a deploymentId and deploymentIdPassword, you must import the deploymentId-based CA certificate into the IDM truststore. For more information, refer to [PingDS repository](../install-guide/external-ds.html). * `ldapConnectionFactories` For an external DS repository, configures the connection to the DS instance. For example: ```json "ldapConnectionFactories": { "bind": { "connectionSecurity": "startTLS", "heartBeatIntervalSeconds": 60, "heartBeatTimeoutMilliSeconds": 10000, "primaryLdapServers": [ { "hostname": "localhost", "port": 31389 } ], "secondaryLdapServers": [] }, "root": { "inheritFrom": "bind", "authentication": { "simple": { "bindDn": "uid=admin", "bindPassword": "password" } } } } ``` The connection to the DS repository uses the DS *REST2LDAP* gateway and the `ldapConnectionFactories` property sets the gateway configuration. For example, the `secondaryLdapServers` property specifies an array of LDAP servers that the gateway can contact if the primary LDAP servers cannot be contacted. Learn more about the [gateway configuration properties](https://docs.pingidentity.com/pingds/7.3/rest-guide/rest2ldap.html#config-json). * `queries` Predefined queries that can be referenced from the configuration. For a DS repository, all predefined queries are really filtered queries (using the `_queryFilter` parameter), for example: ```json "query-all-ids": { "_queryFilter": "true", "_fields": "_id,_rev" } ``` The queries are divided between those for `generic` mappings and those for `explicit` mappings, but the queries themselves are the same for both mapping types. * `commands` Specific commands configured to manage the repository over the REST interface. Currently, only two commands are included by default: * `delete-mapping-links` * `delete-target-ids-for-recon` Both of these commands assist with removing stale reconciliation audit information from the repository, and preventing the repository from growing too large. * `rest2LdapOptions` Specifies the configuration for accessing the LDAP data stored in DS. Learn more about the [gateway REST2LDAP configuration](https://docs.pingidentity.com/pingds/7.3/rest-guide/rest2ldap.html#rest2ldap-json). * `indices` For generic mappings, enables you to set up LDAP indices on custom object properties. Learn more about [indexing in DS](https://docs.pingidentity.com/pingds/8.1/config-guide/indexing.html). * `schemaProviders` For generic mappings, enables you to list custom objects whose properties should be indexed. Learn more about [indexing in DS](https://docs.pingidentity.com/pingds/8.1/config-guide/indexing.html). * `resourceMapping` Defines the mapping between IDM resource URIs (for example, `managed/user`) and the DS directory tree. The structure of the resource mapping object is as follows: ```json { "resourceMapping" : { "defaultMapping": { "dnTemplate": "ou=generic,dc=openidm,dc=forgerock,dc=com" }, "explicitMapping" : {...}, "genericMapping" : {...} } } ``` The default mapping object represents a default generic organizational unit (`ou`) in which any resource that does not have a more specific mapping is stored. The generic and explicit mapping objects are described in [Object mappings](explicit-generic-mapping.html).