Pausing and Stopping

Pause with a sentinel file #

processing:
  sentinel_file: /var/run/goarchive/pause.flag

Before each batch, and before each page of recovery, GoArchive checks whether that file exists. While it is present, the run pauses, checking again every second and logging a reminder about every 30 seconds. Remove the file to resume. Only the file’s presence counts; its contents are ignored. An empty sentinel_file, the default, disables pausing.

touch /var/run/goarchive/pause.flag   # pause, for example to relieve a struggling replica
rm /var/run/goarchive/pause.flag      # resume

• A paused run keeps its locks. For the length of the pause, a second run of the same job is refused as already running, and so is any run whose tables overlap.
• A path that cannot be checked, for example because of a permission error on its directory, counts as absent: the run logs one warning and does not pause.
• Signals still work: a first Ctrl-C or SIGTERM ends the pause and stops the run, and a second signal cancels at once.
• One file, several jobs: jobs that share a sentinel_file path pause together.

Stop with a signal #

The first SIGTERM or SIGINT lets the batch or recovery page in flight finish, then stops the run with exit code 3. With --progress, the closing block says so, and the run’s log ends with Run stopped …. The next run of the same job continues from the start of the where range, after finishing anything the stopped run logged.

• During a replication hold, the first signal ends the hold without waiting for the replicas. The run stops with exit code 3, nothing is rolled back, and the held batch’s roots stay logged for the next run’s recovery. A signal that arrives while the gate is making its first check of the replicas for a chunk waits for that check to return.
• A second signal cancels at once. The open transaction rolls back, the log ends with Run failed, and the next run’s recovery finishes what the log holds.
• A third signal terminates the process.

The closing counts of a stopped run read: roots and batches, the work completed; copied and deleted, the rows committed, including those of the stopped batch.

In a container #

docker stop sends SIGTERM, so it is a graceful stop if the batch in flight finishes before the stop deadline (10 seconds by default). Set docker stop --time, or stop_grace_period in Compose, above one batch’s duration. If the deadline passes, the process is killed, and the next run recovers what the log holds.