Skip to content

🗄️ Database Operations (database-operations)

RawDatabaseSkill exposes the full read / write / DDL surface of a SQL database to the agent. It is the second raw skill in the catalog (alongside Execution & Debugging) and MUST be wrapped in SecureSkill before reaching an agent. It exists as a raw skill on purpose: the catalog ships the full surface area, and each downstream client decides — based on its own schema and threat model — which tools are SAFE, REQUIRES_HITL, or BLOCKED.

When to use it

  • The agent needs structured access to a SQL database for read or write operations.
  • Your client has a clear policy on which tables are safe to mutate autonomously vs. which require human approval.
  • You're building a domain agent that orchestrates SQL alongside other capabilities, and want one shared driver across that surface.

Tools

Tool Purpose
db_select_records Read rows that match a where clause.
db_update_record Mutate a row keyed by primary key.
db_insert_record Append a new row.
db_delete_record Remove a row keyed by primary key.
db_drop_table Destructive schema operation. Should default to BLOCKED in any production policy.

Configuration

Variable Default Purpose
DATABASE_URL none SQLAlchemy-style connection URL.
DATABASE_POOL_SIZE 5 Max concurrent connections. 
from mirai_core.core.types import SecureSkill, SecurityLevel
from mirai_shared_skills.database import RawDatabaseSkill

policy = {
    "db_select_records": SecurityLevel.SAFE,
    "db_update_record": SecurityLevel.REQUIRES_HITL,
    "db_insert_record": SecurityLevel.REQUIRES_HITL,
    # Tools omitted from the policy default to BLOCKED:
    # db_delete_record, db_drop_table
}

gated = SecureSkill(RawDatabaseSkill(), policy=policy)

The BLOCKED-by-omission default for db_delete_record and db_drop_table is intentional: a destructive tool the agent forgot to gate is not exposed by accident.

Security considerations

raw per ADR-0001. The skill ships full write/DDL access. Recommended baseline:

  • Reads (db_select_records) → SAFE if the table is not row-level-secured by user, otherwise wrap with a per-row predicate.
  • Writes (db_update_record, db_insert_record) → REQUIRES_HITL for any production schema.
  • Schema ops (db_drop_table) → BLOCKED always; if you actually need it, wire a one-off admin path outside the agent.

The task_id for HITL approval defaults to the tool name (per agent-core ADR-0012) — UIs render db_update_record approvals deterministically.