DBA Agent Manual

1. What the DBA Agent does

The DBA Agent connects to your databases and runs continuous health checks at the interval set by your subscription tier. It detects problems before they become outages — slow queries, table bloat, replication lag, disk saturation, connection pool exhaustion — and either fixes them automatically or alerts you immediately.

For SapixDB, it also monitors strand chain integrity, reviews Mutant schema evolution proposals using AI, and tracks organism agent health.

Supported databases

2. Reading the daily report

Every morning the agent emails a plain-English health report to the address you provided when subscribing. The report covers the past 24 hours.

Report structure

Health status meanings

3. Alert codes and what to do

Critical alerts are sent immediately by email when detected — you don't need to wait for the daily report.

PostgreSQL alerts

SapixDB alerts

4. Communicating with your agent

Your hired session has two communication channels — both lead to the same conversation history.

Session email address

Every session has a dedicated email address shown on the session page (e.g. dba-a3f9b2c1@agents.boboyka.com). Email your requirements or questions to this address. The agent reads it and responds.

In-session chat panel

The session page at hire.boboyka.com/session/[id] has a live chat panel. Messages appear in real time. Use this for quick questions, urgent requests, or anything you don't want in email.

Both channels feed the same message history — a question asked via email shows up in the chat panel and vice versa.

What you can ask the agent to do

5. SapixDB monitoring

SapixDB is fundamentally different from relational databases. There are no tables, no query planner, and no connection pool. The DBA Agent monitors the structures that are meaningful for SapixDB:

What a SapixDB Mutant proposal is

SapixDB uses a governance system called Mutants for all structural changes. Instead of running ALTER TABLE, you submit a proposal describing the change. The proposal goes through an approval process based on the data zone, then an operator applies it. This makes schema evolution deliberate, auditable, and reversible.

The DBA Agent reviews pending proposals automatically. It approves simple, safe changes to free zone agents. For governed, protected, and immutable_core zones it always escalates to a human — it will notify you in the daily report and via email.

6. SapixDB structure & safe object creation

How SapixDB objects are structured

SapixDB organises data into organisms and agents. An organism is a namespace (like a database). Agents are the data tables inside it (but they behave like living things — each has its own cryptographic identity and strand).

Organism: "myapp"
  Agent: "myapp::users"      ← stores user records
  Agent: "myapp::events"     ← stores application events
  Agent: "myapp::audit"      ← append-only audit log

  Each agent has:
    • A strand (append-only, hash-linked chain of records)
    • An Ed25519 keypair (signs every record it writes)
    • A zone (free / governed / protected / immutable_core)
    • A RocksDB graph index (relationships between records)
    • An optional blob store (binary data)

The critical naming rule

SapixDB uses :: as its internal separator to form full agent IDs. This means you must never put :: in an organism name or agent name.

Zone selection — choose once, escalate only

How to ask the agent to create an organism

Tell the agent clearly: the organism name, the agent names you want inside it, and the zone. The agent will confirm before creating anything.

The agent will confirm the plan, create the organism, and reply with the full agent IDs: analytics::daily_snapshots, analytics::aggregates, analytics::exports.

Naming conventions to follow

7. Useful commands

These are REST API calls you can run directly against your SapixDB instance. Replace $BASE with your SapixDB URL and $KEY with your API key.

Health and status

# Quick health check — no auth required
curl $BASE/v1/health

# Full status: uptime, counters, peers, epigenetics profile
curl -H "Authorization: Bearer $KEY" $BASE/v1/status

Organisms and agents

# List all organisms
curl -H "Authorization: Bearer $KEY" $BASE/v1/organisms

# Get one organism
curl -H "Authorization: Bearer $KEY" $BASE/v1/organisms/myapp

# Create an organism (safe — checks first)
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  $BASE/v1/organisms \
  -d '{"organism_id":"myapp","agents":["users","events","audit"],"zone":"governed"}'

# Add an agent to an existing organism
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  $BASE/v1/organisms/myapp/agents \
  -d '{"agent_name":"notifications"}'

Writing and reading records

# Write a record to myapp::events
# Note: :: in the agent ID is URL-encoded as %3A%3A
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  "$BASE/v1/agents/myapp%3A%3Aevents/records/json" \
  -d '{"data":{"event":"user_login","user_id":"u123","ts":"2026-06-10T10:00:00Z"}}'

# Get chain head (latest hash + total record count)
curl -H "Authorization: Bearer $KEY" "$BASE/v1/agents/myapp%3A%3Aevents/strand/head"

# List recent records
curl -H "Authorization: Bearer $KEY" "$BASE/v1/agents/myapp%3A%3Aevents/strand/records?limit=20"

# Time-travel: what did this agent look like 2 hours ago?
curl -H "Authorization: Bearer $KEY" "$BASE/v1/strand/as-of?timestamp_hlc=1749420000000"

Mutant proposals

# List pending proposals
curl -H "Authorization: Bearer $KEY" "$BASE/v1/mutations?status=Pending"

# Get one proposal
curl -H "Authorization: Bearer $KEY" $BASE/v1/mutations/mut_abc123

# Approve a proposal (human action — governed zone requires this)
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  $BASE/v1/mutations/mut_abc123/approve \
  -d '{"approver_agent_id":"admin","reason":"Reviewed and approved"}'

# Apply after approval threshold is met
curl -X POST -H "Authorization: Bearer $KEY" $BASE/v1/mutations/mut_abc123/apply

Strand verification

# Verify the entire hash chain — should return {"valid":true}
# Run this if you ever receive a SAPIXDB_CHAIN_INTEGRITY alert
curl -H "Authorization: Bearer $KEY" $BASE/v1/strand/verify

Chain export for audit

# Export strand records from the last 24 hours (JSONL format)
curl -H "Authorization: Bearer $KEY" \
  "$BASE/v1/strand/export?from_date=2026-06-09&to_date=2026-06-10&fmt=jsonl" \
  -o audit_export.jsonl

# The response includes X-Export-Hash (SHA-256 of the file) and X-Export-Rows

8. Tier capabilities

9. Troubleshooting

I emailed my agent but got no response

Check that you're emailing the exact session address shown on your session page (e.g. dba-a3f9b2c1@agents.boboyka.com). The address is unique per session — it will not work if the session has been cancelled or expired. Start a new session to get a fresh address.

The daily report says "NO DATA" for one of my databases

This means the agent couldn't connect to that database during the check window. Common causes: the database host is unreachable from the internet (firewall), the port changed, or the credentials are wrong. Reply to your session email or chat to ask the agent to diagnose the connection.

I received a SAPIXDB_CHAIN_INTEGRITY alert

curl -H "Authorization: Bearer $KEY" $BASE/v1/strand/verify

The agent approved a Mutant proposal I wanted to review myself

The agent only auto-approves proposals in the free zone. If you want to review all proposals yourself regardless of zone, tell the agent: "Do not auto-approve any Mutant proposals — always escalate to me first." The agent will update its review policy for your subscription.

I asked the agent to create an organism and it refused

The agent will ask for clarification before creating any SapixDB structure to avoid mistakes. Make sure your request includes: the organism name (flat, no ::), the agent names you want, and the data zone. If it still refuses, it may have detected that an organism with that name already exists.

The SapixDB organism I want doesn't have the agents I need

You can add agents to an existing organism at any time — it doesn't require recreating the organism. Tell the agent: "Add an agent called `notifications` to the `myapp` organism." The new agent gets its own strand and starts from genesis.