# bloomberg/comdb2 architecture

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

- Interactive diagram: https://gitdiagram.com/bloomberg/comdb2
- Repository: https://github.com/bloomberg/comdb2
- Video tour (about a minute): https://gitdiagram.com/bloomberg/comdb2/video

## Overview

Comdb2 is a clustered relational database: clients submit SQL, the server executes it through its SQL and table layers, and transactional data is stored by the Berkeley DB-based engine. The README documents client-side connection negotiation/reconnect, multi-node operation, and optimistic transactions with Snapshot and Serializable isolation. The tree identifies additional product areas for schema changes, queues, stored procedures, and federated databases. Only selected sources were sampled, so links among unsampled subsystems are limited to documented capabilities and clear runtime boundaries.

Main entry points: [`db/sqlglue.c`](https://github.com/bloomberg/comdb2/blob/main/db/sqlglue.c) (SQL integration), [`db/comdb2.c`](https://github.com/bloomberg/comdb2/blob/main/db/comdb2.c) (Database runtime), [`cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/Driver.java`](https://github.com/bloomberg/comdb2/blob/main/cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/Driver.java) (JDBC driver), [`db/trans.c`](https://github.com/bloomberg/comdb2/blob/main/db/trans.c) (Transaction control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client access"]
  node_capi["C client API<br/>[cdb2api.c]"]
  node_jdbc["JDBC driver<br/>[Driver.java]"]
  node_wire["SQL protocol<br/>[sqlquery.proto]"]
end

subgraph group_sql["SQL execution"]
  node_network["Network layer<br/>[net.c]"]
  node_newsql["SQL ingress<br/>[newsql.c]"]
  node_sqlglue["SQL integration<br/>[sqlglue.c]"]
  node_sqlite["SQL engine<br/>[main.c]"]
  node_sqlplan["Plan tracking<br/>[db_query_plan.c]"]
end

subgraph group_data["Data and transactions"]
  node_runtime["Database runtime<br/>[comdb2.c]"]
  node_transactions["Transaction control<br/>[trans.c]"]
  node_tables["Table layer<br/>[bdb.c]"]
  node_storage[("B-tree storage<br/>[bt_method.c]")]
  node_metadata[("Metadata store<br/>[llmeta.c]")]
end

subgraph group_cluster["Cluster services"]
  node_replication["Replication<br/>[phys_rep.c]"]
  node_discovery["Client discovery"]
end

subgraph group_extensions["Database features"]
  node_schema["Schema changes<br/>[schemachange.c]"]
  node_queues["Queue databases<br/>[queuedb.c]"]
  node_federation["Federated databases<br/>[fdb_access.c]"]
  node_procedures["Stored procedures<br/>[lua.c]"]
end

node_app(("SQL application"))
node_peer(("Cluster peers"))

node_app -->|"submits SQL"| node_capi
node_app -->|"submits SQL"| node_jdbc
node_capi -->|"encodes requests"| node_wire
node_jdbc -->|"finds database"| node_discovery
node_jdbc -->|"encodes requests"| node_wire
node_wire -->|"transfers requests"| node_network
node_network -->|"dispatches SQL"| node_newsql
node_newsql -->|"passes requests"| node_sqlglue
node_sqlglue -->|"executes SQL"| node_sqlite
node_sqlite -->|"returns results"| node_sqlglue
node_sqlglue -->|"coordinates transactions"| node_transactions
node_transactions -->|"reads and writes"| node_tables
node_tables -->|"accesses records"| node_storage
node_tables -->|"accesses metadata"| node_metadata
node_transactions -->|"coordinates changes"| node_replication
node_replication -->|"replicates changes"| node_peer
node_runtime -->|"supports DDL"| node_schema
node_runtime -->|"supports queues"| node_queues
node_runtime -->|"supports remote data"| node_federation
node_runtime -->|"supports procedures"| node_procedures
node_sqlglue -->|"tracks query plans"| node_sqlplan

click node_capi "https://github.com/bloomberg/comdb2/blob/main/cdb2api/cdb2api.c"
click node_jdbc "https://github.com/bloomberg/comdb2/blob/main/cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/Driver.java"
click node_wire "https://github.com/bloomberg/comdb2/blob/main/protobuf/sqlquery.proto"
click node_network "https://github.com/bloomberg/comdb2/blob/main/net/net.c"
click node_newsql "https://github.com/bloomberg/comdb2/blob/main/plugins/newsql/newsql.c"
click node_sqlglue "https://github.com/bloomberg/comdb2/blob/main/db/sqlglue.c"
click node_sqlite "https://github.com/bloomberg/comdb2/blob/main/sqlite/src/main.c"
click node_sqlplan "https://github.com/bloomberg/comdb2/blob/main/db/db_query_plan.c"
click node_runtime "https://github.com/bloomberg/comdb2/blob/main/db/comdb2.c"
click node_transactions "https://github.com/bloomberg/comdb2/blob/main/db/trans.c"
click node_tables "https://github.com/bloomberg/comdb2/blob/main/bdb/bdb.c"
click node_storage "https://github.com/bloomberg/comdb2/blob/main/berkdb/btree/bt_method.c"
click node_metadata "https://github.com/bloomberg/comdb2/blob/main/bdb/llmeta.c"
click node_replication "https://github.com/bloomberg/comdb2/blob/main/db/phys_rep.c"
click node_discovery "https://github.com/bloomberg/comdb2/blob/main/cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/DatabaseDiscovery.java"
click node_schema "https://github.com/bloomberg/comdb2/blob/main/schemachange/schemachange.c"
click node_queues "https://github.com/bloomberg/comdb2/blob/main/bdb/queuedb.c"
click node_federation "https://github.com/bloomberg/comdb2/blob/main/db/fdb_access.c"
click node_procedures "https://github.com/bloomberg/comdb2/blob/main/lua/lua.c"

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_capi,node_jdbc,node_wire toneBlue
class node_network,node_newsql,node_sqlglue,node_sqlite,node_sqlplan toneAmber
class node_runtime,node_transactions,node_tables,node_storage,node_metadata toneMint
class node_replication,node_discovery toneRose
class node_schema,node_queues,node_federation,node_procedures,node_app,node_peer toneIndigo
```

## Components

### Client access

- [C client API](https://github.com/bloomberg/comdb2/blob/main/cdb2api/cdb2api.c): `cdb2api/cdb2api.c`
- [JDBC driver](https://github.com/bloomberg/comdb2/blob/main/cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/Driver.java): `cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/Driver.java`
- [SQL protocol](https://github.com/bloomberg/comdb2/blob/main/protobuf/sqlquery.proto): `protobuf/sqlquery.proto`

### SQL execution

- [Network layer](https://github.com/bloomberg/comdb2/blob/main/net/net.c): `net/net.c`
- [SQL ingress](https://github.com/bloomberg/comdb2/blob/main/plugins/newsql/newsql.c): `plugins/newsql/newsql.c`
- [SQL integration](https://github.com/bloomberg/comdb2/blob/main/db/sqlglue.c): `db/sqlglue.c`
- [SQL engine](https://github.com/bloomberg/comdb2/blob/main/sqlite/src/main.c): `sqlite/src/main.c`
- [Plan tracking](https://github.com/bloomberg/comdb2/blob/main/db/db_query_plan.c): `db/db_query_plan.c`

### Data and transactions

- [Database runtime](https://github.com/bloomberg/comdb2/blob/main/db/comdb2.c): `db/comdb2.c`
- [Transaction control](https://github.com/bloomberg/comdb2/blob/main/db/trans.c): `db/trans.c`
- [Table layer](https://github.com/bloomberg/comdb2/blob/main/bdb/bdb.c): `bdb/bdb.c`
- [B-tree storage](https://github.com/bloomberg/comdb2/blob/main/berkdb/btree/bt_method.c): `berkdb/btree/bt_method.c`
- [Metadata store](https://github.com/bloomberg/comdb2/blob/main/bdb/llmeta.c): `bdb/llmeta.c`

### Cluster services

- [Replication](https://github.com/bloomberg/comdb2/blob/main/db/phys_rep.c): `db/phys_rep.c`
- [Client discovery](https://github.com/bloomberg/comdb2/blob/main/cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/DatabaseDiscovery.java): `cdb2jdbc/src/main/java/com/bloomberg/comdb2/jdbc/DatabaseDiscovery.java`

### Database features

- [Schema changes](https://github.com/bloomberg/comdb2/blob/main/schemachange/schemachange.c): `schemachange/schemachange.c`
- [Queue databases](https://github.com/bloomberg/comdb2/blob/main/bdb/queuedb.c): `bdb/queuedb.c`
- [Federated databases](https://github.com/bloomberg/comdb2/blob/main/db/fdb_access.c): `db/fdb_access.c`
- [Stored procedures](https://github.com/bloomberg/comdb2/blob/main/lua/lua.c): `lua/lua.c`

### Other components

- **SQL application**
- **Cluster peers**

## Connections

- SQL application → C client API: submits SQL
- SQL application → JDBC driver: submits SQL
- C client API → SQL protocol: encodes requests
- JDBC driver → Client discovery: finds database
- JDBC driver → SQL protocol: encodes requests
- SQL protocol → Network layer: transfers requests
- Network layer → SQL ingress: dispatches SQL
- SQL ingress → SQL integration: passes requests
- SQL integration → SQL engine: executes SQL
- SQL engine → SQL integration: returns results
- SQL integration → Transaction control: coordinates transactions
- Transaction control → Table layer: reads and writes
- Table layer → B-tree storage: accesses records
- Table layer → Metadata store: accesses metadata
- Transaction control → Replication: coordinates changes
- Replication → Cluster peers: replicates changes
- Database runtime → Schema changes: supports DDL
- Database runtime → Queue databases: supports queues
- Database runtime → Federated databases: supports remote data
- Database runtime → Stored procedures: supports procedures
- SQL integration → Plan tracking: tracks query plans