# nim4/dbshield architecture

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

- Interactive diagram: https://gitdiagram.com/nim4/dbshield
- Repository: https://github.com/nim4/dbshield

## Overview

DBShield is a SQL-aware database proxy: an application connects through it, and it forwards database protocol traffic while learning query patterns or checking them in protect mode. The main path runs from configuration and listener dispatch through a database-specific protocol handler, query classification, and forwarding or configured action. A local Bolt database stores learned patterns and abnormal-query records; a separate authenticated web interface exposes query counters. README documents support for DB2, MariaDB/MySQL, Oracle, PostgreSQL, and SQL Server. Some startup/listener wiring is omitted from the excerpts, so uncertain links are dashed.

Main entry points: [`dbshield/utils.go`](https://github.com/nim4/dbshield/blob/master/dbshield/utils.go) (Connection dispatch), [`dbshield/dbms/utils.go`](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/utils.go) (Query processing), [`dbshield/training/training.go`](https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go) (Learning and checks), [`dbshield/dbshield.go`](https://github.com/nim4/dbshield/blob/master/dbshield/dbshield.go) (Proxy lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Proxy runtime"]
  node_config["Configuration<br/>[config.go]"]
  node_proxy_runtime["Proxy lifecycle<br/>[dbshield.go]"]
  node_connection_dispatch["Connection dispatch<br/>[utils.go]"]
end

subgraph group_protocols["Database protocols"]
  node_mysql["MySQL / MariaDB<br/>[mysql.go]"]
  node_postgres["PostgreSQL<br/>[postgres.go]"]
  node_db2["DB2<br/>[db2.go]"]
  node_oracle["Oracle<br/>[oracle.go]"]
  node_mssql["SQL Server<br/>[mssql.go]"]
end

subgraph group_policy["Learning and policy"]
  node_query_policy["Query processing<br/>[utils.go]"]
  node_sql_patterns["SQL patterns<br/>[sql.go]"]
  node_training["Learning and checks<br/>[training.go]"]
  node_action["Configured action<br/>[action.go]"]
  node_pattern_store[("Pattern store<br/>[training.go]")]
  node_abnormal_records[("Abnormal records<br/>[training.go]")]
end

subgraph group_operations["Management and status"]
  node_cli_entry["CLI entry point<br/>[main.go]"]
  node_admin_api["Pattern management<br/>[dbshield.go]"]
  node_web_server["Web interface<br/>[server.go]"]
  node_logger["Logging<br/>[log.go]"]
end

node_application(("Application server"))
node_database[("Backend database")]
node_cli(("CLI operator"))
node_web_client(("Web UI user"))

node_cli -->|"runs"| node_cli_entry
node_cli_entry -->|"starts"| node_proxy_runtime
node_proxy_runtime -.->|"parses"| node_config
node_proxy_runtime -.->|"accepts connections"| node_connection_dispatch
node_connection_dispatch -->|"opens backend connection"| node_database
node_connection_dispatch -->|"dispatches"| node_mysql
node_connection_dispatch -->|"dispatches"| node_postgres
node_connection_dispatch -->|"dispatches"| node_db2
node_connection_dispatch -->|"dispatches"| node_oracle
node_connection_dispatch -->|"dispatches"| node_mssql
node_application -.->|"sends SQL traffic"| node_connection_dispatch
node_mysql -->|"forwards protocol traffic"| node_database
node_postgres -->|"forwards protocol traffic"| node_database
node_db2 -->|"forwards protocol traffic"| node_database
node_oracle -->|"forwards protocol traffic"| node_database
node_mssql -->|"forwards protocol traffic"| node_database
node_mysql -->|"processes query"| node_query_policy
node_postgres -->|"processes query"| node_query_policy
node_db2 -->|"processes query"| node_query_policy
node_oracle -->|"processes query"| node_query_policy
node_mssql -->|"processes query"| node_query_policy
node_query_policy -->|"checks or learns"| node_training
node_training -->|"normalizes queries"| node_sql_patterns
node_training -->|"reads and writes"| node_pattern_store
node_training -->|"records anomalies"| node_abnormal_records
node_query_policy -->|"invokes on rejection"| node_action
node_web_client -->|"views status"| node_web_server
node_web_server -->|"reads counters"| node_training
node_cli_entry -->|"runs management commands"| node_admin_api
node_admin_api -.->|"lists or removes patterns"| node_pattern_store
node_proxy_runtime -.->|"starts interface"| node_web_server
node_query_policy -.->|"logs events"| node_logger

click node_config "https://github.com/nim4/dbshield/blob/master/dbshield/config/config.go"
click node_proxy_runtime "https://github.com/nim4/dbshield/blob/master/dbshield/dbshield.go"
click node_connection_dispatch "https://github.com/nim4/dbshield/blob/master/dbshield/utils.go"
click node_mysql "https://github.com/nim4/dbshield/blob/master/dbshield/dbms/mysql.go"
click node_postgres "https://github.com/nim4/dbshield/blob/master/dbshield/dbms/postgres.go"
click node_db2 "https://github.com/nim4/dbshield/blob/master/dbshield/dbms/db2.go"
click node_oracle "https://github.com/nim4/dbshield/blob/master/dbshield/dbms/oracle.go"
click node_mssql "https://github.com/nim4/dbshield/blob/master/dbshield/dbms/mssql.go"
click node_query_policy "https://github.com/nim4/dbshield/blob/master/dbshield/dbms/utils.go"
click node_sql_patterns "https://github.com/nim4/dbshield/blob/master/dbshield/sql/sql.go"
click node_training "https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go"
click node_action "https://github.com/nim4/dbshield/blob/master/dbshield/utils/action.go"
click node_pattern_store "https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go"
click node_abnormal_records "https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go"
click node_cli_entry "https://github.com/nim4/dbshield/blob/master/main.go"
click node_admin_api "https://github.com/nim4/dbshield/blob/master/dbshield/dbshield.go"
click node_web_server "https://github.com/nim4/dbshield/blob/master/dbshield/httpserver/server.go"
click node_logger "https://github.com/nim4/dbshield/blob/master/dbshield/logger/log.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_config,node_proxy_runtime,node_connection_dispatch,node_web_client toneBlue
class node_mysql,node_postgres,node_db2,node_oracle,node_mssql,node_database toneAmber
class node_query_policy,node_sql_patterns,node_training,node_action,node_pattern_store,node_abnormal_records,node_application toneMint
class node_cli_entry,node_admin_api,node_web_server,node_logger toneRose
class node_cli toneIndigo
```

## Components

### Proxy runtime

- [Configuration](https://github.com/nim4/dbshield/blob/master/dbshield/config/config.go): `dbshield/config/config.go`
- [Proxy lifecycle](https://github.com/nim4/dbshield/blob/master/dbshield/dbshield.go): `dbshield/dbshield.go`
- [Connection dispatch](https://github.com/nim4/dbshield/blob/master/dbshield/utils.go): `dbshield/utils.go`

### Database protocols

- [MySQL / MariaDB](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/mysql.go): `dbshield/dbms/mysql.go`
- [PostgreSQL](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/postgres.go): `dbshield/dbms/postgres.go`
- [DB2](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/db2.go): `dbshield/dbms/db2.go`
- [Oracle](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/oracle.go): `dbshield/dbms/oracle.go`
- [SQL Server](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/mssql.go): `dbshield/dbms/mssql.go`

### Learning and policy

- [Query processing](https://github.com/nim4/dbshield/blob/master/dbshield/dbms/utils.go): `dbshield/dbms/utils.go`
- [SQL patterns](https://github.com/nim4/dbshield/blob/master/dbshield/sql/sql.go): `dbshield/sql/sql.go`
- [Learning and checks](https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go): `dbshield/training/training.go`
- [Configured action](https://github.com/nim4/dbshield/blob/master/dbshield/utils/action.go): `dbshield/utils/action.go`
- [Pattern store](https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go): `dbshield/training/training.go`
- [Abnormal records](https://github.com/nim4/dbshield/blob/master/dbshield/training/training.go): `dbshield/training/training.go`

### Management and status

- [CLI entry point](https://github.com/nim4/dbshield/blob/master/main.go): `main.go`
- [Pattern management](https://github.com/nim4/dbshield/blob/master/dbshield/dbshield.go): `dbshield/dbshield.go`
- [Web interface](https://github.com/nim4/dbshield/blob/master/dbshield/httpserver/server.go): `dbshield/httpserver/server.go`
- [Logging](https://github.com/nim4/dbshield/blob/master/dbshield/logger/log.go): `dbshield/logger/log.go`

### Other components

- **Application server**
- **Backend database**
- **CLI operator**
- **Web UI user**

## Connections

- CLI operator → CLI entry point: runs (evidence: `main.go`)
- CLI entry point → Proxy lifecycle: starts (evidence: `main.go`)
- Proxy lifecycle → Configuration: parses
- Proxy lifecycle → Connection dispatch: accepts connections
- Connection dispatch → Backend database: opens backend connection (evidence: `dbshield/utils.go`)
- Connection dispatch → MySQL / MariaDB: dispatches (evidence: `dbshield/utils.go`)
- Connection dispatch → PostgreSQL: dispatches (evidence: `dbshield/utils.go`)
- Connection dispatch → DB2: dispatches (evidence: `dbshield/utils.go`)
- Connection dispatch → Oracle: dispatches (evidence: `dbshield/utils.go`)
- Connection dispatch → SQL Server: dispatches (evidence: `dbshield/utils.go`)
- Application server → Connection dispatch: sends SQL traffic (evidence: `README.md`)
- MySQL / MariaDB → Backend database: forwards protocol traffic (evidence: `dbshield/dbms/mysql.go`)
- PostgreSQL → Backend database: forwards protocol traffic (evidence: `dbshield/dbms/postgres.go`)
- DB2 → Backend database: forwards protocol traffic (evidence: `dbshield/dbms/db2.go`)
- Oracle → Backend database: forwards protocol traffic (evidence: `dbshield/dbms/oracle.go`)
- SQL Server → Backend database: forwards protocol traffic (evidence: `dbshield/dbms/mssql.go`)
- MySQL / MariaDB → Query processing: processes query (evidence: `dbshield/dbms/mysql.go`)
- PostgreSQL → Query processing: processes query (evidence: `dbshield/dbms/postgres.go`)
- DB2 → Query processing: processes query (evidence: `dbshield/dbms/db2.go`)
- Oracle → Query processing: processes query (evidence: `dbshield/dbms/oracle.go`)
- SQL Server → Query processing: processes query (evidence: `dbshield/dbms/mssql.go`)
- Query processing → Learning and checks: checks or learns (evidence: `dbshield/dbms/utils.go`)
- Learning and checks → SQL patterns: normalizes queries (evidence: `dbshield/training/training.go`)
- Learning and checks → Pattern store: reads and writes (evidence: `dbshield/training/training.go`)
- Learning and checks → Abnormal records: records anomalies (evidence: `dbshield/training/training.go`)
- Query processing → Configured action: invokes on rejection (evidence: `dbshield/dbms/utils.go`)
- Web UI user → Web interface: views status (evidence: `dbshield/httpserver/server.go`)
- Web interface → Learning and checks: reads counters (evidence: `dbshield/httpserver/server.go`)
- CLI entry point → Pattern management: runs management commands (evidence: `main.go`)
- Pattern management → Pattern store: lists or removes patterns
- Proxy lifecycle → Web interface: starts interface
- Query processing → Logging: logs events
