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>
Each of the following sections describes one subelement:
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 default2KB
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 beforecommit
returns.sync=false
is much faster in writing data to a database, buttrue
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.