Checkpoint

A checkpoint is a state of storage. The goal of creating a checkpoint is to store data securely. 

It is used as a mean to backup the data of a node. If the node crashes, the node restarts from the state it was in at the creation date of the checkpoint.

A node is represented by a transaction time. It contains all the data at that time (dump of memory in memory and list of files flushed on disk).

For a primary/replica cluster, you only need to create a checkpoint for the primary node not for the replica nodes. 

Startup and shutdown

At startup, the node looks for the most recent checkpoint and initialize itself with its data.

When a shutdown is initiated, the node creates a checkpoint before stopping.

Configure a shutdown checkpoint

You can customize the checkpoint created on the next node shutdown to:

  • Decide whether or not the next node shutdown checkpoint should be locked
  • Add a meaningful description for your checkpoint.

To create a locked checkpoint with the description "This is a checkpoint created at shutdown" you would call the command setShutdownCheckpointParameters as follows:

> setShutdownCheckpointParameters true "This is a checkpoint created at shutdown"

These settings are used on the next node shutdown, after which they are reset.

If you customized the settings of the shutdown parameter but you'd like to revert back to the default settings, call the command:

> resetShutdownCheckpointParameters

Automatic checkpoint creation

You can configure a node so that checkpoints are created on a regular basis.

To do so, edit conf/platform.properties and modify the value for the com.systar.calcium.automaticCheckpointCreationInterval setting.
The value represents the number of seconds between 2 automatic checkpoint creations.

If you set 0, checkpoints are never created automatically. The default value is 1800.

Purge strategy

The data directory must be regularly cleaned from old checkpoints, so as to not eat all the free space.

To do so, edit the  conf/ platform .properties  file and change the value for the com.systar.calcium.maxSpareCheckpoints setting.

The value represents the maximum number of checkpoints that can live simultaneously in the data repository. This number excludes the latest checkpoint (locked or unlocked) and all remaining locked checkpoints.

If you set 0, only one checkpoint (latest) can exist at any time.

If you set -1, the purge mechanism is disabled and checkpoints are never deleted.

The default value is 2.

Shell commands 

Using specific commands, you can manually create a checkpoint, lock it (i.e. in order have the time to backup it) and then unlock it when you no longer need it.

Create a new checkpoint

To create a new checkpoint on a store, you simply call the createCheckpoint command:

> createcheckpoint "This is a checkpoint comment"
[Gogo shell] INFO calcium.storageManager - Creation of checkpoint is in progress, with absorption mode:WAIT and comment:'This is a checkpoint comment'

Note : The createCheckpoint comment describing the checkpoint reason cannot be empty.

Retrieve the list of checkpoints

This command lists all the consistent checkpoints over all nodes. The display transaction time identifies the checkpoint, the "locked" displays the status.
(nota: if a checkpoint is not consistent, missing a store for instance, it will not be listed here)

> listcheckpoints
Checkpoints found:
1429197994588110849 - After application import of import.app.xml
1429198038796075009 - Automatic checkpoint at 2013-03-11T08:11:02.657Z
1429198102394306561 - This is a checkpoint comment (locked)

Lock a checkpoint

To manually lock a specific checkpoint, so the checkpoint cannot be deleted by automatic database process.

> lockCheckpoint 1394714001032609793 

Unlock a checkpoint

To manually unlock a specific checkpoint, so the checkpoint will be deleted by automatic database process.

> unlockCheckpoint 1394714001032609793 

Configure the period of automatic checkpoint creation (temporarily)

Use the following command to change the interval between checkpoint creations or to disable the functionality.

The configuration changed by this command is not persisted across node restarts.

To change the configuration durably, modify the conf/p latform .properties file as explained in Automatic checkpoint creation.

To create checkpoint every 15 minutes,  issue the following command:

> setAutomaticCheckpointCreationInterval 900 

You can also use the ISO8601 duration format (PnYnMnDTnHnMnS):  

> setAutomaticCheckpointCreationInterval PT15M

To retrieve the current configuration, use the following command:

> getAutomaticCheckpointCreationInterval
Automatic checkpoint creation interval: PT15M 

Configure the number of spare checkpoints kept (temporarily)

You can use this command to configure the purge of non-locked checkpoints or to disable the functionality.

The configuration changed by this command is not persisted across node restarts.

To change the configuration durably, modify the conf/platform.properties file as explained in the section Purge strategy

To keep only the latest created checkpoint, and three spare checkpoints, use the following command:

> setMaxSpareCheckpoints 3
Max spare checkpoints changed to 3

To keep only the latest created checkpoint, use the following command:

> setMaxSpareCheckpoints 0
Max spare checkpoints changed to 0

To disable the checkpoint purge functionality, use a value of -1:

> setMaxSpareCheckpoints -1
Max spare checkpoints deactivated

To retrieve the current configuration, use the following command:

> getMaxSpareCheckpoints
Max spare checkpoints: 2 

Restore the node state back to a given checkpoint

To restore a node back to a particular checkpoint, see How to rollback a node state to a specific checkpoint?

Manually delete a checkpoint

To manually delete a checkpoint, first you must know the transaction time of the checkpoint.

For example, let's say you have a checkpoint with a transaction time of 123456789:

  1. Navigate to the <node directory>/var/data/titanium-temporal directory, and in all subdirectories of this directory:
  2. Open the checkpoint sub-directory.
  3. Delete the tt123456789 directory.
  4. Open the <node directory>/var/data/calcium/checkpoint directory (if it exists).
  5. Delete the tt123456789 directory.


Related Links