# percona/percona-server architecture

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

- Interactive diagram: https://gitdiagram.com/percona/percona-server
- Repository: https://github.com/percona/percona-server

## Overview

Percona Server for MySQL is a MySQL-compatible database server with client utilities and additional observability, security, and component capabilities. A typical user submits SQL through a client; the server processes it and exposes operational data through Performance Schema. The supplied tree and excerpts cover selected clients and subsystems rather than the server’s full query/storage path, so that central path is intentionally not expanded. The graph also captures documented audit, keyring, and query-event capabilities; several subsystem links are omitted where wiring was not shown.

Main entry points: [`components/keyrings/common/component_helpers/include/keyring_metadata_query_service_impl_template.h`](https://github.com/percona/percona-server/blob/8.4/components/keyrings/common/component_helpers/include/keyring_metadata_query_service_impl_template.h) (Keyring services), [`components/audit_log_filter/audit_log_filter.cc`](https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/audit_log_filter.cc) (Audit filter), [`client/mysql.cc`](https://github.com/percona/percona-server/blob/8.4/client/mysql.cc) (SQL client), [`client/mysqladmin.cc`](https://github.com/percona/percona-server/blob/8.4/client/mysqladmin.cc) (Admin utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client tools"]
  node_mysqlcli["SQL client<br/>[mysql.cc]"]
  node_admincli["Admin utilities<br/>[mysqladmin.cc]"]
  node_dumpcli["Data utilities<br/>[mysqldump.cc]"]
  node_binlogcli["Binlog utility<br/>[mysqlbinlog.cc]"]
end

subgraph group_observability["Observability"]
  node_pfs["Performance Schema"]
  node_audit["Audit filter"]
  node_audit_rules["Audit rules"]
  node_audit_output["Audit writers<br/>[log_writer.cc]"]
  node_query_events["Query event service"]
end

subgraph group_security["Security components"]
  node_keyring_common["Keyring services"]
  node_file_keyring["File keyring<br/>[keyring_file.cc]"]
  node_encrypted_keyring["Encrypted file keyring"]
  node_kms_keyring["KMS keyring<br/>[keyring_kms.cc]"]
  node_kmip_keyring["KMIP keyring<br/>[keyring_kmip.cc]"]
  node_vault_keyring["Vault keyring<br/>[keyring_vault.cc]"]
end

subgraph group_extensions["Server extensions"]
  node_masking["Data masking<br/>[component.cpp]"]
  node_js_component["JavaScript component<br/>[component.cc]"]
  node_binlog_udf["Binlog UDFs"]
  node_encryption_udf["Encryption UDFs"]
end

subgraph group_runtime["Server runtime"]
  node_server["MySQL server"]
  node_transaction_service["Transaction query service"]
end

node_application(("Application client"))

node_application -->|"submits SQL"| node_mysqlcli
node_mysqlcli -->|"sends queries"| node_server
node_application -.->|"requests administration"| node_admincli
node_admincli -.->|"administers"| node_server
node_application -.->|"requests data transfer"| node_dumpcli
node_dumpcli -.->|"queries data"| node_server
node_application -.->|"requests binlog processing"| node_binlogcli
node_binlogcli -.->|"reads binlogs"| node_server
node_server -->|"queries transactions"| node_transaction_service
node_server -->|"exposes monitoring tables"| node_pfs
node_server -.->|"emits audit events"| node_audit
node_audit -->|"evaluates rules"| node_audit_rules
node_audit -->|"writes records"| node_audit_output
node_server -.->|"broadcasts query events"| node_query_events
node_keyring_common -->|"provides services"| node_file_keyring
node_keyring_common -->|"provides services"| node_encrypted_keyring
node_keyring_common -->|"provides services"| node_kms_keyring
node_keyring_common -->|"provides services"| node_kmip_keyring
node_keyring_common -->|"provides services"| node_vault_keyring
node_server -.->|"invokes functions"| node_masking
node_server -.->|"invokes component"| node_js_component
node_server -.->|"invokes functions"| node_binlog_udf
node_server -.->|"invokes functions"| node_encryption_udf

click node_mysqlcli "https://github.com/percona/percona-server/blob/8.4/client/mysql.cc"
click node_admincli "https://github.com/percona/percona-server/blob/8.4/client/mysqladmin.cc"
click node_dumpcli "https://github.com/percona/percona-server/blob/8.4/client/mysqldump.cc"
click node_binlogcli "https://github.com/percona/percona-server/blob/8.4/client/mysqlbinlog.cc"
click node_transaction_service "https://github.com/percona/percona-server/blob/8.4/sql/server_component/ongoing_transaction_query_service.cc"
click node_pfs "https://github.com/percona/percona-server/blob/8.4/storage/perfschema/pfs_engine_table.cc"
click node_audit "https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/audit_log_filter.cc"
click node_audit_rules "https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/audit_rule_parser.cc"
click node_audit_output "https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/log_writer.cc"
click node_query_events "https://github.com/percona/percona-server/blob/8.4/include/mysql/components/services/event_tracking_query_service.h"
click node_keyring_common "https://github.com/percona/percona-server/blob/8.4/components/keyrings/common/component_helpers/include/keyring_metadata_query_service_impl_template.h"
click node_file_keyring "https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_file/keyring_file.cc"
click node_encrypted_keyring "https://github.com/percona/percona-server/blob/8.4/components/keyrings/percona_keyring_encrypted_file/percona_keyring_encrypted_file.cc"
click node_kms_keyring "https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_kms/keyring_kms.cc"
click node_kmip_keyring "https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_kmip/keyring_kmip.cc"
click node_vault_keyring "https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_vault/keyring_vault.cc"
click node_masking "https://github.com/percona/percona-server/blob/8.4/components/masking_functions/src/component.cpp"
click node_js_component "https://github.com/percona/percona-server/blob/8.4/components/js_lang/component.cc"
click node_binlog_udf "https://github.com/percona/percona-server/blob/8.4/components/binlog_utils_udf/binlog_utils_udf.cc"
click node_encryption_udf "https://github.com/percona/percona-server/blob/8.4/components/encryption_udf/encryption_udf_component.cc"

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_mysqlcli,node_admincli,node_dumpcli,node_binlogcli,node_application toneBlue
class node_pfs,node_audit,node_audit_rules,node_audit_output,node_query_events toneAmber
class node_keyring_common,node_file_keyring,node_encrypted_keyring,node_kms_keyring,node_kmip_keyring,node_vault_keyring toneMint
class node_masking,node_js_component,node_binlog_udf,node_encryption_udf toneRose
class node_server,node_transaction_service toneIndigo
```

## Components

### Client tools

- [SQL client](https://github.com/percona/percona-server/blob/8.4/client/mysql.cc): `client/mysql.cc`
- [Admin utilities](https://github.com/percona/percona-server/blob/8.4/client/mysqladmin.cc): `client/mysqladmin.cc`
- [Data utilities](https://github.com/percona/percona-server/blob/8.4/client/mysqldump.cc): `client/mysqldump.cc`
- [Binlog utility](https://github.com/percona/percona-server/blob/8.4/client/mysqlbinlog.cc): `client/mysqlbinlog.cc`

### Observability

- [Performance Schema](https://github.com/percona/percona-server/blob/8.4/storage/perfschema/pfs_engine_table.cc): `storage/perfschema/pfs_engine_table.cc`
- [Audit filter](https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/audit_log_filter.cc): `components/audit_log_filter/audit_log_filter.cc`
- [Audit rules](https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/audit_rule_parser.cc): `components/audit_log_filter/audit_rule_parser.cc`
- [Audit writers](https://github.com/percona/percona-server/blob/8.4/components/audit_log_filter/log_writer.cc): `components/audit_log_filter/log_writer.cc`
- [Query event service](https://github.com/percona/percona-server/blob/8.4/include/mysql/components/services/event_tracking_query_service.h): `include/mysql/components/services/event_tracking_query_service.h`

### Security components

- [Keyring services](https://github.com/percona/percona-server/blob/8.4/components/keyrings/common/component_helpers/include/keyring_metadata_query_service_impl_template.h): `components/keyrings/common/component_helpers/include/keyring_metadata_query_service_impl_template.h`
- [File keyring](https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_file/keyring_file.cc): `components/keyrings/keyring_file/keyring_file.cc`
- [Encrypted file keyring](https://github.com/percona/percona-server/blob/8.4/components/keyrings/percona_keyring_encrypted_file/percona_keyring_encrypted_file.cc): `components/keyrings/percona_keyring_encrypted_file/percona_keyring_encrypted_file.cc`
- [KMS keyring](https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_kms/keyring_kms.cc): `components/keyrings/keyring_kms/keyring_kms.cc`
- [KMIP keyring](https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_kmip/keyring_kmip.cc): `components/keyrings/keyring_kmip/keyring_kmip.cc`
- [Vault keyring](https://github.com/percona/percona-server/blob/8.4/components/keyrings/keyring_vault/keyring_vault.cc): `components/keyrings/keyring_vault/keyring_vault.cc`

### Server extensions

- [Data masking](https://github.com/percona/percona-server/blob/8.4/components/masking_functions/src/component.cpp): `components/masking_functions/src/component.cpp`
- [JavaScript component](https://github.com/percona/percona-server/blob/8.4/components/js_lang/component.cc): `components/js_lang/component.cc`
- [Binlog UDFs](https://github.com/percona/percona-server/blob/8.4/components/binlog_utils_udf/binlog_utils_udf.cc): `components/binlog_utils_udf/binlog_utils_udf.cc`
- [Encryption UDFs](https://github.com/percona/percona-server/blob/8.4/components/encryption_udf/encryption_udf_component.cc): `components/encryption_udf/encryption_udf_component.cc`

### Server runtime

- **MySQL server**
- [Transaction query service](https://github.com/percona/percona-server/blob/8.4/sql/server_component/ongoing_transaction_query_service.cc): `sql/server_component/ongoing_transaction_query_service.cc`

### Other components

- **Application client**

## Connections

- Application client → SQL client: submits SQL
- SQL client → MySQL server: sends queries
- Application client → Admin utilities: requests administration
- Admin utilities → MySQL server: administers
- Application client → Data utilities: requests data transfer
- Data utilities → MySQL server: queries data
- Application client → Binlog utility: requests binlog processing
- Binlog utility → MySQL server: reads binlogs
- MySQL server → Transaction query service: queries transactions
- MySQL server → Performance Schema: exposes monitoring tables
- MySQL server → Audit filter: emits audit events
- Audit filter → Audit rules: evaluates rules
- Audit filter → Audit writers: writes records
- MySQL server → Query event service: broadcasts query events
- Keyring services → File keyring: provides services
- Keyring services → Encrypted file keyring: provides services
- Keyring services → KMS keyring: provides services
- Keyring services → KMIP keyring: provides services
- Keyring services → Vault keyring: provides services
- MySQL server → Data masking: invokes functions
- MySQL server → JavaScript component: invokes component
- MySQL server → Binlog UDFs: invokes functions
- MySQL server → Encryption UDFs: invokes functions