Configuring Application Checkpointing

Appian engines are real-time in-memory (RAM) databases that also persist all data (database and transaction log) in a file on disk. These database files have the extension .kdb. We refer to them as KDB files, which must be treated as a set. Each write transaction is applied immediately to the engine in memory and saved to the transaction log.

When a checkpoint completes, the transaction log is applied to the database and the transaction log is cleared. Each checkpoint increments the number appended to the KDB file name, increasing it by one number to a new KDB file; the old KDB file is left unmodified. For example, the name of a personalization engine KDB file that has not been checkpointed is ag0.kdb. After checkpointing, a new KDB file is created named ag1.kdb. Appian treats the KDB file with the largest number as the current database. Immediately after checkpointing, the file size of the largest-numbered KDB file may be smaller than that of the previous file (as each newly checkpointed KDB file clears the transaction logs). Schedule the [[Data Maintenance|cleanup.bat (.sh)]] script to run on a daily basis to cleanup older KDB files.

During a KDB checkpoint, a temporary writing_*.kdb file is created, which gets deleted when the checkpoint is completed. If the checkpoint fails for any reason, the writing_*.kdb file may remain on the file system. All pending transactions wait in the queue or timeout, depending on how checkpointing is configured.

A proper shutdown of the engines automatically completes a checkpoint. An improper shutdown (such as an abrupt stop using the kill command, a power outage, or an OS shutdown) of the engines does not complete a checkpoint.

When an Appian engine starts up, it loads the largest-numbered KDB file into memory and applies the transaction log.

If there has been a long duration since the last checkpointing of the engines, a large number of transactions may need to be loaded upon start-up.

When using multiple gateways for an engine, a KDB file normally consumes a much larger amount of RAM than the size of the KDB file on disk as all transactions are maintained both in RAM and on disk.

When using a single gateway (the default configuration) transactions are mainly persisted on disk.

The memory consumed by the engine is utilized both for storing data and for processing data.

Running the Checkpoint Script

The checkpoint (checkpoint-suite.bat or script can be executed manually from the following location.


When run without parameters, the checkpoint-suite script saves all engines listed in the appian-topology.xml file.

See also: Server Configuration Topologies

Checkpointing a Specific Engine

To run a checkpoint for one or more Appian engines, run the checkpoint-suite script with the engine name as a parameter.

For example, to pass the channels engine name as a parameter to the checkpoint-suite script, enter the following:

checkpoint-suite channels

You can also pass multiple engine names. For example, to pass both the channels and portal engines, enter the following:

checkpoint-suite channels portal

The following engine names are accepted:

  • forums
  • notify
  • notify-email
  • channels
  • content
  • collaboration-statistics
  • personalization
  • portal
  • process-design
  • process-analytics1. (0-15)
  • process-execution1. (0-15)

When selecting a process-analytics or process-execution engine, you must specify the engine number (such as process-analytics0).

Configuring Checkpointing Frequency (Auto-Database Save)

Automatic checkpointing (default configuration): Appian is configured to run a checkpoint automatically, approximately once every 4 to 12 hours, depending on a number of factors, including transaction volume. Most installations automatically perform a checkpoint approximately once every 12 hours.

Scheduled checkpointing: You can switch off automatic checkpointing and run the checkpoint script using a scheduled task or a cron job. To do so, complete the following:

  1. Configure a custom version of <APPIAN_HOME>/server/_conf/gateway-config.xml (such as gateway-config-currentMonthUpdate.xml) by setting the value of the auto-database-save attribute to 0.
  2. Set up a scheduled task or cron job to perform checkpointing checkpoint-suite.bat (.sh) according to your requirements (typically nightly).
    • The risk of running the checkpoint process as a scheduled job is if the scheduled job does not run for an extended period of time, a large quantity of transactions accumulate that would take a long time to re-apply after an improper shutdown of the engines or a transaction rollback.
    • The benefit to scheduled checkpointing over automatic checkpointing is that you can control and tweak the checkpointing behavior, including staggering the checkpoints.


The following information may be a useful reference if you are looking at potential issues with Application Checkpointing.

Ping-Timeout Limit Exceeded

If you have multiple gateways and experience an issue with a continuous checkpointing, you can first try staggering the checkpointing and then try raising the ping-timeout value. When the ping-timeout value is exceeded, the engines either write a transaction (that can take up memory if done multiple times) or kill themselves. Raising the ping-timeout value lessens the chance of either occurring.

To raise the ping-timeout value, create a customized XML file with the new configuration setting by completing the following:

  1. Navigate to <APPIAN_HOME>/server/_conf.
  2. Create a copy of gateway-config.xml and rename it with a user-defined suffix to the file name in the gateway-config\*.xml pattern.
  3. Modify the ping-timeout value, shown as 300 below.


  4. Save the new custom XML file to the same file path: <APPIAN_HOME>/server/_conf. See also: Customizing Files