# mariadb-corporation/mariadb-connector-j architecture

> Architecture diagram of the GitHub repository mariadb-corporation/mariadb-connector-j, 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-j
- Repository: https://github.com/mariadb-corporation/mariadb-connector-j

## Overview

MariaDB Connector/J is a JDBC driver that lets Java applications connect to MariaDB and MySQL. The principal path is application JDBC use through driver/configuration and connection/statement APIs, then client execution over the wire and result delivery. The source index supports the main execution, protocol, and result relationships shown here; README documentation establishes the driver’s product role and high-availability capability. Some subsystems are represented from the file tree without sampled implementation details, so their internal links are omitted.

Main entry points: [`src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java`](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java) (Standard client), [`src/main/java/org/mariadb/jdbc/message/ClientMessage.java`](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/message/ClientMessage.java) (Protocol messages), [`src/main/java/org/mariadb/jdbc/Connection.java`](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Connection.java) (JDBC connection), [`src/main/java/org/mariadb/jdbc/Configuration.java`](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Configuration.java) (Connection options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_jdbc["JDBC API"]
  node_driver["JDBC driver<br/>[Driver.java]"]
  node_configuration["Connection options<br/>[Configuration.java]"]
  node_connection_api["JDBC connection<br/>[Connection.java]"]
  node_statement["Statement API<br/>[Statement.java]"]
  node_prepared["Prepared statements"]
  node_metadata["Database metadata"]
end

subgraph group_connection["Connection Management"]
  node_host["Host selection<br/>[HostAddress.java]"]
  node_client_api["Client execution API<br/>[Client.java]"]
  node_standard_client["Standard client"]
  node_ha_clients["HA client modes"]
end

subgraph group_wire["Protocol and Results"]
  node_messages["Protocol messages<br/>[ClientMessage.java]"]
  node_writer["Packet writer<br/>[Writer.java]"]
  node_reader["Packet reader<br/>[Reader.java]"]
  node_buffer["Byte buffer"]
  node_column_decoder["Column decoding<br/>[ColumnDecoder.java]"]
  node_result["Query results<br/>[Result.java]"]
  node_complete_result["Complete results"]
end

subgraph group_extensions["Driver Capabilities"]
  node_pool[("Connection pooling<br/>[Pool.java]")]
  node_auth["Authentication plugins"]
  node_tls["TLS plugins"]
  node_codecs["Type codecs"]
end

node_application(("Java application"))

node_application -->|"uses JDBC"| node_driver
node_driver -.->|"opens connection"| node_connection_api
node_connection_api -->|"creates client"| node_standard_client
node_connection_api -->|"uses options"| node_configuration
node_prepared -->|"uses connection"| node_connection_api
node_prepared -->|"references messages"| node_messages
node_standard_client -->|"implements API"| node_client_api
node_standard_client -->|"reads packets"| node_reader
node_standard_client -->|"writes packets"| node_writer
node_messages -->|"reads response"| node_reader
node_messages -->|"creates results"| node_result
node_messages -->|"creates complete result"| node_complete_result
node_messages -->|"decodes columns"| node_column_decoder
node_column_decoder -->|"decodes bytes"| node_buffer
node_configuration -->|"loads plugins"| node_auth
node_configuration -->|"loads codecs"| node_codecs
node_standard_client -.->|"supports HA modes"| node_ha_clients
node_connection_api -->|"provides metadata"| node_metadata

click node_driver "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Driver.java"
click node_configuration "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Configuration.java"
click node_connection_api "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Connection.java"
click node_statement "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Statement.java"
click node_prepared "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/ClientPreparedStatement.java"
click node_host "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/HostAddress.java"
click node_client_api "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/Client.java"
click node_standard_client "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java"
click node_ha_clients "https://github.com/mariadb-corporation/mariadb-connector-j/tree/main/src/main/java/org/mariadb/jdbc/client/impl"
click node_messages "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/message/ClientMessage.java"
click node_writer "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/socket/Writer.java"
click node_reader "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/socket/Reader.java"
click node_buffer "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/ReadableByteBuf.java"
click node_column_decoder "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/ColumnDecoder.java"
click node_result "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/result/Result.java"
click node_complete_result "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/result/CompleteResult.java"
click node_pool "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/pool/Pool.java"
click node_auth "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/plugin/authentication/AuthenticationPluginLoader.java"
click node_tls "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/plugin/tls/TlsSocketPluginLoader.java"
click node_codecs "https://github.com/mariadb-corporation/mariadb-connector-j/tree/main/src/main/java/org/mariadb/jdbc/plugin/codec"
click node_metadata "https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/DatabaseMetaData.java"

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_driver,node_configuration,node_connection_api,node_statement,node_prepared,node_metadata toneBlue
class node_host,node_client_api,node_standard_client,node_ha_clients toneAmber
class node_messages,node_writer,node_reader,node_buffer,node_column_decoder,node_result,node_complete_result toneMint
class node_pool,node_auth,node_tls,node_codecs toneRose
class node_application toneIndigo
```

## Components

### JDBC API

- [JDBC driver](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Driver.java): `src/main/java/org/mariadb/jdbc/Driver.java`
- [Connection options](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Configuration.java): `src/main/java/org/mariadb/jdbc/Configuration.java`
- [JDBC connection](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Connection.java): `src/main/java/org/mariadb/jdbc/Connection.java`
- [Statement API](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/Statement.java): `src/main/java/org/mariadb/jdbc/Statement.java`
- [Prepared statements](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/ClientPreparedStatement.java): `src/main/java/org/mariadb/jdbc/ClientPreparedStatement.java`
- [Database metadata](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/DatabaseMetaData.java): `src/main/java/org/mariadb/jdbc/DatabaseMetaData.java`

### Connection Management

- [Host selection](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/HostAddress.java): `src/main/java/org/mariadb/jdbc/HostAddress.java`
- [Client execution API](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/Client.java): `src/main/java/org/mariadb/jdbc/client/Client.java`
- [Standard client](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java): `src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java`
- [HA client modes](https://github.com/mariadb-corporation/mariadb-connector-j/tree/main/src/main/java/org/mariadb/jdbc/client/impl): `src/main/java/org/mariadb/jdbc/client/impl`

### Protocol and Results

- [Protocol messages](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/message/ClientMessage.java): `src/main/java/org/mariadb/jdbc/message/ClientMessage.java`
- [Packet writer](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/socket/Writer.java): `src/main/java/org/mariadb/jdbc/client/socket/Writer.java`
- [Packet reader](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/socket/Reader.java): `src/main/java/org/mariadb/jdbc/client/socket/Reader.java`
- [Byte buffer](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/ReadableByteBuf.java): `src/main/java/org/mariadb/jdbc/client/ReadableByteBuf.java`
- [Column decoding](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/ColumnDecoder.java): `src/main/java/org/mariadb/jdbc/client/ColumnDecoder.java`
- [Query results](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/result/Result.java): `src/main/java/org/mariadb/jdbc/client/result/Result.java`
- [Complete results](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/client/result/CompleteResult.java): `src/main/java/org/mariadb/jdbc/client/result/CompleteResult.java`

### Driver Capabilities

- [Connection pooling](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/pool/Pool.java): `src/main/java/org/mariadb/jdbc/pool/Pool.java`
- [Authentication plugins](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/plugin/authentication/AuthenticationPluginLoader.java): `src/main/java/org/mariadb/jdbc/plugin/authentication/AuthenticationPluginLoader.java`
- [TLS plugins](https://github.com/mariadb-corporation/mariadb-connector-j/blob/main/src/main/java/org/mariadb/jdbc/plugin/tls/TlsSocketPluginLoader.java): `src/main/java/org/mariadb/jdbc/plugin/tls/TlsSocketPluginLoader.java`
- [Type codecs](https://github.com/mariadb-corporation/mariadb-connector-j/tree/main/src/main/java/org/mariadb/jdbc/plugin/codec): `src/main/java/org/mariadb/jdbc/plugin/codec`

### Other components

- **Java application**

## Connections

- Java application → JDBC driver: uses JDBC (evidence: `README.md`)
- JDBC driver → JDBC connection: opens connection (evidence: `src/main/java/org/mariadb/jdbc/Driver.java`)
- JDBC connection → Standard client: creates client (evidence: `src/main/java/org/mariadb/jdbc/Connection.java`)
- JDBC connection → Connection options: uses options (evidence: `src/main/java/org/mariadb/jdbc/Connection.java`)
- Prepared statements → JDBC connection: uses connection (evidence: `src/main/java/org/mariadb/jdbc/ClientPreparedStatement.java`)
- Prepared statements → Protocol messages: references messages (evidence: `src/main/java/org/mariadb/jdbc/ClientPreparedStatement.java`)
- Standard client → Client execution API: implements API (evidence: `src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java`)
- Standard client → Packet reader: reads packets (evidence: `src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java`)
- Standard client → Packet writer: writes packets (evidence: `src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java`)
- Protocol messages → Packet reader: reads response (evidence: `src/main/java/org/mariadb/jdbc/message/ClientMessage.java`)
- Protocol messages → Query results: creates results (evidence: `src/main/java/org/mariadb/jdbc/message/ClientMessage.java`)
- Protocol messages → Complete results: creates complete result (evidence: `src/main/java/org/mariadb/jdbc/message/ClientMessage.java`)
- Protocol messages → Column decoding: decodes columns (evidence: `src/main/java/org/mariadb/jdbc/message/ClientMessage.java`)
- Column decoding → Byte buffer: decodes bytes (evidence: `src/main/java/org/mariadb/jdbc/client/ColumnDecoder.java`)
- Connection options → Authentication plugins: loads plugins (evidence: `src/main/java/org/mariadb/jdbc/Configuration.java`)
- Connection options → Type codecs: loads codecs (evidence: `src/main/java/org/mariadb/jdbc/Configuration.java`)
- Standard client → HA client modes: supports HA modes (evidence: `src/main/java/org/mariadb/jdbc/client/impl/StandardClient.java`)
- JDBC connection → Database metadata: provides metadata (evidence: `src/main/java/org/mariadb/jdbc/DatabaseMetaData.java`)
