Skip to content

Backup

Overview

The internal backup performs a snapshot of the quad store. All triples (including named graph information) are saved to an RDF file in the configured format. Only formats with support for named graphs are supported. If the provenance repository is enabled, it is saved to a second file. Unless disabled, the uploaded files of the data folder are copied into the backup as well.

While the backup is running, no modifying request are accepted by the REST interface (PUT, DELETE, POST); they are answered with 503 Service Unavailable. Read-only access using GET, HEAD and OPTIONS is possible, as are login and logout.

By default (and if none of the maintenance limits is configured, see below) each backup execution will create a new folder all inside the configured backup directory. In the beginning of the backup process the old backup will be removed. It is possible to configure a different order if the previous backup should be deleted after the new backup was created (delete-after): the previous backup is then kept in all-old until the new backup has completed.

Configuration

All backup settings are configured directly in the entrystore.properties file. The backup is stored in the folder which is specified in the entrystore.properties file.

The parameters are:

entrystore.backup.scheduler=on|off (default: off)
entrystore.backup.folder=/path/to/backup/
entrystore.backup.cronexp=the time when the backup should be run, in Quartz cron format (see below)
entrystore.backup.gzip=on|off (default: off)
entrystore.backup.format=TriX|TriG|N-Quads|BinaryRDF (default: TriX)
entrystore.backup.delete-after=on|off (default: off; only used with the folder `all`, see below)
entrystore.backup.include-files=on|off (default: on)

See Value syntax for the accepted boolean values; an unrecognised value of entrystore.backup.scheduler fails startup. The deprecated entrystore.backup.timeregexp is still read if cronexp is not set. Without a cron expression no backup is scheduled and a warning is logged.

The format name is case-insensitive. An unknown format, or one that cannot hold named graphs (such as Turtle), falls back to TriX with a warning at startup. The format and cron expression in use are shown in the extended status (backup.formatResolved, backup.cronExpressionResolved).

The Quartz cron expression consists of 6 fields:

  • Seconds
  • Minutes
  • Hours
  • Day Of Month
  • Month
  • Day Of Week

The first three fields may be expressed using a randomizing function rnd() (this is non-standard and a feature of EntryStore). Either an asterisk * for any value or an integer range may be provided. Depending on the position (second, minute, hour) it generates a value between 0-59 or 0-23. The ranges are boundary inclusive. The cron expression is evaluated upon every startup of the EntryStore instance.

The randomization feature is particularly useful in cases where many EntryStore instances are hosted in the same environment to avoid overloading the host in case all instances should start their backup process at the same time.

Example: the expression 0 rnd(*) rnd(1-3) * * ? starts the backup process sometime between 1:00 am and 3:59 am.

History and Maintenance

EntryStore's backup can keep more than one backup and perform maintenances by removing outdated backups. This is configured through the following settings in addition to the main backup settings above:

entrystore.backup.maintenance=on|off (default: off) - defines whether maintenance should be performed
entrystore.backup.maintenance.upper-limit=maximum amount of stored backups
entrystore.backup.maintenance.lower-limit=minimum amount of stored backups
entrystore.backup.maintenance.expires-after-days=maximum days a backup is kept

Maintenance is automatically turned off if none of upper-limit, lower-limit and expires-after-days are configured with values higher than 1.

As soon as one of these limits is higher than 1, a new folder named after the current date and time (yyyyMMddHHmmss) is created for each backup, instead of the default folder name all. This depends on the limits only: with entrystore.backup.maintenance=off, the dated folders are created but never removed.

Backup folder contents

Each backup folder contains:

  • repository.<ext> (with .gz appended if gzip is on): the main repository, with the default file extension of the configured format
  • repository_prov.<ext>: the provenance repository, if provenance is enabled
  • the contents of the data folder (entrystore.data.folder), copied directly into the backup folder, unless include-files is off
  • BACKUP_DATE with the timestamp of a completed backup, or BACKUP_FAILED with the timestamp and the error if a step failed

A backup with an error in any step is marked BACKUP_FAILED and gets no BACKUP_DATE; its remaining steps still run, and a partly written repository dump is deleted. Maintenance does not count failed backups towards its limits. It deletes them once a newer backup has completed and otherwise keeps at most upper-limit of them. With delete-after, a failed all folder is replaced instead of rotated to all-old if all-old holds a completed backup, so that backup survives consecutive failures.

EntryStore 5.x

5.x wrote BACKUP_DATE also for failed backups (next to BACKUP_FAILED), counted them towards the maintenance limits, and always rotated all to all-old with delete-after. During a backup, 5.x accepted only GET requests (and login and logout), not HEAD or OPTIONS. A failed repository export was only logged, so a backup could hold an empty or truncated dump without being marked as failed.

Restore

Follow the following steps to restore a backup. Use a backup folder that contains BACKUP_DATE and no BACKUP_FAILED.

  • Shutdown EntryStore.
  • Restore the files of the data folder by copying the contents of the backup folder (except repository* and BACKUP_*) to the configured data folder.
  • Restore the store directory by importing the serialized RDF (repository.<ext>) to an RDF4J store, and repository_prov.<ext> to the provenance store if used. This can be done using EntryStore Tools (see the Git repo on Bitbucket).
  • Start EntryStore.