Database Management Settings

The <database> configuration element specifies back-end (database engine) settings for the server and for 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 for each new database file.
• The resize attribute specifies the size by which to extend the database file when it needs more space. Small values for initial and resize save space. Larger values can improve performance by reducing file fragmentation that can result from frequent resize operations.
• The page attribute specifies the size of a page in a database file. The default value of 2 KB is appropriate for most applications.

The <recovery> element

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

When recovery is enabled, ObjectDB creates a recovery file when a database is opened and deletes it when the database is closed. The recovery file name is based on the database file name, with a $ character appended. Every transaction commit is written first to the recovery file and then to the database. If the system crashes during a write to the database, the recovery file can be used to repair it. ObjectDB automatically performs recovery when it opens a database and finds a recovery file, which indicates that the database was not closed properly. Moving or copying a database file that was not closed properly without its recovery file might corrupt the database.

The <recovery> element specifies the recovery file settings:

• The enabled attribute ("true" or "false") specifies whether a recovery file is used.
• The sync attribute ("true" or "false") specifies whether to wait for the physical write to complete before the commit operation returns. Setting sync="false" results in much faster database writes, but sync="true" is safer for production environments.
• By default, the recovery file is created in the same directory as the database file, but you can specify an alternative path with the path attribute. Storing the recovery file and the database file on separate storage devices, such as different disks, can improve performance.
• The max attribute provides a hint for the amount of space to reserve for the recovery file. ObjectDB might use more space if necessary.

The <recording> element

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

Database engine operations can be recorded to files and later replayed by using the ObjectDB Replayer tool. Recording provides an alternative to recovery that is sometimes more efficient. When recording is enabled and recovery is disabled, recorded operations are used to automatically repair a database that was not closed properly by running the Replayer tool. Recording can also be useful for backups and for debugging because it allows you to reproduce problems by replaying operations.

The <recording> element specifies the recording settings:

• The enabled attribute ("true" or "false") specifies whether recording is used.
• The sync attribute ("true" or "false") specifies whether to wait for the physical write to complete for each recorded operation before returning.
• By default, a recording subdirectory is created in the same directory as the database file, but you can specify an alternative path with the path attribute.
• The mode attribute ("all" or "write") specifies which operations to record. For backups, you only need to record "write" operations, which modify the database. For debugging query failures, you might need to record "all" operations to reproduce the problem. Recording all operations is slower and produces much larger files.

The <locking> element

  <locking version-check="true" />

The version-check attribute of the <locking> element specifies whether optimistic locking is enabled. Optimistic locking is fully automatic and enabled by default in ObjectDB, regardless of whether a version field is defined in the entity class. Some ORM JPA providers require a version field.
You can disable optimistic locking 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 provides a hint for the amount of memory to use for caching database file pages.
• The max-threads attribute specifies the maximum number of concurrent threads that the database engine can serve simultaneously. When this maximum is reached, new requests are queued until previous requests are completed. The optimal number is usually larger than the number of available CPU cores but not so large that it causes performance degradation from thread competition.

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 existing instances are indexed. Indexing a large amount of data can take considerable processing time.

• The enabled attribute ("true" or "false") specifies whether to automatically index existing data in the background as soon as new indexes are detected. This process activates the new indexes.
• The priority attribute specifies the speed of the background index-building process as a number between 10 and 70. This number indicates a processing rate of 10% to 70% of the maximum database writing rate.

After the background index activation is complete, ObjectDB can use the new indexes to accelerate relevant queries.

The <query-cache> element

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

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

• The results attribute specifies the size of the query result cache. Caching results is 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 re-running the query.
• The programs attribute specifies how many compiled query programs to cache. Cached query programs eliminate the need to recompile queries, but the queries still must be executed. Therefore, caching programs is less efficient than caching results. However, cached query programs can be used for recurring queries with different arguments and are not affected by most database updates, except for schema updates.

The <extensions> element

  <extensions drop="temp,tmp" />

The drop attribute of the <extensions> element specifies a comma-separated list of file name extensions that can be used for temporary databases, which are typically used in tests. The content of these temporary databases is deleted when you use the drop URL connection parameter.

The <activation> elements

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

To remove the ObjectDB evaluation restrictions (a limit of 10 entity classes and 1,000,000 entities per database), you must specify a valid activation code in an <activation> element.

Activation codes are generated by running the Activator utility from the command line:

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

Each computer requires a specific activation code, but you can specify multiple <activation> elements in the same configuration. This allows the same configuration file, with multiple activation codes, to be used on multiple computers.

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