Database Management Settings

The <database> configuration element specifies back end (database engine) settings that 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" />
  <index-update enabled="true" priority="40" /> 
  <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 the 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 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 a 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 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 <index-update> element

  <index-update enabled="true" priority="40" />

The <index-update> element specifies how newly defined indexes are handled. When a new index is defined for an existing entity class that already has instances stored in the database, the index cannot be used until all the existing instances are indexed. Indexing a large amount of data may take considerable processing time.

• The enabled attribute (whose value is "true" or "false") specifies if existing data should be indexed automatically by ObjectDB in the background, a soon as new indexes are detected, in order to activate these new indexes.
• The priority attribute specifies the speed of the index building background process as a number between 10 and 70, indicating a processing rate of between 10% to 70% of the maximum database writing rate.

As soon as the background index activation is completed, ObjectDB can start using the new indexes to accelerate the execution of relevant queries.

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.

The <activation> elements

  <activation code="XXXX-XXXX-XXXX-XXXX-XXXX" />

Removing ObjectDB evaluation restrictions (of 10 entity classes and 1,000,000 entity objects per database) requires specifying a valid activation code using an <activation> element. 

Activation codes are generated by running the Activator utility:

> java -cp objectdb.jar com.objectdb.Activator

from the command line.

Every machine requires a specific activation code, but multiple <activation> elements can be specified in the same configuration. This way the same configuration file (with multiple activation codes) can be used on multiple machines.

Note: If you are using an ObjectDB OEM license - you should only activate ObjectDB on developer machines. Classes that are enhanced by the ObjectDB Enhancer (when using the OEM license) are signed and excluded from evaluation restrictions. Therefore, when ObjectDB runtime is bundled in a product that uses only signed enhanced persistable classes - activation by end users is unnecessary.