# diogoaalmeida/dbcli architecture

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

- Interactive diagram: https://gitdiagram.com/diogoaalmeida/dbcli
- Repository: https://github.com/diogoaalmeida/dbcli

## Overview

dbcli is a read-only SQL CLI for AI agents. The main workflow dispatches a command, resolves a connection, runs the requested query or database-introspection operation through the driver, then emits a stable JSON or table result. Database discovery proceeds from schemas to tables to table details; query, explain, and sample are separate operations. README capabilities are retained, though the command implementations for schema listings and profile storage were not excerpted.

Main entry points: [`cmd/common.go`](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/common.go) (Connect and route), [`main.go`](https://github.com/diogoaalmeida/dbcli/blob/main/main.go) (Command dispatch), [`internal/output/json.go`](https://github.com/diogoaalmeida/dbcli/blob/main/internal/output/json.go) (JSON and table output), [`internal/postgres/schema.go`](https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/schema.go) (Schema and table metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_entry["Command dispatch<br/>[main.go]"]
  node_query["Query<br/>[query.go]"]
  node_explain["Explain<br/>[explain.go]"]
  node_schemas["List schemas<br/>[schemas.go]"]
  node_schema["List tables<br/>[schema.go]"]
  node_describe["Describe table<br/>[describe.go]"]
  node_sample["Sample rows<br/>[sample.go]"]
  node_profiles["Manage profiles<br/>[profiles.go]"]
end

subgraph group_connection["Connection setup"]
  node_common["Connect and route<br/>[common.go]"]
  node_config["Profile configuration<br/>[config.go]"]
  node_driver["Driver interface<br/>[driver.go]"]
end

subgraph group_postgres["Postgres operations"]
  node_pgdriver["Postgres connection<br/>[driver.go]"]
  node_pgquery["Query execution<br/>[exec.go]"]
  node_safety["Read-only safeguards<br/>[dbsafety.go]"]
  node_introspection["Schema and table metadata<br/>[schema.go]"]
end

subgraph group_output["Result formatting"]
  node_format["JSON and table output<br/>[json.go]"]
end

node_agent(("AI agent or user"))
node_postgresdb[("Postgres database")]

node_agent -->|"invokes"| node_entry
node_entry -->|"dispatches"| node_query
node_entry -->|"dispatches"| node_explain
node_entry -->|"dispatches"| node_schemas
node_entry -->|"dispatches"| node_schema
node_entry -->|"dispatches"| node_describe
node_entry -->|"dispatches"| node_sample
node_entry -->|"dispatches"| node_profiles
node_query -->|"connects via"| node_common
node_explain -->|"connects via"| node_common
node_schemas -->|"connects via"| node_common
node_schema -->|"connects via"| node_common
node_describe -->|"connects via"| node_common
node_sample -->|"connects via"| node_common
node_common -->|"resolves DSN"| node_config
node_profiles -->|"manages profiles"| node_config
node_common -->|"looks up driver"| node_driver
node_common -->|"registers driver"| node_pgdriver
node_pgdriver -->|"implements"| node_driver
node_pgdriver -->|"connects"| node_postgresdb
node_query -->|"calls Query"| node_pgquery
node_explain -->|"calls Explain"| node_pgquery
node_schemas -->|"lists schemas"| node_introspection
node_schema -->|"lists tables"| node_introspection
node_describe -->|"describes table"| node_introspection
node_sample -->|"samples table"| node_introspection
node_pgquery -->|"validates query"| node_safety
node_pgquery -->|"queries in read-only tx"| node_postgresdb
node_introspection -->|"reads metadata"| node_postgresdb
node_query -->|"writes result"| node_format
node_explain -->|"writes result"| node_format
node_sample -->|"writes result"| node_format
node_describe -->|"writes data"| node_format
node_schemas -->|"writes data"| node_format
node_schema -->|"writes data"| node_format

click node_entry "https://github.com/diogoaalmeida/dbcli/blob/main/main.go"
click node_query "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/query.go"
click node_explain "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/explain.go"
click node_schemas "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/schemas.go"
click node_schema "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/schema.go"
click node_describe "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/describe.go"
click node_sample "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/sample.go"
click node_profiles "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/profiles.go"
click node_common "https://github.com/diogoaalmeida/dbcli/blob/main/cmd/common.go"
click node_config "https://github.com/diogoaalmeida/dbcli/blob/main/internal/config/config.go"
click node_driver "https://github.com/diogoaalmeida/dbcli/blob/main/internal/driver/driver.go"
click node_pgdriver "https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/driver.go"
click node_pgquery "https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/exec.go"
click node_safety "https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/dbsafety.go"
click node_introspection "https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/schema.go"
click node_format "https://github.com/diogoaalmeida/dbcli/blob/main/internal/output/json.go"

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_entry,node_query,node_explain,node_schemas,node_schema,node_describe,node_sample,node_profiles,node_agent toneBlue
class node_common,node_config,node_driver,node_postgresdb toneAmber
class node_pgdriver,node_pgquery,node_safety,node_introspection toneMint
class node_format toneRose
```

## Components

### CLI commands

- [Command dispatch](https://github.com/diogoaalmeida/dbcli/blob/main/main.go): `main.go`
- [Query](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/query.go): `cmd/query.go`
- [Explain](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/explain.go): `cmd/explain.go`
- [List schemas](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/schemas.go): `cmd/schemas.go`
- [List tables](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/schema.go): `cmd/schema.go`
- [Describe table](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/describe.go): `cmd/describe.go`
- [Sample rows](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/sample.go): `cmd/sample.go`
- [Manage profiles](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/profiles.go): `cmd/profiles.go`

### Connection setup

- [Connect and route](https://github.com/diogoaalmeida/dbcli/blob/main/cmd/common.go): `cmd/common.go`
- [Profile configuration](https://github.com/diogoaalmeida/dbcli/blob/main/internal/config/config.go): `internal/config/config.go`
- [Driver interface](https://github.com/diogoaalmeida/dbcli/blob/main/internal/driver/driver.go): `internal/driver/driver.go`

### Postgres operations

- [Postgres connection](https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/driver.go): `internal/postgres/driver.go`
- [Query execution](https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/exec.go): `internal/postgres/exec.go`
- [Read-only safeguards](https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/dbsafety.go): `internal/postgres/dbsafety.go`
- [Schema and table metadata](https://github.com/diogoaalmeida/dbcli/blob/main/internal/postgres/schema.go): `internal/postgres/schema.go`

### Result formatting

- [JSON and table output](https://github.com/diogoaalmeida/dbcli/blob/main/internal/output/json.go): `internal/output/json.go`

### Other components

- **AI agent or user**
- **Postgres database**

## Connections

- AI agent or user → Command dispatch: invokes (evidence: `main.go`)
- Command dispatch → Query: dispatches (evidence: `main.go`)
- Command dispatch → Explain: dispatches (evidence: `main.go`)
- Command dispatch → List schemas: dispatches (evidence: `main.go`)
- Command dispatch → List tables: dispatches (evidence: `main.go`)
- Command dispatch → Describe table: dispatches (evidence: `main.go`)
- Command dispatch → Sample rows: dispatches (evidence: `main.go`)
- Command dispatch → Manage profiles: dispatches (evidence: `main.go`)
- Query → Connect and route: connects via (evidence: `cmd/common.go`)
- Explain → Connect and route: connects via (evidence: `cmd/common.go`)
- List schemas → Connect and route: connects via (evidence: `cmd/common.go`)
- List tables → Connect and route: connects via (evidence: `cmd/common.go`)
- Describe table → Connect and route: connects via (evidence: `cmd/common.go`)
- Sample rows → Connect and route: connects via (evidence: `cmd/common.go`)
- Connect and route → Profile configuration: resolves DSN (evidence: `cmd/common.go`)
- Manage profiles → Profile configuration: manages profiles (evidence: `cmd/profiles.go`)
- Connect and route → Driver interface: looks up driver (evidence: `cmd/common.go`)
- Connect and route → Postgres connection: registers driver (evidence: `cmd/common.go`)
- Postgres connection → Driver interface: implements (evidence: `internal/postgres/driver.go`)
- Postgres connection → Postgres database: connects (evidence: `internal/postgres/driver.go`)
- Query → Query execution: calls Query (evidence: `cmd/query.go`)
- Explain → Query execution: calls Explain (evidence: `cmd/explain.go`)
- List schemas → Schema and table metadata: lists schemas (evidence: `README.md`)
- List tables → Schema and table metadata: lists tables (evidence: `README.md`)
- Describe table → Schema and table metadata: describes table (evidence: `cmd/describe.go`)
- Sample rows → Schema and table metadata: samples table (evidence: `README.md`)
- Query execution → Read-only safeguards: validates query (evidence: `internal/postgres/exec.go`)
- Query execution → Postgres database: queries in read-only tx (evidence: `internal/postgres/exec.go`)
- Schema and table metadata → Postgres database: reads metadata (evidence: `internal/postgres/schema.go`)
- Query → JSON and table output: writes result (evidence: `cmd/query.go`)
- Explain → JSON and table output: writes result (evidence: `cmd/explain.go`)
- Sample rows → JSON and table output: writes result (evidence: `cmd/sample.go`)
- Describe table → JSON and table output: writes data (evidence: `cmd/describe.go`)
- List schemas → JSON and table output: writes data (evidence: `README.md`)
- List tables → JSON and table output: writes data (evidence: `README.md`)
