Idempotency Key Cleanup

Every JSON-RPC request that carries an idempotencyKey field is recorded in the pgarachne.requests table by the pgarachne.save_idempotency_key() function. This is what makes duplicate detection work — but it also means the table grows without bound unless an operator runs cleanup periodically.

PgArachne does not run a background scheduler itself. The cleanest options:

pg_cron (recommended if you can install extensions)

-- Run every hour, remove keys older than 24 hours
SELECT cron.schedule(
  'pgarachne-idempotency-cleanup',
  '0 * * * *',
  $$SELECT pgarachne.cleanup_idempotency_keys('24 hours'::interval);$$
);

External cron/systemd timer

Schedule a shell job that calls the function via psql:

0 * * * * psql "host=... user=... dbname=..." \
  -c "SELECT pgarachne.cleanup_idempotency_keys('24 hours'::interval);" \
  >> /var/log/pgarachne-cleanup.log 2>&1

Manual/ad-hoc

You can call the function at any time from psql, a migration script, or any other client. It returns the number of rows deleted.

SELECT pgarachne.cleanup_idempotency_keys();          -- default: 24 hours
SELECT pgarachne.cleanup_idempotency_keys('7 days'::interval);

Choosing a retention window

Pick a window comfortably longer than the longest expected retry interval for your clients. If a buggy client retries the same idempotency key 48 hours after the original request, a 24-hour retention window will silently let the duplicate through.

For most deployments, 24 hours is a safe default.