QuestDB WAL Suspended Table Sentinel with Kestra

id: questdb-wal-suspended-table-sentinel
namespace: company.team
description: |
  Query QuestDB's wal_tables() function for tables where suspended = true, alert Slack with
  the real suspended table names when the count exceeds a threshold, and optionally issue
  ALTER TABLE RESUME WAL over the REST API for each one, guarded by a safe-character check on
  the table name.

triggers:
  - id: every_15_minutes
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check WAL suspension state every 15 minutes.
    cron: "*/15 * * * *"
    disabled: true
    inputs:
      questdb_host: "questdb"
      questdb_pgwire_port: 8812
      questdb_http_port: 9000
      suspended_count_threshold: 0
      auto_resume_wal: "false"

  - id: on_demand_webhook
    type: io.kestra.plugin.core.trigger.Webhook
    description: Trigger an immediate WAL health check from an incident runbook or CI gate.
    key: "{{ secret('WEBHOOK_KEY') }}"

inputs:
  - id: questdb_host
    type: STRING
    displayName: QuestDB Hostname
    description: Hostname or IP of the QuestDB instance reachable from the Kestra worker.
    defaults: "questdb"

  - id: questdb_pgwire_port
    type: INT
    displayName: QuestDB PGWire Port
    description: PostgreSQL wire protocol port used by QuestDB for the wal_tables() probe.
    defaults: 8812

  - id: questdb_http_port
    type: INT
    displayName: QuestDB HTTP Port
    description: REST API port used to send ALTER TABLE RESUME WAL when
      auto_resume_wal is true.
    defaults: 9000

  - id: suspended_count_threshold
    type: INT
    displayName: Suspended Table Alert Threshold
    description: Fire a Slack alert when the real suspended table count is strictly
      greater than this value. 0 means any suspension triggers an alert.
    defaults: 0

  - id: auto_resume_wal
    type: SELECT
    displayName: Auto-Resume Suspended WAL Tables
    description: When true, send ALTER TABLE RESUME WAL for every suspended table
      that passes the safe-character name check, via the QuestDB REST API, after
      alerting.
    values:
      - "true"
      - "false"
    defaults: "false"

tasks:
  - id: probe_suspended_tables
    type: io.kestra.plugin.jdbc.postgresql.Query
    description: |
      Queries wal_tables() via QuestDB's PostgreSQL wire protocol (PGWire) for the name,
      writerTxn, and sequencerTxn of every table where suspended = true. No dedicated
      QuestDB plugin or JDBC subplugin exists in the Kestra plugin catalog, so this uses the generic plugin-jdbc-postgres Query task against QuestDB's
      PGWire-compatible port. This task is not wrapped in allowFailure, a connection or auth
      failure here is caught by the flow-level errors block below instead of a separate
      PROBE_FAILED branch.
    url: "jdbc:postgresql://{{ inputs.questdb_host }}:{{ inputs.questdb_pgwire_port
      }}/qdb"
    username: "{{ secret('QUESTDB_USERNAME') }}"
    password: "{{ secret('QUESTDB_PASSWORD') }}"
    fetchType: FETCH
    sql: "SELECT name, writerTxn, sequencerTxn FROM wal_tables() WHERE suspended =
      true"

  - id: gate_on_suspension
    type: io.kestra.plugin.core.flow.If
    description: Branches on the real suspended-table count against
      suspended_count_threshold. No sum or count aggregate is computed in SQL,
      outputs.probe_suspended_tables.size is the row count the JDBC task itself
      reports, so there is no NULL-aggregate case to guard against.
    condition: "{{ outputs.probe_suspended_tables.size >
      inputs.suspended_count_threshold }}"
    then:
      - id: alert_wal_suspension
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Alerts with the real suspended count and the real table names,
          joined from outputs.probe_suspended_tables.rows, never an invented
          name or count.
        url: "{{ secret('SLACK_WEBHOOK') }}"
        payload: |
          {{ {"text": "QuestDB WAL suspension detected on " ~ inputs.questdb_host ~ ":" ~ inputs.questdb_pgwire_port ~ ". Suspended table count: " ~ outputs.probe_suspended_tables.size ~ ". Tables: " ~ (outputs.probe_suspended_tables.rows | jq("[.[].name] | join(\", \")") | first) ~ ". Auto-resume: " ~ inputs.auto_resume_wal ~ ". Execution: " ~ execution.id ~ "."} | toJson }}

      - id: check_auto_resume
        type: io.kestra.plugin.core.flow.If
        description: Gates automatic remediation behind the auto_resume_wal toggle.
        condition: "{{ inputs.auto_resume_wal == 'true' }}"
        then:
          - id: resume_loop
            type: io.kestra.plugin.core.flow.Loop
            description: |
              Iterates over a list of plain table-name strings extracted via jq from
              outputs.probe_suspended_tables.rows, not over the raw row maps. Kestra's own
              Loop task documentation states that when values is a list of objects,
              individual objects are coalesced to strings, so looping over the row maps
              directly would not reliably expose item.value.name. Extracting a jq-built list
              of strings first avoids relying on that coalescing behavior. concurrencyLimit 1
              serializes the RESUME WAL calls so they do not compete against each other.
            concurrencyLimit: 1
            values: "{{ outputs.probe_suspended_tables.rows | jq('[.[].name]') | first }}"
            tasks:
              - id: guard_safe_table_name
                type: io.kestra.plugin.core.flow.If
                description: |
                  Only a conservative, self-defined safety guard before interpolating the name
                  into SQL and a URL, not a verified QuestDB identifier grammar, that was not
                  found in the fetched QuestDB documentation. Uses the same
                  value | toJson | jq('test("...")') | first pattern already merged elsewhere
                  in this repository for validating a name before using it unescaped.
                condition: "{{ (item.value | toJson | jq('test(\"^[A-Za-z0-9_.-]{1,255}$\")') |
                  first) }}"
                then:
                  - id: resume_wal_via_rest
                    type: io.kestra.plugin.core.http.Request
                    description: |
                      Sends ALTER TABLE <name> RESUME WAL to QuestDB's REST /exec endpoint as a
                      URL-encoded GET query parameter. QuestDB's own docs mark /exec as the
                      older, still-supported name for /execute, stating it takes the same
                      parameters and returns the same response, this flow uses /exec. options.allowFailed
                      lets a non-2xx response populate outputs instead of throwing, and the
                      separate allowFailure lets one table's failed call skip rather than abort
                      the remaining iterations.
                    uri: "http://{{ inputs.questdb_host }}:{{ inputs.questdb_http_port
                      }}/exec?query={{ ('ALTER TABLE ' ~ item.value ~ ' RESUME
                      WAL') | urlencode }}"
                    method: GET
                    options:
                      allowFailed: true
                    allowFailure: true
                else:
                  - id: log_unsafe_table_name_skipped
                    type: io.kestra.plugin.core.log.Log
                    description: Logs and skips any table name that failed the safe-character check,
                      rather than sending it to SQL or a URL.
                    message: "Skipping RESUME WAL, table name failed the safe-character check: {{
                      item.value }}"
        else:
          - id: log_auto_resume_disabled
            type: io.kestra.plugin.core.log.Log
            description: Records that auto-resume is disabled and names the tables that
              still need a manual RESUME WAL.
            message: "Auto-resume off. Resume manually, tables: {{
              (outputs.probe_suspended_tables.rows | jq('[.[].name] | join(\",
              \")') | first) }}"
    else:
      - id: log_wal_healthy
        type: io.kestra.plugin.core.log.Log
        description: Logs the real suspended count, which may be a non-zero value at or
          below suspended_count_threshold, never a hardcoded zero.
        message: "QuestDB WAL healthy on {{ inputs.questdb_host }}:{{
          inputs.questdb_pgwire_port }}. Suspended count: {{
          outputs.probe_suspended_tables.size }}. Threshold: {{
          inputs.suspended_count_threshold }}."

  - id: log_audit_summary
    type: io.kestra.plugin.core.log.Log
    description: Final audit log confirming the gate ran, regardless of the branch
      taken above.
    message: "AUDIT flow={{ flow.id }} execution={{ execution.id }} host={{
      inputs.questdb_host }}:{{ inputs.questdb_pgwire_port }} suspended_count={{
      outputs.probe_suspended_tables.size }} threshold={{
      inputs.suspended_count_threshold }} auto_resume={{ inputs.auto_resume_wal
      }}"

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alerts on-call when the flow itself fails, for example on a probe
      connection or auth failure.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {{ {"text": "QuestDB WAL suspended table sentinel flow failed (execution " ~ execution.id ~ "). Host: " ~ inputs.questdb_host ~ ":" ~ inputs.questdb_pgwire_port ~ ". Check the execution logs, QuestDB PGWire connectivity, and the QUESTDB_USERNAME and QUESTDB_PASSWORD secrets."} | toJson }}

QuestDB's write-ahead log tables can become suspended either on their own, when applying a transaction fails, or deliberately, when an operator runs ALTER TABLE SUSPEND WAL ahead of a maintenance operation. Either way, while a table is suspended, writes still land in the sequencer but nothing is applied to the table, so queries do not see the new rows until RESUME WAL runs. Nothing in QuestDB itself pages anyone when this happens. This blueprint queries wal_tables() on a schedule, alerts Slack with the real names of every suspended table, and can optionally resume them over the REST API, one at a time, with a safe-character check before any name is used in SQL or a URL.

How it works

probe_suspended_tables (io.kestra.plugin.jdbc.postgresql.Query) runs SELECT name, writerTxn, sequencerTxn FROM wal_tables() WHERE suspended = true over QuestDB's PGWire port. No dedicated QuestDB plugin or JDBC subplugin exists in Kestra's plugin catalog, so this uses the generic PostgreSQL JDBC task.
gate_on_suspension (io.kestra.plugin.core.flow.If) compares outputs.probe_suspended_tables.size, the real row count the query task reports, against suspended_count_threshold.
On suspension, alert_wal_suspension posts a Slack message naming the real suspended tables, extracted with a jq filter, never an invented list.
check_auto_resume (io.kestra.plugin.core.flow.If) gates remediation behind auto_resume_wal. When enabled, resume_loop (io.kestra.plugin.core.flow.Loop, concurrencyLimit: 1) iterates over the suspended table names one at a time. For each one, guard_safe_table_name checks it against a conservative character allowlist before resume_wal_via_rest (io.kestra.plugin.core.http.Request) sends ALTER TABLE <name> RESUME WAL to QuestDB's REST /exec endpoint as a URL-encoded GET query. A name that fails the check is logged and skipped instead.
When auto_resume_wal is false, log_auto_resume_disabled names the tables that still need a manual RESUME WAL.
log_audit_summary always runs last. The flow-level errors block pages Slack if the flow itself fails, for example on a probe connection or authentication error.

What you get

A real list of exactly which tables are suspended, from wal_tables() itself, never a guess.
A Slack alert naming the real tables, with the real count that triggered it.
Optional, serialized remediation with a defensive character check before any name reaches SQL or a URL, and a logged skip rather than a silent failure for a name that does not pass that check.
A manual-resume fallback that still tells you exactly which tables need attention when automatic remediation is off.

Who it's for

Teams running QuestDB for time-series or event data who need to know about a suspended WAL table before downstream queries start silently missing rows.
Teams evaluating QuestDB's PGWire compatibility with Kestra's generic PostgreSQL JDBC plugin, since no dedicated QuestDB plugin exists yet.

Why orchestrate this with Kestra

QuestDB has no built-in alert for a suspended WAL table, and wal_tables() itself reads from disk, which QuestDB's own documentation describes as less suitable for frequent polling, so a naive tight polling loop is not the right approach either. Kestra adds the schedule, the threshold check, the Slack alert naming the real tables, and an optional, guarded remediation loop as one declarative, auditable flow, instead of a cron job and a hand-rolled script.

Prerequisites

A reachable QuestDB instance with its PGWire port open to the Kestra worker, and its HTTP REST port open as well if auto_resume_wal will be used.
At least one WAL-enabled table, created with the WAL keyword, since wal_tables() only reports WAL-enabled tables.

Secrets

QUESTDB_USERNAME: QuestDB PGWire login user.
QUESTDB_PASSWORD: QuestDB PGWire login password.
SLACK_WEBHOOK: Slack incoming webhook URL used by the alert task and the errors block.
WEBHOOK_KEY: random string that authenticates the on_demand_webhook trigger.

In Kestra OSS, set these as base64-encoded environment variables, for example SECRET_QUESTDB_USERNAME, SECRET_QUESTDB_PASSWORD, SECRET_SLACK_WEBHOOK, SECRET_WEBHOOK_KEY.

Quick start

Set the four secrets above.
Set questdb_host, questdb_pgwire_port, and questdb_http_port to your instance.
Keep suspended_count_threshold: 0 to alert on any suspension.
Run the flow manually once to confirm connectivity. Confirm the PGWire connection and the probe query before enabling anything else.
Remove disabled: true from the schedule trigger once confirmed.
Set auto_resume_wal: true only after confirming the cause of any suspension has been addressed.

Local Docker test (OSS):

# 1. Find the Docker network your Kestra containers are on
docker network ls

# 2. Start QuestDB without publishing host port 8080, to avoid clashing with services
#    commonly run on that port
docker run -d --name questdb \
  -p 9000:9000 -p 8812:8812 -p 9009:9009 \
  questdb/questdb:latest

# 3. Attach QuestDB to Kestra's own Docker network, found in step 1
docker network connect YOUR_KESTRA_NETWORK questdb

# 4. Export secrets as base64 for Kestra OSS
export SECRET_QUESTDB_USERNAME=$(echo -n "<questdb-username>" | base64)
export SECRET_QUESTDB_PASSWORD=$(echo -n "<questdb-password>" | base64)
export SECRET_SLACK_WEBHOOK=$(echo -n "<slack-webhook-url>" | base64)
export SECRET_WEBHOOK_KEY=$(echo -n "<webhook-key>" | base64)

# 5. To simulate a suspended table, create a WAL table and suspend it, in the QuestDB
#    web console:
# CREATE TABLE readings (ts TIMESTAMP, val DOUBLE) TIMESTAMP(ts) PARTITION BY DAY WAL;
# ALTER TABLE readings SUSPEND WAL;

How to extend

Add errorTag and errorMessage to the SELECT list, both real wal_tables() columns, to include the reason a table suspended on its own in the Slack alert.
Switch the REST call from the documented-deprecated /exec path to /execute, which QuestDB's own docs describe as taking the same parameters and returning the same response.
Add options.auth to resume_wal_via_rest if the target QuestDB instance has HTTP basic authentication enabled, this blueprint's REST call is unauthenticated as given.

Outputs

Output path	Description
`outputs.probe_suspended_tables.rows`	List of maps, one per suspended table, each with `name`, `writerTxn`, `sequencerTxn`
`outputs.probe_suspended_tables.size`	Real count of suspended tables returned by the query
`outputs.resume_loop.iterationCount`	Total number of tables the resume loop iterated over
`outputs.resume_loop.terminatedIterations`	Count of loop iterations per terminal state

Inputs

Input	Type	Default	Description
`questdb_host`	STRING	`questdb`	QuestDB hostname or IP
`questdb_pgwire_port`	INT	`8812`	PGWire port for the wal_tables() probe
`questdb_http_port`	INT	`9000`	HTTP REST port for RESUME WAL
`suspended_count_threshold`	INT	`0`	Alert when the real suspended count exceeds this value
`auto_resume_wal`	SELECT	`false`	`true` or `false`, auto-resume suspended tables via the REST API

Pitfalls

wal_tables() reads from disk. QuestDB's own documentation describes it as less suitable for frequent polling. A 15-minute schedule is the default here; polling meaningfully more often than that should be weighed against that documented caveat.
A table can be suspended on purpose, for a maintenance operation such as REBASE WAL, not only because of a genuine failure. auto_resume_wal set to true during a planned maintenance window could resume a table an operator deliberately suspended.
The REST call targets the documented-deprecated /exec path, not the current /execute path. Both are documented by QuestDB as taking the same parameters and returning the same response, but /exec is not the path QuestDB recommends for new work.
The safe-character check (^[A-Za-z0-9_.-]{1,255}$) is this blueprint's own defensive guard, not a verified QuestDB identifier grammar, no such grammar was found in the QuestDB documentation consulted for this blueprint. A legitimate table name using a character outside that set would be skipped and logged, not resumed.
The REST call in resume_wal_via_rest is unauthenticated as given. If the target QuestDB instance has HTTP basic authentication enabled, this call needs options.auth added, see How to extend.
No QuestDB version number is claimed anywhere in this blueprint. The QuestDB documentation pages consulted for wal_tables(), RESUME WAL, and SUSPEND WAL did not state which version introduced each.

QuestDB WAL Suspended Table Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Outputs

Inputs

Pitfalls

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

QuestDB WAL Suspended Table Sentinel

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Outputs

Inputs

Pitfalls

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Data Blueprints

AI Data Quality Anomaly Advisor and SQL Remediation Generator

AI Document Data Extraction: Parse PDFs and Web Pages into Structured JSON with OpenAI

Adanos Asset Sentiment Drift Sentinel

Read out an A/B test with a sample ratio check and a guardrail metric

AI-Powered Inventory Demand Forecasting, Auto-Generate Purchase Orders with OpenAI

Actian Vector Table Fragmentation and Storage Sentinel

More Infrastructure Blueprints

ACM Certificate Expiry Compliance Sentinel

Audit Every Agent Tool Call Against Policy Before It Goes Unnoticed

AI Incident Post-Mortem and Root Cause Generator

Aerospike Stop-Writes Headroom Sentinel

Renew TLS certificates through ACME, verify them, deploy them and roll back on failure

ADLS World-Writable ACL Sentinel

New to Kestra?