Database Management Settings

The <database> configuration element specifies back end (database engine) settings which are relevant on the server side and in embedded mode.

The default configuration file contains the following <database> element:

<database>
  <size initial="256kb" resize="256kb" page="2kb" />
  <recovery enabled="true" sync="false" path="." max="128mb" />
  <recording enabled="false" sync="false" path="." mode="write" />
  <locking version-check="true" />
  <processing cache="64mb" max-threads="10" synchronized="false" /> 
  <query-cache results="32mb" programs="500" />
  <extensions drop="temp,tmp" />
</database>

The <size> element

  <size initial="256kb" resize="256kb" page="2kb" />

The <size> element specifies the database file and page size settings:

• The initial attribute specifies an initial size of every new database file. The resize attribute specifies the size by which to extend the database file when additional space is needed. Small initial size and resize values save space. Larger values can improve performance by reducing file fragmentation (many resize operations might cause fragmentation of the database file).
• The page attribute specifies the size of a page in a database file. The default of 2KB is appropriate for most applications.

The <recovery> element

  <recovery enabled="true" sync="false" path="." max="128mb" />

When enabled, a recovery file is created by ObjectDB when a database is opened and deleted by ObjectDB when the database is closed. The name of the recovery file is based on the name of the database file with $ added at the end. Every transaction commit is first written to the recovery file and then to the database. This way, if the system crashes during a write to the database, the recovery file can be used to fix the database. Recovery from failure is automatically applied by ObjectDB when a database is opened and a recovery file exists, indicating that it has not been closed properly. Moving or copying a database file that has not been closed properly without its recovery file may corrupt the database.

The <recovery> element specifies the recovery file settings:

• The enabled attribute (whose value is "true" or "false") specifies if recovery file is used.
• The sync attribute (whose value is "true" or "false") specifies if physical writing is required before commit returns. sync=false is much faster in writing data to a database, but true might be safer in production.
• By default, the recovery file is generated in the directory of the database file, but any other alternative path can be specified by the path attribute. Using separate storage devices (e.g. disks) for the recovery file and the database file can improve performance.
• The max attribute is a hint that specifies the space that should be available for the recovery file (ObjectDB might use more space when necessary).

The <recording> element

  <recording enabled="false" sync="false" path="." mode="all" />

Database engine operations can be recorded in files and later replayed using the ObjectDB Replayer tool. Recording provides an alternative (which is sometimes more efficient) to recovery. When recording is enabled and recovery is disabled, recorded operations are used to automatically fix a database that has not been closed properly by running the Replayer tool. Recording might also be useful for backup purposes and for debugging (by providing the ability to reproduce problems by replay)

The <recording> element specifies the recording settings:

• The enabled attribute (whose value is "true" or "false") specifies if recording is used.

• The sync attribute (whose value is "true" or "false") specifies whether physical writing is required for every recorded operation before returning to the caller.

• By default, a recording subdirectory is generated in the directory of the database file, but any other alternative path can be specified by the path attribute.
• The mode attribute (whose value is "all" or "write") specifies which operations should be recorded. For backup purposes only "write" operations (which modify the database) have to be recorded. For debugging of query failure it might be necessary to record "all" operations in order to reproduce the problem. Naturally, the recording operation is slower and the recording files are much larger when "all" is used.

The <locking> element

  <locking version-check="true" />

The version-check attribute of the <locking> element specifies if optimistic locking is enabled. Optimistic locking is completely automatic and enabled by default in ObjectDB, regardless if a version field (which is required by some ORM JPA providers) is defined in the entity class or not.
It can be disabled by setting the version-check attribute to false.

The <processing> element

  <processing cache="64mb" max-threads="10" />

The <processing> element specifies miscellaneous database engine settings:

• The cache attribute is a hint that specifies the the amount of memory that is used for caching pages of the database file.
• The max-threads attribute specifies the maximum number of concurrent threads that can be served by the database engine simultaneously. When the specified maximum is reached - new requests are pending until previous requests are completed. The optimal number is usually larger than the number of available CPU cores, but not too large, to avoid thread competition that leads to poor performance.

The <query-cache> element

  <query-cache results="32mb" programs="500" />

The <query-cache> element specifies settings of the two cache mechanisms that ObjectDB manages for queries:

• The results attribute specifies the size of the query result cache. Caching results is very useful for recurring queries with identical arguments. As long as the relevant data in the database is unchanged cached results can be returned instead of running queries.

• The programs attribute specifies how many compiled query programs should be cached. Cached query programs may eliminate the need to compile queries again but the queries still have to be executed, so cached programs are less efficient than cached results. However, cached query programs can also be used for recurring queries with different arguments and are not affected by most database updates (except schema updates).

The <extensions> element

  <extensions drop="temp,tmp" />

The drop attribute of the <extensions> element specifies a list of file name extensions that can be used for temporary databases (usually in tests). The content of these temporary databases is deleted when using the drop url connection parameter.