If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sysown/proxysql shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 1d ago
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sysown/proxysql repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sysown/proxysql.

What it runs against: a local clone of sysown/proxysql — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sysown/proxysql | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch v3.0 exists | Catches branch renames | | 4 | 4 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sysown/proxysql. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sysown/proxysql.git
#   cd proxysql
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sysown/proxysql and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sysown/proxysql(\\.git)?\\b" \\
  && ok "origin remote is sysown/proxysql" \\
  || miss "origin remote is not sysown/proxysql (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify v3.0 >/dev/null 2>&1 \\
  && ok "default branch v3.0 exists" \\
  || miss "default branch v3.0 no longer exists"

# 4. Critical files exist
test -f ".github/workflows/CI-basictests.yml" \\
  && ok ".github/workflows/CI-basictests.yml" \\
  || miss "missing critical file: .github/workflows/CI-basictests.yml"
test -f ".github/CLA.md" \\
  && ok ".github/CLA.md" \\
  || miss "missing critical file: .github/CLA.md"
test -f ".clang-tidy" \\
  && ok ".clang-tidy" \\
  || miss "missing critical file: .clang-tidy"
test -f ".aider.conf.yml" \\
  && ok ".aider.conf.yml" \\
  || miss "missing critical file: .aider.conf.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sysown/proxysql"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ProxySQL is a high-performance, protocol-aware proxy for MySQL, MariaDB, Percona Server, and PostgreSQL written in C++ that sits between applications and databases to provide connection pooling, query routing, load balancing, and caching without requiring application changes. It solves the problem of database bottlenecks and connection exhaustion in high-traffic environments by intelligently multiplexing thousands of client connections onto a smaller pool of backend database connections. Monolithic C++ application with modular subsystems: core proxy engine handles connection pooling and protocol parsing, admin interface (port 6032) manages configuration via SQLite-backed .db files, multiple backend drivers for MySQL and PostgreSQL support, query caching layer, and statistics/monitoring. Configuration can be specified via config files (proxysql.cnf) or dynamically via admin SQL interface. Build system uses Makefiles and supports Docker containerization.

DevOps engineers, database administrators, and backend architects who manage large-scale MySQL/PostgreSQL deployments and need to handle connection pooling, query caching, read-write splitting, and intelligent routing without rewriting application code. Organizations running high-traffic web services, microservices architectures, or cloud-native deployments where database performance and availability are critical.

Production-ready and actively maintained. The project has extensive CI/CD pipelines (40+ GitHub Actions workflows testing against MySQL 5.6, 8.4, MariaDB 10 Galera, PostgreSQL, and third-party frameworks), comprehensive test coverage across multiple database versions and frameworks (aiomysql, Django, Laravel, PHP PDO, etc.), and regular development activity. The codebase is 15.2MB of C++ indicating substantial maturity and feature richness.

Standard open source risks apply.

Active development across multiple dimensions: continuous expansion of third-party framework compatibility testing (latest additions visible in CI workflows for aiomysql, Django, Laravel, PHP PDO), macOS build support added (CI-build-macos workflows for both Intel and ARM), and likely ongoing protocol improvements for PostgreSQL support. The 40+ CI/workflow files suggest rapid iteration on compatibility and stability across database versions.

git clone https://github.com/sysown/proxysql.git
cd proxysql
make
# or for containerized: docker pull proxysql/proxysql

ProxySQL requires a C++ build environment (g++/clang), standard Linux development headers, and for testing: MySQL/PostgreSQL client libraries. Review the Dockerfile in the repo for exact dependencies, or use pre-built packages from official repositories (Ubuntu/Debian: apt-get, CentOS/RHEL: yum, etc.).

Daily commands:

# Build from source
make -j$(nproc)
# or build with specific options
make -f Makefile OPTIONS="..."

# Run the proxy
./proxysql -c /etc/proxysql.cnf
# or with systemd (if installed from packages)
sudo systemctl start proxysql

# Access admin interface on port 6032
mysql -h 127.0.0.1 -P 6032 -u admin -padmin

Proxy listens on port 3306 by default for MySQL/PostgreSQL clients, port 6032 for admin connections.

• .github/workflows/CI-basictests.yml — Defines the core CI pipeline for basic functionality tests that validate proxy behavior across multiple database backends
• .github/CLA.md — Contributor License Agreement that all contributors must review and accept before submitting pull requests
• .clang-tidy — Code quality configuration that enforces static analysis standards across the C++ codebase
• .aider.conf.yml — Project configuration that defines coding conventions and tool settings for development consistency

• Listener (Client-facing) (C++ sockets, nonblocking I/O) — TCP listener accepting client connections, performing MySQL/PostgreSQL handshake, buffering queries before routing
  • Failure mode: Listener crashes → all new client connections rejected; existing connections severed
• Connection Manager (C++ thread pool, connection pooling algorithms) — Maintains pool of backend connections, manages client session state, enforces connection limits
  • Failure mode: Manager exhaustion → new clients queued indefinitely, potential timeout/rejection
• Query Router (SQL parser, rule engine) — Parses SQL, applies routing rules (sharding, read/write, user-based), selects backend
  • Failure mode: Routing misconfiguration → queries sent to wrong backend, silent data

Add support for a new database backend

1. Create a new CI workflow file in .github/workflows/ for the target database version (.github/workflows/CI-<database>-<version>-g1.yml)
2. Follow the pattern of existing database test workflows like CI-mysql84-g1.yml, specifying database Docker image and test groups (.github/workflows/CI-mysql84-g1.yml)
3. Add a packaging workflow if distribution-specific binaries are needed (.github/workflows/CI-package-amd64-<distro>-<version>.yml)
4. Reference the new workflows in CI-builds.yml to integrate into main pipeline (.github/workflows/CI-builds.yml)

Add a new third-party framework compatibility test

1. Create a new workflow file following the naming pattern for third-party integrations (.github/workflows/CI-3p-<framework-name>.yml)
2. Model the workflow after similar integrations like CI-3p-sqlalchemy.yml or CI-3p-php-pdo-mysql.yml (.github/workflows/CI-3p-sqlalchemy.yml)
3. Define Docker setup for the framework, ProxySQL instance, and test database backend (.github/workflows/CI-3p-<framework-name>.yml)
4. Include test execution step that validates core proxy functionality with that framework (.github/workflows/CI-3p-<framework-name>.yml)

Enforce new code quality standards

1. Update .clang-tidy to add new linting rules or modify severity levels (.clang-tidy)
2. Enable the CodeQL workflow in CI pipeline to scan for security issues (.github/workflows/CI-codeql.yml)
3. Document new conventions in .aider.conf.yml for automated code generation consistency (.aider.conf.yml)

• C/C++ — High-performance low-latency proxy requires compiled language for connection pooling and query routing at scale
• GitHub Actions — Multi-platform CI/CD automation across 50+ workflow files validates compatibility with diverse MySQL/PostgreSQL versions and Linux distributions
• Docker containers — Isolated test environments for database backends (MySQL 5.6/8.4, MariaDB, PostgreSQL) enabling deterministic testing without infrastructure dependencies
• clang-tidy + CodeQL — Static analysis and security scanning catch memory safety issues and vulnerabilities critical for production proxy software

• Maintains separate test workflows for each database version/cluster topology combination (50+ workflows)

  • Why: Ensures compatibility assertions across wide range of backend configurations but creates maintenance burden
  • Consequence: Each new database version requires new workflow file creation; catch regressions early but increased CI runtime

• Includes third-party framework compatibility testing (Django, Laravel, SQLAlchemy, PHP PDO, etc.)

  • Why: Validates real-world driver integration but requires maintaining test harnesses for each framework
  • Consequence: High confidence in compatibility but CI pipeline complexity grows with each new integration

• Separate packaging workflows per Linux distribution (AlmaLinux, CentOS, Debian, etc.)

  • Why: Ensures binaries are optimized and compatible with each distro's standard library versions
  • Consequence: Cross-platform support increases build time but guarantees package integrity per distribution

• Not a standalone database—acts exclusively as a proxy/middleware between clients and existing MySQL/PostgreSQL backends
• Does not handle authentication/authorization directly—enforces backend credentials management
• Not a real-time data warehouse—optimized for transactional OLTP workloads, not analytical queries
• Does not support NoSQL or non-relational databases—MySQL and PostgreSQL only
• Not Windows-native—targets Linux distributions; macOS support is secondary

1. Configuration is two-phase: changes made via admin interface (port 6032) are volatile until SAVE CONFIG TO DISK — if you only modify /etc/proxysql.cnf and restart, changes are lost if .db file exists. 2) Default admin credentials (admin/admin) must be changed in production; the admin interface listens on 127.0.0.1 by default but this is configurable. 3) Connection pooling requires understanding connection state machines — idle vs. active vs. metadata connections have different behavior. 4) SQLite database file (proxysql.db) must have proper permissions and disk space; it grows as statistics accumulate. 5) Reloading config via LOAD CONFIG FROM DISK does NOT automatically reconnect backends — requires explicit RESET or restart. 6) Multiple protocol support (MySQL + PostgreSQL) means understanding both wire protocols and their differences for debugging.

• MySQL Wire Protocol — ProxySQL must parse and emulate the MySQL client-server protocol to intercept, route, and cache queries; understanding packet structure, handshake, and command types is essential for debugging connection issues
• Connection Pooling — Core feature of ProxySQL — multiplexing many client connections onto fewer backend connections; you must understand idle timeout, max connections, priority queuing to tune performance
• Query Caching (TTL-based) — ProxySQL caches SELECT query results with configurable time-to-live; understanding invalidation, consistency, and match rules is critical for correctness and performance
• Reactor Pattern (Event-Driven I/O) — ProxySQL uses event-driven networking (epoll/libevent) rather than blocking I/O to handle thousands of concurrent connections efficiently; essential for understanding scalability and debugging I/O hangs
• Read-Write Splitting / Sharding — ProxySQL routes queries to different backend hostgroups based on rules (read vs. write, or by hash); you must understand hostgroup configuration and rule matching logic
• SQLite as Configuration Store — ProxySQL persists admin configuration and statistics in an embedded SQLite database (.db file); understanding schema, transactions, and recovery is needed for config management and troubleshooting
• PostgreSQL Wire Protocol — ProxySQL now supports PostgreSQL natively; the protocol differs significantly from MySQL (message-framing, authentication, type system) so understanding both is necessary for full-stack debugging

• vitessio/vitess — Middleware proxy solution for MySQL at scale; Vitess provides advanced sharding and topology management where ProxySQL handles connection pooling and routing
• maxmind/MaxScale — MariaDB's database proxy with similar query routing and load balancing capabilities; direct competitor in the MySQL proxy space
• mysql/mysql-server — Upstream MySQL database server that ProxySQL proxies to; understanding MySQL internals and protocol is essential for contributing
• postgres/postgres — PostgreSQL database server; ProxySQL now supports PostgreSQL so understanding its wire protocol and internals is valuable
• prometheus/prometheus — Monitoring system; ProxySQL emits metrics that can be scraped by Prometheus for observability in production deployments

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow for PostgreSQL third-party compatibility testing

The repo has extensive third-party CI workflows for MySQL drivers (aiomysql, django, laravel, php-pdo-mysql, sqlalchemy, etc.) but is missing PostgreSQL-specific third-party framework tests. Given that ProxySQL supports PostgreSQL proxying, there should be CI workflows for popular PostgreSQL client libraries like psycopg2, asyncpg, and sqlalchemy with PostgreSQL dialect to ensure compatibility.

• [ ] Create .github/workflows/CI-3p-psycopg2.yml following the pattern of existing CI-3p-*.yml files
• [ ] Create .github/workflows/CI-3p-asyncpg.yml for async PostgreSQL driver testing
• [ ] Create .github/workflows/CI-3p-sqlalchemy-postgresql.yml to test SQLAlchemy with PostgreSQL dialect (separate from MySQL variant in CI-3p-sqlalchemy.yml)
• [ ] Reference CI-3p-postgresql.yml as a model and ensure all workflows validate ProxySQL's PostgreSQL proxying functionality

Add missing CI workflow badge and complete CI-package-build.yml coverage

The README references CI-package-build.yml and CI-selftests.yml workflows in badges, but CI-selftests.yml and CI-repltests.yml are not present in the .github/workflows directory. There are partial package workflows listed but the complete matrix appears incomplete. Adding these missing workflows and their corresponding README badges would improve CI transparency.

• [ ] Create .github/workflows/CI-selftests.yml with core self-test suite for ProxySQL functionality
• [ ] Create .github/workflows/CI-repltests.yml for replication/clustering scenario testing
• [ ] Ensure CI-package-build.yml consolidates all the individual CI-package-amd64-*.yml workflows into a matrix-based approach to reduce duplication
• [ ] Update README.md to reflect accurate workflow badge references matching actual workflow files

Create integration test suite for MySQL X Protocol proxy support

There is a CI-mysqlx.yml workflow listed but no corresponding detailed test documentation or integration tests visible in common test locations. MySQL X Protocol (port 33060) is a significant feature that deserves comprehensive test coverage, especially given the extensive test infrastructure for regular MySQL protocol.

• [ ] Create comprehensive test suite in tests/ directory for X Protocol connection handling, query routing, and authentication
• [ ] Add specific test cases for X Protocol-specific features (prepared statements, result streaming, CRUD operations through proxy)
• [ ] Update CI-mysqlx.yml with matrix testing across multiple MySQL versions with X Protocol enabled
• [ ] Document X Protocol proxy configuration and testing requirements in a new docs/X-PROTOCOL.md file

• Add comprehensive integration tests for the PostgreSQL wire protocol in the test/ directory — currently there are CI workflows for PostgreSQL (CI-3p-postgresql.yml) but the main test suite appears MySQL-focused; contribute tests that exercise PostgreSQL-specific features like SASL authentication, prepared statements, and type handling.
• Enhance admin interface documentation by creating Python/Bash examples in a new docs/ folder showing how to programmatically manage ProxySQL via the admin interface — query routing rules, connection pool tuning, and monitoring metrics — as currently the README only covers basic installation.
• Implement missing metrics or stats in the stats_* views accessible via admin interface — review the query statistics collection in src/query_processor.cpp and add tracking for cache hit/miss ratios per hostgroup or per user, then write test cases to validate the new metrics.

ProxySQL shows moderate security concerns primarily in its Docker/CI-CD infrastructure. The most critical issues are: (1) privileged Docker containers allowing potential privilege escalation, (2) unpinned Docker images vulnerable to substitution attacks, and (3) a large number of GitHub Actions workflows creating an extensive attack surface requiring comprehensive audit. The codebase itself requires deeper analysis as source files are not provided - particular attention should be paid to protocol handling, SQL

• High · Privileged Docker Container in docker-compose.yml — docker-compose.yml - _build service. The _build service is configured with 'privileged: true' and 'network_mode: host', which grants excessive capabilities to the container. This could allow privilege escalation attacks and bypass security boundaries. Fix: Remove 'privileged: true' unless absolutely necessary. Use specific Linux capabilities with --cap-add instead of privileged mode. Avoid 'network_mode: host' and use bridge networking with explicit port mappings.
• High · Unversioned Docker Base Image — docker-compose.yml - centos9_build service and related build services. The packaging images (e.g., 'proxysql/packaging:build-centos9-v4.0.0') use custom Docker images without clear source or validation. No image digests are specified, making them vulnerable to image substitution attacks. Fix: Pin Docker images to specific digest hashes (SHA256) instead of tags. Implement image scanning and verification. Document the source and build process of custom images.
• Medium · Sensitive Environment Variables in Docker Compose — docker-compose.yml - _build service environment section. The docker-compose.yml passes multiple environment variables (GIT_VERSION, BUILD_TYPE, etc.) to the build container. If these contain sensitive information or are logged, they could be exposed. Fix: Use .env files with restricted permissions (.env.example without secrets). Never log environment variables in build output. Use Docker secrets or secret management solutions for sensitive data. Review what each environment variable contains.
• Medium · Extensive GitHub Actions Workflows - Large Attack Surface — .github/workflows/ directory. The repository contains 60+ GitHub Actions workflows (.github/workflows/). This large number of workflows increases the attack surface and makes it difficult to audit all CI/CD configurations. Workflows using external actions or untrusted inputs could introduce supply chain risks. Fix: Audit all workflows for secure practices: pin action versions to commits not tags, review all external actions, use GITHUB_TOKEN with minimal permissions, implement workflow approval gates for sensitive operations, consolidate related workflows where possible.
• Medium · Missing Security Configuration in CI/CD — .clang-tidy, .github/workflows/CI-codeql.yml. The .clang-tidy file and multiple CI workflows suggest code analysis, but without seeing the actual configurations, critical security checks may be missing (SAST, dependency scanning, container scanning). Fix: Ensure CodeQL covers all languages used. Add SAST tools (clang-tidy, SonarQube). Implement dependency vulnerability scanning (Dependabot, Snyk). Add container image scanning to build pipelines. Enforce branch protection rules requiring security checks to pass.
• Low · Incomplete Security Analysis - Source Code Not Provided — src/ directory and related source files (not provided). The actual source code files are not provided in the analysis context. Potential vulnerabilities in C/C++ code for MySQL/PostgreSQL proxy functionality (buffer overflows, SQL injection, authentication bypass) cannot be assessed. Fix: Perform comprehensive source code review focusing on: SQL query construction, network protocol handling, authentication/authorization logic, buffer management, cryptographic implementations. Use static analysis tools (Clang Static Analyzer, Cppcheck, Coverity).
• Low · No Visible SBOM or Dependency Manifest — Root directory - missing dependency manifests. The dependency information is marked as empty. Without visible package management files (package.json, requirements.txt, pom.xml, etc.), third-party dependency vulnerabilities cannot be assessed. Fix: Ensure all dependencies are tracked in manifest files appropriate to the language (C/C++ uses git submodules/vcpkg, etc.). Generate and maintain SBOM using tools like CYCLONEDX. Regularly scan dependencies with tools like Dependabot or Snyk.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.