docs: document clean up steps for scheduled triggers

hasura/graphql-engine-mono#2077

Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
GitOrigin-RevId: 7f4fae1

CHANGELOG.md

@@ -15,6 +15,7 @@
 - server: fix GraphQL type for single-row returning functions (close #7109)
 - server: update non-existent event trigger, action and query collection error msgs (close #7396) 
 - console: add support for creation of indexes for Postgres data sources
+- docs: document the cleanup process for scheduled triggers
 - console: allow same named queries and unnamed queries on allowlist file upload
 - console: support computed fields in permission builder
 - console: add custom timeouts to actions

docs/graphql/core/event-triggers/clean-up.rst

@@ -14,7 +14,9 @@ Clean up event data
 Introduction
 ------------
 
-Hasura stores event data associated with Event Triggers in the metadata schema. If there are lots of events, the metadata tables can get huge and you may want to prune them. You can use any of the following options to prune your event data depending on your need.
+Hasura stores event data associated with Event Triggers in **the `hdb_catalog` schema of the database containing the source table**.
+
+If there are lots of events, the metadata tables can get huge and you may want to prune them. You can use any of the following options to prune your event data depending on your need.
 
 Tables involved
 ---------------
@@ -79,3 +81,28 @@ Option 5: Clear everything
    DELETE FROM hdb_catalog.event_invocation_logs;
 
    DELETE FROM hdb_catalog.event_log;
+
+Clearing data before a particular time period
+---------------------------------------------
+
+If you wish to keep recent data and only clear data before a particular time period
+you can add the following time clause to your query's where clause:
+
+.. code-block:: SQL
+
+   -- units can be 'minutes', 'hours', 'days', 'months', 'years'
+   created_at < now() - interval '<x> <units>'
+
+For example: to delete all processed events and HTTP logs older than 3 months:
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.event_invocation_logs
+   WHERE created_at < now() - interval '3 months';
+
+   DELETE FROM hdb_catalog.event_log
+   WHERE (delivered = true OR error = true)
+    AND created_at < now() - interval '3 months';
+
+See the `Postgres date/time functions <https://www.postgresql.org/docs/current/functions-datetime.html>`__
+for more details.

docs/graphql/core/scheduled-triggers/clean-up.rst

@@ -0,0 +1,132 @@
+.. meta::
+   :description: Clean up event data of scheduled triggers in Hasura
+   :keywords: hasura, docs, scheduled triggers, cron triggers, scheduled events, clean up, purge logs
+
+.. _clean_up_scheduled_triggers_data:
+
+Clean up scheduled triggers data
+================================
+
+.. contents:: Table of contents
+   :backlinks: none
+   :depth: 1
+   :local:
+
+Introduction
+------------
+
+Hasura stores event data associated with scheduled triggers in **the `hdb_catalog` schema of the Hasura metadata
+database**.
+
+If there are lots of events, the events tables can get huge and you may want to prune them.
+You can use any of the following options to prune your event data depending on your need.
+
+Tables involved
+---------------
+
+Cron triggers have two tables managed by Hasura:
+
+1. ``hdb_catalog.hdb_cron_events``: Table that stores all the cron events.
+2. ``hdb_catalog.hdb_cron_event_invocation_logs``: Table that stores all the HTTP requests and their responses of the cron events invocations.
+
+Similarly, scheduled events also have two tables managed by Hasura:
+
+1. ``hdb_catalog.hdb_scheduled_events``: Table that stores all the scheduled events.
+2. ``hdb_catalog.hdb_scheduled_event_invocation_logs``: Table that stores all the HTTP requests and their responses of the scheduled events invocations.
+
+Option 1: Clear only HTTP logs
+------------------------------
+
+1. Cron event invocation logs
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_cron_event_invocation_logs;
+
+2. Scheduled event invocation logs
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_scheduled_event_invocation_logs;
+
+Option 2: Clear processed events
+--------------------------------
+
+1. Cron events
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_cron_events
+   WHERE status IN ('delivered', 'error', 'dead');
+
+2. Scheduled events
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_scheduled_events
+   WHERE status IN ('delivered', 'error', 'dead');
+
+.. note::
+
+   Deleting a cron/scheduled event will also delete the invocations related to that event.
+
+.. admonition:: Warning
+
+   The below options will clear all events including yet to be delivered events.
+   If the cron trigger exists in the metadata, then new events will be generated automatically
+   by the graphql-engine, but this step can take upto a minute.
+
+Option 3: Clear all data for a particular cron trigger only
+-----------------------------------------------------------
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_cron_events
+   WHERE trigger_name = '<trigger_name>';
+
+Option 4: Clear everything
+--------------------------
+
+1. Cron triggers
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_cron_events;
+
+2. Scheduled events
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_scheduled_events;
+
+Clearing data before a particular time period
+---------------------------------------------
+
+If you wish to keep recent data and only clear data before a particular time period
+you can add the following time clause to your query's where clause:
+
+.. code-block:: SQL
+
+   -- units can be 'minutes', 'hours', 'days', 'months', 'years'
+   created_at < now() - interval '<x> <units>'
+
+For example: to delete all processed events and HTTP logs older than 3 months:
+
+1. Cron triggers
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_cron_events
+   WHERE status IN ('delivered', 'error', 'dead')
+     AND created_at < now() - interval '3 months';
+
+2. Scheduled events
+
+.. code-block:: SQL
+
+   DELETE FROM hdb_catalog.hdb_scheduled_events
+   WHERE status IN ('delivered', 'error', 'dead')
+    AND created_at < now() - interval '3 months';
+
+See the `Postgres date/time functions <https://www.postgresql.org/docs/current/functions-datetime.html>`__
+for more details.

docs/graphql/core/scheduled-triggers/index.rst

@@ -41,3 +41,4 @@ There are two types of timed events:
 
    create-cron-trigger
    create-one-off-scheduled-event
+   clean-up