Cognitive Agents — Autonomous Database Management

Prerequisites

HeliosDB Full v8.0.3 or later, as a cluster (single node is fine for this tutorial)
A database with at least 1M rows and a query workload (the agents need data to learn from)
Network access to a Prometheus instance if you want metric scraping (optional)
~30 minutes

The cognitive agents subsystem is always compiled in Full. There is no feature flag — you enable it via the runtime API or a CLI command.

1. The Five Agents at a Glance

Agent	Role	Trigger	Typical Actions
Performance Optimizer	Find slow queries, wasted I/O	Workload metric drift, p95 spike	`REWRITE QUERY`, suggest hints, parallelism tweaks
Index Advisor	Recommend / drop indexes	Missing-index hits, unused-index decay	`CREATE INDEX`, `DROP INDEX`, hypothetical-index trial
Query Tuner	Rewrite / re-plan individual queries	Plan regression, cardinality miss	Plan pinning, predicate pushdown, join-order swap
Schema Manager	Schema drift, dead tables, partition tuning	DDL events, growth pattern	Suggest partitions, archive cold tables, fix bloat
Security Monitor (a.k.a. self-healer)	Anomalous logins, lock storms, replica lag	Audit-log signal	Kill connections, freeze role, alert on-call

All five share the same agent runtime. You can spawn one, several, or all of them. A running agent polls the database every observation_interval, plans an action, simulates it in a sandbox, runs it only if confidence is high enough, and rolls back if anything goes wrong.

2. The 5-Layer Safety Framework

This is the part you must understand before turning autonomy on in production. The framework is not optional — it’s enforced by the runtime on every action.

Layer	What it does	Default behaviour
L1 — Sandbox simulation	Run the candidate action in an isolated transaction; check expected vs actual state diff	On
L2 — Confidence scoring	Score the candidate action’s confidence; reject if below threshold	0.95
L3 — Human-in-loop	If confidence is below threshold but above floor, request approval (default 5-min timeout)	On (off-hours opt-out)
L4 — Automatic rollback	Snapshot state before any reversible action; revert on failure or anomaly	On
L5 — Audit trail	Append every decision, score, and outcome to a write-ahead audit log	On

You can dial down individual layers (disable the sandbox, lower the confidence threshold) but don’t disable L4 or L5 in production — those are the load-bearing safeties.

What an audit entry looks like

{
  "ts": "2026-04-26T10:14:32Z",
  "agent_id": "perf-opt-1",
  "action": "create_index",
  "target": "orders(customer_id, status)",
  "confidence": 0.974,
  "sandbox_pass": true,
  "applied": true,
  "rollback_token": "rb_8af3c1",
  "outcome": "p95 -38ms after 60s",
  "human_approval": null
}

Audit entries are queryable through SQL once the agent is connected to the metadata store:

SELECT ts, agent_id, action, confidence, outcome
FROM heliosdb_agent_audit
WHERE applied = true
ORDER BY ts DESC LIMIT 20;

3. Walkthrough — The Index Advisor Earning Its Keep

Let’s run a realistic scenario end-to-end. We’ll create a workload that obviously needs an index, and watch the agent find it, propose it, and apply it.

Setup

CREATE TABLE orders (
  id          BIGSERIAL PRIMARY KEY,
  customer_id BIGINT NOT NULL,
  status      TEXT,
  amount      NUMERIC(12,2),
  created_at  TIMESTAMP DEFAULT now()
);

-- 5M rows, no index on customer_id
INSERT INTO orders (customer_id, status, amount)
SELECT (random()*1000000)::bigint, 'paid', random()*1000
FROM generate_series(1, 5000000);

Now hammer it from a client:

for i in $(seq 1 200); do
  psql -c "SELECT * FROM orders WHERE customer_id = $((RANDOM % 1000000)) LIMIT 5;" &
done; wait

What you’ll see in the audit log

SELECT ts, action, target, confidence, outcome FROM heliosdb_agent_audit
WHERE agent_id='idx-advisor-1' ORDER BY ts;

ts	action	target	confidence	outcome
`…:01:10Z`	`observe`	`orders`	—	“120 seq scans / 60s, p95=412ms”
`…:01:12Z`	`simulate_index`	`orders(customer_id)`	0.96	”sandbox: -94% rows scanned”
`…:01:14Z`	`create_index`	`orders(customer_id)`	0.96	”applied; rollback_token=rb_…”
`…:02:14Z`	`verify_outcome`	`orders`	—	“p95 412ms → 18ms”

That whole loop took roughly 4 seconds of agent time. The action recommendation latency target is <2 seconds.

4. Multi-Agent Coordination

You can run all five agents at once. A coordinator resolves conflicts (e.g. the schema agent wanting to drop a column the index agent just indexed) using a priority strategy.

The coordinator gives the Schema Manager veto power over DDL collisions — the Index Advisor cannot create an index on a column the Schema Manager has flagged for deletion.

5. Tuning the Agents

The defaults are conservative on purpose. A lower confidence threshold means more autonomy and more rollbacks.

Performance targets the runtime ships with (indicative; measure on your own workload):

Action recommendation latency: <2s
Confidence threshold for auto-execution: ≥0.95 (default)
Autonomous success rate target: ≥90%
RL convergence: <100 iterations on most workloads

6. SQL Surface

Most operators don’t want to write Rust. The Full edition exposes the agents through SQL once they’re attached to the cluster:

-- List running agents
SHOW COGNITIVE AGENTS;

-- Pause an agent (it stays observing but won't act)
ALTER COGNITIVE AGENT 'idx-advisor-1' SET enabled = false;

-- Inspect the current goal queue
SELECT * FROM heliosdb_agent_goals WHERE agent_id = 'perf-opt-1';

-- Get the audit trail for a specific action
SELECT * FROM heliosdb_agent_audit WHERE rollback_token = 'rb_8af3c1';

-- Manually roll back
SELECT heliosdb.rollback_action('rb_8af3c1');

How to Configure

The SQL in this tutorial shows the intended agent workflow. It is not a guaranteed command reference for your release. Enabling the agents on a cluster, the SQL and API control surface in your release, and the safety-framework settings (confidence threshold, human-in-loop routing, observation interval) are provided during onboarding — contact support@heliosdb.com (or sales@heliosdb.com if you are not yet a customer).

7. Production Checklist

Before flipping the switch on a prod cluster:

L4 (auto-rollback) and L5 (audit) are on
L2 confidence threshold is ≥0.95 for the first 30 days
L3 (human-in-loop) routes to a real on-call channel
Audit log is being shipped to long-term storage (the heliosdb_agent_audit table is hot-only by default)
You’ve reviewed at least 100 audit entries before disabling human-in-loop
Prometheus is scraping the metrics_port so SLA regressions surface immediately
The agent’s metadata store is on the same Raft group as the data it’s managing (otherwise rollbacks can race)

8. What Each Agent Patrols

Agent	Reads	Writes
Performance Optimizer	`pg_stat_statements`, plan cache, system metrics	Plan hints, parallelism settings
Index Advisor	seq-scan counters, index usage, hypothetical-index estimator	`CREATE INDEX`, `DROP INDEX`
Query Tuner	individual query plans, cardinality vs estimate	Plan pinning, rewrites
Schema Manager	catalog drift, partition pruning effectiveness, table bloat	`ALTER TABLE` (additive only by default)
Security Monitor	audit log, login patterns, lock waits	`KILL CONNECTION`, role freeze

Anything destructive (DROP, TRUNCATE, schema-removal ALTER) requires human approval regardless of confidence.

Where Next

Intelligent Tiering — the storage-side counterpart, run by a sibling ML engine