doc/ai-generated/architecture/ARCHITECTURE-OVERVIEW.md
⚠️ Important Notice: This documentation was generated by AI and may contain inaccuracies. It should be used as a starting point for exploration only. Always verify critical information against the actual source code.
Last AI Update: 2025-09-11 Status: NON-VERIFIED Maintainer: Rene Cannao
ProxySQL is a MySQL and PostgreSQL protocol-aware proxy server written in C++11/17. It implements a multi-threaded architecture with connection pooling, query routing, caching, and monitoring.
Multi-Threaded Worker Model
MySQL_Thread) handle client connectionsPgSQL_Thread) for PostgreSQL supportIDLE_THREADS enabled)Event-Driven I/O
libev for event loop managementConnection Pooling & Multiplexing
Protocol Implementation
MySQL_Protocol)PgSQL_Protocol)https://github.com/sysown/proxysql/tree/v3.0.agentics/src/main.cppproxysql.cfgtemplate<typename T>
class ConsumerThread : public Thread {
wqueue<WorkItem<T>*>& m_queue;
}
__thread variables for per-thread configurationMySQL_Thread)https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/MySQL_Thread.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/MySQL_Thread.hPgSQL_Thread)https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/PgSQL_Thread.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/PgSQL_Thread.hMySQL_Session)https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/MySQL_Session.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/MySQL_Session.hPgSQL_Session)https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/PgSQL_Session.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/PgSQL_Session.hhttps://github.com/sysown/proxysql/tree/v3.0.agentics/lib/MySQL_HostGroups_Manager.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/MySQL_HostGroups_Manager.hread_only_action() to read_only_action_v2()read_only=0: Server promoted to writer hostgroupread_only=1: Server moved to reader hostgroupwriter_is_also_reader: Controls writer presence in reader hostgroupsONLINE → SHUNNED (temporary failures) → OFFLINE_SOFT → OFFLINE_HARD
https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/MySQL_Query_Processor.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/MySQL_Query_Processor.h??,?,?,? → ?,?,?,... when exceeding limitmysql-query_digests_replace_nullc_tokenizer.cpp using SpookyV2 hashinghttps://github.com/sysown/proxysql/tree/v3.0.agentics/lib/sqlite3db.cppProxySQL_Admin)https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/ProxySQL_Admin.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/proxysql_admin.hhttps://github.com/sysown/proxysql/tree/v3.0.agentics/src/SQLite3_Server.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/include/SQLite3_Server.hMySQL_Monitor, PgSQL_Monitor)wsrep_local_state (must be 4=SYNCED or 2=DONOR with conditions)wsrep_cluster_status (Primary/Non-Primary detection)wsrep_desync, wsrep_reject_queries, pxc_maint_modeweight DESC, hostname DESC, port DESCwsrep_sst_donor_rejects_queriesmysql-monitor_galera_healthcheck_interval: 1000ms defaultmysql-monitor_galera_healthcheck_max_timeout_count: 3 consecutive failuresperformance_schema.replication_group_membershttps://github.com/sysown/proxysql/tree/v3.0.agentics/lib/MySQL_Query_Cache.cpp, https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/PgSQL_Query_Cache.cppProxySQL_Cluster)https://github.com/sysown/proxysql/tree/v3.0.agentics/lib/ProxySQL_Cluster.cpphttps://github.com/sysown/proxysql/tree/v3.0.agentics/lib/ProxySQL_Statistics.cpphttps://github.com/sysown/proxysql/tree/v3.0.agentics/src/proxysql.cfgadmin_variables: Admin interface settingsmysql_variables: MySQL protocol settingspgsql_variables: PostgreSQL settingsmysql_servers: Backend server definitionsmysql_users: User authenticationmysql_query_rules: Query routing ruleshttps://github.com/sysown/proxysql/tree/v3.0.agentics/test/tap/Multi-Tier Pool Management:
Pool Algorithms:
// Connection retrieval with multiple criteria
MySQL_Connection* get_MyConn_from_pool(
uint32_t wait_until_ms, // Timeout control
bool ff_flag, // Fast forward flag
char* gtid_uuid, // GTID consistency
uint64_t gtid_trxid, // Transaction ID
int max_lag_ms // Max replication lag
)
Query Processing:
regex_engine1/2Memory Management:
Lock-Free Structures:
spiffe:// SAN URIsPROXYSQL RELOAD TLS without downtime (v2.3.0+)GloMyAuthcaching_sha2_password fast authenticationstruct QP_query_digest_stats {
uint64_t digest;
time_t first_seen, last_seen;
unsigned long long sum_time, min_time, max_time;
unsigned long long rows_affected, rows_sent;
}
next_query_flagIN enables sequential processingServer State Management:
enum MySerStatus {
MYSQL_SERVER_STATUS_ONLINE = 0,
MYSQL_SERVER_STATUS_SHUNNED = 1,
MYSQL_SERVER_STATUS_OFFLINE_SOFT = 2,
MYSQL_SERVER_STATUS_OFFLINE_HARD = 3,
MYSQL_SERVER_STATUS_SHUNNED_REPLICATION_LAG = 4
}
Automatic Server Management:
Health Monitoring:
IF (node_version > 1 AND
(own_version == 1 OR node_epoch > own_epoch))
AND diff_check >= cluster_module_diffs_before_sync
THEN sync_from_peer
Architecture supports: