db-api - SKILL.md Agent Skill

name: db-api description: >- The db-api skill exposes the repository's SQLite database to agents via a lightweight CLI (scripts/db.sh) and a small Python wrapper (scripts/skills/db-api.py). Use this skill for safe, read-first operations and limited CRUD tasks when a full service layer is not available.

db-api skill

The db-api skill exposes the repository's SQLite database to agents via a lightweight CLI (scripts/db.sh) and a small Python wrapper (scripts/skills/db-api.py). Use this skill for safe, read-first operations and limited CRUD tasks when a full service layer is not available.

Usage

scripts/skills/db-api.py list-tables
scripts/skills/db-api.py status
scripts/skills/db-api.py show-table todos
scripts/skills/db-api.py view todos [limit|'all'] [format] # formats: pretty (default), raw, csv
scripts/skills/db-api.py view todos all pretty
scripts/skills/db-api.py view todos 10 csv
scripts/skills/db-api.py query "SELECT count(*) FROM todos;"

Output formats and status fields

view: supports three output formats:
- pretty: sqlite3 -header -column (human-friendly table with column headers)
- raw: pipe-delimited values without headers (good for scripting)
- csv: header + CSV output
status: prints the following fields to aid agents and operators:
- DB_PATH, size, last_modified, last_access
- tables: list of table names
- table_row_counts: per-table counts
- table_count: total number of tables
- PRAGMA values: journal_mode, foreign_keys, busy_timeout
- connected_processes: lsof output if available

Troubleshooting

Ensure sqlite3 is installed and scripts/lib/sql.sh DB_PATH points to the expected DB file (default: run/v-daemon.db).
If WAL cannot be enabled, move the DB to a WAL-capable filesystem (avoid certain CIFS mounts).
PRAGMA settings like foreign_keys must be applied per-connection; scripts/lib/sql.sh sets sensible defaults per run.
Check run/system.log and logs/sql-agent.log for initialization and errors.

Notes

Do not run untrusted SQL via the query endpoint; treat it as an administrative capability.
For complex or high-frequency DB work, implement a dedicated service layer rather than giving agents direct SQL access.
See docs/db-api.md and docs/db-api-spec.md for full reference and examples.