How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I tune the DS (All versions) database file cache?

Last updated Jan 12, 2023

The purpose of this article is to provide information on tuning the DS database file cache.

1 reader recommends this article


The je.log.fileCacheSize property represents the number of file handles that are cached, that is, file handles that remain open by the underlying database (DB). The default value is 200.


You should also be aware of the maximum number of file handlers defined in DS as discussed in the release notes applicable to your version: Maximum open files.

When the DB cannot be fully cached, the DB needs to access the record from the log files. Since only a portion of the files can be opened at one time, the DB keeps closing them and opening the ones it needs. Each close does a disk sync, which has a large penalty on performance.

The number of .jdb files depends on the DB content and also on the occupancy ratio. Occupancy ratio has an impact on the number of files. Berkeley DB JE uses a rolling log algorithm in which writes to the DB are always appended to the current log file. When the log reaches a certain size, JE creates a new one and writes to it. When records are deleted or even updated, the old record is marked as deleted and the new one is appended to the log file. This creates unused records in the previous log files. The occupancy ratio is the ratio of used records / total number of records per log file. When the ratio for one log file hits a certain limit (50% by default), the remaining valid records are copied to the current log file (still appending) and the old log file is deleted. So in theory and in the worse case, the number of log files cannot exceed twice the initial number of files after an import (with the same amount of data).

See Database Log File Settings for further information.

Tuning database file cache

To determine what value you should use for je.log.fileCacheSize, you should count the current number of .jdb files in the backend, double it and round down.

If the number of .jdb files exceeds the value set, then the DB starts closing files and reopening other ones, which can degrade performance.

This property can be maintained using the db-log-filecache-size configuration attribute, for example:

  • DS 7.1 and later: $ ./dsconfig set-backend-prop --hostname --port 4444 --bindDN uid=admin --bindPassword password --backend-name exampleBackend --advanced --set db-log-filecache-size:[cachesize] --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/ --no-prompt
  • DS 7: $ ./dsconfig set-backend-prop --hostname --port 4444 --bindDN uid=admin --bindPassword password --backend-name exampleBackend --advanced --set db-log-filecache-size:[cachesize] --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/ --no-prompt
  • DS 6.x: $ ./dsconfig set-backend-prop --hostname --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --backend-name userRoot --advanced --set db-log-filecache-size:[cachesize] --trustAll --no-prompt

You must restart DS for this change to take effect, or alternatively, you can disable and re-enable the backend to apply the change.

See Also

FAQ: DS performance and tuning

How do I tune DS process sizes: JVM heap and database cache?

Performance tuning and monitoring ForgeRock products

JE Backend

Related Training

ForgeRock Directory Services Core Concepts (DS-400)

Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.