# 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](#root-documentation)
2. [Architecture Documentation](#architecture-documentation)
3. [Internal Documentation](#internal-documentation)
4. [ProxySQL Cluster Documentation](#proxysql-cluster-documentation)
5. [Release Notes](#release-notes)
6. [Additional Resources](#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

```bash
# 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*