# mariadb-corporation/mariadb-connector-nodejs architecture

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

- Interactive diagram: https://gitdiagram.com/mariadb-corporation/mariadb-connector-nodejs
- Repository: https://github.com/mariadb-corporation/mariadb-connector-nodejs

## Overview

MariaDB Node.js Connector is a non-blocking MariaDB/MySQL client with Promise and callback APIs. The main workflow configures a pool or connection, obtains a connection, submits SQL, encodes and sends protocol packets, then parses server responses into results. Separate command paths support prepared execution, bulk batches, and streamed inserts; connection establishment includes authentication. The graph preserves documented clustering, pipelining, SSL, and streaming capabilities. Some subsystem links rely on README or SOURCE INDEX references because their implementation files were not excerpted; those limits are reflected by omitted uncertain edges.

Main entry points: [`lib/connection.js`](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/connection.js) (Connection runtime), [`lib/cmd/query.js`](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/query.js) (Text queries), [`lib/cmd/parser.js`](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/parser.js) (Result parser), [`lib/pool.js`](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/pool.js) (Connection pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client APIs"]
  node_promise["Promise API<br/>[promise.js]"]
  node_callback["Callback API<br/>[callback.js]"]
end

subgraph group_lifecycle["Connection Management"]
  node_pool["Connection pool<br/>[pool.js]"]
  node_cluster["Cluster routing<br/>[cluster.js]"]
  node_connection["Connection runtime<br/>[connection.js]"]
  node_options["Connection options"]
end

subgraph group_commands["SQL Commands"]
  node_auth["Authentication<br/>[authentication.js]"]
  node_query["Text queries<br/>[query.js]"]
  node_prepare["Prepared statements<br/>[execute.js]"]
  node_batch["Bulk batches<br/>[batch-bulk.js]"]
  node_parser["Result parser<br/>[parser.js]"]
end

subgraph group_protocol["Wire Protocol"]
  node_packetout["Packet output"]
  node_packetin["Packet input"]
  node_decoder["Binary decoder<br/>[binary-decoder.js]"]
  node_encoder["Text encoder<br/>[text-encoder.js]"]
end

subgraph group_support["Protocol Support"]
  node_sqlparse["SQL parsing<br/>[parse.js]"]
  node_collations["Character collations<br/>[collations.js]"]
  node_errors["SQL errors<br/>[errors.js]"]
  node_capabilities["Protocol capabilities<br/>[capabilities.js]"]
  node_fieldtypes["Field types<br/>[field-type.js]"]
  node_serverstatus["Server status<br/>[server-status.js]"]
end

node_app(("Node.js application"))
node_server[("MariaDB / MySQL")]

node_app -->|"uses"| node_promise
node_app -->|"uses"| node_callback
node_promise -.->|"creates pool"| node_pool
node_callback -->|"wraps pool"| node_pool
node_pool -->|"creates connections"| node_connection
node_app -->|"queries SQL"| node_connection
node_connection -->|"uses options"| node_options
node_connection -->|"connects"| node_server
node_connection -->|"authenticates"| node_auth
node_connection -->|"dispatches query"| node_query
node_connection -->|"dispatches execute"| node_prepare
node_connection -.->|"dispatches batch"| node_batch
node_query -->|"splits SQL"| node_sqlparse
node_query -->|"extends parser"| node_parser
node_connection -->|"writes packets"| node_packetout
node_packetout -->|"sends commands"| node_server
node_server -->|"returns packets"| node_packetin
node_connection -->|"reads packets"| node_packetin
node_parser -->|"decodes binary rows"| node_decoder
node_parser -->|"uses field types"| node_fieldtypes
node_packetout -->|"encodes values"| node_encoder
node_options -->|"selects collation"| node_collations
node_auth -->|"checks capabilities"| node_capabilities
node_parser -->|"reads status"| node_serverstatus
node_query -->|"creates errors"| node_errors
node_cluster -.->|"routes requests"| node_pool
node_app -.->|"uses cluster"| node_cluster
node_app -->|"streams inserts"| node_connection
node_app -->|"pipelines commands"| node_connection

click node_promise "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/promise.js"
click node_callback "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/callback.js"
click node_pool "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/pool.js"
click node_cluster "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cluster.js"
click node_connection "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/connection.js"
click node_options "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/config/connection-options.js"
click node_auth "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/handshake/authentication.js"
click node_query "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/query.js"
click node_prepare "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/execute.js"
click node_batch "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/batch-bulk.js"
click node_parser "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/parser.js"
click node_sqlparse "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/misc/parse.js"
click node_packetout "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/io/packet-output-stream.js"
click node_packetin "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/io/packet-input-stream.js"
click node_decoder "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/decoder/binary-decoder.js"
click node_encoder "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/encoder/text-encoder.js"
click node_collations "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/collations.js"
click node_errors "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/misc/errors.js"
click node_capabilities "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/capabilities.js"
click node_fieldtypes "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/field-type.js"
click node_serverstatus "https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/server-status.js"

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_promise,node_callback toneBlue
class node_pool,node_cluster,node_connection,node_options,node_server toneAmber
class node_auth,node_query,node_prepare,node_batch,node_parser toneMint
class node_packetout,node_packetin,node_decoder,node_encoder toneRose
class node_sqlparse,node_collations,node_errors,node_capabilities,node_fieldtypes,node_serverstatus,node_app toneIndigo
```

## Components

### Client APIs

- [Promise API](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/promise.js): `promise.js`
- [Callback API](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/callback.js): `callback.js`

### Connection Management

- [Connection pool](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/pool.js): `lib/pool.js`
- [Cluster routing](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cluster.js): `lib/cluster.js`
- [Connection runtime](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/connection.js): `lib/connection.js`
- [Connection options](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/config/connection-options.js): `lib/config/connection-options.js`

### SQL Commands

- [Authentication](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/handshake/authentication.js): `lib/cmd/handshake/authentication.js`
- [Text queries](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/query.js): `lib/cmd/query.js`
- [Prepared statements](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/execute.js): `lib/cmd/execute.js`
- [Bulk batches](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/batch-bulk.js): `lib/cmd/batch-bulk.js`
- [Result parser](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/parser.js): `lib/cmd/parser.js`

### Wire Protocol

- [Packet output](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/io/packet-output-stream.js): `lib/io/packet-output-stream.js`
- [Packet input](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/io/packet-input-stream.js): `lib/io/packet-input-stream.js`
- [Binary decoder](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/decoder/binary-decoder.js): `lib/cmd/decoder/binary-decoder.js`
- [Text encoder](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/cmd/encoder/text-encoder.js): `lib/cmd/encoder/text-encoder.js`

### Protocol Support

- [SQL parsing](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/misc/parse.js): `lib/misc/parse.js`
- [Character collations](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/collations.js): `lib/const/collations.js`
- [SQL errors](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/misc/errors.js): `lib/misc/errors.js`
- [Protocol capabilities](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/capabilities.js): `lib/const/capabilities.js`
- [Field types](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/field-type.js): `lib/const/field-type.js`
- [Server status](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/main/lib/const/server-status.js): `lib/const/server-status.js`

### Other components

- **Node.js application**
- **MariaDB / MySQL**

## Connections

- Node.js application → Promise API: uses
- Node.js application → Callback API: uses
- Promise API → Connection pool: creates pool
- Callback API → Connection pool: wraps pool (evidence: `callback.js`)
- Connection pool → Connection runtime: creates connections (evidence: `lib/pool.js`)
- Node.js application → Connection runtime: queries SQL
- Connection runtime → Connection options: uses options (evidence: `lib/connection.js`)
- Connection runtime → MariaDB / MySQL: connects
- Connection runtime → Authentication: authenticates (evidence: `lib/connection.js`)
- Connection runtime → Text queries: dispatches query (evidence: `lib/connection.js`)
- Connection runtime → Prepared statements: dispatches execute (evidence: `lib/connection.js`)
- Connection runtime → Bulk batches: dispatches batch (evidence: `lib/connection.js`)
- Text queries → SQL parsing: splits SQL (evidence: `lib/cmd/query.js`)
- Text queries → Result parser: extends parser (evidence: `lib/cmd/query.js`)
- Connection runtime → Packet output: writes packets (evidence: `lib/connection.js`)
- Packet output → MariaDB / MySQL: sends commands
- MariaDB / MySQL → Packet input: returns packets
- Connection runtime → Packet input: reads packets (evidence: `lib/connection.js`)
- Result parser → Binary decoder: decodes binary rows (evidence: `lib/cmd/parser.js`)
- Result parser → Field types: uses field types
- Packet output → Text encoder: encodes values (evidence: `lib/io/packet-output-stream.js`)
- Connection options → Character collations: selects collation (evidence: `lib/config/connection-options.js`)
- Authentication → Protocol capabilities: checks capabilities (evidence: `lib/cmd/handshake/authentication.js`)
- Result parser → Server status: reads status (evidence: `lib/cmd/parser.js`)
- Text queries → SQL errors: creates errors (evidence: `lib/cmd/query.js`)
- Cluster routing → Connection pool: routes requests
- Node.js application → Cluster routing: uses cluster
- Node.js application → Connection runtime: streams inserts
- Node.js application → Connection runtime: pipelines commands
