267 Commits (feature/pgsql-native-backend-protocol)

Author	SHA1	Message	Date
René Cannaò	08cc2dbaa5	Merge commit from fork ... fix(security): MCP run_sql_readonly multi-statement bypass (CVE-2026-48774 / GHSA-7wh6-2vcc-gcm4)	1 month ago
Rene Cannao	f17f63dcdb	docs(agents): formalize procedural lessons from the v3.0-260523 session ... Adds a Pre-Push Checklist at the top of doc/agents/common-mistakes.md and six new entries (sections 8 extended; 10-15 new) covering the mistakes I actually made during the v3.0-260523 integration session and the discipline corrections that came out of fixing each one: * Pre-Push Checklist — six items, each cross-linked to the relevant section. Item 2 (unit tests) is intentionally qualified: only when binaries are already built and exercise costs seconds; not a 10+-minute extra build. * Section 8 (Didn't Verify Compilation) — extended with the `-j$(nproc)` requirement (`make debug` silently single-threads), the header-changes-need-full-debug-build rule, and the `build_tap_test_debug` requirement when test code changes. * Section 10 — Validate dependency fixes via the real consumer before tagging. The 8-step ParserSQL <-> ProxySQL integration-test gate, motivated by the v1.0.4 -> v1.0.5 -> v1.0.6 churn. * Section 11 — Don't dismiss failing tests as "pre-existing" / "baseline" / "flaky". Cites the set_parser_algorithm_3-g1 case where the "baseline failure" label hid 10 real ParserSQL bugs. * Section 12 — Exhaustive probe before declaring "comprehensive fix". Catalogue first, fix second. * Section 13 — Distinguish test failure from CI infrastructure failure. The LouisBrunner/checks-action 401 case and the cache-restore-race case. * Section 14 — Don't understand the test before "fixing" it. reg_test_4072-show-warnings-t as the example; usleep(10) is load-bearing because it's the bug's reproducer condition. * Section 15 — Don't insert new values in public-API enums; append. The NodeType segfault during the ParserSQL P3/P4/P5 work. All examples are real from the past day. The doc is intended to be read by future agents (myself included) before starting work on the codebase.	1 month ago
Rene Cannao	f4fd5e4c06	fix(security): require non-empty auth token on every MCP endpoint (GHSA-7wh6-2vcc-gcm4) ... Previously only /mcp/query refused empty tokens. /mcp/admin, /mcp/cache, /mcp/config, /mcp/stats, /mcp/ai, and /mcp/rag still fell through to the permissive "no token = allow anyone" branch. Each of those endpoints either executes SQL on configured backends (admin, query, ai, rag), exposes proxy configuration including credentials (config), or surfaces internal runtime state (cache, stats). The original GHSA-7wh6-2vcc-gcm4 fix justified the /mcp/query change on grounds that "an unauthenticated attacker reaching the MCP listener can still read arbitrary data from any configured target using the documented read-only tools" — the same argument applies in equal or greater force to /mcp/admin (which exposes admin_kill_query, admin_flush_cache, admin_reload). Generalize the empty-token rejection to all endpoints. Operators must set the corresponding mcp-<endpoint>_endpoint_auth variable to a non-empty bearer token before that endpoint will respond. The permissive "empty = open" default is removed. Update doc/MCP/VARIABLES.md to flag every endpoint-auth variable as required.	1 month ago
Rene Cannao	a2779c0792	fix(security): require non-empty mcp-query_endpoint_auth for /mcp/query (GHSA-7wh6-2vcc-gcm4) ... Even after the run_sql_readonly multi-statement bypass is closed, the /mcp/query endpoint executes SQL against configured MCP target backends using the documented read-only tools (run_sql_readonly, explain_sql, list_*, sample_*, etc). Exposing this endpoint without authentication lets any network attacker who can reach the MCP listener read arbitrary data from any configured target. The variable mcp-query_endpoint_auth defaults to an empty string. The pre-fix authenticate_request() treated an empty token as "no auth configured, allow the request", which means the secure-default expectation is reversed: by default, /mcp/query is wide open whenever mcp-enabled=true. Refuse all /mcp/query requests when mcp-query_endpoint_auth is empty. An operator must set the variable to a chosen non-empty bearer token before the endpoint will serve requests. This is intentionally restricted to /mcp/query for now; the other endpoints retain their existing behavior pending a broader review. Document the requirement in doc/MCP/VARIABLES.md.	2 months ago
Rene Cannao	9aee6d639e	Implement real RAG source fetch ... Replace the rag.fetch_from_source stub with a real backend read path for MySQL and PostgreSQL sources. The handler now looks up document metadata from the RAG vector database, resolves the configured source backend, validates identifiers, builds a safe source query, and returns a per-document result row that includes either the authoritative source row or a fetch error. Unsupported backend types are rejected explicitly, and the source query is capped to a single-row result. Add a focused unit test that seeds the RAG metadata tables, exercises the tool entry point, and verifies backend failure propagation plus missing-document handling without requiring a live external database. Also document /mcp/rag and the fetch semantics in the MCP architecture guide.	2 months ago
Rene Cannao	cd33ea1113	Document and test config query restrictions ... Add end-user documentation for the /mcp/config query tool, including the SQL allowlist/denylist model, the single-statement requirement, and the structured response fields returned by the handler. Expand the TAP coverage to verify allowed SELECT/WITH/UPDATE paths, explicit rejection of PRAGMA/DDL/ATTACH, and false-positive resistance when forbidden tokens appear inside strings or comments. This keeps the config endpoint useful for controlled admin writes while preventing multi-statement and dangerous SQL execution.	2 months ago
Rene Cannao	1a7ed3bab1	chore: consolidate scattered documentation into doc/ and remove stale files ... Remove outdated/superseded files: - bounty.md (2015 student bounty program) - compile_examples.txt (gcc 4.8/FreeBSD 1.x era, superseded by Makefile) - proxysql_notes.txt (ProxySQL 1.x era, references deleted directories) - test_analysis_reg_test_3317.md (one-off test failure analysis) - RAG_IMPLEMENTATION_SUMMARY.md (exact duplicate of RAG_IMPLEMENTATION_COMPLETE.md) - genai_prototype/ (entire directory: prototype now implemented in plugins/genai/) - .github/issue_template.md (superseded by .github/ISSUE_TEMPLATE/) Consolidate RAG docs into doc/RAG/ (12 files, ~4000 lines): - Move 9 files from RAG_POC/ (architecture, design, guides, examples) - Move 3 files from repo root (RAG_COMPLETION_SUMMARY, RAG_FILE_SUMMARY, RAG_IMPLEMENTATION_COMPLETE) - Normalize filenames to lowercase for consistency Move scattered docs to doc/: - Read_Only_Testing.md, Aurora_Automated_Testing.md (testing guides) - RELEASE_NOTES_WORKFLOW.md (release process) - ProxySQL-3.0.4-Release-Notes.md -> doc/release_notes/ - docs/pgsql_servers_ssl_params.md (feature documentation)	2 months ago
Rene Cannao	88db9fd10f	fix: resolve PR #5741 review findings (issue #5729) ... - Fix groups.json sort order (CI lint failure) - Add sqlite3_mprintf null check in Anomaly_Detector (Gemini high) - Add ROLLBACK on DELETE/COMMIT error in 5 plugin_tables.cpp callbacks - Fix TAP plan count in test_stats_mcp_tables-t (12→11) - Fix TAP plan count in genai_plugin_anomaly_unit-t (24→25) - Fix ABI.md: register_runtime_view is ABI 3+, not ABI 4 - Update plan/spec docs: db_kind at struct tail (ABI backward compat) - Add Darwin -force_load fallback in src/Makefile - Add mkdir() error handling in AI_Features_Manager Verified: build clean, 30/30 unit tests pass, lint passes.	2 months ago
Rene Cannao	b8cfa32c63	fix: address all critical and important code review findings (issue #5729) ... Critical fixes: - Move db_kind to end of ProxySQL_PluginRuntimeView (tail-append = free ABI-3 compat) - Add mutex to protect Anomaly_Detector::user_statistics from concurrent session threads - Replace system(mkdir -p) with pure mkdir() loop (command injection fix) - Replace 77 std::stoi/stoll with non-throwing parse_int_or_zero/parse_ll_or_zero - Fix proxysql.cnf filename: Mysqlx -> MySQLX - Add --whole-archive to non-ClickHouse link path (plugin symbol resolution) Important fixes: - Add default: case with warning to db_kind switch in ProxySQL_PluginManager.cpp - Add config_db dispatch and null-handle tests to plugin_runtime_views_unit-t (6 new tests) - Update CLAUDE.md with sqlite-vec PROXYSQLGENAI exception - Remove stale anomaly_detection-t Makefile target - Replace fixed 1024-byte buffer with dynamic sqlite3_mprintf in Anomaly_Detector Minor: update ABI.md, PLUGIN_API.md, stale comments, unit test plan counts	2 months ago
Rene Cannao	d60e52712b	docs: document ABI v4 db_kind extension in ABI.md (issue #5729)	2 months ago
Rene Cannao	7153ac3193	docs(mysqlx): document tls_mode='passthrough' + Router parity matrix update ... Documents the per-route TLS passthrough mode added by issue #5692 and flips the corresponding row in the MySQL Router parity matrix from "P1 gap" to "implemented". doc/mysqlx/README.md: * Adds the `tls_mode` column to the `mysqlx_routes` schema reference in §4.3. * Adds a per-route override subsection to §8.1 (Frontend TLS Modes) documenting all five values (inherit, disabled, preferred, required, passthrough) and explaining the inherit -> deployment-wide `mysqlx_tls_mode` fallback. * Adds a new §8.4 (End-to-end TLS Passthrough) covering the use case (compliance / cert-and-SNI preservation), the operator trade-offs (no pooling, no multiplexing, no per-query routing, no frame-level observability — bytes only), and a worked example. doc/mysqlx/MYSQL_ROUTER_PARITY.md: * Promotes the TLS-modes / TLS-passthrough rows in the comparison table from "No" to "Yes via mysqlx_routes.tls_mode='passthrough'". * Updates the TLS Architecture narrative to call out the third configuration handle (per-route override) alongside the two deployment-wide variables, and adds a paragraph describing the X_PASSTHROUGH_FORWARD splice path. * Strikes through "P1 TLS passthrough" in the Feature Gaps table and adds an implementation reference. * Updates the Summary section to note that all five Router TLS modes are now matched.	2 months ago
Rene Cannao	744fb0bf36	feat(mysqlx): preferred-mode backend TLS fallback to plaintext + docs ... Closes the loop on issue #5693 (P1: asymmetric TLS / AsClient mode). The previous two commits added the runtime variable and the per- session decision; this commit wires the actual `preferred`-mode fallback path in the backend auth state machine and updates the operator-facing documentation to describe the full four-mode model. What changes: * MysqlxConnection::step_auth_capabilities_set_sent now treats a Mysqlx::Error response from CapabilitiesSet(tls=true) as a fall-back trigger when backend_tls_fallback_allowed_ is set (set by the session for mode=preferred). The connection silently downgrades on the same TCP socket — backend_tls_required_ is cleared so subsequent steps don't re-attempt TLS, tls_active_ stays false (which keeps the connection out of the encrypted half of the per-thread pool), and step_auth proceeds straight into AuthenticateStart on plaintext. Under mode=required (and AsClient + frontend-TLS), the same Error is still fatal — the operator's policy demands encryption. The pre-existing `Frame is not OK` rejection branch is preserved for malformed / unexpected response types. * doc/mysqlx/README.md §8 rewritten: * §8.1 frontend TLS modes (mysqlx_tls_mode, unchanged behaviour). * §8.2 backend TLS modes (mysqlx_tls_backend_mode, full table of the four documented values, migration notes from MySQL Router AsClient, and a connection-pool partitioning note explaining that the cache key now includes tls_active. * §8.3 configuration example showing the asymmetric pattern (frontend REQUIRED + backend preferred). The §3.1 variables table gains the new variable. * doc/mysqlx/MYSQL_ROUTER_PARITY.md updated: * Feature comparison row 4 (TLS modes) now lists 4-frontend x 4-backend with explicit mention of mysqlx_tls_backend_mode and issue #5693. * Asymmetric TLS row marked implemented. * Architecture section §TLS rewritten to describe both the frontend mysqlx_tls_mode and backend mysqlx_tls_backend_mode models; identifies passthrough as the remaining gap. * Feature gaps table marks "Asymmetric TLS / AsClient" and "Per-message response state machines" as implemented. * Summary updated. Tests: test/tap/tests/unit/mysqlx_backend_auth_unit-t (was 34): adds 7 new ok lines covering both branches of the fallback decision: * test_backend_auth_preferred_mode_fallback_to_plaintext: 5 assertions across the wire-level transition (state on entry, rc=1 on Error, AUTHENTICATE_START_SENT after fallback, backend_tls_required_ cleared, tls_active false, AuthStart frame on the wire). * test_backend_auth_required_mode_no_fallback_on_error: 2 assertions confirming the same Error is fatal when fallback_allowed=false. Total 42. All 8 (mode x frontend_tls) acceptance combinations from the issue are now covered: 6 by the decision-function tests in mysqlx_message_dispatch_unit-t (commit 2), and the remaining 2 mode=preferred + backend Error cases by the wire-level fallback tests added here. Tested under NOJEMALLOC=1 WITHASAN=1 PROXYSQLGENAI=1. Closes #5693. Stacks on #5706 / #5704.	2 months ago
Rene Cannao	29ee30daf9	docs(plugin-chassis): address PR-#5690 review feedback ... CodeRabbit + Gemini review pass surfaced four small doc-precision items, all legitimate. None were code bugs. # CodeRabbit (markdownlint nit) - doc/PLUGIN_API.md:455: fenced code block at "DISK ↔ MEMORY ↔ RUNTIME" lacked a language specifier. Added `text` to satisfy MD040 / fenced-code-language. # Gemini (3x same root: clarify the matching algorithm) The chassis dispatch matcher is case-insensitive whole-identifier substring match, but three docs described it loosely. Plugin authors deciding what table name to register need to know that runtime_X does not match runtime_X_extra or stats_runtime_X. - doc/PLUGIN_API.md:289 ("any admin SELECT against it") -> spell out the whole-identifier rule with the longer-prefix / longer-suffix rejection examples. - doc/plugin-chassis/ABI.md:156 ("appears in the SQL") -> "is referenced as a whole identifier in the SQL query (case-insensitive; identifier-aware, so runtime_X_extra or stats_runtime_X do not match runtime_X)". - doc/plugin-chassis/FILE_CHANGES.md:102 ("substring match") -> "case-insensitive whole-identifier substring match", matching the precise wording already used in section B for the sql_references_table_ci helper. Cross-section consistency. No source code touched. No new content sections, only existing prose tightened.	2 months ago
Rene Cannao	64e7334297	docs(plugin-chassis): align FILE_CHANGES/ABI/REVIEW_GUIDE/PLUGIN_API with PR #5688 ... The four chassis docs still described the pre-fix architecture: - ABI version 2 (now 3 — register_runtime_view appended at services tail) - MysqlxConfigStore::load_from_runtime (removed; replaced by per-entity install/save/project triplets) - copy_table / copy_to_runtime as the LOAD/SAVE shovels (deleted) - Listener reconciler reading runtime_mysqlx_routes (now reads MysqlxConfigStore::snapshot_active_routes) - "Three-tier" disk/memory/runtime model with the empty-source-sync invariant applied uniformly (the runtime tier was wrong; runtime_<X> is now an admin-side projection of module state, not a tier; the invariant only applies to disk-tier copies) - Plugin-context layout listing a non-existent MysqlxStatsStore Updates per file (no source code touched): - FILE_CHANGES.md §A: PROXYSQL_PLUGIN_ABI_VERSION 2 → 3, services list gains register_runtime_view, ProxySQL_PluginRuntimeView struct documented, separation-of-duties contract spelled out. §B: PluginManager methods list gains register_runtime_view, refresh_runtime_views_for_query; service trampolines list gains register_runtime_view_service; sql_references_table_ci whole-identifier match described; services_phase_b_ wiring of register_runtime_view explained. §C: new pre-SELECT runtime-view dispatch site in GenericRefreshStatistics described — gated on if (admin), OUTSIDE the if (refresh==true) block, so any admin-port query gets the chassis dispatcher fired. §H: mysqlx_start() no longer does runtime sync; describes the four install_<X>_from_admin calls in their place. §I: copy_table removed from the description; new LOAD/SAVE callbacks calling MysqlxConfigStore install/save APIs; four refresh_<X>_runtime_view callbacks registered via services.register_runtime_view(). §J: MysqlxConfigStore reframed as the canonical source of truth (runtime_mysqlx_<X> are projections of it). API list replaced load_from_runtime with the four install/save/ project triplets, install_all_from_admin (test convenience), snapshot_active_routes, and MysqlxBackendEndpointOverride. §K: listener reconciler reads MysqlxConfigStore directly via snapshot_active_routes(); inline rationale notes why we must NOT read runtime_mysqlx_routes (empty between LOAD calls under the new architecture). - ABI.md: services availability matrix gains register_runtime_view (live in Phase B and D); current-ABI block 3/3; §5 retitled "Separation of duties" with the new contract; disk-tier exception keeps the empty-source-sync invariant. - REVIEW_GUIDE.md: ABI-surface bullets updated; mysqlx phase descriptions updated to point at install_*_from_admin / runtime-view projections / snapshot_active_routes-driven reconciler. - PLUGIN_API.md: descriptor table updated for ABI 3; services struct snippet shows the ABI-2 and ABI-3 tail extensions; new register_runtime_view callback section with the contract; "Three-Tier" section retitled "Separation of duties", clarifies that runtime_<X> is an admin-side projection (not a persistent tier) and the empty-source-sync invariant applies only to disk- tier copies; alias-handling note corrected. The only surviving "ABI version 2" mention is in PLUGIN_API.md line 46 ("plugins that declare ABI version 2 or higher") — that is a correct version-or-higher predicate, not a stale reference.	2 months ago
Rene Cannao	af270316b9	docs(mysqlx): correct ABI version, mysqlx_variables list, start() flow ... Doc-accuracy review pass found three substantive lies in README.md / ARCHITECTURE.md the previous doc rewrite missed. # ABI version Both README §13 and ARCHITECTURE §1 stated "ProxySQL Plugin ABI version 1". The plugin descriptor in mysqlx_plugin.cpp has used PROXYSQL_PLUGIN_ABI_VERSION since chassis introduction; that macro is now 3 (descriptor ABI 2 four-phase lifecycle + ABI-3 register_runtime_view services field). Updated both files to call the right number with a one-liner on what each ABI bump added. # mysqlx_variables list README §3.1 listed eight variables: mysqlx_thread_pool_size, mysqlx_connect_timeout, mysqlx_tls_mode, mysqlx_tls_cert, mysqlx_tls_key, mysqlx_tls_ca, mysqlx_tls_backend_mode, and mysqlx_max_cached_connections_per_thread. Only the four canonical scalars are wired through MysqlxConfigStore — load_variables() in mysqlx_config_store.cpp matches against four exact names and silently ignores everything else; save_variables_to_admin_table DELETEs the entire table and re-inserts only the four. So the TLS-related entries the README told operators to set are accepted into the table by the CHECK constraints, never read by LOAD, and deleted by the next SAVE. §8.2 example was equally misleading: it instructed operators to UPDATE mysqlx_tls_cert / mysqlx_tls_key paths and run LOAD MYSQLX VARIABLES TO RUNTIME, which is a silent no-op. Trim the §3.1 table to the four wired variables, add a paragraph explaining that other variable_name values are silently ignored by LOAD and deleted by SAVE, and trim §8.2 to the one TLS-related variable that actually round-trips (mysqlx_tls_mode). # start() flow README §2.3 step 6 said "The plugin's start() function loads configuration from runtime tables, ...". After the architectural fix mysqlx_start() syncs disk → memory for the editable mysqlx_* tables, then drives the four install_*_from_admin calls (each SELECTing the editable table plus the relevant cross-module runtime_mysql_* projection). Updated to spell out the actual flow. # Smaller corrections ARCHITECTURE §3.5 listed a "MysqlxStatsStore" in the plugin context — there is no such struct. Replaced with the actual context members. ARCHITECTURE §3.6 listed runtime_mysql_users as the only cross-module dependency for installs; install_endpoints also reads runtime_mysql_servers — added that.	2 months ago
Rene Cannao	e678d101a0	docs(mysqlx): rewrite architecture/README for module-owned runtime state ... Both files described the OLD model — runtime_mysqlx_<X> tables as persistent admin-side mirrors, MysqlxConfigStore::load_from_runtime as the canonical reload, copy_table as the LOAD/SAVE mechanism. None of that is true after the architectural fix on this branch. # ARCHITECTURE.md changes - §3.6 mysqlx_config_store row: Responsibility cell now identifies the store as the canonical source of truth and runtime_mysqlx_* as projections. Key methods cell lists the four install_*_from_admin / save_*_to_admin_table / project_*_to_ runtime_view triplets in place of the removed load_from_runtime. Thread-safety cell updated to match. - §3.8 mysqlx_admin_schema row: describes direct interaction with MysqlxConfigStore (no SQLite-to-SQLite copies) and the four refresh_<X>_runtime_view callbacks registered via the chassis services.register_runtime_view(). - §10.2 Admin Command Flow: replaced the single copy_table flow diagram with three flows (LOAD, runtime-view refresh on SELECT, SAVE). Added §10.2.5 explicitly contrasting the new model with the old "authoritative SQLite mirror" model so a reader who skimmed the old docs knows which mental model to discard. - §11 Thread Model: the call graph shows sync_disk_to_memory plus the four install_<X>_from_admin calls instead of the removed single load_from_runtime(). Startup prose updated. # README.md changes - §4.2 / §4.4 / §4.6: section titles changed from "Runtime Table" to "Runtime View"; bodies rewritten to describe the on-demand projection mechanism, with explicit "LOAD never writes / SAVE never reads" notes. - §4.7 (NEW): dedicated runtime_mysqlx_variables section so the documentation surface is symmetric across all four entities. Old §4.7/§4.8 stats sections renumbered to §4.8/§4.9. - §6.3 Dual-Mode Identity Resolution: corrected a stale claim that a user existing only in mysql_users (no mysqlx_users row) could still authenticate with default X Protocol settings. install_users_from_admin explicitly drops canonical-only users from the store; the doc now reflects that. # Intentional historical reference ARCHITECTURE.md §10.2.5 still names the obsolete identifiers (load_from_runtime, copy_table, "INSERT INTO runtime_mysqlx_users SELECT * FROM mysqlx_users") — that paragraph is exactly the "what to unlearn" anchor for readers who internalized the old docs. README.md §4.2 still shows the literal SQL the projection callback emits (DELETE FROM ... INSERT INTO ...), which is the concrete mechanism description rather than a description of the old wrong path.	2 months ago
Rene Cannao	42afebcb64	docs(plugin-chassis): add reviewer's guide, ABI contract, and file inventory ... PR #5651 is large enough that reading commit-by-commit or file-by-file without context is unproductive. Add three companion docs under doc/plugin-chassis/ so a senior reviewer can validate the PR layer by layer. * REVIEW_GUIDE.md (~345 lines) — entry point. One-paragraph project description, scope diagram, three reading orders (30 minutes / 2 hours / full day), the 4-phase plugin lifecycle with a sequence-style ASCII diagram, the worked-example walk-through of a mysqlx client request end to end, the build-system tier-flag propagation map (5 Makefile layers), 17 explicit "consistency seams" each with a one-line shell verification, the 5 commit-intent bands so the ~150 commits map to a small number of logical changes, and a final verification checklist. * ABI.md (~270 lines) — the canonical reference for the plugin ABI: the descriptor surface, the services surface and its phase-availability matrix, the C++-ABI coupling (std::string and prometheus-cpp must match between core and plugin), the empty-source-sync invariant, the concurrency model and lifecycle pairing rules ("stop pairs with init, not start"), the ABI versioning rules (tail-append, version-gate every new-field read, reject anything > MAX), and a minimal plugin skeleton for reference. * FILE_CHANGES.md (~503 lines) — the per-file inventory. Sections A–G cover the chassis core (15 files), H–S cover the mysqlx plugin (12 source files + 1 build file + 16 generated protobuf files described collectively), T covers tests/CI/infra (28 unit tests with their individual plan() counts, 4 integration tests, the build glue, the groups.json delta, and the new CI workflow). Each entry: path, status, line-count, purpose, key contents, what to spot-check. Total: 1117 lines of reviewer documentation. The expectation is that a reviewer with 30 minutes can ship-no-ship from REVIEW_GUIDE alone; a reviewer with 2 hours can validate the architecture; a reviewer with a full day can run every test and walk every file via FILE_CHANGES. These docs are written for THIS PR. They are not a replacement for doc/PLUGIN_API.md (which is the public-facing API doc for plugin authors) — REVIEW_GUIDE explicitly points at PLUGIN_API for plugin authors and at ABI.md for the canonical contract. Verified: - All 17 §7 verification rows actually pass on the current HEAD (spot-checked: register_schemas gating at abi_version >= 2, TLS_PASSTHROUGH absence, shared_mutex change, ABI version macros, groups.json tag counts). - Cross-doc references (REVIEW_GUIDE → ABI → FILE_CHANGES) are consistent.	2 months ago
Rene Cannao	c723ede0cf	Merge remote-tracking branch 'origin/plugin-chassis' into ProtocolX-rebased ... # Conflicts: # lib/ProxySQL_PluginManager.cpp # plugins/mysqlx/Makefile # plugins/mysqlx/include/mysqlx_plugin.h # plugins/mysqlx/include/mysqlx_session.h # test/tap/groups/groups.json # test/tap/tests/test_mysqlx_listener_smoke-t.cpp # test/tap/tests/unit/Makefile	2 months ago
Rene Cannao	e462bb0cb4	fix: address PR review feedback ... Resolves in-scope review items on PR #5651. Items deemed out of scope for this PR (O(N) admin dispatch lookup, per-plugin mutex, worker backpressure, runtime-reload DDL semantics, E2E tests going through ProxySQL rather than directly to MySQL) are tracked elsewhere; items that were already fixed in earlier commits on this branch (Admin_Handler MYSQLX alias vectors, Admin_Bootstrap PROXYSQL40 gating) are acknowledged as stale. Changes: * .github/workflows/CI-mysqlx.yml: add `include/` and `src/proxysql_global.cpp` to both `sparse-checkout` blocks. The plugin Makefile discovers the repo root via `src/proxysql_global.cpp` and includes headers from `include/`; without these, `make` inside `plugins/mysqlx` climbs up to `/` or fails on missing includes. (coderabbit: "Checkout the files required by the plugin Makefile.") * .github/workflows/CI-mysqlx.yml: `fail-on-cache-miss` now depends on `github.event_name == 'workflow_run'`. Strict behavior is retained for the cache-driven pipeline that CI-trigger populates; manual `workflow_dispatch` runs no longer fail when the SHA-specific cache doesn't exist yet. (coderabbit: "Don't make manual runs depend on a pre-existing build cache.") * plugins/mysqlx/Makefile: replace the unbounded `while [ ! -f ./src/proxysql_global.cpp ]; do cd ..; done` with a bounded upward walk (up to 12 levels) that fails fast with a clear error message when the marker file is missing — e.g. on a sparse checkout that omits `src/proxysql_global.cpp`. Build output no longer appears to hang indefinitely. (coderabbit: "Prevent root discovery from hanging on sparse or invalid checkouts.") * doc/PLUGIN_API.md: update startup sequence from the old three-phase (load → init → start) description to the four-phase chassis lifecycle (load → register_schemas → admin materialize → init → start). Document the `register_schemas` descriptor field and the `abi_version` / `PROXYSQL_PLUGIN_ABI_VERSION` contract. Clarify that `stop()` pairs with `init()` (not `start()`) for teardown symmetry. (coderabbit: "Update plugin lifecycle documentation to reflect four-phase model and ABI versioning.") * plugins/mysqlx/include/mysqlx_session.h: default-initialize every field in `MysqlxCredentials`. `bool x_enabled` was indeterminate for a default-constructed instance, which would let a lookup miss produce a value that silently authenticates. In-class initializers give every field a deterministic default. (coderabbit: "Default- initialize credential fields used by auth decisions.") * plugins/mysqlx/src/mysqlx_backend_session.cpp: close `backend_fd_` when `authenticate_backend()` returns false. Previously `connect()` stored the newly-opened fd in `backend_fd_` and returned the auth result; a retry on the same `MysqlxBackendSession` would then overwrite `backend_fd_` and leak the previous socket. (coderabbit: "Close/reset `backend_fd_` when authentication fails.") * lib/Admin_Bootstrap.cpp: `materialize_plugin_tables()` now runs DDL only for the subset of plugin-declared tables that were freshly inserted into `tables_defs_*` (the rest are already materialized). DDL failures are startup-fatal: on `execute()` returning false, log the plugin kind + table name + SQL and `exit(EXIT_FAILURE)`. A partially materialized schema produces opaque runtime errors from the plugin later on, so aborting startup is the right default. (gemini + coderabbit: "Execute DDL only for newly materialized plugin tables" / "add error checking".) Not changed in this commit (deferred / out of scope / stale): * CI-mysqlx E2E tests going through ProxySQL (requires plumbing listener + admin config in the CI workflow). * O(N) admin dispatch scan → hash map. * Descriptor build-id hash for libstdc++ compat detection. * Per-plugin mutex on mutable plugin context. * Worker client-fd enqueue backpressure. * Stale plan-doc feedback on docs/superpowers/plans/*.md. Verification (clean tree): * `unset PROXYSQL*; make cleanall && make debug -j$(nproc) && make build_tap_test_debug -j$(nproc)` -- 0 errors. * `PROXYSQLGENAI=1 make cleanall && PROXYSQLGENAI=1 make debug -j$(nproc) && PROXYSQLGENAI=1 make build_tap_test_debug -j$(nproc)` -- 0 errors. * Plugin unit tests (PROXYSQL40): 48 + 52 + 26 + 46 + 10 = 182 pass.	2 months ago
Rene Cannao	f104116926	fix(plugin-mgr): serialize lifecycle and always reset manager on stop ... Add g_plugin_lifecycle_mutex to serialize load/start/stop transitions so two reload paths cannot race on g_registry_target and the registration-failure globals. g_active_plugin_manager_mutex remains the pointer-read guard for the dispatch path; the new mutex is held only for the duration of a lifecycle transition. In proxysql_stop_configured_plugins, always call manager.reset() so the .so is unmapped and no stale function pointers remain reachable, even when stop_all() reports a failure. stop_all() is idempotent across failure (each plugin is marked stopped after one attempt) so the destructor's stop_all() will be a no-op. Also fix the log-level table in PLUGIN_API.md: numeric levels are 3 (Error), 4 (Warning), and any-other (Info), matching the internal proxy_* severity scheme — not 1/2/3 as previously documented.	2 months ago
Rene Cannao	a1def9d927	docs(mysqlx): fix stale TLS, table name, and missing documentation ... Update all four doc/mysqlx/ files to reflect current implementation: - TLS: change from "stub" to "supported" (OpenSSL Memory BIO) - Fix table name: mysqlx_endpoints → mysqlx_backend_endpoints - Add missing X_SESSION_RESET_WAITING state - Add section 5.3 documenting 8 DISK commands - Fix allowed_auth_methods default (empty, not 'MYSQL41,PLAIN') - Add missing comment column to all table schemas - Update test counts: 24 files, 600+ assertions - Update MYSQL_ROUTER_PARITY with accurate TLS/connect-timeout info	3 months ago
Rene Cannao	5c1549dcc6	merge: resolve conflicts with v3.0 branch ... Merge origin/v3.0 into ProtocolX. One conflict in test/tap/tests/unit/Makefile resolved by keeping both mysqlx unit tests (ProtocolX) and pgsql_servers_ssl_params unit test + GENAI vec.o link (v3.0).	3 months ago
Rene Cannao	57c3e3fa28	docs: excise sqlite-rembed sections from GENAI.md and SQLite3-Server.md ... - GENAI.md: Remove two rembed-related links from Related Documentation section - SQLite3-Server.md: Delete Embedding Generation section (was lines 72-103) - SQLite3-Server.md: Remove rembed-dependent use cases (embedding generation, AI pipelines)	3 months ago
Rene Cannao	f821ebcdc7	docs: remove sqlite-rembed guides, examples, and embeddings script	3 months ago
Rene Cannao	cd11df3a7f	doc: add Plugin API documentation for external users ... ProxySQL's plugin system was previously undocumented except for the header file (include/ProxySQL_Plugin.h) and the mysqlx reference implementation. A developer wanting to write a plugin had to reverse-engineer the contract from those sources. Add doc/PLUGIN_API.md covering: - How plugins are loaded (plugins= directive in proxysql.cnf) - Startup/shutdown lifecycle sequence - The ProxySQL_PluginDescriptor contract (name, abi_version, init/start/stop/status_json) - The proxysql_plugin_descriptor_v1 entry point - ProxySQL_PluginServices callbacks (register_table, register_command, log_message, get_admindb/configdb/statsdb, snapshots) - ProxySQL_PluginCommandContext and ProxySQL_PluginCommandResult types - Complete minimal plugin example - Build requirements and compiler compatibility notes - Admin integration patterns (three-tier config model, table registration) - Current limitations (no hot-loading, no dependency resolution, compiler coupling) - Pointer to the mysqlx reference implementation	3 months ago
Rene Cannao	81b406a428	doc(GH-Actions): address gemini review nits on §12 vocabulary section ... Four minor corrections from the PR #5607 review: 1. §12 intro: "from issue" → "from the issue" (missing article) 2. §12.1.1: comma splice "(... — ProxySQL does exactly this, see #7 below)" → semicolon for grammatical correctness 3. §12.1.1 YAML example: replaced the `← ← ←` arrow annotations with `# <- ...` comments so the snippet is valid YAML if copy-pasted 4. §12.1.1: "has runs on 10 commits" → "has run on 10 commits" (past participle) No change to meaning or structure. The `←` arrows that remain in the ASCII box diagrams at §12.2 / §12.3 / §12.4 are untouched - those diagrams are illustrative text inside un-typed fenced blocks, not copy-pasteable code, and the gemini review only flagged the yaml-typed block. Coderabbit's "Critical" finding about anchor links using `--` instead of `-` is a false alarm: the em-dash in the §12 heading is stripped by GitHub's slugger, leaving two adjacent spaces which become two adjacent hyphens. I verified this by asking GitHub's own `/markdown` API to render the heading and inspecting the generated `<a id="...">`, which contains exactly `...vocabulary--read-this-first-if-confused` (double hyphen). No anchor fix is needed.	3 months ago
Rene Cannao	90c103a345	doc(GH-Actions): add §12.6 terminal flow — how to actually see what ran ... Follow-up to the vocabulary section added in ca4da932e. A maintainer hit GitHub's longstanding check-run UX papercut: clicking a row in the PR "Checks" tab lands on /runs/<check_id>, which shows only a status card and whose "View more details on GitHub Actions" link often points back at the same page because details_url on auto-created check runs is self-referential. The same dead-end is reached via the PR checks table's "Details" button (an earlier draft of this doc claimed otherwise — the claim was wrong and is corrected here). This commit inserts §12.6 "Seeing what actually ran — the terminal flow" between §12.5 (Common confusions) and what is now §12.7 (Sanity check, formerly §12.6). The new section walks the exact four-command terminal flow needed to go from a single row of `gh pr checks` output to the log lines of the failing step, using the real row from PR 5596 as the walked example: ✓ CI-trigger/CI-legacy-g1 / tests (mysql57) → gh run list -R sysown/proxysql --workflow CI-legacy-g1 → gh run view 24281031512 -R sysown/proxysql → gh run view --log-failed --job=70902846188 -R sysown/proxysql The section covers: - A character-by-character breakdown of the check row, identifying which fields are useful (workflow name) and which are dead ends (the /runs/<id> URL). - Why `gh run list`'s `branch:` column lies ("v3.0" rather than the PR's actual branch) because workflow_run-triggered runs inherit the default branch's metadata, not the triggering PR's. The documented gotcha in §10.2 cross-referenced. - How the run's display-title is the ONLY place where the PR head SHA appears, and the idiom to grep / `jq .displayTitle | contains(...)` against it. - How job name and check-run name differ ("run / tests (mysql57)" vs "CI-legacy-g1 / tests (mysql57)") because the prefixes come from different namespaces (caller job key vs workflow name). - Three flavors of log retrieval (--log-failed, --log | less, full-run --log) with concrete awk / grep idioms for the tab-separated log format. - A copy-pasteable condensed cheat sheet parameterised over PR number and workflow name. - A "why the web UI cannot do this" explanation stacking the three separate GitHub design issues: check-runs vs job-runs are different objects with no explicit link, details_url is self-referential, and workflow_run runs are tagged with the default branch's SHA not the PR's. Also: - §12.7 Sanity-check renumbered from §12.6, internal cross-refs in its "if you didn't get this, re-read X" pointer updated. - §12.7 gains a sixth self-test question covering the terminal flow. - No TOC change needed: the TOC lists only top-level sections (§12 as a whole), subsections are reached via the heading anchors. Doc-only change. 1547 → 1818 lines. Code fences balanced at 100.	3 months ago
Rene Cannao	ca4da932ef	doc(GH-Actions): add detailed GitHub Actions vocabulary section with diagrams ... The existing CI architecture doc assumes the reader already knows the GitHub Actions terminology and can parse check-run labels like 'CI-maketest / builds (testgalera)'. A maintainer asked what that label means and where to find it by grep, and the only answer was "re-read the whole doc and work it out yourself, most of the pieces are in different sections". That's not good enough. This commit adds a new §12 'Understanding GitHub Actions vocabulary' that: - Walks through the seven core terms (workflow, workflow run, job, matrix cell, step, check run, caller/reusable split) bottom-up, using ci-maketest.yml as a single concrete example throughout. - Includes an ASCII nesting diagram that shows how workflow -> run -> job -> matrix cell -> steps slot into each other, with check runs as separate objects attached to the commit SHA. - Includes a second ASCII diagram showing the ProxySQL two-branch caller/reusable split: one logical trigger -> two workflow runs, one on v3.0 and one on GH-Actions, sharing the same workflow name. - Includes a third diagram tracing exactly how the check-run label 'CI-maketest / builds (testgalera)' is assembled at runtime from github.workflow + github.job + env.MATRIX, explaining why the literal string exists nowhere on disk and grepping for it or for 'galera' will fail. - Answers five common confusion questions directly (why click-throughs land on GH-Actions, why two check rows per cell, where 'make testgalera' is defined, which file produced a given check row, CI-legacy-g2-genai vs CI-legacy-g2). - Ends with a five-question self-test so the reader can check they have the model right before closing the section. Also: - Added a 'New to GitHub Actions terminology?' pointer at the top of the doc so a confused reader jumps directly to the new section instead of wading through the two-branch architecture explanation first. - Renamed the existing compact Glossary table to 'Glossary (quick reference)' to make clear it is the lookup-by-term reference and the new narrative section is the learn-by-walkthrough explanation. - Both sections are kept: §12 for people who need the model, §13 for people who just need a word defined quickly. No source-code or workflow changes. Doc only.	3 months ago
Rene Cannao	22e0ec2c91	docs(ci): document matrix.infradb gotcha; tag fenced blocks with text ... Addresses review feedback on #5598: 1. Adds `matrix.infradb` to the "What a sibling differs in" checklist. Gemini-code-assist flagged it -- and it was also a real bug in the merged ci-mysql84-g{1..5}.yml files, fixed in the separate #5600. The doc now explains that `infradb` is cosmetic for routing but displayed in the PR UI via env.MATRIX, so leaving it at the template default creates a misleading "CI-mysql84-g3 / tests (mysql57)" label. 2. Updates the sed example in "Adding a new test group" to substitute the infradb string alongside the group name, so copy-pasting from the doc produces a correct file on the first try. 3. Adds `text` language tag to seven previously untyped fenced code blocks (ASCII diagrams, directory listings, plain-text output) to satisfy markdownlint MD040. CodeRabbit flagged these. The repo doesn't enforce markdownlint, but the tag is harmless and silences the bot for future contributors editing the doc.	3 months ago
Rene Cannao	5aad576125	ci: rewire group callers to dedicated reusables; add CI-unittests; document CI architecture ... Rewiring -------- Following the landing of sysown/proxysql#5597 on the GH-Actions branch (which adds the nine dedicated reusable workflows), point each of the eight existing group callers at its dedicated reusable instead of the broken generic ci-taptests-groups.yml: CI-legacy-g1.yml → ci-legacy-g1.yml@GH-Actions CI-legacy-g3.yml → ci-legacy-g3.yml@GH-Actions CI-legacy-g5.yml → ci-legacy-g5.yml@GH-Actions CI-mysql84-g1.yml → ci-mysql84-g1.yml@GH-Actions CI-mysql84-g2.yml → ci-mysql84-g2.yml@GH-Actions CI-mysql84-g3.yml → ci-mysql84-g3.yml@GH-Actions CI-mysql84-g4.yml → ci-mysql84-g4.yml@GH-Actions CI-mysql84-g5.yml → ci-mysql84-g5.yml@GH-Actions Each edit also drops the now-useless `testgroup: '["<group>"]'` input that the new dedicated reusables do not accept (and the old generic reusable silently ignored). This is the other half of the fix started in #5597. Before this change, the eight group workflows were routed to ci-taptests-groups.yml, whose tests job strategy evaluates from a cached proxysql/tap-matrix.json that CI-builds has been populating as "[ ]". With an empty matrix vector GitHub Actions rejects the strategy with "Matrix vector 'testgroup' does not contain any values" and the tests job never instantiates -- visible for example in run 24240099115. With this PR merged (after #5597), these eight workflows will route to their own dedicated reusables and start running real tests on the next push. CI-unittests caller ------------------- Adds a new v3.0 caller CI-unittests.yml targeting ci-unittests.yml@GH-Actions (also added in #5597). This runs the 42 unit-tests-g1 binaries listed in test/tap/groups/groups.json directly on the runner, via the SKIP_PROXYSQL=1 host-only branch in run-tests-isolated.bash -- no Docker, no backends. Documentation ------------- Replaces doc/GH-Actions/README.md with an expanded, current CI architecture reference (~800 lines). Covers: * The two-branch caller/reusable split and the workflow_run default-branch rule that forces it * The CI-trigger / CI-builds babysitter pattern and why test workflows chain on CI-trigger completion (and not on CI-builds directly -- see 78b8f5ac6 for the incident that taught us why) * The dedicated-reusable pattern, with ci-legacy-g4.yml walked through step by step as the canonical template * Build cache layout (_bin / _src / _test / _matrix) * The TAP groups system: groups.json, BASE_GROUP stripping, infras.lst, env.sh, SKIP_PROXYSQL mode for unit tests * Full workflow catalogue as of 2026-04-11 with status per file * End-to-end walkthrough for adding a new test group * Common pitfalls: merge ordering, workflow_run head_sha propagation, the empty-matrix wedge, the LouisBrunner/checks-action false-positive permissions hotspot * Debugging guide: how to trace a failing run through CI-trigger → CI-builds → test workflow, and how to reproduce locally * Glossary Adds a Mermaid sequence diagram for the execution flow and inline ASCII diagrams throughout. Also updates CLAUDE.md to point agents at doc/GH-Actions/README.md before they touch anything under .github/workflows/.	3 months ago
Rene Cannao	1a33009667	docs(mysqlx): add MySQL Router X Protocol parity comparison ... Detailed feature-by-feature comparison between MySQL Router 8.0 and the ProxySQL X Protocol plugin covering: - Architecture: async callback vs poll()-based event loop - TLS: Router has 5 modes (Disabled/Preferred/Required/AsClient/Passthrough), ProxySQL has stubs only - this is the biggest feature gap - Authentication: Router is pass-through, ProxySQL does local validation - Connection pooling: ProxySQL has per-thread LRU cache, Router has none - Query-level routing: ProxySQL supports it via hostgroups, Router pins sessions - State machines: Router has ~100 states, ProxySQL has 15 Key findings: - ProxySQL has superior proxy architecture (pooling, multiplexing, local auth, query routing, dynamic config) that Router cannot match - Router has more mature protocol implementation (TLS, per-message states, Capabilities negotiation) - Biggest gap to close is TLS (P0 priority) - Most other differences are by design	3 months ago
Rene Cannao	39b86e0296	docs(mysqlx): update documentation for v2 event-driven architecture ... All three docs updated to reflect the complete rewrite: - ARCHITECTURE.md: poll() event loop, thread pool, session state machine, connection pool, frame forwarding, TLS stubs, Phase 1 vs 2 comparison - README.md: new config variables (thread_pool_size, connect_timeout, tls_mode, max_cached_connections), 23 message type support, v2.0.0 - TESTING.md: 6 new test files, ~138 new assertions, coverage map	3 months ago
Rene Cannao	7c782d05bd	docs: add MySQL X Protocol plugin architecture document ... Developer-facing architecture documentation with ASCII diagrams showing component relationships, client connection flow, admin command flow, thread model, plugin ABI contract, memory ownership rules, and MYSQL41 authentication internals.	3 months ago
Rene Cannao	d90108e5c3	docs: add MySQL X Protocol plugin testing documentation ... Comprehensive testing documentation covering all 16 test files (292+ assertions), three test tiers (unit/integration/E2E), running instructions, test infrastructure patterns, CI workflow using dbdeployer, test coverage map, and guidelines for adding new tests.	3 months ago
Rene Cannao	1dded26e9e	docs: add MySQL X Protocol plugin reference manual ... Comprehensive user-facing documentation covering plugin loading, admin tables (mysqlx_users, mysqlx_routes, mysqlx_backend_endpoints), admin commands (LOAD/SAVE MYSQLX ... TO RUNTIME/MEMORY), authentication methods (MYSQL41/PLAIN), dual-mode identity resolution, routing strategies, quick start example, and Phase 1 limitations.	3 months ago
Rene Cannao	80ff2242e6	merge: resolve v3.0 conflict and add pgsql_servers_ssl_params cluster sync ... v3.0 added pgsql_servers_ssl_params table. Integrate into pgsql cluster sync path: - Add CLUSTER_QUERY_PGSQL_SERVERS_SSL_PARAMS to Admin_Handler interception block alongside other pgsql cluster queries - Add ssl_params fetch query to pull_pgsql_servers_v2_from_peer - Add update_pgsql_servers_ssl_params() for applying synced data - Update convert_pgsql_servers_resultsets to handle 5 result sets - Include ssl_params in v2 checksum computation (4 tables)	3 months ago
Rene Cannao	822f4aaa6e	doc: remove stale pgsql cluster sync PR status document ... The pgsql_cluster_sync_pr5297_status.md was written during development and is now outdated — the TAP test passes fully with cluster sync validation including disk persistence.	3 months ago
Rene Cannao	47758a468d	merge: resolve groups.json conflict with v3.0 ... Take v3.0's groups.json as base (legacy-gN naming, mysql84-gN groups, new test entries) and add test_cluster_sync_pgsql-t from this branch. Drop duplicate pgsql_admin_metacmds-t (already exists as pgsql-admin_metacmds-t in v3.0).	3 months ago
Rahim Kanji	50221943a3	Fix numbering in ssl_keylog user guide troubleshooting section (#5281)	3 months ago
Rahim Kanji	f2bd222145	Fixed compilation issue	3 months ago
Rahim Kanji	e7ee68dda5	Add SSL/TLS traffic decryption for PostgreSQL backend connections (#5281) ... Extends the existing NSS keylog-based SSL decryption to PostgreSQL backend connections by patching libpq with a global PQsetSSLKeyLogCallback() API. When admin-ssl_keylog_file is configured, TLS secrets from all PgSQL backend SSL handshakes are written to the keylog file in NSS Key Log Format, enabling traffic decryption with Wireshark/tshark. Approach: - Patch libpq with global callback following the PQsslKeyPassHook pattern - Single startup call covers all backend paths (regular, monitor, kill, harvester) - No new admin variables — existing admin-ssl_keylog_file covers PgSQL backends - Zero changes to ProxySQL PgSQL connection code Includes 9 integration tests (pgsql-ssl_keylog-t) and user guide updates.	3 months ago
Rene Cannao	bc42730061	Add GitHub Actions CI/CD documentation ... Comprehensive documentation covering: - Two-tier architecture (caller + reusable workflows) - Execution flow and trigger cascade - Build matrix (debian12-dbg, ubuntu22-tap, ubuntu24-tap-genai-gcov) - Cache strategy and key naming - All 25 workflows with status, purpose, and dependencies - Third-party integration testing (10 workflows) - Test infrastructure pipeline (ensure-infras → run-tests → cleanup) - TAP group system and hooks - Guide for adding new test workflows Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	3 months ago
René Cannaò	586fb734f8	Move git workflow to top of task template — agents skip buried instructions ... Learned from agent post-mortem: agents prioritize technical content over administrative instructions. Even when branch info is present, agents skim past it while focusing on code requirements, then use heuristics to fill the gap they don't realize they have. Fix: git workflow is now the FIRST section with "do this before reading anything else" label. Also updates common-mistakes.md with the expanded root cause analysis.	3 months ago
René Cannaò	c54e6e1805	Expand task assignment template with learnings from CodeRabbit plans ... Adds four new checklist items based on analyzing CodeRabbit's auto- generated plans for issues #5491 and #5492: - #9: Write ready-made prompts for executing agents — pre-digest the task into imperative, sequential, agent-optimized format - #10: Document design decisions with rationale — prevent agents from re-litigating settled architecture choices - #11: Show the research — make codebase analysis visible for verification and context transfer - #12: For refactoring tasks, specify what to replace — exact line ranges, replacement calls, include dependencies Also adds two new entries to the common mistakes table: - "Recreates existing infrastructure" (research contradicts plan) - "Uses wrong infrastructure" (multiple similar patterns exist) Updates the good-vs-bad example to demonstrate the new items.	3 months ago
René Cannaò	bf250c6307	Add agent guidelines documentation ... Adds doc/agents/ with three guidance documents for AI coding agents, based on lessons learned from Milestone 2-3 unit testing work: - project-conventions.md: ProxySQL-specific rules — directory layout, build system, unit test harness usage, header conventions, circular include dependency warnings, git workflow, dual-protocol coverage - task-assignment-template.md: Generic template and orchestrator checklist for writing GitHub issues that agents can execute correctly. Covers: specifying WHERE/HOW/environment, DO NOT lists, binary acceptance criteria, and the good-vs-bad issue example - common-mistakes.md: Catalog of 9 observed failure patterns with root cause analysis, prevention strategies, and shell commands for detection in agent PRs Also updates CLAUDE.md with a reference to the agent guidelines and a note about the unit test harness.	3 months ago
Rene Cannao	859c89b30e	cluster: harden PostgreSQL cluster sync parity paths after real two-node validation ... This commit turns the current working branch follow-up into one coherent changeset after reviewing the PostgreSQL cluster sync implementation against real multi-node behavior instead of relying only on checksum presence and basic TAP accessibility checks. The main implementation change is that PostgreSQL cluster sync now updates the replica admin-memory tables in the places where the previous branch state was still weaker than the established MySQL behavior. In the PostgreSQL servers path, the replica now rewrites pgsql_servers, pgsql_replication_hostgroups, and pgsql_hostgroup_attributes before promoting the fetched state into runtime. That closes the most important parity gap that showed up during replica-side validation, because the cluster sync operation no longer leaves runtime state correct while replica admin-memory tables lag behind. In the PostgreSQL query rules path, the fetched query-rules and fast-routing resultsets are now hashed using the same converted representation that runtime loading consumes, then passed directly into load_pgsql_query_rules_to_runtime(), and finally written back from runtime into the replica admin-memory tables. In the PostgreSQL users path, the branch now relies on PostgreSQL-specific runtime checksum logic and persists accepted rows into the replica pgsql_users admin-memory table. This commit also fixes a real correctness bug that was discovered only after running a true two-node manual validation flow. The refactored module table in ProxySQL_Cluster::set_checksums() passed the full module names "pgsql_variables" and "ldap_variables" into pull_global_variables_from_peer(), but that shared helper only accepts the short dispatch keys "pgsql" and "ldap". In practice, changing a PostgreSQL variable on the primary caused the replica to abort on an assertion as soon as the cluster monitor attempted the variable pull. This commit restores the correct short dispatch keys so the PostgreSQL and LDAP variable sync paths actually execute instead of crashing. On the TAP side, the PostgreSQL cluster sync test is strengthened so it checks what the implementation is supposed to guarantee rather than what the earlier test happened to probe. The server sync test now mutates the real pgsql_servers admin table, then validates replica runtime_pgsql_servers, replica pgsql_servers, and disk.pgsql_servers when save_to_disk is enabled. The users sync test now validates runtime, main, and optional disk state on the replica. The query-rules sync test now validates both query rules and fast-routing rows across runtime, main, and optional disk persistence. The polling helpers were also hardened to support fresh replica admin sessions, because during local validation a long-lived admin session did not reliably observe synced rows even though fresh sessions and the manual harness did. The test now asserts the externally observable replica state seen by new admin clients. The documentation is updated to reflect the branch as it actually exists after this review pass. The PostgreSQL cluster sync status document now records the remaining non-CI TODO, the module-by-module behavior, the real two-node test plan, the outcomes for save_to_disk=false and save_to_disk=true, the variable sync dispatcher crash that was found and fixed locally, and the current MySQL parity assessment. This makes the branch easier to continue without having to reconstruct the reasoning from terminal logs or partial memory. Validation performed for this commit: - git diff --check - make build_src -j2 - PostgreSQL cluster-sync TAP two-node validation with save_to_disk=false - PostgreSQL cluster-sync TAP two-node validation with save_to_disk=true - manual two-node validation of pgsql_servers, pgsql_replication_hostgroups, pgsql_hostgroup_attributes, and a real PostgreSQL variable with save_to_disk=false - manual two-node validation of the same paths with save_to_disk=true Residual caveat intentionally documented but not treated as a blocker in this commit: - a long-lived replica admin session did not reliably observe synced PostgreSQL rows during polling, while fresh admin sessions and the manual validation harness did observe the expected state - the underlying cluster-sync apply path now validates correctly in real two-node runs, but the admin-session visibility quirk should still be understood better before calling the branch completely finished	3 months ago
Rene Cannao	c2e383701d	doc: add non-CI todo for pgsql cluster sync	3 months ago
Rene Cannao	d702e7d3e9	doc: summarize pgsql cluster sync branch status	3 months ago
Rene Cannao	c98f544db5	Enhance infrastructure stability and dynamic configuration ... - Implement clean slate logic in docker-compose-init.bash (stop containers + wipe data dirs). - Dynamically patch Orchestrator configurations with INFRA_ID-derived ROOT_PASSWORD. - Ensure all literal placeholders are preserved across all infrastructures. - Fix permission issues for PostgreSQL and MySQL log directories. - Verified successful infra-mysql57 initialization and ProxySQL registration.	4 months ago
Rene Cannao	70647fb426	fix: Remove unused legacy mcp-mysql_* variables ... These variables were deprecated in favor of profile-based routing but were never removed from the code. They existed in the struct definition, getters, and setters but were not consumed anywhere - Query_Tool_Handler uses target_auth_map via mcp_auth_profiles and mcp_target_profiles. Removed: - mcp-mysql_hosts, mcp-mysql_ports, mcp-mysql_user, mcp-mysql_password, mcp-mysql_schema from MCP_Thread.h struct - Variable names from mcp_thread_variables_names array - Initialization, cleanup, getters, and setters in MCP_Thread.cpp - Documentation in doc/MCP/VARIABLES.md	4 months ago