# rioliu/dbq architecture

> Architecture diagram of the GitHub repository rioliu/dbq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rioliu/dbq
- Repository: https://github.com/rioliu/dbq

## Overview

dbq is a multi-database CLI and bundled agent skill: users manage credential profiles, discover schemas, test connections, and run bounded SQL queries to receive table, JSON, or CSV results. The runtime path is CLI dispatch, profile resolution, statement and engine-level safeguards, database execution, then result formatting. Profile creation, editing, and removal are distinct workflows. The graph also preserves the documented agent-skill integration and five supported database engines. Several source excerpts are partial; links to unsampled behavior rely on README documentation rather than inferred calls.

Main entry points: [`internal/dbq/query.go`](https://github.com/rioliu/dbq/blob/main/internal/dbq/query.go) (Query and schema execution), [`main.go`](https://github.com/rioliu/dbq/blob/main/main.go) (Command dispatch), [`internal/dbq/profile.go`](https://github.com/rioliu/dbq/blob/main/internal/dbq/profile.go) (Load profiles), [`internal/dbq/profile_add.go`](https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_add.go) (Add profile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_command["Command dispatch<br/>[main.go]"]
  node_profile_commands["Profile commands<br/>[main.go]"]
  node_schema_command["Schema command<br/>[main.go]"]
  node_ping_command["Ping command<br/>[main.go]"]
  node_query_command["Query command<br/>[main.go]"]
end

subgraph group_profiles["Profile management"]
  node_profile_load["Load profiles<br/>[profile.go]"]
  node_profile_add["Add profile<br/>[profile_add.go]"]
  node_profile_edit["Edit profile<br/>[profile_edit.go]"]
  node_profile_remove["Remove profile<br/>[profile_remove.go]"]
  node_profile_store[("Profile file")]
end

subgraph group_query["Query execution"]
  node_statement_guard["Statement guard<br/>[guard.go]"]
  node_query_engine["Query and schema execution<br/>[query.go]"]
  node_readonly_engine["Engine read-only mode<br/>[query.go]"]
  node_result_format["Result formatting<br/>[output.go]"]
end

subgraph group_integrations["Database and agent integrations"]
  node_mysql[("MySQL")]
  node_postgres[("PostgreSQL")]
  node_sqlserver[("SQL Server")]
  node_oracle[("Oracle")]
  node_sqlite[("SQLite")]
  node_agent_skill["dbq agent skill<br/>[SKILL.md]"]
end

node_operator(("User or agent"))

node_operator -->|"runs commands"| node_command
node_command -->|"dispatches profile actions"| node_profile_commands
node_command -->|"dispatches schema"| node_schema_command
node_command -->|"dispatches ping"| node_ping_command
node_command -->|"dispatches query"| node_query_command
node_profile_commands -->|"adds profiles"| node_profile_add
node_profile_commands -->|"edits profiles"| node_profile_edit
node_profile_commands -->|"removes profiles"| node_profile_remove
node_profile_add -->|"appends securely"| node_profile_store
node_profile_edit -->|"updates securely"| node_profile_store
node_profile_remove -->|"removes securely"| node_profile_store
node_profile_load -->|"reads profiles"| node_profile_store
node_query_command -->|"resolves profile"| node_profile_load
node_ping_command -->|"resolves profile"| node_profile_load
node_schema_command -->|"resolves profile"| node_profile_load
node_query_command -->|"validates statement"| node_statement_guard
node_query_command -->|"runs query"| node_query_engine
node_schema_command -->|"lists schema"| node_query_engine
node_ping_command -->|"tests connection"| node_query_engine
node_query_engine -->|"enables read-only"| node_readonly_engine
node_query_command -->|"formats results"| node_result_format
node_query_engine -->|"queries"| node_mysql
node_query_engine -->|"queries"| node_postgres
node_query_engine -->|"queries"| node_sqlserver
node_query_engine -->|"queries"| node_oracle
node_query_engine -->|"queries"| node_sqlite
node_readonly_engine -->|"sets read-only"| node_mysql
node_readonly_engine -->|"sets read-only"| node_postgres
node_readonly_engine -->|"sets read-only"| node_oracle
node_readonly_engine -->|"sets read-only"| node_sqlite
node_operator -->|"uses guidance"| node_agent_skill

click node_command "https://github.com/rioliu/dbq/blob/main/main.go"
click node_profile_commands "https://github.com/rioliu/dbq/blob/main/main.go"
click node_schema_command "https://github.com/rioliu/dbq/blob/main/main.go"
click node_ping_command "https://github.com/rioliu/dbq/blob/main/main.go"
click node_query_command "https://github.com/rioliu/dbq/blob/main/main.go"
click node_profile_load "https://github.com/rioliu/dbq/blob/main/internal/dbq/profile.go"
click node_profile_add "https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_add.go"
click node_profile_edit "https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_edit.go"
click node_profile_remove "https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_remove.go"
click node_statement_guard "https://github.com/rioliu/dbq/blob/main/internal/dbq/guard.go"
click node_query_engine "https://github.com/rioliu/dbq/blob/main/internal/dbq/query.go"
click node_readonly_engine "https://github.com/rioliu/dbq/blob/main/internal/dbq/query.go"
click node_result_format "https://github.com/rioliu/dbq/blob/main/internal/dbq/output.go"
click node_agent_skill "https://github.com/rioliu/dbq/blob/main/skills/dbq/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command,node_profile_commands,node_schema_command,node_ping_command,node_query_command,node_operator toneBlue
class node_profile_load,node_profile_add,node_profile_edit,node_profile_remove,node_profile_store toneAmber
class node_statement_guard,node_query_engine,node_readonly_engine,node_result_format toneMint
class node_mysql,node_postgres,node_sqlserver,node_oracle,node_sqlite,node_agent_skill toneRose
```

## Components

### CLI workflows

- [Command dispatch](https://github.com/rioliu/dbq/blob/main/main.go): `main.go`
- [Profile commands](https://github.com/rioliu/dbq/blob/main/main.go): `main.go`
- [Schema command](https://github.com/rioliu/dbq/blob/main/main.go): `main.go`
- [Ping command](https://github.com/rioliu/dbq/blob/main/main.go): `main.go`
- [Query command](https://github.com/rioliu/dbq/blob/main/main.go): `main.go`

### Profile management

- [Load profiles](https://github.com/rioliu/dbq/blob/main/internal/dbq/profile.go): `internal/dbq/profile.go`
- [Add profile](https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_add.go): `internal/dbq/profile_add.go`
- [Edit profile](https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_edit.go): `internal/dbq/profile_edit.go`
- [Remove profile](https://github.com/rioliu/dbq/blob/main/internal/dbq/profile_remove.go): `internal/dbq/profile_remove.go`
- **Profile file**

### Query execution

- [Statement guard](https://github.com/rioliu/dbq/blob/main/internal/dbq/guard.go): `internal/dbq/guard.go`
- [Query and schema execution](https://github.com/rioliu/dbq/blob/main/internal/dbq/query.go): `internal/dbq/query.go`
- [Engine read-only mode](https://github.com/rioliu/dbq/blob/main/internal/dbq/query.go): `internal/dbq/query.go`
- [Result formatting](https://github.com/rioliu/dbq/blob/main/internal/dbq/output.go): `internal/dbq/output.go`

### Database and agent integrations

- **MySQL**
- **PostgreSQL**
- **SQL Server**
- **Oracle**
- **SQLite**
- [dbq agent skill](https://github.com/rioliu/dbq/blob/main/skills/dbq/SKILL.md): `skills/dbq/SKILL.md`

### Other components

- **User or agent**

## Connections

- User or agent → Command dispatch: runs commands (evidence: `README.md`)
- Command dispatch → Profile commands: dispatches profile actions (evidence: `main.go`)
- Command dispatch → Schema command: dispatches schema (evidence: `main.go`)
- Command dispatch → Ping command: dispatches ping (evidence: `main.go`)
- Command dispatch → Query command: dispatches query (evidence: `main.go`)
- Profile commands → Add profile: adds profiles (evidence: `README.md`)
- Profile commands → Edit profile: edits profiles (evidence: `README.md`)
- Profile commands → Remove profile: removes profiles (evidence: `README.md`)
- Add profile → Profile file: appends securely (evidence: `internal/dbq/profile_add.go`)
- Edit profile → Profile file: updates securely (evidence: `internal/dbq/profile_edit.go`)
- Remove profile → Profile file: removes securely (evidence: `internal/dbq/profile_remove.go`)
- Load profiles → Profile file: reads profiles (evidence: `internal/dbq/profile.go`)
- Query command → Load profiles: resolves profile (evidence: `README.md`)
- Ping command → Load profiles: resolves profile (evidence: `README.md`)
- Schema command → Load profiles: resolves profile (evidence: `README.md`)
- Query command → Statement guard: validates statement
- Query command → Query and schema execution: runs query (evidence: `main.go`)
- Schema command → Query and schema execution: lists schema (evidence: `README.md`)
- Ping command → Query and schema execution: tests connection (evidence: `main.go`)
- Query and schema execution → Engine read-only mode: enables read-only (evidence: `internal/dbq/query.go`)
- Query command → Result formatting: formats results (evidence: `README.md`)
- Query and schema execution → MySQL: queries (evidence: `README.md`)
- Query and schema execution → PostgreSQL: queries (evidence: `README.md`)
- Query and schema execution → SQL Server: queries (evidence: `README.md`)
- Query and schema execution → Oracle: queries (evidence: `README.md`)
- Query and schema execution → SQLite: queries (evidence: `README.md`)
- Engine read-only mode → MySQL: sets read-only (evidence: `README.md`)
- Engine read-only mode → PostgreSQL: sets read-only (evidence: `README.md`)
- Engine read-only mode → Oracle: sets read-only (evidence: `README.md`)
- Engine read-only mode → SQLite: sets read-only (evidence: `README.md`)
- User or agent → dbq agent skill: uses guidance (evidence: `README.md`)