ProxySQL Documentation Index

⚠️ 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

Table of Contents

1. Root Documentation
2. Architecture Documentation
3. Internal Documentation
4. ProxySQL Cluster Documentation
5. Release Notes
6. Additional Resources

Root Documentation

Core Documentation Files

• README.md (11.8 KB) - Main project overview, features, and quick start guide
• INSTALL.md (4.0 KB) - Detailed installation instructions for various platforms
• FAQ.md (8.3 KB) - Frequently asked questions and troubleshooting
• RUNNING.md (3.5 KB) - Runtime configuration and operational guidance
• CHANGELOG.md - Version history and change tracking
• CLAUDE.md (5.4 KB) - Claude Code integration and agent usage guide

Configuration Examples

• proxysql-tests.ini.example - Test configuration template
• docker-compose.yml (9.2 KB) - Docker orchestration configuration

Architecture Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/architecture/

Architecture Guides

• ARCHITECTURE-OVERVIEW.md - Architectural analysis

  • Threading model and concurrency patterns
  • Protocol implementation details (MySQL/PostgreSQL)
  • Memory management strategies
  • Connection pooling architecture
  • Query processing pipeline

• PROJECT-LAYOUT.md - Physical codebase organization

  • Directory structure mapping
  • Module boundaries and dependencies
  • Build system overview
  • Testing infrastructure layout

• VISUAL-GUIDE.md - Visual architecture representations

  • System diagrams and flowcharts
  • Class hierarchy diagrams
  • ERD for SQLite3 schema
  • Protocol sequence diagrams
  • Deployment topology patterns

Internal Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/internal/

MySQL Protocol Implementation

• MySQL_Connection.md (8.9 KB) - MySQL connection handling internals
• MySQL_Data_Stream.md (8.5 KB) - MySQL data stream processing
• MySQL_HostGroups_Manager.md (30.1 KB) - Hostgroup management
• MySQL_Prepared_Statements.md (11.6 KB) - Prepared statement implementation
• MySQL_Query_Cache.md (5.9 KB) - Query caching mechanisms
• MySQL_Query_Rules_Evaluation.md (10.6 KB) - Rule processing logic
• MySQL_Query_Rules_Fast_Routing.md (6.8 KB) - Fast routing optimization
• MySQL_Session.md (10.5 KB) - Session lifecycle management
• MySQL_Thread.md (12.5 KB) - MySQL thread pool architecture

PostgreSQL Protocol Implementation

• PgSQL_Connection.md (7.8 KB) - PostgreSQL connection handling
• PgSQL_Data_Stream.md (6.2 KB) - PostgreSQL data stream processing
• PgSQL_HostGroups_Manager.md (18.4 KB) - PostgreSQL hostgroup management
• PgSQL_Protocol.md (14.3 KB) - PostgreSQL wire protocol details
• PgSQL_Session.md (8.7 KB) - PostgreSQL session management
• PgSQL_Thread.md (9.1 KB) - PostgreSQL thread implementation

Core Infrastructure

• ProxySQL_Admin.md (22.7 KB) - Admin interface implementation
• ProxySQL_Admin_Interface.md (15.3 KB) - Admin API specification
• ProxySQL_Configuration.md (12.8 KB) - Configuration system details
• ProxySQL_Global.md (9.4 KB) - Global state management
• ProxySQL_Statistics.md (11.2 KB) - Statistics collection framework

Connection Pooling & Management

• Connection_Pool.md (13.6 KB) - Connection pool architecture
• Connection_Multiplexing.md (8.9 KB) - Multiplexing strategies
• Connection_Errors_Handling.md (7.4 KB) - Error recovery mechanisms

Query Processing

• Query_Processor.md (16.5 KB) - Query processing pipeline
• Query_Cache_Implementation.md (10.3 KB) - Cache implementation details
• Query_Routing_Logic.md (12.1 KB) - Routing decision algorithms

Monitoring & Health Checks

• Monitor_Module.md (14.8 KB) - Monitoring framework
• Health_Check_Implementation.md (9.6 KB) - Health check mechanisms
• Replication_Lag_Detection.md (7.8 KB) - Lag detection algorithms

Memory Management

• Memory_Management.md (11.4 KB) - Memory allocation strategies
• jemalloc_Integration.md (6.7 KB) - jemalloc usage patterns

Threading & Concurrency

• Threading_Model.md (13.9 KB) - Thread architecture
• Lock_Hierarchy.md (8.2 KB) - Locking strategies
• Event_Loop_Integration.md (7.5 KB) - libev integration

ProxySQL Cluster Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/proxysql_cluster/

Cluster Configuration & Management

• ProxySQL_Cluster_Architecture.md (18.7 KB) - Cluster design principles
• Cluster_Configuration_Guide.md (14.3 KB) - Step-by-step cluster setup
• Cluster_Synchronization.md (11.8 KB) - Config sync mechanisms
• Cluster_Monitoring.md (9.4 KB) - Cluster health monitoring
• Cluster_Failover_Strategies.md (12.6 KB) - HA and failover patterns

Cluster Tables & API

• proxysql_servers_table.md (7.2 KB) - Cluster member configuration
• runtime_checksums.md (8.5 KB) - Configuration checksums
• cluster_mysql_query_rules.md (6.9 KB) - Query rule synchronization
• cluster_mysql_servers.md (7.8 KB) - Server config sync
• cluster_mysql_users.md (6.4 KB) - User sync across cluster

Release Notes

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/release_notes/

Version History

• ProxySQL_v3.0.0.md - Latest major release notes
• ProxySQL_v2.7.x.md - Current stable branch notes
• ProxySQL_v2.6.x.md - Previous stable release
• ProxySQL_v2.5.x.md - Historical release notes
• Migration_Guides/ - Version migration guides
  • v2_to_v3_migration.md
  • v1_to_v2_migration.md

Feature Documentation

• New_Features_v3.0.md - v3.0 feature descriptions
• Breaking_Changes.md - API/config breaking changes
• Deprecation_Notices.md - Deprecated features

Additional Resources

Testing Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/test/

• test/README.md - Test framework overview
• test/tap/README.md - TAP test documentation
• test/cluster/README.md - Cluster testing guide

Docker Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/docker/

• docker/README.md - Docker deployment guide
• docker/scenarios/README.md - Test scenario documentation

Dependency Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/deps/

Notable dependency docs:

• deps/mariadb-client-library/README.md - MariaDB connector
• deps/postgresql/README.md - PostgreSQL client library
• deps/prometheus-cpp/README.md - Metrics integration
• deps/libev/README - Event loop documentation

Script Documentation

Location: https://github.com/sysown/proxysql/tree/v3.0.agentics/scripts/

• scripts/README.md - Utility scripts overview
• scripts/admin/README.md - Admin automation scripts

Documentation Categories Summary

By Purpose

1. Installation & Setup: INSTALL.md, docker/README.md
2. Configuration: RUNNING.md, ProxySQL_Configuration.md, examples
3. Architecture: architecture/.md, internal/.md
4. Operations: FAQ.md, Monitor_Module.md, Statistics
5. Development: CLAUDE.md, test/README.md, internal docs
6. Clustering: proxysql_cluster/*.md
7. Migration: release_notes/Migration_Guides/

By Audience

• Users/Operators: README, INSTALL, RUNNING, FAQ
• Administrators: Admin docs, Cluster docs, Monitor docs
• Developers: Internal docs, Architecture guides, CLAUDE.md
• DevOps: Docker docs, Scripts, Deployment patterns

By Protocol

• MySQL-specific: MySQL_*.md files (15+ documents)
• PostgreSQL-specific: PgSQL_*.md files (10+ documents)
• Protocol-agnostic: Base_.md, ProxySQL_.md files

Key Documentation Insights

Largest Documents

1. MySQL_HostGroups_Manager.md (30.1 KB) - Hostgroup management
2. ProxySQL_Admin.md (22.7 KB) - Admin interface guide
3. ProxySQL_Cluster_Architecture.md (18.7 KB) - Cluster design
4. Query_Processor.md (16.5 KB) - Query processing
5. ProxySQL_Admin_Interface.md (15.3 KB) - Admin API reference

Implementation Topics

• Connection pooling strategies and optimizations
• Query routing algorithms and rule evaluation
• Memory management with jemalloc
• Thread synchronization and lock hierarchy
• Protocol-specific handling (MySQL vs PostgreSQL)
• Cluster synchronization mechanisms
• Statistics collection and monitoring

Documentation Gaps Identified

• Limited SSL/TLS configuration examples
• Sparse Kubernetes deployment guides
• Missing performance tuning cookbook
• Incomplete troubleshooting scenarios
• Limited integration examples with monitoring systems

Quick Reference Paths

# Main documentation
https://github.com/sysown/proxysql/tree/v3.0.agentics/README.md
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/

# Architecture docs
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/architecture/

# Internal implementation
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/internal/

# Cluster documentation
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/proxysql_cluster/

# Release information
https://github.com/sysown/proxysql/tree/v3.0.agentics/doc/release_notes/

# Test documentation
https://github.com/sysown/proxysql/tree/v3.0.agentics/test/tap/tests/README.md

# Docker guides
https://github.com/sysown/proxysql/tree/v3.0.agentics/docker/README.md

Based on ProxySQL v3.0 branch Documentation Files: 300+ Documentation Size: ~2.5 MB