Skip to content
CF / PROJECT 03

database-cli

Safe database investigation for agents

A CLI-first database Skill that lets agents investigate real data inside guardrails.

Status
Active
Started
2026
Stack
Python · CLI · Codex Skill · Database
Links
01

Why

Production debugging keeps coming back to the database: which table holds this, which column changed, what does this order actually look like in QA?

Agents are good at that loop. Handing one a general-purpose database client is the wrong trade, though. database-cli gives the agent one narrow, auditable way in.

02

Problem

  1. 01

    Agents guess at schema instead of reading it, and write SQL against tables that don't exist.

  2. 02

    A general SQL client lets every statement through, writes and DDL included.

  3. 03

    Connection details end up in command lines and chat history.

  4. 04

    Each environment is set up differently, so humans and agents don't share one entry point.

03

System

The CLI is the product. Everything else is a thin layer on top of it.

  1. L1Skill · SKILL.md

    The operating procedure: confirm the environment, read the real schema, run bounded read-only queries, and change data only with explicit approval.

  2. L2Optional MCP adapter

    scripts/database-mcp exposes the same capabilities over stdio MCP and delegates every call to the CLI.

  3. L3CLI · scripts/db-query

    The single execution entry. It validates SQL, enforces read-only defaults and row limits, and searches metadata.

  4. L4sq backend

    Queries run through sq, with environments described in a local connections.local.json that never enters the repository.

04

Implementation

  • Setup status an agent can act on

    --setup-status returns JSON with ready, problems and next_actions — without connecting to any database — so an agent can repair its own setup first.

  • Object search

    Find schemas, tables, columns, indexes and procedures by pattern at names, summary or full detail, instead of hand-writing information_schema SQL.

  • Connections with intent

    Environments carry a display name, project, description and aliases, so the agent can choose a connection by what the user means.

  • One-step install

    scripts/install checks for sq, collects connection details and writes the local config in a single command.

05

Decisions

  1. D1

    One execution path

    The MCP adapter is not allowed its own query logic. Safety rules live in the CLI, so no client can route around them.

  2. D2

    Write access comes from config, not a flag

    --allow-write only works on environments marked "writable": true; ad-hoc connections need an extra --writable. A protected database cannot be re-entered as a temporary connection to escape its config.

  3. D3

    Count before changing

    Approved UPDATE and DELETE statements count affected rows first and are refused above max_write_rows (1000 by default), so a WHERE 1=1 cannot slip through.

  4. D4

    Some SQL is never allowed

    DDL, privileges, transactions, procedures, locks and exports stay blocked even when writes are approved.

  5. D5

    Not a platform

    No workbench, permission service or multi-tenant server. It stays a Skill that humans and agents install and can audit.

06

Result

Entry point
scripts/db-query
Default
Read-only · bounded rows
Clients
Codex Skill · MCP

It is the database entry point of my own agent setup: schema lookups, cross-environment checks and repair SQL all go through the same guarded CLI.

GitHub