How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jan 12, 2023

The purpose of this article is to provide information on tuning DS process sizes, including setting the JVM heap size and the database cache size.

3 readers recommend this article

Tuning heap size

Setting a larger heap size for the DS servers is generally a good thing that improves performance. You should also ensure all DS servers in a cluster have the same heap sizes.

The correct way to set the heap size is to edit the line in the file in the /path/to/ds/config directory. For example, to set the minimum and maximum heap sizes to 2GB, you would change this line as follows: -Xms2g -Xmx2g

You must restart the DS server after you have edited the file.


  • Set the minimum and maximum heap sizes to the same value for best performance. Otherwise, the JVM runs a full Garbage Collector (GC) cycle when increasing its heap, during which time it can pause ongoing operations for up to a few seconds. Generally, a smaller heap will increase the frequency at which the JVM GC executes but reduce the duration; similarly, a larger heap will reduce the frequency and increase the duration. When tuning the JVM heap, the goal is to strike a balance between frequency and duration to reduce the impact of the GC on the application.
  • Typically, a 64-bit JVM needs a larger heap size than an equivalent 32-bit JVM as a 64-bit JVM has a bigger memory footprint due to its object headers and object references being larger. An approximate guide is the heap size should be 1.5 times bigger in a 64-bit JVM compared to a similar 32-bit JVM.

Tuning database cache size

As of DS 6.5, new DS servers use a shared cache by default for all JE database backends. See What's New in 6.5.0 for further information.

In earlier versions, you have to configure this cache per JE backend.

Cache size for individual JE database backends (pre-DS 6.5)

For optimal performance, the database (DB) cache size should be larger than the sum of the DB file sizes.

First check the size of /path/to/ds/db/userRoot. If the DB has just been imported or hasn't been updated much since import, double that size. This will give you a maximum size the DB can grow to with the current data. You can then budget for the growth of the user data.

Once you have an estimated overall size of the DB, you should make sure that it can fit in the DB cache, which is by default estimated as a percentage of the overall heap size. The default cache size percentage (db-cache-percent) is 50%. You should adjust the database cache settings to avoid allocating all memory available to the JVM to the database cache when creating additional database backends. Over-allocating memory to the database cache leads to out of memory errors.

You can change the db-cache-percent using the dsconfig command. For example, to increase it to 60%:

$ ./dsconfig set-backend-prop --port 4444 --bindPassword password --backend-name userRoot --set db-cache-percent:60 --trustAll --no-prompt

We've run tests with many heap sizes, including some very large ones, and most of the large deployments use between 2GB and 32GB of JVM heap size.

See Also

Best practice for JVM Tuning with G1 GC

Best practice for JVM Tuning with CMS GC

FAQ: DS performance and tuning

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

How do I tune Background Database Verification in DS (All versions)?

How do I enable Garbage Collector (GC) Logging for DS?

Performance Settings 

JE Backend

Entry Cache

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