# bytebase/dbhub architecture

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

- Interactive diagram: https://gitdiagram.com/bytebase/dbhub
- Repository: https://github.com/bytebase/dbhub

## Overview

DBHub is a database gateway exposing MCP tools over stdio or HTTP, with a built-in web workbench. The main workflow is client request → registered tool handler → source-specific connector → database, with SQL guardrails and request tracing along the way. The README also documents optional explain, health-check, and custom tools, plus multi-source configuration and six database families. The excerpts confirm server setup, tool registration, connector management, and custom-tool execution; other handler and route wiring is included only where supported by the README and tree.

Main entry points: [`src/server.ts`](https://github.com/bytebase/dbhub/blob/main/src/server.ts) (Transport Server), [`src/connectors/manager.ts`](https://github.com/bytebase/dbhub/blob/main/src/connectors/manager.ts) (Connector Manager), [`src/connectors`](https://github.com/bytebase/dbhub/tree/main/src/connectors) (Database Connectors), [`src/tools/index.ts`](https://github.com/bytebase/dbhub/blob/main/src/tools/index.ts) (Tool Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_server["Transport Server<br/>[server.ts]"]
  node_config["Source Configuration<br/>[toml-loader.ts]"]
end

subgraph group_tools["Database Tools"]
  node_policy["SQL Guardrails"]
  node_registry["Tool Registration<br/>[index.ts]"]
  node_execute["Execute SQL<br/>[execute-sql.ts]"]
  node_search["Search Objects<br/>[search-objects.ts]"]
  node_explain["Explain SQL<br/>[explain-sql.ts]"]
  node_health["Health Check<br/>[health-check.ts]"]
  node_custom["Custom Tools"]
  node_trace[("Request Tracing<br/>[index.ts]")]
end

subgraph group_connections["Sources And Connectors"]
  node_manager["Connector Manager<br/>[manager.ts]"]
  node_connectors["Database Connectors"]
end

subgraph group_workbench["Web Workbench"]
  node_frontend["Workbench UI<br/>[App.tsx]"]
  node_sourceapi["Sources API<br/>[sources.ts]"]
  node_requestapi["Requests API<br/>[requests.ts]"]
  node_toolapi["Tools API"]
  node_views["Workbench Views"]
end

node_clients(("MCP Clients"))
node_database[("Databases")]
node_webuser(("Workbench User"))

node_clients -->|"send MCP requests"| node_server
node_server -->|"resolve sources"| node_config
node_server -->|"connect sources"| node_manager
node_server -->|"register tools"| node_registry
node_registry -->|"register handler"| node_execute
node_registry -->|"register handler"| node_search
node_registry -.->|"register handler"| node_explain
node_registry -.->|"register handler"| node_health
node_registry -->|"register handler"| node_custom
node_execute -->|"get connector"| node_manager
node_search -->|"get connector"| node_manager
node_explain -.->|"get connector"| node_manager
node_health -.->|"get connector"| node_manager
node_custom -->|"ensure connection"| node_manager
node_execute -->|"check SQL"| node_policy
node_custom -->|"check SQL"| node_policy
node_execute -->|"execute SQL"| node_connectors
node_search -->|"inspect schema"| node_connectors
node_explain -.->|"explain query"| node_connectors
node_health -.->|"check health"| node_connectors
node_custom -->|"execute SQL"| node_connectors
node_manager -->|"select connector"| node_connectors
node_connectors -->|"query database"| node_database
node_custom -->|"record request"| node_trace
node_webuser -->|"use workbench"| node_frontend
node_frontend -->|"fetch sources"| node_sourceapi
node_frontend -->|"render routes"| node_views
node_views -->|"fetch request traces"| node_requestapi
node_views -->|"invoke tools"| node_toolapi
node_sourceapi -->|"request sources"| node_server
node_requestapi -->|"request traces"| node_server
node_toolapi -->|"invoke tools"| node_server

click node_server "https://github.com/bytebase/dbhub/blob/main/src/server.ts"
click node_config "https://github.com/bytebase/dbhub/blob/main/src/config/toml-loader.ts"
click node_policy "https://github.com/bytebase/dbhub/blob/main/src/utils/sql-access-policy.ts"
click node_registry "https://github.com/bytebase/dbhub/blob/main/src/tools/index.ts"
click node_execute "https://github.com/bytebase/dbhub/blob/main/src/tools/execute-sql.ts"
click node_search "https://github.com/bytebase/dbhub/blob/main/src/tools/search-objects.ts"
click node_explain "https://github.com/bytebase/dbhub/blob/main/src/tools/explain-sql.ts"
click node_health "https://github.com/bytebase/dbhub/blob/main/src/tools/health-check.ts"
click node_custom "https://github.com/bytebase/dbhub/blob/main/src/tools/custom-tool-handler.ts"
click node_trace "https://github.com/bytebase/dbhub/blob/main/src/requests/index.ts"
click node_manager "https://github.com/bytebase/dbhub/blob/main/src/connectors/manager.ts"
click node_connectors "https://github.com/bytebase/dbhub/tree/main/src/connectors"
click node_frontend "https://github.com/bytebase/dbhub/blob/main/frontend/src/App.tsx"
click node_sourceapi "https://github.com/bytebase/dbhub/blob/main/src/api/sources.ts"
click node_requestapi "https://github.com/bytebase/dbhub/blob/main/src/api/requests.ts"
click node_views "https://github.com/bytebase/dbhub/tree/main/frontend/src/components/views"

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_server,node_config,node_clients,node_webuser toneBlue
class node_policy,node_registry,node_execute,node_search,node_explain,node_health,node_custom,node_trace,node_database toneAmber
class node_manager,node_connectors toneMint
class node_frontend,node_sourceapi,node_requestapi,node_toolapi,node_views toneRose
```

## Components

### MCP Server

- [Transport Server](https://github.com/bytebase/dbhub/blob/main/src/server.ts): `src/server.ts`
- [Source Configuration](https://github.com/bytebase/dbhub/blob/main/src/config/toml-loader.ts): `src/config/toml-loader.ts`

### Database Tools

- [SQL Guardrails](https://github.com/bytebase/dbhub/blob/main/src/utils/sql-access-policy.ts): `src/utils/sql-access-policy.ts`
- [Tool Registration](https://github.com/bytebase/dbhub/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Execute SQL](https://github.com/bytebase/dbhub/blob/main/src/tools/execute-sql.ts): `src/tools/execute-sql.ts`
- [Search Objects](https://github.com/bytebase/dbhub/blob/main/src/tools/search-objects.ts): `src/tools/search-objects.ts`
- [Explain SQL](https://github.com/bytebase/dbhub/blob/main/src/tools/explain-sql.ts): `src/tools/explain-sql.ts`
- [Health Check](https://github.com/bytebase/dbhub/blob/main/src/tools/health-check.ts): `src/tools/health-check.ts`
- [Custom Tools](https://github.com/bytebase/dbhub/blob/main/src/tools/custom-tool-handler.ts): `src/tools/custom-tool-handler.ts`
- [Request Tracing](https://github.com/bytebase/dbhub/blob/main/src/requests/index.ts): `src/requests/index.ts`

### Sources And Connectors

- [Connector Manager](https://github.com/bytebase/dbhub/blob/main/src/connectors/manager.ts): `src/connectors/manager.ts`
- [Database Connectors](https://github.com/bytebase/dbhub/tree/main/src/connectors): `src/connectors`

### Web Workbench

- [Workbench UI](https://github.com/bytebase/dbhub/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sources API](https://github.com/bytebase/dbhub/blob/main/src/api/sources.ts): `src/api/sources.ts`
- [Requests API](https://github.com/bytebase/dbhub/blob/main/src/api/requests.ts): `src/api/requests.ts`
- **Tools API**
- [Workbench Views](https://github.com/bytebase/dbhub/tree/main/frontend/src/components/views): `frontend/src/components/views`

### Other components

- **MCP Clients**
- **Databases**
- **Workbench User**

## Connections

- MCP Clients → Transport Server: send MCP requests
- Transport Server → Source Configuration: resolve sources
- Transport Server → Connector Manager: connect sources
- Transport Server → Tool Registration: register tools
- Tool Registration → Execute SQL: register handler
- Tool Registration → Search Objects: register handler
- Tool Registration → Explain SQL: register handler
- Tool Registration → Health Check: register handler
- Tool Registration → Custom Tools: register handler
- Execute SQL → Connector Manager: get connector
- Search Objects → Connector Manager: get connector
- Explain SQL → Connector Manager: get connector
- Health Check → Connector Manager: get connector
- Custom Tools → Connector Manager: ensure connection
- Execute SQL → SQL Guardrails: check SQL
- Custom Tools → SQL Guardrails: check SQL
- Execute SQL → Database Connectors: execute SQL
- Search Objects → Database Connectors: inspect schema
- Explain SQL → Database Connectors: explain query
- Health Check → Database Connectors: check health
- Custom Tools → Database Connectors: execute SQL
- Connector Manager → Database Connectors: select connector
- Database Connectors → Databases: query database
- Custom Tools → Request Tracing: record request
- Workbench User → Workbench UI: use workbench
- Workbench UI → Sources API: fetch sources
- Workbench UI → Workbench Views: render routes
- Workbench Views → Requests API: fetch request traces
- Workbench Views → Tools API: invoke tools
- Sources API → Transport Server: request sources
- Requests API → Transport Server: request traces
- Tools API → Transport Server: invoke tools