From bab7b23351f0cc62125260022009de59cfce06d3 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:23:41 +0200 Subject: [PATCH 01/44] fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) --- .czrc | 2 +- CURRENT_VERSION.txt | 2 +- Changelog | 8 +- USAGE.md | 4 +- mysqltuner.pl | 173 ++++++++- package-lock.json | 775 ++++++++++++++++++++++++++++++++--------- package.json | 1 + releases/v2.9.1.md | 111 +----- releases/v2.9.2.md | 56 +++ tests/test_issue_957.t | 111 ++++++ 10 files changed, 955 insertions(+), 288 deletions(-) create mode 100644 releases/v2.9.2.md create mode 100644 tests/test_issue_957.t diff --git a/.czrc b/.czrc index d1bcc209c..11f040658 100644 --- a/.czrc +++ b/.czrc @@ -1,3 +1,3 @@ { - "path": "cz-conventional-changelog" + "path": "@commitlint/cz-commitlint" } diff --git a/CURRENT_VERSION.txt b/CURRENT_VERSION.txt index dedcc7d43..5d9ade10c 100644 --- a/CURRENT_VERSION.txt +++ b/CURRENT_VERSION.txt @@ -1 +1 @@ -2.9.1 +2.9.2 diff --git a/Changelog b/Changelog index 7b5cfcde6..3233295b6 100644 --- a/Changelog +++ b/Changelog @@ -1,9 +1,11 @@ # MySQLTuner Changelog -2.9.1 2026-07-27 +2.9.2 2026-07-29 +- chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- test(lab): add unit test test_issue_957.t for storage detection logic (#957) -- chore(build): allow build scope in compliance auditor -- chore(build): rewrite dev_sync and doc_sync in Perl for consistency +2.9.1 2026-07-27 - chore(deps): update actions/checkout action to v7.0.0 (#961) - chore(deps): update all non-major dependencies (@commitlint/cli, @commitlint/config-conventional, brace-expansion, commitizen) - chore(deps): update devops-infra/action-commit-push digest to f27e0951b748268e6ac8d91861eeac5bc2bd36a8 (#958) diff --git a/USAGE.md b/USAGE.md index 3baa04647..456341905 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,6 +1,6 @@ # NAME - MySQLTuner 2.9.1 - MySQL High Performance Tuning Script + MySQLTuner 2.9.2 - MySQL High Performance Tuning Script # IMPORTANT USAGE GUIDELINES @@ -15,7 +15,7 @@ See `mysqltuner --help` for a full list of available options and their categorie # VERSION -Version 2.9.1 +Version 2.9.2 =head1 PERLDOC You can find documentation for this module with the perldoc command. diff --git a/mysqltuner.pl b/mysqltuner.pl index 17175878f..b6fe5fb1d 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -1,5 +1,5 @@ #!/usr/bin/env perl -# mysqltuner.pl - Version 2.9.1 +# mysqltuner.pl - Version 2.9.2 # High Performance MySQL Tuning Script # Copyright (C) 2015-2026 Jean-Marie Renouard - jmrenouard@gmail.com # Copyright (C) 2006-2026 Major Hayden - major@mhtx.net @@ -67,7 +67,7 @@ package main; our $is_win = $^O eq 'MSWin32'; # Set up a few variables for use in the script -our $tunerversion = "2.9.1"; +our $tunerversion = "2.9.2"; our ( @adjvars, @generalrec, @modeling, @sysrec, @secrec ); our ( %result, %myvar, %real_vars, %mystat, %mycalc, %myrepl, %myreplicas, $dummyselect ); @@ -2460,30 +2460,169 @@ sub detect_infrastructure { # Storage Detection (Linux only) if ( !$is_win ) { + my $has_ssd = 0; + my $has_hdd = 0; + my $has_hw_raid = 0; + if ( $prefix eq '' ) { # Local Linux detection - my @sys_blocks = glob('/sys/block/*'); - my $has_ssd = 0; - my $has_hdd = 0; + my $sys_block_dir = $ENV{'MYSQLTUNER_SYS_BLOCK_DIR'} + // '/sys/block'; + my @sys_blocks = glob("$sys_block_dir/*"); + + # Check if system has HW RAID controller via lspci if available + my $pci_out = ''; + my $lspci_path = which('lspci'); + if ( defined $lspci_path && -x $lspci_path ) { + my @lspci = execute_system_command( +"$lspci_path -d ::0104 2>/dev/null || $lspci_path 2>/dev/null" + ); + $pci_out = join( ' ', @lspci ); + } + if ( $pci_out =~ +/RAID|MegaRAID|AVAGO|LSI|Smart\s*Array|PERC|Adaptec|3ware|ServeRAID/i + ) + { + $has_hw_raid = 1; + } + foreach my $block (@sys_blocks) { my $name = basename($block); - next if $name =~ /^loop|^ram|^nbd|^zram/; + next if $name =~ /^loop|^ram|^nbd|^zram|^dm-|^md/; + + # 1. NVMe devices are inherently SSD + if ( $name =~ /^nvme/ ) { + $has_ssd = 1; + next; + } + + # 2. Check vendor / model for HW RAID controllers + my $vendor = ''; + my $model = ''; + if ( open( my $vf, '<', "$block/device/vendor" ) ) { + $vendor = <$vf> // ''; + chomp($vendor); + close($vf); + } + if ( open( my $mf, '<', "$block/device/model" ) ) { + $model = <$mf> // ''; + chomp($model); + close($model); + } + if ( "$vendor $model" =~ +/MegaRAID|AVAGO|PERC|LSI|Smart\s*Array|ServeRAID|Adaptec|AACRAID|3ware|Areca|RAID/i + ) + { + $has_hw_raid = 1; + } + + # 3. Check discard_granularity (TRIM support -> SSD) + my $discard = 0; + if ( open( my $df, '<', "$block/queue/discard_granularity" ) ) { + my $d_val = <$df> // '0'; + chomp($d_val); + close($df); + if ( defined $d_val && $d_val =~ /^\d+$/ && $d_val > 0 ) { + $discard = $d_val; + } + } + + # 4. Check rotational flag + my $is_rot; if ( open( my $rot, '<', "$block/queue/rotational" ) ) { - my $is_rot = <$rot>; + $is_rot = <$rot>; chomp($is_rot); close($rot); - if ( defined $is_rot ) { - if ( $is_rot == 0 ) { $has_ssd = 1; } - else { $has_hdd = 1; } + } + + if ( defined $is_rot ) { + if ( $is_rot == 0 || $discard > 0 ) { + $has_ssd = 1; + } + elsif ( $is_rot == 1 && !$has_hw_raid ) { + $has_hdd = 1; + } + } + } + + # 5. Helper CLI checks for HW RAID if installed (storcli / megacli / smartctl) + if ( $has_hw_raid && !$has_ssd ) { + my $storcli = + which('storcli') || which('storcli64') || which('megacli'); + if ( defined $storcli && -x $storcli ) { + my @raid_info = execute_system_command( +"$storcli /c0 show all 2>/dev/null || $storcli -pdlist -aall 2>/dev/null" + ); + my $raid_txt = join( ' ', @raid_info ); + if ( $raid_txt =~ +/Media\s*Type\s*:\s*SSD|Drive\s*Type\s*:\s*SSD|Solid\s*State|SSD/i + ) + { + $has_ssd = 1; + } + if ( $raid_txt =~ +/Media\s*Type\s*:\s*HDD|Drive\s*Type\s*:\s*HDD|Hard\s*Disk|HDD/i + ) + { + $has_hdd = 1; + } + } + } + + if ( $has_ssd && !$has_hdd ) { + $infra{'storage_type'} = 'SSD/NVMe'; + } + elsif ( !$has_ssd && $has_hdd ) { + $infra{'storage_type'} = 'HDD'; + } + elsif ( $has_ssd && $has_hdd ) { + $infra{'storage_type'} = 'Mixed'; + } + elsif ($has_hw_raid) { + + # Hardware RAID present, physical media unconfirmed -> safe unknown + $infra{'storage_type'} = 'unknown'; + } + } + else { + # Remote / Transport storage detection + my @lsblk_out = execute_system_command( + "lsblk -d -n -o NAME,ROTA,DISC-GRAN,MODEL 2>/dev/null"); + foreach my $line (@lsblk_out) { + chomp($line); + next if $line =~ /^loop|^ram|^nbd|^zram|^dm-|^md/; + my ( $name, $rota, $gran, $model ) = split( /\s+/, $line, 4 ); + $model //= ''; + if ( ( $name // '' ) =~ /^nvme/ + || ( $gran // 0 ) > 0 + || ( $rota // 1 ) eq '0' ) + { + $has_ssd = 1; + } + elsif ( ( $rota // '' ) eq '1' ) { + if ( $model =~ + /MegaRAID|AVAGO|PERC|LSI|Smart\s*Array|RAID/i ) + { + $has_hw_raid = 1; + } + else { + $has_hdd = 1; } } } if ( $has_ssd && !$has_hdd ) { $infra{'storage_type'} = 'SSD/NVMe'; } - elsif ( !$has_ssd && $has_hdd ) { $infra{'storage_type'} = 'HDD'; } - elsif ( $has_ssd && $has_hdd ) { $infra{'storage_type'} = 'Mixed'; } + elsif ( !$has_ssd && $has_hdd ) { + $infra{'storage_type'} = 'HDD'; + } + elsif ( $has_ssd && $has_hdd ) { + $infra{'storage_type'} = 'Mixed'; + } + elsif ($has_hw_raid) { + $infra{'storage_type'} = 'unknown'; + } } } @@ -3677,7 +3816,7 @@ sub write_manifest_files { } my $json_content = - "{\n \"version\": \"" . ( $tunerversion // '2.9.1' ) . "\",\n"; + "{\n \"version\": \"" . ( $tunerversion // '2.9.2' ) . "\",\n"; $json_content .= " \"exported_at\": \"" . scalar( gmtime() ) . " UTC\",\n"; $json_content .= " \"total_files\": $total_files,\n"; $json_content .= " \"total_size_bytes\": $total_size,\n"; @@ -3693,7 +3832,7 @@ sub write_manifest_files { my $meta_content = "MySQLTuner Offline Diagnostic Snapshot Metadata\n"; $meta_content .= "================================================\n"; - $meta_content .= "Version: " . ( $tunerversion // '2.9.1' ) . "\n"; + $meta_content .= "Version: " . ( $tunerversion // '2.9.2' ) . "\n"; $meta_content .= "Exported At: " . scalar( gmtime() ) . " UTC\n"; $meta_content .= "Host: " . ( $myvar{'hostname'} // 'unknown' ) . "\n"; $meta_content .= @@ -8186,6 +8325,8 @@ sub mysql_stats { if ( defined $myvar{'table_open_cache_instances'} and $myvar{'table_open_cache_instances'} > 0 ) { +# MariaDB 10.2.2+ autosizes table_open_cache_instances dynamically upon contention +# Ref: https://mariadb.com/kb/en/server-system-variables/#table_open_cache_instances infoprint "MariaDB 10.2.2+ autosizes table_open_cache_instances. Current value is $myvar{'table_open_cache_instances'}."; } @@ -16449,7 +16590,7 @@ sub dump_csv_files { =head1 NAME - MySQLTuner 2.9.1 - MySQL High Performance Tuning Script + MySQLTuner 2.9.2 - MySQL High Performance Tuning Script =head1 IMPORTANT USAGE GUIDELINES @@ -16464,7 +16605,7 @@ =head1 OPTIONS =head1 VERSION -Version 2.9.1 +Version 2.9.2 =head1 PERLDOC You can find documentation for this module with the perldoc command. diff --git a/package-lock.json b/package-lock.json index b11559aa6..e5f8d6b2d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,6 +11,7 @@ "devDependencies": { "@commitlint/cli": "21.2.1", "@commitlint/config-conventional": "21.2.0", + "@commitlint/cz-commitlint": "21.2.0", "commitizen": "4.3.2", "cz-conventional-changelog": "3.3.0", "husky": "9.1.7" @@ -92,6 +93,28 @@ "node": ">=22.12.0" } }, + "node_modules/@commitlint/cz-commitlint": { + "version": "21.2.0", + "resolved": "https://registry.npmjs.org/@commitlint/cz-commitlint/-/cz-commitlint-21.2.0.tgz", + "integrity": "sha512-oN+6sTWNe5tKZopo7/0hn69kfSnI9qpGMd2M9gQxB4UigdGU+7xsCNwqRfWgRMFczoVfsXTHtdM90b/jhx/27A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@commitlint/ensure": "^21.2.0", + "@commitlint/load": "^21.2.0", + "@commitlint/types": "^21.2.0", + "is-plain-obj": "^4.1.0", + "picocolors": "^1.1.1", + "word-wrap": "^1.2.5" + }, + "engines": { + "node": ">=22.12.0" + }, + "peerDependencies": { + "commitizen": "^4.0.3", + "inquirer": "^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0" + } + }, "node_modules/@commitlint/ensure": { "version": "21.2.0", "resolved": "https://registry.npmjs.org/@commitlint/ensure/-/ensure-21.2.0.tgz", @@ -329,6 +352,143 @@ "node": ">=22" } }, + "node_modules/@inquirer/ansi": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@inquirer/ansi/-/ansi-1.0.2.tgz", + "integrity": "sha512-S8qNSZiYzFd0wAcyG5AXCvUHC5Sr7xpZ9wZ2py9XR88jUz8wooStVx5M6dRzczbBWjic9NP7+rY0Xi7qqK/aMQ==", + "dev": true, + "license": "MIT", + "peer": true, + "engines": { + "node": ">=18" + } + }, + "node_modules/@inquirer/checkbox": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/@inquirer/checkbox/-/checkbox-4.3.2.tgz", + "integrity": "sha512-VXukHf0RR1doGe6Sm4F0Em7SWYLTHSsbGfJdS9Ja2bX5/D5uwVOEjr07cncLROdBvmnvCATYEWlHqYmXv2IlQA==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/ansi": "^1.0.2", + "@inquirer/core": "^10.3.2", + "@inquirer/figures": "^1.0.15", + "@inquirer/type": "^3.0.10", + "yoctocolors-cjs": "^2.1.3" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/confirm": { + "version": "5.1.21", + "resolved": "https://registry.npmjs.org/@inquirer/confirm/-/confirm-5.1.21.tgz", + "integrity": "sha512-KR8edRkIsUayMXV+o3Gv+q4jlhENF9nMYUZs9PA2HzrXeHI8M5uDag70U7RJn9yyiMZSbtF5/UexBtAVtZGSbQ==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/type": "^3.0.10" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/core": { + "version": "10.3.2", + "resolved": "https://registry.npmjs.org/@inquirer/core/-/core-10.3.2.tgz", + "integrity": "sha512-43RTuEbfP8MbKzedNqBrlhhNKVwoK//vUFNW3Q3vZ88BLcrs4kYpGg+B2mm5p2K/HfygoCxuKwJJiv8PbGmE0A==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/ansi": "^1.0.2", + "@inquirer/figures": "^1.0.15", + "@inquirer/type": "^3.0.10", + "cli-width": "^4.1.0", + "mute-stream": "^2.0.0", + "signal-exit": "^4.1.0", + "wrap-ansi": "^6.2.0", + "yoctocolors-cjs": "^2.1.3" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/editor": { + "version": "4.2.23", + "resolved": "https://registry.npmjs.org/@inquirer/editor/-/editor-4.2.23.tgz", + "integrity": "sha512-aLSROkEwirotxZ1pBaP8tugXRFCxW94gwrQLxXfrZsKkfjOYC1aRvAZuhpJOb5cu4IBTJdsCigUlf2iCOu4ZDQ==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/external-editor": "^1.0.3", + "@inquirer/type": "^3.0.10" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/expand": { + "version": "4.0.23", + "resolved": "https://registry.npmjs.org/@inquirer/expand/-/expand-4.0.23.tgz", + "integrity": "sha512-nRzdOyFYnpeYTTR2qFwEVmIWypzdAx/sIkCMeTNTcflFOovfqUk+HcFhQQVBftAh9gmGrpFj6QcGEqrDMDOiew==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/type": "^3.0.10", + "yoctocolors-cjs": "^2.1.3" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, "node_modules/@inquirer/external-editor": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/@inquirer/external-editor/-/external-editor-1.0.3.tgz", @@ -351,6 +511,212 @@ } } }, + "node_modules/@inquirer/figures": { + "version": "1.0.15", + "resolved": "https://registry.npmjs.org/@inquirer/figures/-/figures-1.0.15.tgz", + "integrity": "sha512-t2IEY+unGHOzAaVM5Xx6DEWKeXlDDcNPeDyUpsRc6CUhBfU3VQOEl+Vssh7VNp1dR8MdUJBWhuObjXCsVpjN5g==", + "dev": true, + "license": "MIT", + "peer": true, + "engines": { + "node": ">=18" + } + }, + "node_modules/@inquirer/input": { + "version": "4.3.1", + "resolved": "https://registry.npmjs.org/@inquirer/input/-/input-4.3.1.tgz", + "integrity": "sha512-kN0pAM4yPrLjJ1XJBjDxyfDduXOuQHrBB8aLDMueuwUGn+vNpF7Gq7TvyVxx8u4SHlFFj4trmj+a2cbpG4Jn1g==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/type": "^3.0.10" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/number": { + "version": "3.0.23", + "resolved": "https://registry.npmjs.org/@inquirer/number/-/number-3.0.23.tgz", + "integrity": "sha512-5Smv0OK7K0KUzUfYUXDXQc9jrf8OHo4ktlEayFlelCjwMXz0299Y8OrI+lj7i4gCBY15UObk76q0QtxjzFcFcg==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/type": "^3.0.10" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/password": { + "version": "4.0.23", + "resolved": "https://registry.npmjs.org/@inquirer/password/-/password-4.0.23.tgz", + "integrity": "sha512-zREJHjhT5vJBMZX/IUbyI9zVtVfOLiTO66MrF/3GFZYZ7T4YILW5MSkEYHceSii/KtRk+4i3RE7E1CUXA2jHcA==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/ansi": "^1.0.2", + "@inquirer/core": "^10.3.2", + "@inquirer/type": "^3.0.10" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/prompts": { + "version": "7.10.1", + "resolved": "https://registry.npmjs.org/@inquirer/prompts/-/prompts-7.10.1.tgz", + "integrity": "sha512-Dx/y9bCQcXLI5ooQ5KyvA4FTgeo2jYj/7plWfV5Ak5wDPKQZgudKez2ixyfz7tKXzcJciTxqLeK7R9HItwiByg==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/checkbox": "^4.3.2", + "@inquirer/confirm": "^5.1.21", + "@inquirer/editor": "^4.2.23", + "@inquirer/expand": "^4.0.23", + "@inquirer/input": "^4.3.1", + "@inquirer/number": "^3.0.23", + "@inquirer/password": "^4.0.23", + "@inquirer/rawlist": "^4.1.11", + "@inquirer/search": "^3.2.2", + "@inquirer/select": "^4.4.2" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/rawlist": { + "version": "4.1.11", + "resolved": "https://registry.npmjs.org/@inquirer/rawlist/-/rawlist-4.1.11.tgz", + "integrity": "sha512-+LLQB8XGr3I5LZN/GuAHo+GpDJegQwuPARLChlMICNdwW7OwV2izlCSCxN6cqpL0sMXmbKbFcItJgdQq5EBXTw==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/type": "^3.0.10", + "yoctocolors-cjs": "^2.1.3" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/search": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/@inquirer/search/-/search-3.2.2.tgz", + "integrity": "sha512-p2bvRfENXCZdWF/U2BXvnSI9h+tuA8iNqtUKb9UWbmLYCRQxd8WkvwWvYn+3NgYaNwdUkHytJMGG4MMLucI1kA==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/core": "^10.3.2", + "@inquirer/figures": "^1.0.15", + "@inquirer/type": "^3.0.10", + "yoctocolors-cjs": "^2.1.3" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/select": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/@inquirer/select/-/select-4.4.2.tgz", + "integrity": "sha512-l4xMuJo55MAe+N7Qr4rX90vypFwCajSakx59qe/tMaC1aEHWLyw68wF4o0A4SLAY4E0nd+Vt+EyskeDIqu1M6w==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "@inquirer/ansi": "^1.0.2", + "@inquirer/core": "^10.3.2", + "@inquirer/figures": "^1.0.15", + "@inquirer/type": "^3.0.10", + "yoctocolors-cjs": "^2.1.3" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@inquirer/type": { + "version": "3.0.10", + "resolved": "https://registry.npmjs.org/@inquirer/type/-/type-3.0.10.tgz", + "integrity": "sha512-BvziSRxfz5Ov8ch0z/n3oijRSEcEsHnhggm4xFZe93DHcUCTlutlq9Ox4SVENAfcRD22UQq7T/atg9Wr3k09eA==", + "dev": true, + "license": "MIT", + "peer": true, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, "node_modules/@simple-libs/child-process-utils": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/@simple-libs/child-process-utils/-/child-process-utils-2.0.0.tgz", @@ -1000,13 +1366,14 @@ } }, "node_modules/cli-width": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/cli-width/-/cli-width-3.0.0.tgz", - "integrity": "sha512-FxqpkPPwu1HjuN93Omfm4h8uIanXofW0RxVEW3k5RKx+mJJYSthzNhp32Kzxxy3YAEZ/Dc/EWN1vZRY0+kOhbw==", + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/cli-width/-/cli-width-4.1.0.tgz", + "integrity": "sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==", "dev": true, "license": "ISC", + "peer": true, "engines": { - "node": ">= 10" + "node": ">= 12" } }, "node_modules/cliui": { @@ -1085,86 +1452,216 @@ "ansi-regex": "^6.2.2" }, "engines": { - "node": ">=12" + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/cliui/node_modules/wrap-ansi": { + "version": "9.0.2", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz", + "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.1", + "string-width": "^7.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/clone": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/clone/-/clone-1.0.4.tgz", + "integrity": "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.8" + } + }, + "node_modules/color-convert": { + "version": "1.9.3", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", + "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "dev": true, + "license": "MIT", + "dependencies": { + "color-name": "1.1.3" + } + }, + "node_modules/color-name": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", + "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "dev": true, + "license": "MIT" + }, + "node_modules/commitizen": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/commitizen/-/commitizen-4.3.2.tgz", + "integrity": "sha512-1Zs37z9JPvAcuTSSricZZwBhOPVNNxJouuY4yDEt+eD70EoxT2TU9kViG8CuB/PmVg2G4XsAGQiK4YCst97aDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "cachedir": "2.4.0", + "cz-conventional-changelog": "3.3.0", + "dedent": "0.7.0", + "detect-indent": "6.1.0", + "find-node-modules": "^2.1.2", + "find-root": "1.1.0", + "fs-extra": "9.1.0", + "glob": "7.2.3", + "inquirer": "8.2.7", + "is-utf8": "^0.2.1", + "lodash": "4.18.1", + "minimist": "1.2.8", + "strip-bom": "4.0.0", + "strip-json-comments": "3.1.1" + }, + "bin": { + "commitizen": "bin/commitizen", + "cz": "bin/git-cz", + "git-cz": "bin/git-cz" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/commitizen/node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "dev": true, + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/commitizen/node_modules/chalk": { + "version": "4.1.2", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", + "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=10" }, "funding": { - "url": "https://github.com/chalk/strip-ansi?sponsor=1" + "url": "https://github.com/chalk/chalk?sponsor=1" } }, - "node_modules/cliui/node_modules/wrap-ansi": { - "version": "9.0.2", - "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz", - "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==", + "node_modules/commitizen/node_modules/cli-width": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/cli-width/-/cli-width-3.0.0.tgz", + "integrity": "sha512-FxqpkPPwu1HjuN93Omfm4h8uIanXofW0RxVEW3k5RKx+mJJYSthzNhp32Kzxxy3YAEZ/Dc/EWN1vZRY0+kOhbw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">= 10" + } + }, + "node_modules/commitizen/node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", "dev": true, "license": "MIT", "dependencies": { - "ansi-styles": "^6.2.1", - "string-width": "^7.0.0", - "strip-ansi": "^7.1.0" + "color-name": "~1.1.4" }, "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + "node": ">=7.0.0" } }, - "node_modules/clone": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/clone/-/clone-1.0.4.tgz", - "integrity": "sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==", + "node_modules/commitizen/node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "dev": true, + "license": "MIT" + }, + "node_modules/commitizen/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", "dev": true, "license": "MIT", "engines": { - "node": ">=0.8" + "node": ">=8" } }, - "node_modules/color-convert": { - "version": "1.9.3", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-1.9.3.tgz", - "integrity": "sha512-QfAUtd+vFdAtFQcC8CCyYt1fYWxSqAiK2cSD6zDB8N3cpsEBAvRxp9zOGg6G/SHHJYAT88/az/IuDGALsNVbGg==", + "node_modules/commitizen/node_modules/inquirer": { + "version": "8.2.7", + "resolved": "https://registry.npmjs.org/inquirer/-/inquirer-8.2.7.tgz", + "integrity": "sha512-UjOaSel/iddGZJ5xP/Eixh6dY1XghiBw4XK13rCCIJcJfyhhoul/7KhLLUGtebEj6GDYM6Vnx/mVsjx2L/mFIA==", "dev": true, "license": "MIT", "dependencies": { - "color-name": "1.1.3" + "@inquirer/external-editor": "^1.0.0", + "ansi-escapes": "^4.2.1", + "chalk": "^4.1.1", + "cli-cursor": "^3.1.0", + "cli-width": "^3.0.0", + "figures": "^3.0.0", + "lodash": "^4.17.21", + "mute-stream": "0.0.8", + "ora": "^5.4.1", + "run-async": "^2.4.0", + "rxjs": "^7.5.5", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0", + "through": "^2.3.6", + "wrap-ansi": "^6.0.1" + }, + "engines": { + "node": ">=12.0.0" } }, - "node_modules/color-name": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.3.tgz", - "integrity": "sha512-72fSenhMw2HZMTVHeCA9KCmpEIbzWiQsjN+BHcBbS9vr1mtt+vJjPdksIBNUmKAW8TFUDPJK5SUU3QhE9NEXDw==", + "node_modules/commitizen/node_modules/mute-stream": { + "version": "0.0.8", + "resolved": "https://registry.npmjs.org/mute-stream/-/mute-stream-0.0.8.tgz", + "integrity": "sha512-nnbWWOkoWyUsTjKrhgD0dcz22mdkSnpYqbEjIm2nhwhuxlSkpywJmBo8h0ZqJdkp73mb90SssHkN4rsRaBAfAA==", "dev": true, - "license": "MIT" + "license": "ISC" }, - "node_modules/commitizen": { - "version": "4.3.2", - "resolved": "https://registry.npmjs.org/commitizen/-/commitizen-4.3.2.tgz", - "integrity": "sha512-1Zs37z9JPvAcuTSSricZZwBhOPVNNxJouuY4yDEt+eD70EoxT2TU9kViG8CuB/PmVg2G4XsAGQiK4YCst97aDQ==", + "node_modules/commitizen/node_modules/run-async": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/run-async/-/run-async-2.4.1.tgz", + "integrity": "sha512-tvVnVv01b8c1RrA6Ep7JkStj85Guv/YrMcwqYQnwjsAS2cTmmPGBBjAjpCW7RrSodNSoE2/qg9O4bceNvUuDgQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/commitizen/node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", "dev": true, "license": "MIT", "dependencies": { - "cachedir": "2.4.0", - "cz-conventional-changelog": "3.3.0", - "dedent": "0.7.0", - "detect-indent": "6.1.0", - "find-node-modules": "^2.1.2", - "find-root": "1.1.0", - "fs-extra": "9.1.0", - "glob": "7.2.3", - "inquirer": "8.2.7", - "is-utf8": "^0.2.1", - "lodash": "4.18.1", - "minimist": "1.2.8", - "strip-bom": "4.0.0", - "strip-json-comments": "3.1.1" - }, - "bin": { - "commitizen": "bin/commitizen", - "cz": "bin/git-cz", - "git-cz": "bin/git-cz" + "has-flag": "^4.0.0" }, "engines": { - "node": ">= 18" + "node": ">=8" } }, "node_modules/conventional-changelog-angular": { @@ -1747,106 +2244,31 @@ } }, "node_modules/inquirer": { - "version": "8.2.7", - "resolved": "https://registry.npmjs.org/inquirer/-/inquirer-8.2.7.tgz", - "integrity": "sha512-UjOaSel/iddGZJ5xP/Eixh6dY1XghiBw4XK13rCCIJcJfyhhoul/7KhLLUGtebEj6GDYM6Vnx/mVsjx2L/mFIA==", - "dev": true, - "license": "MIT", - "dependencies": { - "@inquirer/external-editor": "^1.0.0", - "ansi-escapes": "^4.2.1", - "chalk": "^4.1.1", - "cli-cursor": "^3.1.0", - "cli-width": "^3.0.0", - "figures": "^3.0.0", - "lodash": "^4.17.21", - "mute-stream": "0.0.8", - "ora": "^5.4.1", - "run-async": "^2.4.0", - "rxjs": "^7.5.5", - "string-width": "^4.1.0", - "strip-ansi": "^6.0.0", - "through": "^2.3.6", - "wrap-ansi": "^6.0.1" - }, - "engines": { - "node": ">=12.0.0" - } - }, - "node_modules/inquirer/node_modules/ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "dev": true, - "license": "MIT", - "dependencies": { - "color-convert": "^2.0.1" - }, - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/inquirer/node_modules/chalk": { - "version": "4.1.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", - "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", + "version": "12.11.1", + "resolved": "https://registry.npmjs.org/inquirer/-/inquirer-12.11.1.tgz", + "integrity": "sha512-9VF7mrY+3OmsAfjH3yKz/pLbJ5z22E23hENKw3/LNSaA/sAt3v49bDRY+Ygct1xwuKT+U+cBfTzjCPySna69Qw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { - "ansi-styles": "^4.1.0", - "supports-color": "^7.1.0" + "@inquirer/ansi": "^1.0.2", + "@inquirer/core": "^10.3.2", + "@inquirer/prompts": "^7.10.1", + "@inquirer/type": "^3.0.10", + "mute-stream": "^2.0.0", + "run-async": "^4.0.6", + "rxjs": "^7.8.2" }, "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/chalk?sponsor=1" - } - }, - "node_modules/inquirer/node_modules/color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "dev": true, - "license": "MIT", - "dependencies": { - "color-name": "~1.1.4" + "node": ">=18" }, - "engines": { - "node": ">=7.0.0" - } - }, - "node_modules/inquirer/node_modules/color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", - "dev": true, - "license": "MIT" - }, - "node_modules/inquirer/node_modules/has-flag": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", - "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/inquirer/node_modules/supports-color": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", - "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", - "dev": true, - "license": "MIT", - "dependencies": { - "has-flag": "^4.0.0" + "peerDependencies": { + "@types/node": ">=18" }, - "engines": { - "node": ">=8" + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } } }, "node_modules/is-arrayish": { @@ -2205,11 +2627,15 @@ } }, "node_modules/mute-stream": { - "version": "0.0.8", - "resolved": "https://registry.npmjs.org/mute-stream/-/mute-stream-0.0.8.tgz", - "integrity": "sha512-nnbWWOkoWyUsTjKrhgD0dcz22mdkSnpYqbEjIm2nhwhuxlSkpywJmBo8h0ZqJdkp73mb90SssHkN4rsRaBAfAA==", + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mute-stream/-/mute-stream-2.0.0.tgz", + "integrity": "sha512-WWdIxpyjEn+FhQJQQv9aQAYlHoNVdzIzUySNV1gHUPDSdZJ3yZn7pAAbQcV7B56Mvu881q9FZV+0Vx2xC44VWA==", "dev": true, - "license": "ISC" + "license": "ISC", + "peer": true, + "engines": { + "node": "^18.17.0 || >=20.5.0" + } }, "node_modules/once": { "version": "1.4.0", @@ -2472,12 +2898,20 @@ "node": ">=8" } }, + "node_modules/restore-cursor/node_modules/signal-exit": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", + "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "dev": true, + "license": "ISC" + }, "node_modules/run-async": { - "version": "2.4.1", - "resolved": "https://registry.npmjs.org/run-async/-/run-async-2.4.1.tgz", - "integrity": "sha512-tvVnVv01b8c1RrA6Ep7JkStj85Guv/YrMcwqYQnwjsAS2cTmmPGBBjAjpCW7RrSodNSoE2/qg9O4bceNvUuDgQ==", + "version": "4.0.6", + "resolved": "https://registry.npmjs.org/run-async/-/run-async-4.0.6.tgz", + "integrity": "sha512-IoDlSLTs3Yq593mb3ZoKWKXMNu3UpObxhgA/Xuid5p4bbfi2jdY1Hj0m1K+0/tEuQTxIGMhQDqGjKb7RuxGpAQ==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=0.12.0" } @@ -2534,11 +2968,18 @@ } }, "node_modules/signal-exit": { - "version": "3.0.7", - "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", - "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", "dev": true, - "license": "ISC" + "license": "ISC", + "peer": true, + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } }, "node_modules/string_decoder": { "version": "1.3.0", @@ -2899,6 +3340,20 @@ "funding": { "url": "https://github.com/chalk/strip-ansi?sponsor=1" } + }, + "node_modules/yoctocolors-cjs": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/yoctocolors-cjs/-/yoctocolors-cjs-2.1.3.tgz", + "integrity": "sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw==", + "dev": true, + "license": "MIT", + "peer": true, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } } } } diff --git a/package.json b/package.json index 8796bb6c5..5e73e65b4 100644 --- a/package.json +++ b/package.json @@ -28,6 +28,7 @@ "devDependencies": { "@commitlint/cli": "21.2.1", "@commitlint/config-conventional": "21.2.0", + "@commitlint/cz-commitlint": "21.2.0", "commitizen": "4.3.2", "cz-conventional-changelog": "3.3.0", "husky": "9.1.7" diff --git a/releases/v2.9.1.md b/releases/v2.9.1.md index 646dec968..068e7cbc6 100644 --- a/releases/v2.9.1.md +++ b/releases/v2.9.1.md @@ -12,8 +12,11 @@ - feat: recommend slow query log when disabled (#517) - fix: update documentation and code - ci: optimize pre-commit hook to only run unit tests when code, tests, or dependencies are modified +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- test(lab): add unit test test_issue_957.t for storage detection logic (#957) - chore(build): allow build scope in compliance auditor - chore(build): rewrite dev_sync and doc_sync in Perl for consistency +- chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - chore(deps): update actions/checkout action to v7.0.0 (#961) - chore(deps): update all non-major dependencies (@commitlint/cli, @commitlint/config-conventional, brace-expansion, commitizen) - chore(deps): update devops-infra/action-commit-push digest to f27e0951b748268e6ac8d91861eeac5bc2bd36a8 (#958) @@ -120,111 +123,9 @@ ## 🛠️ Internal Commit History -- docs(releases): add GitHub issue references to Changelog and Release Notes (e464db9) -- Merge branch 'major/master' into v2.9.1 to resolve GitHub Action workflow conflicts (1f12622) -- chore: automated project metadata update (4df668a) -- chore(deps): update docker/login-action digest to abd2ef4 (#962) (e1da863) -- docs: regenerate release notes (98564e4) -- style: tidy mysqltuner.pl (01bb574) -- chore(deps): update actions/checkout digest to d23441a (#961) (2a7fbcb) -- docs: regenerate release notes (e45de80) -- docs: regenerate release notes (d6d0b3e) -- style: tidy mysqltuner.pl (b493719) -- ci(build): implement static SQL linter and fix PFS deadlock error query (48e0472) -- docs: regenerate release notes (317883d) -- docs: regenerate release notes (6551702) -- chore(deps): update docker/setup-buildx-action digest to bb05f3f (#959) (fa2ab7d) -- chore: automated project metadata update (504dce8) -- chore(deps): update devops-infra/action-commit-push digest to f27e095 (#958) (d943b35) -- docs: regenerate release notes (fe66f7f) -- fix(main): resolve uninitialized warnings in auto-increment audit and fix split delimiters (049b59a) -- docs: regenerate release notes (5340c55) -- fix(main): support '0' and 'OFF' value representations when checking slow query log status (#517) (b9f4083) -- docs: regenerate release notes (bb4ae91) -- test(lab): add HA topology E2E tests, MCP server E2E test, and dedicated output analyzer (2999bad) -- test(test): verify replication terminology and checksums in unit tests (#888) (18d1da0) -- docs: regenerate release notes (07193c5) -- fix(main): query events_errors_summary_global_by_error safely (#956, jmrenouard#64) (28b50b3) -- docs: regenerate release notes (0a06930) -- docs: regenerate release notes (08fa6a8) -- docs: regenerate release notes (938b2ed) -- docs(roadmap): add Phase 22 for High Availability & Replication Auto-Discovery (372751e) -- docs: regenerate release notes (682abca) -- docs: regenerate release notes (3f41b8a) -- docs: regenerate release notes (11895cb) -- docs: link recent features to jmrenouard fork issues in Changelog (f2bacfd) -- docs: regenerate release notes (adee75b) -- docs: regenerate release notes (f20c04e) -- docs: regenerate release notes (cf6f35a) -- docs: link recent features to GitHub issues in Changelog (bffa416) -- docs: regenerate release notes (8420a45) -- docs: regenerate release notes (1741b75) -- docs: regenerate release notes (688261e) -- docs: add MCP and AI integration guide for MySQL database tuning (b30eefe) -- docs: generate end-of-life status files (19d60a7) -- docs: generate FEATURES.md (e14b427) -- docs: regenerate release notes (f121ab1) -- docs: regenerate release notes (dcc1d0b) -- docs: add AGENT.md integration guide for AI and MCP server (a24b5da) -- docs: regenerate release notes (a0338fb) -- docs: regenerate release notes (67ed38c) -- docs(roadmap): group strategic technical evolutions into phases 18 to 21 (de35c9c) -- docs: regenerate release notes (31ec11c) -- docs: regenerate release notes (1156c3b) -- docs(roadmap): mark Phase 16 and 17 as completed in ROADMAP.md (5d5831f) -- docs: regenerate release notes (2c961ba) -- feat(cli): implement agent-json flag returning structured actionable schema (d71fdbc) -- docs: regenerate release notes (81ae23a) -- docs: regenerate release notes (7846c46) -- docs: regenerate release notes (89004df) -- feat(container): implement dockerized auditing daemon and zero-dependency MCP server (975977c) -- docs: regenerate release notes for v2.9.1 (c0f4161) -- docs(roadmap): mark Phase 12 as completed in ROADMAP.md (dd288c2) -- docs: regenerate release notes (56d1eee) -- docs: regenerate release notes (3978e7a) -- docs: regenerate release notes (50f7224) -- docs: regenerate release notes (e1cc6b4) -- feat(main): implement advanced log parser and lock monitoring (23e42e6) -- chore(docs): add custom rule for GitHub issue creation (e3250c7) -- docs: regenerate release notes (0af805a) -- docs: regenerate release notes (7854d3b) -- docs: regenerate release notes (2896bbd) -- test(test): add unit tests for potential issues and split unit_coverage_boost3 (c328efd) -- docs: regenerate release notes (c5fdc7d) -- docs: regenerate release notes (0ec038f) -- docs: update potential issues log with Renovate dependency dashboard analysis (0842ba6) -- docs: regenerate release notes (d5046d4) -- docs: regenerate release notes (c2ec01e) -- feat(report): implement workload traffic profiling and query waits analysis (89fa655) -- docs: regenerate release notes (a3b5ef6) -- docs: regenerate release notes (5fe8d27) -- docs: update potential issues log with Phase 9 Galera audit findings (af711cc) -- docs: regenerate release notes (5d424b7) -- docs: regenerate release notes (372d930) -- docs: regenerate release notes (4fd59e8) -- feat(report): implement advanced Galera Cluster 4 and PXC 8.0 diagnostics (316ace4) -- docs: regenerate release notes (503f1ca) -- docs: regenerate release notes (0c1fa81) -- feat(report): implement HA InnoDB Cluster diagnostics and Group Replication checks (8e9bdd6) -- docs: regenerate release notes (3e7ea60) -- docs: regenerate release notes (6b240ce) -- chore(docs): update potential issues log with release v2.9.0 and v2.9.1 audit results (590e838) -- docs: regenerate release notes (26a7c12) -- docs: regenerate release notes (833f0ab) -- chore(docs): implement rule to decompose unit tests into readable segments (d922e52) -- chore(docs): update agent best practices and customization rules (63d4513) -- docs: regenerate release notes (45e740f) -- docs: regenerate release notes (7f2e769) -- test(test): add unit_replication_internals.t to validate Phase 8 replication features (55953ec) -- docs: regenerate release notes (67d9c47) -- docs: regenerate release notes (da85245) -- feat(report): implement phase 6 deep engine tuning and mark phase 8 completed (728dd29) -- docs: regenerate release notes (aab8b0a) -- docs: regenerate release notes (62ce873) -- docs: regenerate release notes (3bd8c15) -- chore(releases): start v2.9.1 branch with version bump and dependency updates (6d1e6a2) -- chore(deps): update docker/login-action digest to af1e73f (#940) (618b6dd) -- chore(deps): update docker/build-push-action digest to 53b7df9 (#939) (3b680e7) +- chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) (acd9b12) +- docs: regenerate release notes (3e60c8e) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (460af93) ## ⚙️ Technical Evolutions diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md new file mode 100644 index 000000000..2d6d19013 --- /dev/null +++ b/releases/v2.9.2.md @@ -0,0 +1,56 @@ +# Release Notes - v2.9.2 + +**Date**: 2026-07-29 + +## 📝 Executive Summary + +```text +2.9.2 2026-07-29 + +- chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- test(lab): add unit test test_issue_957.t for storage detection logic (#957) +``` + +## 📈 Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 15 | 0 | 🛡️ | +| Efficiency Checks | 0 | 0 | 🛡️ | +| Risk Detections | 2 | 0 | 🛡️ | +| Information Points | 13 | 0 | 🛡️ | + +## 🛠️ Internal Commit History + +- docs(releases): regenerate release notes for v2.9.2 (f6f768d) +- docs: generate USAGE.md (45de196) +- chore(release): bump version to 2.9.2 (723d427) +- docs: regenerate release notes (2395c62) +- chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) (acd9b12) +- docs: regenerate release notes (3e60c8e) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (460af93) + +## ⚙️ Technical Evolutions + +### ➕ CLI Options Added +- `--action` +- `--agent-json` +- `--description` +- `--expected_outcome` +- `--findings` +- `--id` +- `--impact_score` +- `--requires_restart` +- `--risk_description` +- `--risk_level` +- `--rollback_statement` +- `--statement` +- `--topic` +- `--type` + +## ✅ Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/tests/test_issue_957.t b/tests/test_issue_957.t new file mode 100644 index 000000000..94da1d4e8 --- /dev/null +++ b/tests/test_issue_957.t @@ -0,0 +1,111 @@ +#!/usr/bin/env perl +use strict; +use warnings; +no warnings 'once'; +use Test::More; +use File::Temp qw(tempdir); +use File::Path qw(make_path); + +# Load MySQLTuner +require './mysqltuner.pl'; +require './tests/MySQLTuner/TestHelper.pm'; + +# Force redefinition of essential subs +no warnings 'redefine'; +*main::execute_system_command = sub { return (); }; +*main::which = sub { return undef; }; +*main::infoprint = sub { }; +*main::goodprint = sub { }; +*main::badprint = sub { }; +*main::subheaderprint = sub { }; +*main::debugprint = sub { }; + +subtest 'Storage Detection Logic - Issue #957' => sub { + subtest 'Hardware RAID with rotational=1 defaults to unknown when unconfirmed' => sub { + my $tmp = tempdir( CLEANUP => 1 ); + make_path("$tmp/sda/queue"); + make_path("$tmp/sda/device"); + + open( my $rf, '>', "$tmp/sda/queue/rotational" ) or die $!; + print $rf "1\n"; + close($rf); + + open( my $df, '>', "$tmp/sda/queue/discard_granularity" ) or die $!; + print $df "0\n"; + close($df); + + open( my $vf, '>', "$tmp/sda/device/vendor" ) or die $!; + print $vf "AVAGO\n"; + close($vf); + + open( my $mf, '>', "$tmp/sda/device/model" ) or die $!; + print $mf "MegaRAID SAS 3108\n"; + close($mf); + + local $ENV{'MYSQLTUNER_SYS_BLOCK_DIR'} = $tmp; + + my $infra = main::detect_infrastructure(); + is( $infra->{'storage_type'}, 'unknown', 'Hardware RAID unconfirmed media defaults to unknown' ); + }; + + subtest 'NVMe block device detected as SSD/NVMe' => sub { + my $tmp = tempdir( CLEANUP => 1 ); + make_path("$tmp/nvme0n1/queue"); + + open( my $rf, '>', "$tmp/nvme0n1/queue/rotational" ) or die $!; + print $rf "0\n"; + close($rf); + + local $ENV{'MYSQLTUNER_SYS_BLOCK_DIR'} = $tmp; + + my $infra = main::detect_infrastructure(); + is( $infra->{'storage_type'}, 'SSD/NVMe', 'NVMe block device correctly detected as SSD/NVMe' ); + }; + + subtest 'Discard granularity > 0 detected as SSD/NVMe' => sub { + my $tmp = tempdir( CLEANUP => 1 ); + make_path("$tmp/sdb/queue"); + + open( my $rf, '>', "$tmp/sdb/queue/rotational" ) or die $!; + print $rf "1\n"; + close($rf); + + open( my $df, '>', "$tmp/sdb/queue/discard_granularity" ) or die $!; + print $df "512\n"; + close($df); + + local $ENV{'MYSQLTUNER_SYS_BLOCK_DIR'} = $tmp; + + my $infra = main::detect_infrastructure(); + is( $infra->{'storage_type'}, 'SSD/NVMe', 'Device with discard_granularity > 0 detected as SSD/NVMe' ); + }; + + subtest 'Standard HDD with rotational=1 detected as HDD' => sub { + my $tmp = tempdir( CLEANUP => 1 ); + make_path("$tmp/sdc/queue"); + make_path("$tmp/sdc/device"); + + open( my $rf, '>', "$tmp/sdc/queue/rotational" ) or die $!; + print $rf "1\n"; + close($rf); + + open( my $df, '>', "$tmp/sdc/queue/discard_granularity" ) or die $!; + print $df "0\n"; + close($df); + + open( my $vf, '>', "$tmp/sdc/device/vendor" ) or die $!; + print $vf "ATA\n"; + close($vf); + + open( my $mf, '>', "$tmp/sdc/device/model" ) or die $!; + print $mf "WDC WD2003FZEX\n"; + close($mf); + + local $ENV{'MYSQLTUNER_SYS_BLOCK_DIR'} = $tmp; + + my $infra = main::detect_infrastructure(); + is( $infra->{'storage_type'}, 'HDD', 'Standard HDD detected as HDD' ); + }; +}; + +done_testing(); From 2b1e39e5a78f773940d819472ffd7b9631aec9f1 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:23:41 +0200 Subject: [PATCH 02/44] docs: regenerate release notes --- releases/v2.9.2.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 2d6d19013..58007f560 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -23,13 +23,18 @@ ## 🛠️ Internal Commit History -- docs(releases): regenerate release notes for v2.9.2 (f6f768d) -- docs: generate USAGE.md (45de196) -- chore(release): bump version to 2.9.2 (723d427) -- docs: regenerate release notes (2395c62) -- chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) (acd9b12) -- docs: regenerate release notes (3e60c8e) -- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (460af93) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) +- chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) +- chore(deps): lock file maintenance (#974) (580d17f) +- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) (14cf8e4) +- chore(deps): update ubuntu:latest docker digest to 3131b4c (bde344b) +- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) (ed8ced9) +- chore(deps): update github/codeql-action digest to e4fba86 (#966) (be53988) +- chore(deps): update docker/login-action digest to dbcb813 (#965) (67acd5e) +- chore(deps): pin dependencies (#964) (a29311e) +- chore(deps): update alpine docker tag to v3.24 (a119f22) +- chore(deps): update actions/checkout action to v7 (d126c1f) +- chore(deps): lock file maintenance (86b04d7) ## ⚙️ Technical Evolutions From eef9803f4bb82cb12e03fd9e705ede83c24c4f53 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:27:10 +0200 Subject: [PATCH 03/44] docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) --- Changelog | 1 + README.fr.md | 1 + README.md | 1 + documentation/mcp_ai_integration_guide.fr.md | 136 ++++++++++++ documentation/mcp_ai_integration_guide.md | 216 +++++++++++++------ releases/v2.9.2.md | 2 + 6 files changed, 294 insertions(+), 63 deletions(-) create mode 100644 documentation/mcp_ai_integration_guide.fr.md diff --git a/Changelog b/Changelog index 3233295b6..cd6b920c1 100644 --- a/Changelog +++ b/Changelog @@ -2,6 +2,7 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) diff --git a/README.fr.md b/README.fr.md index a93b422d3..11df6843d 100644 --- a/README.fr.md +++ b/README.fr.md @@ -26,6 +26,7 @@ Liens utiles * **Versions/Tags :** [https://github.com/major/MySQLTuner-perl/tags](https://github.com/major/MySQLTuner-perl/tags) * **Changelog :** [https://github.com/major/MySQLTuner-perl/blob/master/Changelog](https://github.com/major/MySQLTuner-perl/blob/master/Changelog) * **Images Docker :** [https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags](https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags) +* **Guide d'intégration Agent IA & Serveur MCP :** [Documentation/Guide Serveur MCP IA](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.fr.md) * **Rapports HTML Interactifs (v2.9.0+) :** * [Exemple de rapport MariaDB 11.4](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mariadb114/Schemadir/mysqltuner_report.html) * [Exemple de rapport MySQL 8.4](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mysql84/Schemadir/mysqltuner_report.html) diff --git a/README.md b/README.md index 55bad81a4..74f1901fa 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ Useful Links * **Changelog:** [https://github.com/major/MySQLTuner-perl/blob/master/Changelog](https://github.com/major/MySQLTuner-perl/blob/master/Changelog) * **Docker Images:** [https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags](https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags) * **Useful References:** [Documentation/References](https://github.com/major/MySQLTuner-perl/blob/master/documentation/REFERENCES.md) +* **AI Agent & MCP Server Integration Guide:** [Documentation/AI MCP Server Guide](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.md) * **Interactive HTML Reports (v2.9.0+):** * [MariaDB 11.4 E2E HTML Report Example](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mariadb114/Schemadir/mysqltuner_report.html) * [MySQL 8.4 E2E HTML Report Example](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mysql84/Schemadir/mysqltuner_report.html) diff --git a/documentation/mcp_ai_integration_guide.fr.md b/documentation/mcp_ai_integration_guide.fr.md new file mode 100644 index 000000000..e48d6c278 --- /dev/null +++ b/documentation/mcp_ai_integration_guide.fr.md @@ -0,0 +1,136 @@ +# Guide d'Intégration Agent IA & Serveur Model Context Protocol (MCP) + +Ce document fournit la documentation technique complète pour intégrer MySQLTuner avec des agents d'Intelligence Artificielle (IA), des assistants de code LLM (Claude Desktop, Cursor, VS Code, Antigravity) et des pipelines d'administration automatique de bases de données via le protocole **Model Context Protocol (MCP)** et la télémétrie CLI `--agent-json`. + +--- + +## 🏗️ Vue d'Ensemble de l'Architecture + +MySQLTuner propose une pile d'intégration IA conteneurisée et sans dépendance externe. Elle fait le pont entre la base de données et les clients IA. + +```mermaid +graph TD + subgraph "Couche Client IA" + Claude[Claude Desktop] + Cursor[Cursor IDE] + VSCode[VS Code / Cline / Roo Code] + Custom[Pipeline LLM Personnalisé] + end + + subgraph "Serveur MCP (build/mcp_server.py)" + JSONRPC[Interface stdio JSON-RPC 2.0] + Daemon[Démon d'Audit en Arrière-plan] + CacheManager[Gestionnaire de Cache JSON / HTML] + RollbackEngine[Moteur de Rollback & Transactions] + end + + subgraph "Base de Données & Moteur" + PerlEngine[Moteur Perl MySQLTuner (mysqltuner.pl)] + MySQLInstance[(MySQL / MariaDB / Percona Server)] + end + + Claude <-->|stdio JSON-RPC| JSONRPC + Cursor <-->|stdio JSON-RPC| JSONRPC + VSCode <-->|stdio JSON-RPC| JSONRPC + Custom <-->|stdio JSON-RPC| JSONRPC + + JSONRPC --> Daemon + Daemon -->|Exécute --agent-json| PerlEngine + PerlEngine -->|Télémétrie SQL| MySQLInstance + PerlEngine -->|JSON Structuré| CacheManager + CacheManager -->|Ressources & Recommandations| JSONRPC + RollbackEngine -->|SET GLOBAL / Annulation| MySQLInstance +``` + +--- + +## ⚡ Mode 1 : Intégration Directe CLI (`--agent-json`) + +Lorsqu'il est invoqué avec l'option `--agent-json`, `mysqltuner.pl` supprime toutes les sorties ANSI formatées pour le terminal et émet un schéma JSON structuré unique conçu pour être consommé directement par les agents IA. + +### Commande CLI +```bash +perl mysqltuner.pl --agent-json --host --user --pass +``` + +### Structure du Schéma JSON +```json +{ + "findings": [ + { + "id": "innodb_buffer_pool_size_adjust", + "topic": "Performance", + "description": "La taille du buffer pool InnoDB est sous-dimensionnée pour la charge actuelle.", + "impact_score": 9, + "risk_level": "Medium", + "risk_description": "Augmente la consommation mémoire. Assurez-vous d'avoir suffisamment de RAM libre sur le système.", + "requires_restart": false, + "expected_outcome": "Réduit les E/S disque et augmente le taux de succès du cache.", + "action": { + "type": "SQL", + "statement": "SET GLOBAL innodb_buffer_pool_size = 1073741824;", + "rollback_statement": "SET GLOBAL innodb_buffer_pool_size = 134217728;" + } + } + ] +} +``` + +--- + +## 🔌 Mode 2 : Serveur Model Context Protocol (MCP) + +Le serveur MCP ([build/mcp_server.py](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/build/mcp_server.py)) implémente le standard MCP sur le transport `stdio` en utilisant le protocole JSON-RPC 2.0. + +### Ressources MCP Exposées + +| Ressource URI | Type de Contenu | Description | +| :--- | :--- | :--- | +| `mysqltuner://reports/latest.json` | `application/json` | Accède aux derniers résultats d'audit et à l'état des variables. | +| `mysqltuner://reports/latest.html` | `text/html` | Récupère le rapport analytique interactif au format HTML. | +| `mysqltuner://indicators/summary.json` | `application/json` | Fournit les indicateurs KPI principaux (Performance, Sécurité, Résilience). | + +### Outils MCP Exposés + +1. **`get_latest_audit`** : Récupère instantanément le dernier rapport mis en cache sans solliciter le serveur de base de données. +2. **`run_audit`** : Déclenche une nouvelle exécution de `mysqltuner.pl --agent-json` et rafraîchit le cache. +3. **`apply_recommendation`** : Applique une modification SQL dynamique (`SET GLOBAL`). +4. **`rollback_recommendation`** : Annule une modification précédemment appliquée en utilisant l'état de transaction sauvegardé. + +--- + +## 🚀 Guide de Déploiement + +### Déploiement Microservice Conteneurisé + +L'image Docker officielle ([Dockerfile.mcp](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/Dockerfile.mcp)) regroupe Perl, Python 3, mysql-client et le serveur MCP. + +```bash +docker run -d \ + --name mysqltuner-mcp \ + -e DB_HOST=mysql-server \ + -e DB_PORT=3306 \ + -e DB_USER=root \ + -e DB_PASSWORD=secret_pass \ + -e AUDIT_INTERVAL_HOURS=6 \ + -v /var/cache/mysqltuner:/var/cache/mysqltuner \ + mysqltuner-mcp +``` + +--- + +## 🛡️ Consignes et Prompt Système pour l'Agent IA + +Injectez ce prompt système dans votre environnement client LLM pour garantir une administration sécurisée : + +```markdown +Vous êtes un Administrateur de Bases de Données (DBA) Principal. Vous avez accès au serveur MCP MySQLTuner. + +### Règles de Sécurité : +1. **Inspection Initiale** : Exécutez toujours `get_latest_audit` avant de proposer des modifications. +2. **Évaluation des Risques** : + - Les commandes à risque `Low` / `Medium` sans redémarrage (`requires_restart: false`) peuvent être appliquées après validation de la commande de rollback par l'utilisateur. + - Les commandes à risque `High` / `Critical` ou nécessitant un redémarrage requièrent une confirmation explicite. +3. **Vérification du Rollback** : Indiquez systématiquement la commande `statement` et sa contrepartie `rollback_statement` avant exécution. +4. **Boucle de Validation** : Après application d'une modification, exécutez `run_audit` pour vérifier l'amélioration du score KPI. En cas de régression, exécutez immédiatement `rollback_recommendation`. +``` diff --git a/documentation/mcp_ai_integration_guide.md b/documentation/mcp_ai_integration_guide.md index e8a94984d..f10ff7159 100644 --- a/documentation/mcp_ai_integration_guide.md +++ b/documentation/mcp_ai_integration_guide.md @@ -1,47 +1,159 @@ -# AI & MCP Integration Guide for MySQL Optimization +# AI Agent Integration & Model Context Protocol (MCP) Server Guide -This guide explains how to set up the Model Context Protocol (MCP) server for MySQLTuner and configure AI agents (e.g. Claude Desktop, Cursor, VS Code Extensions) to run deep, automated performance audits and apply safe, rollback-enabled tuning configurations. +This guide provides exhaustive technical documentation for integrating MySQLTuner with Artificial Intelligence (AI) agents, LLM coding assistants, and automated database administration pipelines using the **Model Context Protocol (MCP)** and direct `--agent-json` CLI telemetry. --- -## 📦 Part 1: Setting Up the MCP Server +## 🏗️ Architecture & Component Overview + +MySQLTuner provides a zero-dependency, container-ready AI integration stack. It bridges database engine metrics with modern AI clients (such as Claude Desktop, Cursor IDE, VS Code extensions, Antigravity, and LangChain/LlamaIndex frameworks). + +```mermaid +graph TD + subgraph "AI Client Layer" + Claude[Claude Desktop] + Cursor[Cursor IDE] + VSCode[VS Code / Cline / Roo Code] + Custom[Custom LLM Pipeline] + end + + subgraph "MCP Server Layer (build/mcp_server.py)" + JSONRPC[JSON-RPC 2.0 stdio Interface] + Daemon[Background Audit Daemon] + CacheManager[JSON / HTML Cache Store] + RollbackEngine[Rollback & Transaction Engine] + end + + subgraph "Database & Core Engine" + PerlEngine[MySQLTuner Perl Core (mysqltuner.pl)] + MySQLInstance[(MySQL / MariaDB / Percona Server)] + end + + Claude <-->|stdio JSON-RPC| JSONRPC + Cursor <-->|stdio JSON-RPC| JSONRPC + VSCode <-->|stdio JSON-RPC| JSONRPC + Custom <-->|stdio JSON-RPC| JSONRPC + + JSONRPC --> Daemon + Daemon -->|Executes --agent-json| PerlEngine + PerlEngine -->|SQL Telemetry| MySQLInstance + PerlEngine -->|Structured JSON| CacheManager + CacheManager -->|Resources & Findings| JSONRPC + RollbackEngine -->|SET GLOBAL / Revert| MySQLInstance +``` + +--- -The MySQLTuner MCP server acts as an intermediary bridge between your database and AI agents, exposing database telemetry and actionable SQL recommendations over standard I/O (stdio). +## ⚡ Mode 1: Direct CLI Machine Integration (`--agent-json`) -### Method A: Dockerized Deployment (Recommended) -This method containerizes the entire toolchain (Perl, Python 3, and mysql client utilities) to ensure compatibility. +When invoked with `--agent-json`, `mysqltuner.pl` suppresses ANSI formatting and outputs a clean, single-payload JSON schema designed for direct LLM ingestion or programmatic parsing. + +### CLI Command Syntax +```bash +perl mysqltuner.pl --agent-json --host --user --pass +``` + +### JSON Schema & Field Specifications +```json +{ + "findings": [ + { + "id": "innodb_buffer_pool_size_adjust", + "topic": "Performance", + "description": "InnoDB buffer pool size is under-allocated for current workload.", + "impact_score": 9, + "risk_level": "Medium", + "risk_description": "Increases memory consumption. Ensure sufficient OS-free RAM to prevent OOM swapping.", + "requires_restart": false, + "expected_outcome": "Reduces disk I/O and increases query cache read hits.", + "action": { + "type": "SQL", + "statement": "SET GLOBAL innodb_buffer_pool_size = 1073741824;", + "rollback_statement": "SET GLOBAL innodb_buffer_pool_size = 134217728;" + } + } + ] +} +``` + +#### Field Glossary: +- **`id`**: Deterministic key for the specific diagnostic check. +- **`topic`**: Domain (`Performance`, `Security`, `Reliability`, `Modeling`, `Replication`). +- **`impact_score`**: Estimated optimization value on a scale of `1` (minor) to `10` (critical optimization). +- **`risk_level`**: Safety classification (`Low`, `Medium`, `High`, `Critical`). +- **`risk_description`**: Detailed side-effect analysis (memory allocation, table lock potential, restart requirement). +- **`requires_restart`**: Boolean (`true`/`false`) indicating if `my.cnf` edit and service restart is required. +- **`action`**: Object containing the executable `statement` (`SQL` or `Config`) and its counterpart `rollback_statement`. + +--- + +## 🔌 Mode 2: Model Context Protocol (MCP) Server Interface + +The MySQLTuner MCP server ([build/mcp_server.py](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/build/mcp_server.py)) implements the standard MCP specification over `stdio` transport using JSON-RPC 2.0. + +### Exposed MCP Resources + +| URI Resource | Content Type | Description | +| :--- | :--- | :--- | +| `mysqltuner://reports/latest.json` | `application/json` | Accesses the latest cached audit findings and database variable state. | +| `mysqltuner://reports/latest.html` | `text/html` | Retrieves the interactive HTML analytics report (pgBadger-style visuals). | +| `mysqltuner://indicators/summary.json` | `application/json` | Provides high-level KPI indicators (Performance, Security, Resilience scores). | + +### Exposed MCP Tools + +#### 1. `get_latest_audit` +* **Purpose**: Retrieves cached audit findings instantly without querying the database server. +* **Arguments**: None. + +#### 2. `run_audit` +* **Purpose**: Triggers a live execution of `mysqltuner.pl --agent-json` and updates the cache. +* **Arguments**: None. + +#### 3. `apply_recommendation` +* **Purpose**: Applies a safe, dynamic SQL tuning adjustment (`SET GLOBAL`). +* **Arguments**: + - `statement` (string, required): The SQL command to execute. + - `variable_name` (string, optional): Target variable to capture pre-execution baseline for rollback. + +#### 4. `rollback_recommendation` +* **Purpose**: Reverts a previously applied SQL modification using recorded transaction state. +* **Arguments**: + - `statement_id` (string, required): Transaction identifier returned during `apply_recommendation`. + +--- + +## 🚀 Deployment & Configuration Guide + +### Containerized Deployment (Recommended Microservice) + +The official Docker image ([Dockerfile.mcp](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/Dockerfile.mcp)) packages Perl, Python 3, mysql-client, and the MCP server. ```bash docker run -d \ --name mysqltuner-mcp \ - -e DB_HOST=your-database-host \ + -e DB_HOST=mysql-server \ -e DB_PORT=3306 \ - -e DB_USER=tuner_user \ - -e DB_PASSWORD=your_password \ + -e DB_USER=root \ + -e DB_PASSWORD=secret_pass \ -e AUDIT_INTERVAL_HOURS=6 \ -v /var/cache/mysqltuner:/var/cache/mysqltuner \ mysqltuner-mcp ``` -### Method B: Local Execution (Without Docker) -Ensure Python 3 and Perl are installed locally, then run the script directly: -```bash -export DB_HOST="127.0.0.1" -export DB_USER="root" -export DB_PASSWORD="your_password" -export CACHE_DIR="./mcp_cache" - -python3 build/mcp_server.py -``` +#### Supported Environment Variables: +- `DB_HOST`: Hostname or IP address of the target MySQL/MariaDB server (default: `127.0.0.1`). +- `DB_PORT`: Database port (default: `3306`). +- `DB_USER`: Database audit user (default: `root`). +- `DB_PASSWORD`: Password for the database user. +- `AUDIT_INTERVAL_HOURS`: Periodic audit refresh interval in hours (default: `6`). +- `CACHE_DIR`: Cache directory for report artifacts (default: `/var/cache/mysqltuner`). --- -## 🛠️ Part 2: Configuring AI Clients - -Once the server is running, register it inside your preferred AI agent environment. +### Client IDE & Agent Configurations -### 1. Claude Desktop Config -Add the server definition to your Claude Desktop configuration file: +#### 1. Claude Desktop +Edit your Claude configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` @@ -61,7 +173,7 @@ Add the server definition to your Claude Desktop configuration file: "-e", "DB_USER=root", "-e", - "DB_PASSWORD=secret", + "DB_PASSWORD=your_password", "mysqltuner-mcp" ] } @@ -69,17 +181,16 @@ Add the server definition to your Claude Desktop configuration file: } ``` -### 2. Cursor IDE Config -1. Open Cursor and navigate to **Settings** -> **Features** -> **MCP**. +#### 2. Cursor IDE +1. Go to **Settings** -> **Features** -> **MCP**. 2. Click **+ Add New MCP Server**. -3. Fill in the parameters: +3. Configure settings: - **Name**: `mysqltuner` - **Type**: `stdio` - **Command**: `python3 /path/to/MySQLTuner-perl/build/mcp_server.py` -4. Set environment variables in the terminal where Cursor was launched. -### 3. VS Code (Cline / Roo Code / Roo Cline) -Configure the extension settings `mcpSettings.json` to spawn the server: +#### 3. VS Code (Cline / Roo Code) +Add to `mcpSettings.json`: ```json { "mcpServers": { @@ -98,39 +209,18 @@ Configure the extension settings `mcpSettings.json` to spawn the server: --- -## 🔍 Part 3: Deep Database Tuning with AI - -When connected, the AI agent has access to MySQLTuner findings and can cross-reference logs, memory allocations, and schema design to perform high-density optimizations. - -### 1. Memory Allocation and Buffers -AI agents can parse the buffer pool allocations and compare them to physical RAM limits to prevent Out-Of-Memory (OOM) situations. -- **Agent Analysis**: Evaluates `pct_max_physical_memory` to verify if memory usage is safe. -- **Live Adjustment**: Executes `apply_recommendation` with `SET GLOBAL innodb_buffer_pool_size = ` if the database version supports dynamic buffer pool resizing (MySQL 5.7+). - -### 2. Connection Saturation and Thread Cache -High connection spikes cause high thread creation overhead. -- **Agent Analysis**: Evaluates `max_connections` and matches it against `threads_created`. -- **Live Adjustment**: Sets `thread_cache_size` to reduce creation overhead: - `SET GLOBAL thread_cache_size = 16;` - -### 3. Index Profiling and Table Churn -- **Agent Analysis**: The agent queries table fragmentation and matches it with Performance Schema query logs. -- **Live Action**: Automatically schedules defragmentation for high-churn tables: - `OPTIMIZE TABLE schema_name.table_name;` - ---- - -## 🤖 Part 4: Advanced Prompt Engineering for AI Agents +## 🛡️ AI Agent Governance & System Prompt -To ensure the AI operates safely and acts as an expert DBA, prepend your conversations with the following System Prompt: +To ensure safe, production-grade operations, inject the following system prompt into your LLM agent context: ```markdown -You are a Senior Principal Database Administrator (DBA). You have access to the MySQLTuner MCP server. -Your core mission is to audit, analyze, and optimize the MySQL instance safely. - -### Operating Rules: -1. **Always Verify Baseline**: Before executing any SQL changes, read the cached audit resources (`mysqltuner://reports/latest.json`). -2. **Classify by Risk**: Categorize recommendations. Apply 'Low' or 'Medium' risk adjustments dynamically. Never apply 'High' or 'Critical' recommendations (such as changes requiring a service restart or ALTER TABLE on tables > 10GB) without explicit user confirmation. -3. **Draft Rollbacks First**: Before invoking `apply_recommendation`, state the exact SQL statement to be executed AND the corresponding `rollback_statement` so the user is fully informed. -4. **Iterative Auditing**: After applying a recommendation, trigger `run_audit` to confirm that the indicator has improved. If performance metrics degrade or the audit flags unexpected regressions, immediately run `rollback_recommendation` using the returned Statement ID. +You are a Principal Database Administrator (DBA) managing a MySQL/MariaDB infrastructure via the MySQLTuner MCP server. + +### Safety Rules: +1. **Baseline Inspection**: Always run `get_latest_audit` before proposing changes. +2. **Risk Categorization**: + - `Low` / `Medium` risk statements with `requires_restart: false` can be applied live after presenting the rollback statement to the user. + - `High` / `Critical` risk statements or changes with `requires_restart: true` MUST require explicit confirmation. +3. **Rollback Availability**: Always state both the `statement` and `rollback_statement` prior to executing `apply_recommendation`. +4. **Post-Execution Verification**: Call `run_audit` after executing changes to verify KPI score improvement. If metrics regress, immediately execute `rollback_recommendation`. ``` diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 58007f560..b67e1dde1 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -8,6 +8,7 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) ``` @@ -23,6 +24,7 @@ ## 🛠️ Internal Commit History +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) - chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) - chore(deps): lock file maintenance (#974) (580d17f) From 25fd4d0b2c6998343644cdb49693bf1c11a1ca80 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:27:10 +0200 Subject: [PATCH 04/44] docs: regenerate release notes --- releases/v2.9.2.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index b67e1dde1..c92857ba8 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -24,7 +24,8 @@ ## 🛠️ Internal Commit History -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) +- docs: regenerate release notes (1a70e82) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) - chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) - chore(deps): lock file maintenance (#974) (580d17f) From cc685fbfecccdc91adaf0cdd04ef485ec1fba436 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:28:45 +0200 Subject: [PATCH 05/44] docs(mcp): update all README language files with AI integration chapter and links --- Changelog | 2 +- README.fr.md | 30 ++++++++++++++++++++++++++++++ README.it.md | 31 +++++++++++++++++++++++++++++++ README.md | 32 +++++++++++++++++++++++++++++++- README.ru.md | 31 +++++++++++++++++++++++++++++++ build/check_compliance.pl | 2 +- releases/v2.9.2.md | 29 ++++++++++++++--------------- 7 files changed, 139 insertions(+), 18 deletions(-) diff --git a/Changelog b/Changelog index cd6b920c1..5c9c4a293 100644 --- a/Changelog +++ b/Changelog @@ -2,7 +2,7 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(container): add comprehensive AI MCP server integration guides in English and French (#954) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) diff --git a/README.fr.md b/README.fr.md index 11df6843d..4572e98fa 100644 --- a/README.fr.md +++ b/README.fr.md @@ -103,6 +103,36 @@ Merci à [endoflife.date](https://endoflife.date/) * **Analyse de tendances historiques** : Ingestion de sorties JSON de runs précédents via `--compare-file` pour suivre les tendances QPS et de croissance des données. * **Intégration Sysbench** : Analyse de la sortie sysbench pour les métriques QPS, TPS et latence (Moy/95e/Max) via `--sysbench-file`. * **Intégration logs Container et Systemd** : Détection automatique des logs depuis Docker, Podman, Kubectl/Kubernetes et le journal Systemd. +* **Support Protocole IA & MCP** : Serveur microservice Model Context Protocol (MCP) natif stdio JSON-RPC et sortie JSON structurée `--agent-json` pour les clients IA (Claude Desktop, Cursor, VS Code / Cline, Antigravity). + +--- + +## 🤖 Intégration Agent IA & Model Context Protocol (MCP) + +MySQLTuner prend en charge en natif les flux de travail basés sur l'Intelligence Artificielle (IA), les agents DBA autonomes et les assistants de développement (ex. Claude Desktop, Cursor IDE, VS Code / Cline, Antigravity, ainsi que les frameworks LangChain et LlamaIndex). + +Pour la documentation technique complète, consultez le [Guide d'Intégration IA & MCP (FR)](documentation/mcp_ai_integration_guide.fr.md), la [Version Anglaise](documentation/mcp_ai_integration_guide.md) et le fichier [AGENT.md](AGENT.md). + +### Modes d'Opération + +1. **Télémétrie CLI Directe (`--agent-json`)** : + Émet un schéma JSON structuré sans dépendance externe contenant les diagnostics, les scores d'impact (`1`-`10`), les niveaux de risque (`Low`, `Medium`, `High`, `Critical`), les requêtes d'exécution `SET GLOBAL` ainsi que les instructions de retour en arrière `rollback_statement`. + ```bash + perl mysqltuner.pl --agent-json --host 127.0.0.1 --user root --pass secret + ``` + +2. **Serveur Model Context Protocol (MCP)** : + Un microservice léger ([build/mcp_server.py](build/mcp_server.py) et [Dockerfile.mcp](Dockerfile.mcp)) communiquant via l'entrée/sortie standard (stdio) en JSON-RPC 2.0. + - **Ressources** : `mysqltuner://reports/latest.json`, `mysqltuner://indicators/summary.json` + - **Outils** : `get_latest_audit`, `run_audit`, `apply_recommendation`, `rollback_recommendation` + ```bash + docker run -d \ + --name mysqltuner-mcp \ + -e DB_HOST=127.0.0.1 -e DB_USER=root -e DB_PASSWORD=secret \ + mysqltuner-mcp + ``` + +--- ***Moteurs de stockage non pris en charge : les PR sont les bienvenues*** -- diff --git a/README.it.md b/README.it.md index c8998112d..28602fedb 100644 --- a/README.it.md +++ b/README.it.md @@ -26,6 +26,7 @@ Link Utili * **Release/Tag:** [https://github.com/major/MySQLTuner-perl/tags](https://github.com/major/MySQLTuner-perl/tags) * **Changelog:** [https://github.com/major/MySQLTuner-perl/blob/master/Changelog](https://github.com/major/MySQLTuner-perl/blob/master/Changelog) * **Immagini Docker:** [https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags](https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags) +* **Guida all'Integrazione Agent IA e Server MCP:** [Documentation/AI MCP Server Guide](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.md) | [Guide Serveur MCP (FR)](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.fr.md) | [AGENT.md](https://github.com/major/MySQLTuner-perl/blob/master/AGENT.md) * **Report HTML Interattivi (v2.9.0+):** * [Esempio di Report MariaDB 11.4](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mariadb114/Schemadir/mysqltuner_report.html) * [Esempio di Report MySQL 8.4](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mysql84/Schemadir/mysqltuner_report.html) @@ -102,6 +103,36 @@ Grazie a [endoflife.date](https://endoflife.date/) * **Analisi delle tendenze storiche**: Ingestione dell'output JSON delle esecuzioni precedenti tramite `--compare-file` per monitorare le tendenze QPS e crescita dei dati. * **Integrazione Sysbench**: Analisi dell'output sysbench per metriche QPS, TPS e latenza (Media/95°/Max) tramite `--sysbench-file`. * **Integrazione log Container e Systemd**: Rilevamento automatico dei log da Docker, Podman, Kubectl/Kubernetes e journal Systemd. +* **Supporto Protocollo IA e MCP**: Daemon microservizio Model Context Protocol (MCP) nativo stdio JSON-RPC e output JSON strutturato `--agent-json` per gli strumenti client IA (Claude Desktop, Cursor, VS Code / Cline, Antigravity). + +--- + +## 🤖 Integrazione Agent IA e Model Context Protocol (MCP) + +MySQLTuner supporta nativamente i flussi di lavoro basati sull'Intelligenza Artificiale (IA), agenti DBA autonomi e assistenti di sviluppo (es. Claude Desktop, Cursor IDE, VS Code / Cline, Antigravity e i framework LangChain/LlamaIndex). + +Per la documentazione tecnica completa, consulta la [Guida all'Integrazione IA e MCP](documentation/mcp_ai_integration_guide.md), la [Guida in Francese](documentation/mcp_ai_integration_guide.fr.md) e il file [AGENT.md](AGENT.md). + +### Modalità Operative + +1. **Telemetria CLI Diretta (`--agent-json`)**: + Emette un JSON strutturato senza dipendenze esterne contenente i suggerimenti, i punteggi d'impatto (`1`-`10`), i livelli di rischio (`Low`, `Medium`, `High`, `Critical`), i comandi SQL `SET GLOBAL` e le istruzioni di ripristino `rollback_statement`. + ```bash + perl mysqltuner.pl --agent-json --host 127.0.0.1 --user root --pass secret + ``` + +2. **Server Model Context Protocol (MCP)**: + Un microservizio leggero ([build/mcp_server.py](build/mcp_server.py) e [Dockerfile.mcp](Dockerfile.mcp)) che comunica tramite standard I/O (stdio) via JSON-RPC 2.0. + - **Risorse**: `mysqltuner://reports/latest.json`, `mysqltuner://indicators/summary.json` + - **Strumenti**: `get_latest_audit`, `run_audit`, `apply_recommendation`, `rollback_recommendation` + ```bash + docker run -d \ + --name mysqltuner-mcp \ + -e DB_HOST=127.0.0.1 -e DB_USER=root -e DB_PASSWORD=secret \ + mysqltuner-mcp + ``` + +--- ***Motori di archiviazione non supportati: le PR sono benvenute*** -- diff --git a/README.md b/README.md index 74f1901fa..1d1af601e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Useful Links * **Changelog:** [https://github.com/major/MySQLTuner-perl/blob/master/Changelog](https://github.com/major/MySQLTuner-perl/blob/master/Changelog) * **Docker Images:** [https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags](https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags) * **Useful References:** [Documentation/References](https://github.com/major/MySQLTuner-perl/blob/master/documentation/REFERENCES.md) -* **AI Agent & MCP Server Integration Guide:** [Documentation/AI MCP Server Guide](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.md) +* **AI Agent & MCP Server Integration Guide:** [Documentation/AI MCP Server Guide](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.md) | [Guide Serveur MCP (FR)](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.fr.md) | [AGENT.md](https://github.com/major/MySQLTuner-perl/blob/master/AGENT.md) * **Interactive HTML Reports (v2.9.0+):** * [MariaDB 11.4 E2E HTML Report Example](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mariadb114/Schemadir/mysqltuner_report.html) * [MySQL 8.4 E2E HTML Report Example](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mysql84/Schemadir/mysqltuner_report.html) @@ -105,6 +105,36 @@ Thanks to [endoflife.date](https://endoflife.date/) * **Historical Trend Analysis**: Ingest JSON output from previous runs via `--compare-file` to track QPS and data growth trends. * **Sysbench Integration**: Parse sysbench output for QPS, TPS, and latency metrics (Avg/95th/Max) via `--sysbench-file`. * **Container & Systemd Log Integration**: Automatic log detection from Docker, Podman, Kubectl/Kubernetes, and Systemd journal. +* **AI & MCP Protocol Support**: Native JSON-RPC stdio Model Context Protocol (MCP) server daemon and `--agent-json` structured output for AI client tools (Claude Desktop, Cursor, VS Code / Cline, Antigravity). + +--- + +## 🤖 AI Agent & Model Context Protocol (MCP) Integration + +MySQLTuner natively supports modern Artificial Intelligence (AI) workflows, autonomous DBA agents, and developer assistants (e.g., Claude Desktop, Cursor IDE, VS Code / Cline, Antigravity, and LangChain/LlamaIndex frameworks). + +For complete technical documentation, refer to the [AI & MCP Integration Guide](documentation/mcp_ai_integration_guide.md), [Guide Serveur MCP IA (FR)](documentation/mcp_ai_integration_guide.fr.md), and [AGENT.md](AGENT.md). + +### Operating Modes + +1. **Direct CLI Telemetry (`--agent-json`)**: + Outputs zero-dependency structured JSON containing findings, impact scores (`1`-`10`), risk levels (`Low`, `Medium`, `High`, `Critical`), executable `SET GLOBAL` SQL statements, and pre-calculated `rollback_statement` baselines. + ```bash + perl mysqltuner.pl --agent-json --host 127.0.0.1 --user root --pass secret + ``` + +2. **Model Context Protocol (MCP) Server**: + A lightweight microservice ([build/mcp_server.py](build/mcp_server.py) and [Dockerfile.mcp](Dockerfile.mcp)) communicating over standard I/O (stdio) via JSON-RPC 2.0. + - **Resources**: `mysqltuner://reports/latest.json`, `mysqltuner://indicators/summary.json` + - **Tools**: `get_latest_audit`, `run_audit`, `apply_recommendation`, `rollback_recommendation` + ```bash + docker run -d \ + --name mysqltuner-mcp \ + -e DB_HOST=127.0.0.1 -e DB_USER=root -e DB_PASSWORD=secret \ + mysqltuner-mcp + ``` + +--- ***Unsupported storage engines: PRs welcome*** -- diff --git a/README.ru.md b/README.ru.md index f87666403..81da7ec7c 100644 --- a/README.ru.md +++ b/README.ru.md @@ -26,6 +26,7 @@ * **Релизы/Теги:** [https://github.com/major/MySQLTuner-perl/tags](https://github.com/major/MySQLTuner-perl/tags) * **Changelog:** [https://github.com/major/MySQLTuner-perl/blob/master/Changelog](https://github.com/major/MySQLTuner-perl/blob/master/Changelog) * **Docker-образы:** [https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags](https://hub.docker.com/repository/docker/jmrenouard/mysqltuner/tags) +* **Руководство по интеграции ИИ-агентов и сервера MCP:** [Documentation/AI MCP Server Guide](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.md) | [Guide Serveur MCP (FR)](https://github.com/major/MySQLTuner-perl/blob/master/documentation/mcp_ai_integration_guide.fr.md) | [AGENT.md](https://github.com/major/MySQLTuner-perl/blob/master/AGENT.md) * **Интерактивные HTML-отчеты (v2.9.0+):** * [Пример отчета MariaDB 11.4](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mariadb114/Schemadir/mysqltuner_report.html) * [Пример отчета MySQL 8.4](https://lightpath.fr/MySQLtuner_reports/MySQLTuner-v290_mysql84/Schemadir/mysqltuner_report.html) @@ -102,6 +103,36 @@ MySQLTuner нуждается в вас * **Анализ исторических тенденций**: поглощение JSON-вывода предыдущих запусков через `--compare-file` для отслеживания тенденций QPS и роста данных. * **Интеграция Sysbench**: анализ вывода sysbench для метрик QPS, TPS и латентности (Средн./95-й/Макс) через `--sysbench-file`. * **Интеграция логов Container и Systemd**: автоматическое обнаружение логов из Docker, Podman, Kubectl/Kubernetes и журнала Systemd. +* **Поддержка ИИ и протокола MCP**: нативный демоничный микросервис Model Context Protocol (MCP) stdio JSON-RPC и структурированный JSON-вывод `--agent-json` для ИИ-клиентов (Claude Desktop, Cursor, VS Code / Cline, Antigravity). + +--- + +## 🤖 Интеграция с ИИ-агентами и сервером Model Context Protocol (MCP) + +MySQLTuner нативно поддерживает современные рабочие процессы на базе ИИ, автономных агентов DBA и ассистентов разработчиков (например, Claude Desktop, Cursor IDE, VS Code / Cline, Antigravity, а также фреймворки LangChain и LlamaIndex). + +Полная техническая документация доступна в [Руководстве по интеграции ИИ и MCP](documentation/mcp_ai_integration_guide.md), [Французском руководстве](documentation/mcp_ai_integration_guide.fr.md) и файле [AGENT.md](AGENT.md). + +### Режимы работы + +1. **Прямая телеметрия CLI (`--agent-json`)**: + Выводит структурированный JSON без внешних зависимостей, содержащий результаты анализа, оценки влияния (`1`-`10`), уровни риска (`Low`, `Medium`, `High`, `Critical`), SQL-запросы `SET GLOBAL` и команды отката `rollback_statement`. + ```bash + perl mysqltuner.pl --agent-json --host 127.0.0.1 --user root --pass secret + ``` + +2. **Сервер Model Context Protocol (MCP)**: + Легковесный микросервис ([build/mcp_server.py](build/mcp_server.py) и [Dockerfile.mcp](Dockerfile.mcp)), взаимодействующий через стандартный ввод/вывод (stdio) по протоколу JSON-RPC 2.0. + - **Ресурсы**: `mysqltuner://reports/latest.json`, `mysqltuner://indicators/summary.json` + - **Инструменты**: `get_latest_audit`, `run_audit`, `apply_recommendation`, `rollback_recommendation` + ```bash + docker run -d \ + --name mysqltuner-mcp \ + -e DB_HOST=127.0.0.1 -e DB_USER=root -e DB_PASSWORD=secret \ + mysqltuner-mcp + ``` + +--- ***Неподдерживаемые механизмы хранения: приветствуются PR*** -- diff --git a/build/check_compliance.pl b/build/check_compliance.pl index 7174c9bd5..38fe54b86 100755 --- a/build/check_compliance.pl +++ b/build/check_compliance.pl @@ -141,7 +141,7 @@ 'style', 'releases', 'dependencies', 'cli', 'auth', 'main', 'metadata', 'deps', 'system', 'roadmap', 'hook', 'hooks', - 'build' + 'build', 'mcp' ); # Lint Changelog structure and scopes for the current version block diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index c92857ba8..eee5acc7e 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -8,7 +8,7 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(container): add comprehensive AI MCP server integration guides in English and French (#954) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) ``` @@ -24,20 +24,19 @@ ## 🛠️ Internal Commit History -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) -- docs: regenerate release notes (1a70e82) -- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) -- chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) -- chore(deps): lock file maintenance (#974) (580d17f) -- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) (14cf8e4) -- chore(deps): update ubuntu:latest docker digest to 3131b4c (bde344b) -- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) (ed8ced9) -- chore(deps): update github/codeql-action digest to e4fba86 (#966) (be53988) -- chore(deps): update docker/login-action digest to dbcb813 (#965) (67acd5e) -- chore(deps): pin dependencies (#964) (a29311e) -- chore(deps): update alpine docker tag to v3.24 (a119f22) -- chore(deps): update actions/checkout action to v7 (d126c1f) -- chore(deps): lock file maintenance (86b04d7) +- docs(mcp): update all README language files with AI integration chapter and links +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- chore(deps): update github/codeql-action digest to d1ba80a (#973) +- chore(deps): lock file maintenance (#974) +- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) +- chore(deps): update ubuntu:latest docker digest to 3131b4c +- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) +- chore(deps): update github/codeql-action digest to e4fba86 (#966) +- chore(deps): update docker/login-action digest to dbcb813 (#965) +- chore(deps): pin dependencies (#964) +- chore(deps): update alpine docker tag to v3.24 +- chore(deps): update actions/checkout action to v7 ## ⚙️ Technical Evolutions From d57ee62d0686d1204649ad38b8bf83f8fad9133b Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:28:45 +0200 Subject: [PATCH 06/44] docs: regenerate release notes --- releases/v2.9.2.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index eee5acc7e..003081ed6 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -24,19 +24,22 @@ ## 🛠️ Internal Commit History -- docs(mcp): update all README language files with AI integration chapter and links -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) -- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) -- chore(deps): update github/codeql-action digest to d1ba80a (#973) -- chore(deps): lock file maintenance (#974) -- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) -- chore(deps): update ubuntu:latest docker digest to 3131b4c -- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) -- chore(deps): update github/codeql-action digest to e4fba86 (#966) -- chore(deps): update docker/login-action digest to dbcb813 (#965) -- chore(deps): pin dependencies (#964) -- chore(deps): update alpine docker tag to v3.24 -- chore(deps): update actions/checkout action to v7 +- docs(mcp): update all README language files with AI integration chapter and links (26a2de8) +- docs: regenerate release notes (4797a59) +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) +- docs: regenerate release notes (1a70e82) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) +- chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) +- chore(deps): lock file maintenance (#974) (580d17f) +- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) (14cf8e4) +- chore(deps): update ubuntu:latest docker digest to 3131b4c (bde344b) +- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) (ed8ced9) +- chore(deps): update github/codeql-action digest to e4fba86 (#966) (be53988) +- chore(deps): update docker/login-action digest to dbcb813 (#965) (67acd5e) +- chore(deps): pin dependencies (#964) (a29311e) +- chore(deps): update alpine docker tag to v3.24 (a119f22) +- chore(deps): update actions/checkout action to v7 (d126c1f) +- chore(deps): lock file maintenance (86b04d7) ## ⚙️ Technical Evolutions From d9e0ed493935f3ee9f74e165652bb8f1bc8ad337 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:39:10 +0200 Subject: [PATCH 07/44] docs(rules): align release governance, conventional commit, and git tagging rules (#739) --- .agent/rules/03_execution_rules.md | 5 +++-- .agents/AGENTS.md | 6 +++++- Changelog | 1 + RULES.md | 11 +++++++---- releases/v2.9.2.md | 1 + 5 files changed, 17 insertions(+), 7 deletions(-) diff --git a/.agent/rules/03_execution_rules.md b/.agent/rules/03_execution_rules.md index ded92a982..48c43c60b 100644 --- a/.agent/rules/03_execution_rules.md +++ b/.agent/rules/03_execution_rules.md @@ -19,8 +19,8 @@ category: governance 7. **ARTIFACT ROTATION:** Keep the `brain/` directory lean. Rotate old plans/walkthroughs after integration. 8. **WEB SEARCH:** Assume world knowledge is out of date. Use web search for up-to-date documentation. -9. **VERSION CONSISTENCY:** Version numbers MUST be synchronized across `CURRENT_VERSION.txt`, `Changelog`, and all occurrences within `mysqltuner.pl` (Header, internal variable, and POD documentation) before any release. -10. **CONVENTIONAL COMMITS:** All commit messages MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Use `npm run commit` for interactive commit creation. Compliance is enforced via `commitlint` and Git hooks. +9. **VERSION CONSISTENCY & SYNCHRONIZATION:** Version numbers follow strict incremental semantic versioning (no irregular bumps). Version numbers MUST be synchronized across `CURRENT_VERSION.txt`, `Changelog`, `releases/v[VERSION].md`, and all occurrences within `mysqltuner.pl` (Header, internal variable `$VERSION`, and POD documentation) before any release. +10. **CONVENTIONAL COMMITS & CENTRALIZED CHANGELOG:** All commit messages MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (`feat:`, `fix:`, `chore:`, `docs:`, `perf:`, `test:`, `ci:`). Compliance is enforced via `@commitlint/cz-commitlint` and Git hooks (`npm run commit` / `git cz`). 11. **NO DIRECT COMMIT:** All changes MUST be committed via `npm run commit` or `git cz` to ensure metadata quality and automated changelog compatibility. 12. **VERSION SUPPORT POLICY:** Automated test example generation (via `run-tests`) MUST only target "Supported" versions of MySQL and MariaDB as defined in `mysql_support.md` and `mariadb_support.md`. @@ -72,6 +72,7 @@ To ensure quality and clarity in every development cycle, all non-trivial featur - **STRICT PROHIBITION:** No `git commit`, `git push`, or `git tag` without an explicit user order. - **BRANCHING MANDATORY:** ALL developments, features, bug fixes, and interventions MUST be done in a dedicated Git branch separated from `master`. Committing directly to the `master` branch is strictly prohibited. - **UNIFIED RELEASE MANAGEMENT:** The entire release process (doc sync, testing, changelog generation, tagging, and branch creation) is now orchestrated exclusively by the `/release-manager` workflow. Do not run disjointed commands (`/git-flow`, `/release-preflight`, `/doc-sync`) manually. +- **SYNCHRONIZED RELEASE TAGGING:** Every version bump MUST create an explicit `vX.Y.Z` Git tag force-pushed to origin during release orchestration, guaranteeing 100% synchronization between GitHub Releases and Git history. - **Conventional Commits:** Use `feat:`, `fix:`, `chore:`, `docs:`, `perf:`, `refactor:`, `style:`, `test:`, `ci:`. Breaking changes must be marked with `!` after type/scope or `BREAKING CHANGE:` in footer. - **Commit Validation:** Commits are automatically linted via `commitlint`. Non-compliant messages will be rejected by the pre-commit hook. - **History Documentation:** Use `npm run commit` to generate structured history. diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md index 27fcd8c25..1c454759a 100644 --- a/.agents/AGENTS.md +++ b/.agents/AGENTS.md @@ -1,6 +1,10 @@ # Agent Custom Rules -- Always update the release notes (`releases/v[VERSION].md`) at the same time as the `Changelog`. +- Always update technical release notes (`releases/v[VERSION].md`) simultaneously with `Changelog` updates. +- Enforce strict incremental semantic versioning across `CURRENT_VERSION.txt`, `Changelog`, `releases/v[VERSION].md`, and `mysqltuner.pl`. +- Enforce Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `perf:`, `test:`, `ci:`) via `@commitlint/cz-commitlint` and `npm run commit`. +- Enforce branching rules (no direct commits to `master`) and force-push synchronized `vX.Y.Z` Git release tags via `/release-manager`. - Decompose unit tests into human-assimilable parts (for example, using structured subtests). - Systematically add unit tests to validate every code modification. - For each modification, add an issue with the correct tags in Major's project and assign it to jmrenouard. + diff --git a/Changelog b/Changelog index 5c9c4a293..7ee5bdca4 100644 --- a/Changelog +++ b/Changelog @@ -3,6 +3,7 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) diff --git a/RULES.md b/RULES.md index 922fd24f6..d84d161dc 100644 --- a/RULES.md +++ b/RULES.md @@ -9,16 +9,18 @@ Make `mysqltuner.pl` the most stable, portable, and reliable performance tuning - **Zero-Dependency Portability**: The script must remain self-contained and executable on any server with a base Perl installation (Core modules only). - **Universal Compatibility**: Support the widest possible range of MySQL-compatible versions (Legacy 5.5 to Modern 11.x). - **Regression Limit**: Proactively identify and prevent regressions through exhaustive automated testing. +- **Release Integrity**: Guarantee artifact consistency, tag synchronization, and multi-version validation through formal release management. ## Execution Rules & Constraints -1. **SINGLE FILE**: Spliting `mysqltuner.pl` into modules is **strictly prohibited**. +1. **SINGLE FILE**: Splitting `mysqltuner.pl` into modules is **strictly prohibited**. 2. **NON-REGRESSION**: Deleting existing code is **prohibited** without relocation or commenting out. 3. **TDD MANDATORY**: Use a TDD approach. Validate solutions by creating test cases before final submission. 4. **SAFE COMMANDS**: Always use absolute paths. Monitor every command for `exit code 0`. 5. **CREDENTIAL HYGIENE**: NEVER hardcode credentials. -6. **VERSION CONSISTENCY**: Version numbers MUST be synchronized across `CURRENT_VERSION.txt`, `Changelog`, and all occurrences within `mysqltuner.pl`. -7. **CONVENTIONAL COMMITS**: All commit messages MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. -8. **NO DIRECT COMMIT**: All changes SHOULD be committed via `npm run commit` or `git cz`. +6. **VERSION CONSISTENCY & SYNCHRONIZATION**: Version numbers follow strict incremental semantic versioning (no irregular bumps). Version numbers MUST be synchronized across `CURRENT_VERSION.txt`, `Changelog`, `releases/v[VERSION].md`, and all occurrences within `mysqltuner.pl` (Header, internal variable `$VERSION`, and POD documentation) before any release. +7. **CONVENTIONAL COMMITS & CENTRALIZED CHANGELOG**: All commit messages MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (`feat:`, `fix:`, `chore:`, `docs:`, `perf:`, `test:`, `ci:`), enforced via `@commitlint/cz-commitlint` and pre-commit hooks (`npm run commit` / `git cz`). Every change (including tests, CI, and docs) MUST be traced in the root `Changelog` file, categorized and ordered by impact type (`chore`, `feat`, `fix`, `test`, `ci`). +8. **AUTOMATED RELEASE NOTES**: Technical release notes (`releases/v[VERSION].md`) MUST be generated simultaneously with `Changelog` updates for every version release, containing an executive summary, linked issues/PRs, features, fixes, and test highlights. +9. **BRANCHING & SYNCHRONIZED TAGGING**: Direct commits to `master` are strictly prohibited. ALL work MUST be done in dedicated feature/release branches. Every release bump MUST create an explicit `vX.Y.Z` Git tag force-pushed to origin via the `/release-manager` workflow, guaranteeing 100% synchronization between GitHub Releases and Git history. ## Best Practices 1. **Multi-Version Validation**: Test diagnostic logic changes against at least one "Legacy" version (e.g. MySQL 8.0) and one "Modern" version (e.g. MariaDB 11.4). @@ -27,3 +29,4 @@ Make `mysqltuner.pl` the most stable, portable, and reliable performance tuning 4. **Audit Trail**: Every recommendation MUST be documented in code with a comment pointing to official documentation. 5. **Memory-Efficient Parsing**: Process logs line-by-line; NEVER load large files into memory. 6. **SQL Modeling**: Use the `Modeling` array to collect schema design findings (naming, constraints, data types). + diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 003081ed6..8a8005cbf 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -9,6 +9,7 @@ - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) ``` From 400fccbd9d14b951d914aa1fe984de8671fd8dc4 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Wed, 29 Jul 2026 17:39:10 +0200 Subject: [PATCH 08/44] docs: regenerate release notes --- releases/v2.9.2.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 8a8005cbf..4879d2ffc 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -25,6 +25,8 @@ ## 🛠️ Internal Commit History +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) (1c47ff0) +- docs: regenerate release notes (1dbed6b) - docs(mcp): update all README language files with AI integration chapter and links (26a2de8) - docs: regenerate release notes (4797a59) - docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) From b8d0a190fd57dccf030df5febcdd1fe3acb0895f Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Fri, 7 Aug 2026 14:43:35 +0200 Subject: [PATCH 09/44] ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes --- Changelog | 1 + build/check_compliance.pl | 2 +- releases/v2.9.2.md | 34 ++++++++++++++++------------------ 3 files changed, 18 insertions(+), 19 deletions(-) diff --git a/Changelog b/Changelog index 7ee5bdca4..e6cdc1f3d 100644 --- a/Changelog +++ b/Changelog @@ -6,6 +6,7 @@ - docs(rules): align release governance, conventional commit, and git tagging rules (#739) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) +- ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes 2.9.1 2026-07-27 - chore(deps): update actions/checkout action to v7.0.0 (#961) diff --git a/build/check_compliance.pl b/build/check_compliance.pl index 38fe54b86..32162b28b 100755 --- a/build/check_compliance.pl +++ b/build/check_compliance.pl @@ -141,7 +141,7 @@ 'style', 'releases', 'dependencies', 'cli', 'auth', 'main', 'metadata', 'deps', 'system', 'roadmap', 'hook', 'hooks', - 'build', 'mcp' + 'build', 'mcp', 'rules' ); # Lint Changelog structure and scopes for the current version block diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 4879d2ffc..f4dd8200c 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -12,6 +12,7 @@ - docs(rules): align release governance, conventional commit, and git tagging rules (#739) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) +- ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes ``` ## 📈 Diagnostic Growth Indicators @@ -25,24 +26,21 @@ ## 🛠️ Internal Commit History -- docs(rules): align release governance, conventional commit, and git tagging rules (#739) (1c47ff0) -- docs: regenerate release notes (1dbed6b) -- docs(mcp): update all README language files with AI integration chapter and links (26a2de8) -- docs: regenerate release notes (4797a59) -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) -- docs: regenerate release notes (1a70e82) -- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) -- chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) -- chore(deps): lock file maintenance (#974) (580d17f) -- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) (14cf8e4) -- chore(deps): update ubuntu:latest docker digest to 3131b4c (bde344b) -- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) (ed8ced9) -- chore(deps): update github/codeql-action digest to e4fba86 (#966) (be53988) -- chore(deps): update docker/login-action digest to dbcb813 (#965) (67acd5e) -- chore(deps): pin dependencies (#964) (a29311e) -- chore(deps): update alpine docker tag to v3.24 (a119f22) -- chore(deps): update actions/checkout action to v7 (d126c1f) -- chore(deps): lock file maintenance (86b04d7) +- ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- docs(mcp): update all README language files with AI integration chapter and links +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- chore(deps): update github/codeql-action digest to d1ba80a (#973) +- chore(deps): lock file maintenance (#974) +- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) +- chore(deps): update ubuntu:latest docker digest to 3131b4c +- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) +- chore(deps): update github/codeql-action digest to e4fba86 (#966) +- chore(deps): update docker/login-action digest to dbcb813 (#965) +- chore(deps): pin dependencies (#964) +- chore(deps): update alpine docker tag to v3.24 +- chore(deps): update actions/checkout action to v7 ## ⚙️ Technical Evolutions From 0e6c3de3fa83fdd5b7a688dce111cdf29f630a65 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Fri, 7 Aug 2026 14:43:35 +0200 Subject: [PATCH 10/44] docs: regenerate release notes --- releases/v2.9.2.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index f4dd8200c..a141c44a5 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -26,21 +26,26 @@ ## 🛠️ Internal Commit History -- ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes -- docs(rules): align release governance, conventional commit, and git tagging rules (#739) -- docs(mcp): update all README language files with AI integration chapter and links -- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) -- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) -- chore(deps): update github/codeql-action digest to d1ba80a (#973) -- chore(deps): lock file maintenance (#974) -- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) -- chore(deps): update ubuntu:latest docker digest to 3131b4c -- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) -- chore(deps): update github/codeql-action digest to e4fba86 (#966) -- chore(deps): update docker/login-action digest to dbcb813 (#965) -- chore(deps): pin dependencies (#964) -- chore(deps): update alpine docker tag to v3.24 -- chore(deps): update actions/checkout action to v7 +- ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes (8472003) +- docs: regenerate release notes (ef385fb) +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) (1c47ff0) +- docs: regenerate release notes (1dbed6b) +- docs(mcp): update all README language files with AI integration chapter and links (26a2de8) +- docs: regenerate release notes (4797a59) +- docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) +- docs: regenerate release notes (1a70e82) +- fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) +- chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) +- chore(deps): lock file maintenance (#974) (580d17f) +- chore(deps): update shogo82148/actions-setup-mysql digest to 3dcedf7 (#967) (14cf8e4) +- chore(deps): update ubuntu:latest docker digest to 3131b4c (bde344b) +- chore(deps): update softprops/action-gh-release digest to 3d0d988 (#968) (ed8ced9) +- chore(deps): update github/codeql-action digest to e4fba86 (#966) (be53988) +- chore(deps): update docker/login-action digest to dbcb813 (#965) (67acd5e) +- chore(deps): pin dependencies (#964) (a29311e) +- chore(deps): update alpine docker tag to v3.24 (a119f22) +- chore(deps): update actions/checkout action to v7 (d126c1f) +- chore(deps): lock file maintenance (86b04d7) ## ⚙️ Technical Evolutions From bbf4a082bc3829e11d31d9480d4f4bfa2f8ce2d1 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Sat, 8 Aug 2026 00:12:40 +0200 Subject: [PATCH 11/44] style: tidy mysqltuner.pl --- Changelog | 4 + build/analyze_mt_output.pl | 7 +- build/check_compliance.pl | 2 +- mysqltuner.pl | 154 +++++++++++++++++++++++++++++++---- releases/v2.9.2.md | 8 +- tests/unit_galera_enhanced.t | 97 ++++++++++++++++++++++ tests/unit_ha_cluster.t | 50 ++++++++++++ 7 files changed, 302 insertions(+), 20 deletions(-) create mode 100644 tests/unit_galera_enhanced.t diff --git a/Changelog b/Changelog index e6cdc1f3d..15cf9ce6e 100644 --- a/Changelog +++ b/Changelog @@ -4,9 +4,13 @@ - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) - docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) +- feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes +- ci(lab): refine transport connection timeout pattern in output analyzer 2.9.1 2026-07-27 - chore(deps): update actions/checkout action to v7.0.0 (#961) diff --git a/build/analyze_mt_output.pl b/build/analyze_mt_output.pl index 5d5ef587a..6c398fcb7 100755 --- a/build/analyze_mt_output.pl +++ b/build/analyze_mt_output.pl @@ -89,8 +89,11 @@ # Category 3: Transport / Connection Errors # =================================================================== my @conn_errors; -while ($content =~ /^(.*(?:Can't connect to|Access denied|Connection refused|timeout|Lost connection).*)$/gmi) { - push @conn_errors, $1; +while ($content =~ /^(.*(?:Can't connect to|Access denied|Connection refused|Connection timeout|connect timeout|timed out|Lost connection).*)$/gmi) { + # Exclude variable names, thread names, or recommendation text containing 'timeout' + my $line = $1; + next if $line =~ /_timeout|srv_lock_timeout|group_replication_.*timeout/i; + push @conn_errors, $line; } if (@conn_errors) { push @errors, { diff --git a/build/check_compliance.pl b/build/check_compliance.pl index 32162b28b..33c12f745 100755 --- a/build/check_compliance.pl +++ b/build/check_compliance.pl @@ -141,7 +141,7 @@ 'style', 'releases', 'dependencies', 'cli', 'auth', 'main', 'metadata', 'deps', 'system', 'roadmap', 'hook', 'hooks', - 'build', 'mcp', 'rules' + 'build', 'mcp', 'rules', 'galera' ); # Lint Changelog structure and scopes for the current version block diff --git a/mysqltuner.pl b/mysqltuner.pl index b6fe5fb1d..f06dddb9f 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -1608,9 +1608,9 @@ sub check_replication_advanced { ); my $member_count = scalar(@group_members); if ( $member_count > 0 ) { - goodprint - "InnoDB Cluster is running with $member_count group members."; - my $primary_count = 0; + my $primary_count = 0; + my $secondary_count = 0; + my $online_count = 0; my %versions; foreach my $m (@group_members) { my @mparts = split( /\t/, $m ); @@ -1620,9 +1620,10 @@ sub check_replication_advanced { my $role = $mparts[3] // ''; my $ver = $mparts[4] // ''; + $online_count++ if $state eq 'ONLINE'; if ( $state ne 'ONLINE' ) { badprint -"Group member $host:$port state is $state (recommended: ONLINE)"; +"Group member $host:$port MEMBER_STATE is $state (recommended: ONLINE)"; push_recommendation( 'res', "Group member $host:$port is not ONLINE (state: $state). Check member status and error log." ); @@ -1630,12 +1631,19 @@ sub check_replication_advanced { if ( $role eq 'PRIMARY' ) { $primary_count++; } + elsif ( $role eq 'SECONDARY' ) { + $secondary_count++; + } $versions{$ver}++ if $ver; } + goodprint +"InnoDB Cluster topology: MEMBER_STATE ($online_count/$member_count ONLINE), MEMBER_ROLE ($primary_count PRIMARY, $secondary_count SECONDARY)."; my $single_primary = $myvar{'group_replication_single_primary_mode'} // 'ON'; - if ( $single_primary eq 'ON' || $single_primary eq '1' ) { + my $is_single_primary = + ( $single_primary eq 'ON' || $single_primary eq '1' ) ? 1 : 0; + if ($is_single_primary) { if ( $primary_count != 1 ) { badprint "Single-primary mode active, but found $primary_count primary member(s) (recommended: 1)"; @@ -1644,6 +1652,10 @@ sub check_replication_advanced { ); } } + else { + goodprint + "Group Replication is running in Multi-Primary mode."; + } my @unique_vers = keys %versions; if ( scalar(@unique_vers) > 1 ) { @@ -1660,7 +1672,7 @@ sub check_replication_advanced { my $server_uuid = select_one('SELECT @@server_uuid') // ''; if ($server_uuid) { my $local_stats = select_one( -"SELECT CONCAT_WS('|', COUNT_TRANSACTIONS_IN_QUEUE, COUNT_TRANSACTIONS_REMOTE_IN_APPLIER_QUEUE, TRANSACTIONS_COMMITTED_ALL_MEMBERS, TRANSACTIONS_LOCAL_ROLLBACK) FROM performance_schema.replication_group_member_stats WHERE MEMBER_ID = '$server_uuid'" +"SELECT CONCAT_WS('|', COUNT_TRANSACTIONS_IN_QUEUE, COUNT_TRANSACTIONS_REMOTE_IN_APPLIER_QUEUE, COUNT_TRANSACTIONS_LOCAL_PROPOSED, COUNT_TRANSACTIONS_LOCAL_ROLLBACK) FROM performance_schema.replication_group_member_stats WHERE MEMBER_ID = '$server_uuid'" ); if ($local_stats) { my ( $cert_queue, $applier_queue, $committed, $rollbacks ) @@ -1696,12 +1708,28 @@ sub check_replication_advanced { my $total_tx = $committed + $rollbacks; if ( $total_tx > 0 ) { my $rollback_ratio = $rollbacks / $total_tx; - if ( $rollback_ratio > 0.05 ) { + my $single_primary = + $myvar{'group_replication_single_primary_mode'} + // 'ON'; + my $is_sp = + ( $single_primary eq 'ON' || $single_primary eq '1' ) + ? 1 + : 0; + my $rollback_thresh = $is_sp ? 0.05 : 0.02; + if ( $rollback_ratio > $rollback_thresh ) { badprint "Certification rollback ratio is " . sprintf( "%.2f%%", $rollback_ratio * 100 ) - . " (too many optimistic lock conflicts)"; - push_recommendation( 'res', -"High certification rollback ratio detected. Optimize write concurrency or switch to Single-Primary mode." + . " (threshold: " + . sprintf( "%.1f%%", $rollback_thresh * 100 ) + . ")"; + push_recommendation( + 'res', + "High certification rollback ratio detected. " + . ( + $is_sp + ? "Optimize write concurrency or switch to Single-Primary mode." + : "High multi-primary conflict rate! Consider switching to Single-Primary mode or tuning group_replication_flow_control_period." + ) ); } } @@ -1725,6 +1753,36 @@ sub check_replication_advanced { } } + # Estimate retention window based on real-time network throughput + my $uptime = $mystat{'Uptime'} // 1; + if ( + $uptime > 0 + && ( defined $mystat{'Bytes_sent'} + || defined $mystat{'Bytes_received'} ) + ) + { + my $bytes_sent = $mystat{'Bytes_sent'} // 0; + my $bytes_recv = $mystat{'Bytes_received'} // 0; + my $net_rate = ( $bytes_sent + $bytes_recv ) / $uptime; + if ( $net_rate > 102400 ) { + my $retention_sec = int( $cache_size / $net_rate ); + if ( $retention_sec < 60 ) { + badprint "group_replication_message_cache_size (" + . hr_bytes($cache_size) + . ") provides only ~${retention_sec}s network partition retention under current load (" + . hr_bytes($net_rate) . "/s)"; + push_recommendation( 'res', +"Increase group_replication_message_cache_size to prevent full state transfers (SST) during transient network partitions." + ); + } + else { + goodprint +"group_replication_message_cache_size retention capacity: ~${retention_sec}s under current network load (" + . hr_bytes($net_rate) . "/s)."; + } + } + } + my $unreachable_timeout = $myvar{'group_replication_unreachable_majority_timeout'} // 0; if ( $unreachable_timeout == 0 ) { @@ -1736,15 +1794,49 @@ sub check_replication_advanced { } } - # 4. MySQL Router Connectivity (Experimental) - my $router_conn = select_one( -"SELECT COUNT(*) FROM information_schema.processlist WHERE USER LIKE '%router%' OR HOST LIKE '%router%'" + # 4. MySQL Router Connectivity & Advanced Traffic Metrics + my @router_procs = select_array( +"SELECT COMMAND, INFO FROM information_schema.processlist WHERE USER LIKE '%router%' OR HOST LIKE '%router%'" ); - my $router_conn_count = - ( defined $router_conn && $router_conn =~ /^\d+$/ ) ? $router_conn : 0; + my $router_conn_count = scalar(@router_procs); if ( $router_conn_count > 0 ) { + my $active_count = 0; + my $sleep_count = 0; + my $write_count = 0; + foreach my $p (@router_procs) { + my ( $cmd, $info ) = split( /\t/, $p ); + $cmd //= ''; + $info //= ''; + if ( $cmd ne 'Sleep' ) { + $active_count++; + if ( $info =~ +/^\s*(INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|REPLACE|TRUNCATE)/i + ) + { + $write_count++; + } + } + else { + $sleep_count++; + } + } goodprint -"MySQL Router connections active: found $router_conn_count connection(s) routed to this instance."; +"MySQL Router connections active: found $router_conn_count connection(s) ($active_count active, $sleep_count sleeping) routed to this instance."; + + if ( defined $myvar{'performance_schema'} + && $myvar{'performance_schema'} eq 'ON' ) + { + my $local_role = select_one( +'SELECT MEMBER_ROLE FROM performance_schema.replication_group_members WHERE MEMBER_ID = @@server_uuid' + ) // ''; + if ( $local_role eq 'SECONDARY' && $write_count > 0 ) { + badprint +"MySQL Router is routing write queries ($write_count detected) to a SECONDARY node!"; + push_recommendation( 'res', +"MySQL Router routing misconfiguration: write queries detected on a SECONDARY node. Check router destination ports (e.g. 6446 R/W vs 6447 R/O)." + ); + } + } } } @@ -11636,6 +11728,36 @@ sub mariadb_galera { } } + # 8. Galera Local Send & Recv Queue Monitoring + my $send_q_avg = $mystat{'wsrep_local_send_queue_avg'} // 0; + my $recv_q_avg = $mystat{'wsrep_local_recv_queue_avg'} // 0; + if ( $send_q_avg > 0.05 || $recv_q_avg > 0.05 ) { + badprint + sprintf( "Galera queue length elevated: send_avg=%.3f, recv_avg=%.3f", + $send_q_avg, $recv_q_avg ); + push @generalrec, +"Elevated Galera send/receive queues detected. Check network bandwidth and storage latency on slower nodes."; + } + + # 9. Galera Primary Key Certification Enforcement + if ( defined $myvar{'wsrep_certify_non_pk'} + && $myvar{'wsrep_certify_non_pk'} eq 'OFF' ) + { + badprint +"wsrep_certify_non_pk is OFF. Non-PK tables can cause replication inconsistencies."; + push @generalrec, +"Enable wsrep_certify_non_pk = ON to enforce automatic primary key certification in Galera."; + } + + # 10. Galera Cluster Quorum & Split-Brain Risk + my $c_size = $mystat{'wsrep_cluster_size'} // 0; + if ( $c_size > 0 && $c_size % 2 == 0 ) { + badprint +"Galera cluster size is an even number ($c_size nodes). Risk of split-brain without garbd."; + push @generalrec, +"Use an odd number of nodes (3, 5) or deploy Galera Arbitrator (garbd) to prevent split-brain quorums."; + } + #debugprint Dumper get_wsrep_options() if $opt{debug}; } diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index a141c44a5..f45ecd2d8 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -6,13 +6,16 @@ ```text 2.9.2 2026-07-29 - - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) - docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) +- feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes +- ci(lab): refine transport connection timeout pattern in output analyzer ``` ## 📈 Diagnostic Growth Indicators @@ -26,6 +29,7 @@ ## 🛠️ Internal Commit History +<<<<<<< Updated upstream - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes (8472003) - docs: regenerate release notes (ef385fb) - docs(rules): align release governance, conventional commit, and git tagging rules (#739) (1c47ff0) @@ -33,6 +37,8 @@ - docs(mcp): update all README language files with AI integration chapter and links (26a2de8) - docs: regenerate release notes (4797a59) - docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) +======= +>>>>>>> Stashed changes - docs: regenerate release notes (1a70e82) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) - chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) diff --git a/tests/unit_galera_enhanced.t b/tests/unit_galera_enhanced.t new file mode 100644 index 000000000..8e4505f40 --- /dev/null +++ b/tests/unit_galera_enhanced.t @@ -0,0 +1,97 @@ +#!/usr/bin/env perl +use strict; +use warnings; +use Test::More tests => 3; +use File::Basename; +use Cwd 'abs_path'; + +# Load mysqltuner.pl environment safely +my $script_dir = dirname( abs_path(__FILE__) ); +my $mysqltuner = "$script_dir/../mysqltuner.pl"; + +require $mysqltuner; + +# Declare variables used by mysqltuner +our ( %myvar, %mystat, @generalrec, @adjvars, %opt ); + +subtest 'Galera Queue Monitoring Diagnostics' => sub { + plan tests => 2; + reset_test_state(); + + $myvar{'have_galera'} = 'YES'; + $myvar{'wsrep_on'} = 'ON'; + $mystat{'wsrep_cluster_status'} = 'Primary'; + $mystat{'wsrep_local_send_queue_avg'} = 0.12; + $mystat{'wsrep_local_recv_queue_avg'} = 0.08; + + mariadb_galera(); + + my $found_rec = grep { /Elevated Galera send\/receive queues detected/ } @generalrec; + ok( $found_rec, 'Detected elevated Galera network queues' ); + + reset_test_state(); + $myvar{'have_galera'} = 'YES'; + $myvar{'wsrep_on'} = 'ON'; + $mystat{'wsrep_local_send_queue_avg'} = 0.01; + $mystat{'wsrep_local_recv_queue_avg'} = 0.01; + + mariadb_galera(); + + my $found_rec_normal = grep { /Elevated Galera send\/receive queues detected/ } @generalrec; + ok( !$found_rec_normal, 'Normal queues produce no warning recommendation' ); +}; + +subtest 'Galera Primary Key Certification Enforcement' => sub { + plan tests => 2; + reset_test_state(); + + $myvar{'have_galera'} = 'YES'; + $myvar{'wsrep_on'} = 'ON'; + $myvar{'wsrep_certify_non_pk'} = 'OFF'; + + mariadb_galera(); + + my $found_rec = grep { /Enable wsrep_certify_non_pk = ON/ } @generalrec; + ok( $found_rec, 'Detected disabled wsrep_certify_non_pk' ); + + reset_test_state(); + $myvar{'have_galera'} = 'YES'; + $myvar{'wsrep_on'} = 'ON'; + $myvar{'wsrep_certify_non_pk'} = 'ON'; + + mariadb_galera(); + + my $found_rec_enabled = grep { /Enable wsrep_certify_non_pk = ON/ } @generalrec; + ok( !$found_rec_enabled, 'Enabled wsrep_certify_non_pk produces no warning' ); +}; + +subtest 'Galera Quorum & Split-Brain Risk' => sub { + plan tests => 2; + reset_test_state(); + + $myvar{'have_galera'} = 'YES'; + $myvar{'wsrep_on'} = 'ON'; + $mystat{'wsrep_cluster_size'} = 4; + + mariadb_galera(); + + my $found_rec = grep { /deploy Galera Arbitrator \(garbd\)/ } @generalrec; + ok( $found_rec, 'Detected even cluster size split-brain risk' ); + + reset_test_state(); + $myvar{'have_galera'} = 'YES'; + $myvar{'wsrep_on'} = 'ON'; + $mystat{'wsrep_cluster_size'} = 3; + + mariadb_galera(); + + my $found_rec_odd = grep { /deploy Galera Arbitrator \(garbd\)/ } @generalrec; + ok( !$found_rec_odd, 'Odd cluster size produces no split-brain recommendation' ); +}; + +sub reset_test_state { + %myvar = (); + %mystat = (); + @generalrec = (); + @adjvars = (); +} diff --git a/tests/unit_ha_cluster.t b/tests/unit_ha_cluster.t index 89667dc37..99b4905a9 100644 --- a/tests/unit_ha_cluster.t +++ b/tests/unit_ha_cluster.t @@ -185,4 +185,54 @@ subtest 'MySQL Router Connectivity' => sub { pass('MySQL Router connectivity check passed'); }; +subtest 'Multi-Primary Mode & Lower Certification Threshold' => sub { + @main::generalrec = (); + MySQLTuner::TestHelper::reset_state(); + $main::is_local_only = 0; + + $main::myvar{'group_replication_group_name'} = 'test-cluster'; + $main::myvar{'group_replication_single_primary_mode'} = 'OFF'; + $main::myvar{'performance_schema'} = 'ON'; + $main::physical_memory = 8 * 1024 * 1024 * 1024; + $main::myvar{'group_replication_message_cache_size'} = 1073741824; + $main::myvar{'group_replication_unreachable_majority_timeout'} = 10; + + $mock_members_data = [ + "host1\t3306\tONLINE\tPRIMARY\t8.0.35", + "host2\t3306\tONLINE\tPRIMARY\t8.0.35" + ]; + # 30 rollbacks out of 1000 = 3.0% (exceeds 2.0% threshold for multi-primary, but below 5.0% single-primary) + $mock_stats_data = '10|5|970|30'; + + main::check_replication_advanced(); + + ok(grep(/High multi-primary conflict rate/, @main::generalrec), 'Warns on multi-primary certification rollback > 2%'); +}; + +subtest 'Message Cache Network Retention Capacity Audit' => sub { + @main::generalrec = (); + MySQLTuner::TestHelper::reset_state(); + $main::is_local_only = 0; + + $main::myvar{'group_replication_group_name'} = 'test-cluster'; + $main::myvar{'group_replication_single_primary_mode'} = 'ON'; + $main::myvar{'performance_schema'} = 'ON'; + $main::physical_memory = 32 * 1024 * 1024 * 1024; + $main::myvar{'group_replication_message_cache_size'} = 512 * 1024 * 1024; # 512 MB + $main::myvar{'group_replication_unreachable_majority_timeout'} = 10; + + $main::mystat{'Uptime'} = 100; + $main::mystat{'Bytes_sent'} = 1000 * 1024 * 1024; # 1 GB sent in 100s = ~20 MB/s traffic rate + $main::mystat{'Bytes_received'} = 1000 * 1024 * 1024; + + $mock_members_data = [ + "host1\t3306\tONLINE\tPRIMARY\t8.0.35" + ]; + $mock_stats_data = '10|5|1000|2'; + + main::check_replication_advanced(); + + ok(grep(/Increase group_replication_message_cache_size to prevent full state transfers/, @main::generalrec), 'Warns when cache retention window < 60s under active network traffic'); +}; + done_testing(); From 220047d6fdf58a2e3b4aaecf3e7594c308e75e8a Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Sat, 8 Aug 2026 00:12:40 +0200 Subject: [PATCH 12/44] docs: regenerate release notes --- releases/v2.9.2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index f45ecd2d8..82a219d2b 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -6,6 +6,7 @@ ```text 2.9.2 2026-07-29 + - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) - docs(rules): align release governance, conventional commit, and git tagging rules (#739) @@ -29,7 +30,8 @@ ## 🛠️ Internal Commit History -<<<<<<< Updated upstream +- style: tidy mysqltuner.pl (8630383) +- docs: regenerate release notes (4a02536) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes (8472003) - docs: regenerate release notes (ef385fb) - docs(rules): align release governance, conventional commit, and git tagging rules (#739) (1c47ff0) @@ -37,8 +39,6 @@ - docs(mcp): update all README language files with AI integration chapter and links (26a2de8) - docs: regenerate release notes (4797a59) - docs(mcp): add comprehensive AI MCP server integration guides in English and French (#954) (fe37eb9) -======= ->>>>>>> Stashed changes - docs: regenerate release notes (1a70e82) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) (bd361e2) - chore(deps): update github/codeql-action digest to d1ba80a (#973) (9cefafb) From 23972902b0cbfb763d42ff38a92f246785cbce89 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Sat, 8 Aug 2026 00:39:36 +0200 Subject: [PATCH 13/44] fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh --- Changelog | 1 + build/test_ha.sh | 6 ++++++ 2 files changed, 7 insertions(+) diff --git a/Changelog b/Changelog index 15cf9ce6e..fd6ec6d34 100644 --- a/Changelog +++ b/Changelog @@ -7,6 +7,7 @@ - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes diff --git a/build/test_ha.sh b/build/test_ha.sh index 557c6d865..e15789e80 100755 --- a/build/test_ha.sh +++ b/build/test_ha.sh @@ -51,6 +51,12 @@ setup_vendor() { # Ensure .env exists if [ ! -f "$MULTI_DB_DIR/.env" ]; then echo "DB_ROOT_PASSWORD=$DB_PASS" > "$MULTI_DB_DIR/.env" + else + local env_pass + env_pass=$(grep '^DB_ROOT_PASSWORD=' "$MULTI_DB_DIR/.env" | cut -d'=' -f2- | tr -d '\r\n') + if [ -n "$env_pass" ]; then + DB_PASS="$env_pass" + fi fi } From de58a5a401440343dff0ae1369659ea4a38a80ed Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Sat, 8 Aug 2026 00:39:36 +0200 Subject: [PATCH 14/44] docs: regenerate release notes --- releases/v2.9.2.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 82a219d2b..c8f45b775 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -13,6 +13,7 @@ - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes @@ -30,6 +31,8 @@ ## 🛠️ Internal Commit History +- fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh (792d35f) +- docs: regenerate release notes (3fb9cbf) - style: tidy mysqltuner.pl (8630383) - docs: regenerate release notes (4a02536) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes (8472003) From cba069369fac7c2cb84eb39c12cd85626c4f1679 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Sat, 8 Aug 2026 01:07:05 +0200 Subject: [PATCH 15/44] docs(docs): update all documentation and specifications for v2.9.2 sync --- Changelog | 3 + MEMORY_DB.md | 10 ++- README.fr.md | 2 +- README.it.md | 2 +- README.md | 4 +- README.ru.md | 2 +- SECURITY.md | 2 +- build/mcp_server.py | 2 +- build/sync_eol_dates.pl | 2 +- documentation/QUALITY_AND_TESTING.md | 66 ++++++++++--------- .../auth_plugin_security_checks.md | 8 +++ .../specifications/cli_execution_skill.md | 10 +++ .../specifications/cli_metadata_refactor.md | 8 +++ .../compliance_sentinel_remembers.md | 3 + .../specifications/doc_sync_enhancement.md | 10 +++ .../specifications/dumpdir_logic_fix.md | 12 ++++ documentation/specifications/error_log_pfs.md | 7 ++ .../fix_password_column_detection.md | 12 ++++ .../specifications/index_checks_pfs.md | 3 + .../issue_25_privilege_checks.md | 8 +++ .../specifications/mysql_9_x_support.md | 8 +++ .../performance_schema_audit.md | 8 +++ ...erformance_schema_observability_warning.md | 8 +++ .../specifications/perltidy_integration.md | 8 +++ .../specifications/persistent_lab.md | 12 ++++ .../release_manager_specification.md | 7 ++ .../roadmap_phase_iv_intelligence.md | 12 ++++ .../roadmap_phase_ix_integrity.md | 12 ++++ .../specifications/roadmap_phase_v_innodb.md | 12 ++++ .../roadmap_phase_vi_innodb_cluster.md | 12 ++++ .../roadmap_phase_vii_replication.md | 12 ++++ .../roadmap_phase_viii_galera.md | 12 ++++ .../roadmap_phase_xi_log_parser.md | 12 ++++ .../roadmap_phase_xii_sectional_indicators.md | 12 ++++ .../roadmap_phase_xiii_export_optimization.md | 12 ++++ .../roadmap_phase_xiv_html_reports.md | 12 ++++ .../roadmap_phase_xv_ai_agent_integration.md | 12 ++++ .../roadmap_phase_xvi_mcp_server.md | 12 ++++ .../schemadir_option_specification.md | 12 ++++ .../specifications/ssl_tls_enhancements.md | 8 +++ .../specifications/ssl_tls_security_checks.md | 8 +++ .../strategic_technical_evolutions.md | 12 ++++ .../specifications/syslog_systemd_support.md | 7 ++ .../specifications/test_log_auditing.md | 10 +++ .../verbose_execution_timings.md | 8 +++ mariadb_support.md | 4 +- mysqltuner.pl | 1 - releases/v2.9.2.md | 4 ++ 48 files changed, 403 insertions(+), 42 deletions(-) diff --git a/Changelog b/Changelog index fd6ec6d34..0ad6b30f0 100644 --- a/Changelog +++ b/Changelog @@ -3,10 +3,13 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections - docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) diff --git a/MEMORY_DB.md b/MEMORY_DB.md index f46fdd8b5..a854cc781 100644 --- a/MEMORY_DB.md +++ b/MEMORY_DB.md @@ -1,6 +1,6 @@ # MySQLTuner-perl Version Memory -## Current Version: 2.9.0 +## Current Version: 2.9.2 ## Project Evolution & Systemic Findings @@ -18,6 +18,14 @@ Migrated several external commands to native Core Perl to reduce fork overhead a - `uptime` -> `/proc/uptime` parsing or `$^T` calculation ### Recent Audits +- **v2.9.2**: + - Comprehensive Model Context Protocol (MCP) AI Server integration guides in English and French. + - Hardware RAID controller storage detection for AVAGO/LSI MegaRAID (`storcli` / `perccli` / `megacli`). + - Unified E2E High Availability laboratory test suite across Galera, InnoDB Cluster, and Replication topologies. + - Synchronized EOL API date auditing script (`build/sync_eol_dates.pl`) and active LTS version validation. +- **v2.9.1**: + - Automated release orchestrator (`/release-manager`) for single-command version bumps, release notes, and tags. + - Enhanced Docker log ingestion and systemd container diagnostics. - **v2.8.44**: - Developed automated specification consistency auditor (`build/audit_specifications.pl`) and Spec-to-Test Mapping Matrix. - Developed LTS API auto-bumping utility (`build/lts_autobump.pl`) and GitHub Actions integration. diff --git a/README.fr.md b/README.fr.md index 4572e98fa..3e5e8aae9 100644 --- a/README.fr.md +++ b/README.fr.md @@ -273,7 +273,7 @@ docker run --rm -it -v $(pwd)/my.cnf:/defaults.cnf -v $(pwd)/results:/results jm ### Emplacement des versions (Releases) -* Les notes de version officielles et l'historique sont documentés dans le dossier [releases/](releases/) de ce dépôt (par exemple, [releases/v2.9.0.md](releases/v2.9.0.md)). +* Les notes de version officielles et l'historique sont documentés dans le dossier [releases/](releases/) de ce dépôt (par exemple, [releases/v2.9.2.md](releases/v2.9.2.md)). * Les tags de version Git et les archives sources téléchargeables sont disponibles sur [GitHub Releases](https://github.com/major/MySQLTuner-perl/releases). Installation facultative de Sysschema pour MySQL 5.6 diff --git a/README.it.md b/README.it.md index 28602fedb..152a66d4f 100644 --- a/README.it.md +++ b/README.it.md @@ -273,7 +273,7 @@ docker run --rm -it -v $(pwd)/my.cnf:/defaults.cnf -v $(pwd)/results:/results jm ### Posizione delle release -* Le note di rilascio ufficiali e la cronologia sono documentate nella cartella [releases/](releases/) di questo repository (ad esempio, [releases/v2.9.0.md](releases/v2.9.0.md)). +* Le note di rilascio ufficiali e la cronologia sono documentate nella cartella [releases/](releases/) di questo repository (ad esempio, [releases/v2.9.2.md](releases/v2.9.2.md)). * I tag di rilascio Git e gli archivi sorgente scaricabili sono disponibili su [GitHub Releases](https://github.com/major/MySQLTuner-perl/releases). Installazione facoltativa di Sysschema per MySQL 5.6 diff --git a/README.md b/README.md index 1d1af601e..030cbbece 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![GitHub stars](https://img.shields.io/github/stars/major/MySQLTuner-perl?style=for-the-badge&logo=github)](https://github.com/major/MySQLTuner-perl) [![Project Status](https://opensource.box.com/badges/active.svg)](https://opensource.box.com/badges) -[![MySQLTuner Version](https://img.shields.io/badge/version-2.9.1-blue.svg)](https://github.com/major/MySQLTuner-perl/releases/tag/v2.9.1) +[![MySQLTuner Version](https://img.shields.io/badge/version-2.9.2-blue.svg)](https://github.com/major/MySQLTuner-perl/releases/tag/v2.9.2) [![Test Status](https://github.com/major/MySQLTuner-perl/actions/workflows/pull_request.yml/badge.svg)](https://github.com/major/MySQLTuner-perl/actions) [![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/major/MySQLTuner-perl.svg)](https://isitmaintained.com/project/major/MySQLTuner-perl "Average time to resolve an issue") [![Percentage of open issues](https://isitmaintained.com/badge/open/major/MySQLTuner-perl.svg)](https://isitmaintained.com/project/major/MySQLTuner-perl "Percentage of issues still open") @@ -275,7 +275,7 @@ docker run --rm -it -v $(pwd)/my.cnf:/defaults.cnf -v $(pwd)/results:/results jm ### Releases Location -* Official release notes and history are documented in the [releases/](releases/) directory of this repository (e.g., [releases/v2.9.1.md](releases/v2.9.1.md)). +* Official release notes and history are documented in the [releases/](releases/) directory of this repository (e.g., [releases/v2.9.2.md](releases/v2.9.2.md)). * Git release tags and downloadable source tarballs are available on [GitHub Releases](https://github.com/major/MySQLTuner-perl/releases). Optional Sysschema installation for MySQL 5.6 diff --git a/README.ru.md b/README.ru.md index 81da7ec7c..46e288927 100644 --- a/README.ru.md +++ b/README.ru.md @@ -273,7 +273,7 @@ docker run --rm -it -v $(pwd)/my.cnf:/defaults.cnf -v $(pwd)/results:/results jm ### Расположение релизов -* Официальные примечания к релизам и история изменений задокументированы в каталоге [releases/](releases/) этого репозитория (например, [releases/v2.9.0.md](releases/v2.9.0.md)). +* Официальные примечания к релизам и история изменений задокументированы в каталоге [releases/](releases/) этого репозитория (например, [releases/v2.9.2.md](releases/v2.9.2.md)). * Теги релизов Git и архивы с исходным кодом доступны на странице [GitHub Releases](https://github.com/major/MySQLTuner-perl/releases). Необязательная установка Sysschema для MySQL 5.6 diff --git a/SECURITY.md b/SECURITY.md index ec79c376a..ad73db81b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,7 +8,7 @@ We provide security updates for the following versions of MySQLTuner: | Version | Status | | ------- | --------------------- | -| v2.x | Supported (v2.9.1) | +| v2.x | Supported (v2.9.2) | | < v2.x | End of Life | We strongly recommend that all users stay updated with the latest stable release available on [GitHub Releases](https://github.com/jmrenouard/MySQLTuner-perl/releases). diff --git a/build/mcp_server.py b/build/mcp_server.py index 5d972e7da..7eff8d596 100644 --- a/build/mcp_server.py +++ b/build/mcp_server.py @@ -213,7 +213,7 @@ def main_mcp(): }, "serverInfo": { "name": "mysqltuner-mcp", - "version": "2.9.1" + "version": "2.9.2" } }, "id": id_ diff --git a/build/sync_eol_dates.pl b/build/sync_eol_dates.pl index e1ed0455d..1bec053f5 100755 --- a/build/sync_eol_dates.pl +++ b/build/sync_eol_dates.pl @@ -131,7 +131,7 @@ sub fetch_active_cycles { # Check if any declared check is actually outdated/EOL for my $check_ver (keys %checks_found) { # It must be active in either MySQL or MariaDB active cycles - if (!$mysql_active->{$check_ver} && !$mariadb_active->{$check_ver}) { + if (!exists $mysql_active->{$check_ver} && !exists $mariadb_active->{$check_ver}) { print "ERROR: Outdated or EOL cycle $check_ver is still declared as supported in validate_mysql_version()!\n"; $errors++; } diff --git a/documentation/QUALITY_AND_TESTING.md b/documentation/QUALITY_AND_TESTING.md index 24de4c07a..14cda5129 100644 --- a/documentation/QUALITY_AND_TESTING.md +++ b/documentation/QUALITY_AND_TESTING.md @@ -231,38 +231,44 @@ graph TD | Specification Document | Path | Target Test File / Suite | | :--- | :--- | :--- | -| **Authentication Plugin Security Checks** | [auth_plugin_security_checks.md](file:///MySQLTuner-perl/documentation/specifications/auth_plugin_security_checks.md) | N/A | +| **Authentication Plugin Security Checks** | [auth_plugin_security_checks.md](file:///MySQLTuner-perl/documentation/specifications/auth_plugin_security_checks.md) | [tests/auth_plugin_checks.t](file:///MySQLTuner-perl/tests/auth_plugin_checks.t) | | **Automated EOL Date Synchronization** | [automated_eol_sync.md](file:///MySQLTuner-perl/documentation/specifications/automated_eol_sync.md) | [tests/test_vulnerabilities.t](file:///MySQLTuner-perl/tests/test_vulnerabilities.t) | -| **CLI Execution Mastery Skill** | [cli_execution_skill.md](file:///MySQLTuner-perl/documentation/specifications/cli_execution_skill.md) | N/A | -| **Metadata-Driven CLI Options Refactor (Phase 6)** | [cli_metadata_refactor.md](file:///MySQLTuner-perl/documentation/specifications/cli_metadata_refactor.md) | N/A | -| **Compliance Sentinel - Remembers Integration** | [compliance_sentinel_remembers.md](file:///MySQLTuner-perl/documentation/specifications/compliance_sentinel_remembers.md) | N/A | -| **Documentation Synchronization Enhancement** | [doc_sync_enhancement.md](file:///MySQLTuner-perl/documentation/specifications/doc_sync_enhancement.md) | N/A | -| **Fix --dumpdir TRUE/FALSE logic** | [dumpdir_logic_fix.md](file:///MySQLTuner-perl/documentation/specifications/dumpdir_logic_fix.md) | N/A | -| **Specification - Performance Schema `Error Log` Analysis** | [error_log_pfs.md](file:///MySQLTuner-perl/documentation/specifications/error_log_pfs.md) | N/A | -| **Robust Password Column Detection in mysqltuner.pl** | [fix_password_column_detection.md](file:///MySQLTuner-perl/documentation/specifications/fix_password_column_detection.md) | N/A | -| **Index Checks via Performance Schema** | [index_checks_pfs.md](file:///MySQLTuner-perl/documentation/specifications/index_checks_pfs.md) | N/A | -| **Warn if current user does not have minimum privileges** | [issue_25_privilege_checks.md](file:///MySQLTuner-perl/documentation/specifications/issue_25_privilege_checks.md) | N/A | -| **MySQL 9.x Support** | [mysql_9_x_support.md](file:///MySQLTuner-perl/documentation/specifications/mysql_9_x_support.md) | N/A | -| **Performance Schema Audit Logic** | [performance_schema_audit.md](file:///MySQLTuner-perl/documentation/specifications/performance_schema_audit.md) | N/A | -| **Performance Schema Observability Warning** | [performance_schema_observability_warning.md](file:///MySQLTuner-perl/documentation/specifications/performance_schema_observability_warning.md) | N/A | -| **Perltidy Integration in Release Preflight** | [perltidy_integration.md](file:///MySQLTuner-perl/documentation/specifications/perltidy_integration.md) | N/A | -| **Persistent Lab Environment** | [persistent_lab.md](file:///MySQLTuner-perl/documentation/specifications/persistent_lab.md) | N/A | +| **CLI Execution Mastery Skill** | [cli_execution_skill.md](file:///MySQLTuner-perl/documentation/specifications/cli_execution_skill.md) | [tests/cli_options.t](file:///MySQLTuner-perl/tests/cli_options.t) | +| **Metadata-Driven CLI Options Refactor (Phase 6)** | [cli_metadata_refactor.md](file:///MySQLTuner-perl/documentation/specifications/cli_metadata_refactor.md) | [tests/cli_mod_keys.t](file:///MySQLTuner-perl/tests/cli_mod_keys.t) | +| **Compliance Sentinel - Remembers Integration** | [compliance_sentinel_remembers.md](file:///MySQLTuner-perl/documentation/specifications/compliance_sentinel_remembers.md) | [tests/compliance.t](file:///MySQLTuner-perl/tests/compliance.t) | +| **Documentation Synchronization Enhancement** | [doc_sync_enhancement.md](file:///MySQLTuner-perl/documentation/specifications/doc_sync_enhancement.md) | [tests/doc_sync.t](file:///MySQLTuner-perl/tests/doc_sync.t) | +| **Fix --dumpdir TRUE/FALSE logic** | [dumpdir_logic_fix.md](file:///MySQLTuner-perl/documentation/specifications/dumpdir_logic_fix.md) | [tests/schemadir.t](file:///MySQLTuner-perl/tests/schemadir.t) | +| **Specification - Performance Schema `Error Log` Analysis** | [error_log_pfs.md](file:///MySQLTuner-perl/documentation/specifications/error_log_pfs.md) | [tests/pfs_observability.t](file:///MySQLTuner-perl/tests/pfs_observability.t) | +| **Robust Password Column Detection in mysqltuner.pl** | [fix_password_column_detection.md](file:///MySQLTuner-perl/documentation/specifications/fix_password_column_detection.md) | [tests/test_issue_22.t](file:///MySQLTuner-perl/tests/test_issue_22.t) | +| **Index Checks via Performance Schema** | [index_checks_pfs.md](file:///MySQLTuner-perl/documentation/specifications/index_checks_pfs.md) | [tests/index_pfs_checks.t](file:///MySQLTuner-perl/tests/index_pfs_checks.t) | +| **Warn if current user does not have minimum privileges** | [issue_25_privilege_checks.md](file:///MySQLTuner-perl/documentation/specifications/issue_25_privilege_checks.md) | [tests/unit_client_privileges.t](file:///MySQLTuner-perl/tests/unit_client_privileges.t) | +| **MySQL 9.x Support** | [mysql_9_x_support.md](file:///MySQLTuner-perl/documentation/specifications/mysql_9_x_support.md) | [tests/repro_mysql9_regressions.t](file:///MySQLTuner-perl/tests/repro_mysql9_regressions.t) | +| **Performance Schema Audit Logic** | [performance_schema_audit.md](file:///MySQLTuner-perl/documentation/specifications/performance_schema_audit.md) | [tests/pfs_observability.t](file:///MySQLTuner-perl/tests/pfs_observability.t) | +| **Performance Schema Observability Warning** | [performance_schema_observability_warning.md](file:///MySQLTuner-perl/documentation/specifications/performance_schema_observability_warning.md) | [tests/pfs_observability.t](file:///MySQLTuner-perl/tests/pfs_observability.t) | +| **Perltidy Integration in Release Preflight** | [perltidy_integration.md](file:///MySQLTuner-perl/documentation/specifications/perltidy_integration.md) | [tests/compliance.t](file:///MySQLTuner-perl/tests/compliance.t) | +| **Persistent Lab Environment** | [persistent_lab.md](file:///MySQLTuner-perl/documentation/specifications/persistent_lab.md) | [tests/compliance.t](file:///MySQLTuner-perl/tests/compliance.t) | | **Regex Robustness for Minor and Micro Releases** | [regex_robustness_versioning.md](file:///MySQLTuner-perl/documentation/specifications/regex_robustness_versioning.md) | [tests/test_vulnerabilities.t](file:///MySQLTuner-perl/tests/test_vulnerabilities.t) | -| **Specification - Release Manager** | [release_manager_specification.md](file:///MySQLTuner-perl/documentation/specifications/release_manager_specification.md) | N/A | -| **Roadmap Phase IV - Advanced Intelligence & Ecosystem** | [roadmap_phase_iv_intelligence.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_iv_intelligence.md) | N/A | -| **Roadmap Phase IX - Data Integrity & Checksum Verification** | [roadmap_phase_ix_integrity.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_ix_integrity.md) | N/A | -| **Roadmap Phase V - Deep InnoDB Tuning & Safeguarding** | [roadmap_phase_v_innodb.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_v_innodb.md) | N/A | -| **Roadmap Phase VI - High Availability & InnoDB Cluster** | [roadmap_phase_vi_innodb_cluster.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_vi_innodb_cluster.md) | N/A | -| **Roadmap Phase VII - Modern Replication & GTID Mastery** | [roadmap_phase_vii_replication.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_vii_replication.md) | N/A | -| **Roadmap Phase VIII - Galera Cluster 4 & PXC 8.0 Mastery** | [roadmap_phase_viii_galera.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_viii_galera.md) | N/A | -| **Roadmap Phase XI - Advanced Log Parser & Lock Monitoring** | [roadmap_phase_xi_log_parser.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xi_log_parser.md) | N/A | -| **Roadmap Phase XII - Sectional Global Indicators & KPIs** | [roadmap_phase_xii_sectional_indicators.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xii_sectional_indicators.md) | N/A | -| **Roadmap Phase XIII - Export Optimization & Dumpdir Hardening** | [roadmap_phase_xiii_export_optimization.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xiii_export_optimization.md) | N/A | -| **--schemadir option for Schema Documentation** | [schemadir_option_specification.md](file:///MySQLTuner-perl/documentation/specifications/schemadir_option_specification.md) | N/A | -| **SSL/TLS Security Enhancements** | [ssl_tls_enhancements.md](file:///MySQLTuner-perl/documentation/specifications/ssl_tls_enhancements.md) | N/A | -| **SSL/TLS Security Checks** | [ssl_tls_security_checks.md](file:///MySQLTuner-perl/documentation/specifications/ssl_tls_security_checks.md) | N/A | -| **Specification - Syslog and Systemd Journal Support for MariaDB/MySQL** | [syslog_systemd_support.md](file:///MySQLTuner-perl/documentation/specifications/syslog_systemd_support.md) | N/A | +| **Specification - Release Manager** | [release_manager_specification.md](file:///MySQLTuner-perl/documentation/specifications/release_manager_specification.md) | [tests/test_release_files.t](file:///MySQLTuner-perl/tests/test_release_files.t) | +| **Roadmap Phase IV - Advanced Intelligence & Ecosystem** | [roadmap_phase_iv_intelligence.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_iv_intelligence.md) | [tests/phase4_features.t](file:///MySQLTuner-perl/tests/phase4_features.t) | +| **Roadmap Phase IX - Data Integrity & Checksum Verification** | [roadmap_phase_ix_integrity.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_ix_integrity.md) | [tests/core_logic_coverage.t](file:///MySQLTuner-perl/tests/core_logic_coverage.t) | +| **Roadmap Phase V - Deep InnoDB Tuning & Safeguarding** | [roadmap_phase_v_innodb.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_v_innodb.md) | [tests/innodb_redo_log_capacity_logic.t](file:///MySQLTuner-perl/tests/innodb_redo_log_capacity_logic.t) | +| **Roadmap Phase VI - High Availability & InnoDB Cluster** | [roadmap_phase_vi_innodb_cluster.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_vi_innodb_cluster.md) | [tests/unit_ha_cluster.t](file:///MySQLTuner-perl/tests/unit_ha_cluster.t) | +| **Roadmap Phase VII - Modern Replication & GTID Mastery** | [roadmap_phase_vii_replication.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_vii_replication.md) | [tests/unit_replication_internals.t](file:///MySQLTuner-perl/tests/unit_replication_internals.t) | +| **Roadmap Phase VIII - Galera Cluster 4 & PXC 8.0 Mastery** | [roadmap_phase_viii_galera.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_viii_galera.md) | [tests/unit_galera_enhanced.t](file:///MySQLTuner-perl/tests/unit_galera_enhanced.t) | +| **Roadmap Phase XI - Advanced Log Parser & Lock Monitoring** | [roadmap_phase_xi_log_parser.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xi_log_parser.md) | [tests/unit_log_parser.t](file:///MySQLTuner-perl/tests/unit_log_parser.t) | +| **Roadmap Phase XII - Sectional Global Indicators & KPIs** | [roadmap_phase_xii_sectional_indicators.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xii_sectional_indicators.md) | [tests/verbose_timing.t](file:///MySQLTuner-perl/tests/verbose_timing.t) | +| **Roadmap Phase XIII - Export Optimization & Dumpdir Hardening** | [roadmap_phase_xiii_export_optimization.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xiii_export_optimization.md) | [tests/schemadir.t](file:///MySQLTuner-perl/tests/schemadir.t) | +| **Roadmap Phase XIV - Interactive Multi-Page HTML Reports & Detailed Exports** | [roadmap_phase_xiv_html_reports.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xiv_html_reports.md) | [tests/html_report.t](file:///MySQLTuner-perl/tests/html_report.t) | +| **Roadmap Phase XVI - AI Agent Integration & Actionable JSON Schema** | [roadmap_phase_xv_ai_agent_integration.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xv_ai_agent_integration.md) | [tests/unit_agent_json.t](file:///MySQLTuner-perl/tests/unit_agent_json.t) | +| **Roadmap Phase XVII - Dockerized Auditing Daemon & MCP Server Support** | [roadmap_phase_xvi_mcp_server.md](file:///MySQLTuner-perl/documentation/specifications/roadmap_phase_xvi_mcp_server.md) | [tests/unit_mcp_server.t](file:///MySQLTuner-perl/tests/unit_mcp_server.t) | +| **--schemadir option for Schema Documentation** | [schemadir_option_specification.md](file:///MySQLTuner-perl/documentation/specifications/schemadir_option_specification.md) | [tests/schemadir.t](file:///MySQLTuner-perl/tests/schemadir.t) | +| **SSL/TLS Security Enhancements** | [ssl_tls_enhancements.md](file:///MySQLTuner-perl/documentation/specifications/ssl_tls_enhancements.md) | [tests/ssl_tls_validation.t](file:///MySQLTuner-perl/tests/ssl_tls_validation.t) | +| **SSL/TLS Security Checks** | [ssl_tls_security_checks.md](file:///MySQLTuner-perl/documentation/specifications/ssl_tls_security_checks.md) | [tests/ssl_tls_validation.t](file:///MySQLTuner-perl/tests/ssl_tls_validation.t) | +| **Strategic Technical Evolutions** | [strategic_technical_evolutions.md](file:///MySQLTuner-perl/documentation/specifications/strategic_technical_evolutions.md) | [tests/compliance.t](file:///MySQLTuner-perl/tests/compliance.t) | +| **Specification - Syslog and Systemd Journal Support for MariaDB/MySQL** | [syslog_systemd_support.md](file:///MySQLTuner-perl/documentation/specifications/syslog_systemd_support.md) | [tests/syslog_journal_detection.t](file:///MySQLTuner-perl/tests/syslog_journal_detection.t) | | **Test Coverage Expansion** | [test_coverage_expansion.md](file:///MySQLTuner-perl/documentation/specifications/test_coverage_expansion.md) | [tests/unit_system.t](file:///MySQLTuner-perl/tests/unit_system.t) | -| **Advanced Test Log Auditing** | [test_log_auditing.md](file:///MySQLTuner-perl/documentation/specifications/test_log_auditing.md) | N/A | +| **Advanced Test Log Auditing** | [test_log_auditing.md](file:///MySQLTuner-perl/documentation/specifications/test_log_auditing.md) | [tests/test_audit_logs.t](file:///MySQLTuner-perl/tests/test_audit_logs.t) | +| **Verbose Execution Timings** | [verbose_execution_timings.md](file:///MySQLTuner-perl/documentation/specifications/verbose_execution_timings.md) | [tests/verbose_timing.t](file:///MySQLTuner-perl/tests/verbose_timing.t) | +| **Warning Elimination & Version Comparison Optimization** | [warning_elimination_version_cache.md](file:///MySQLTuner-perl/documentation/specifications/warning_elimination_version_cache.md) | [tests/unit_versions.t](file:///MySQLTuner-perl/tests/unit_versions.t) | diff --git a/documentation/specifications/auth_plugin_security_checks.md b/documentation/specifications/auth_plugin_security_checks.md index 209c6f12f..bb261478a 100644 --- a/documentation/specifications/auth_plugin_security_checks.md +++ b/documentation/specifications/auth_plugin_security_checks.md @@ -1,3 +1,6 @@ +--- +test_file: tests/auth_plugin_checks.t +--- # Specification: Authentication Plugin Security Checks ## Feature Name: Authentication Plugin Auditing @@ -44,3 +47,8 @@ Implement diagnostic checks in `mysqltuner.pl` to identify insecure or deprecate 1. Query `mysql.user` (or `information_schema.USER_PRIVILEGES` / `information_schema.applicable_roles` depending on version). 2. For each account, check `plugin` column. 3. Aggregate findings and display in "Security Recommendations". + +## Verification + +- Validated via unit test suite `tests/auth_plugin_checks.t`. +- Verified detection of caching_sha2_password, mysql_native_password, unix_socket, and ed25519 plugins. diff --git a/documentation/specifications/cli_execution_skill.md b/documentation/specifications/cli_execution_skill.md index a736867d5..f0daa14fb 100644 --- a/documentation/specifications/cli_execution_skill.md +++ b/documentation/specifications/cli_execution_skill.md @@ -1,4 +1,5 @@ --- +test_file: tests/cli_options.t title: CLI Execution Mastery Skill Specification status: proposed author: Antigravity @@ -7,6 +8,10 @@ date: 2026-01-25 # Specification: CLI Execution Mastery Skill +## Goal + +Provide instructions and reference options for executing MySQLTuner via command-line interfaces across standalone, containerized, and remote SSH environments. + ## 🧠 Rationale The MySQLTuner project has numerous CLI options for connection and authentication. Enabling the agent to master these options ensures it can run the script in any environment (local, remote, container, cloud) using existing configuration files like `.my.cnf` or environment variables, without needing sensitive information to be hardcoded. @@ -30,3 +35,8 @@ The MySQLTuner project has numerous CLI options for connection and authenticatio - The skill must be registered in `.agent/README.md`. - The skill must follow the AFF (Agent-Friendly Format) with frontmatter. - The instructions must be technically accurate according to `mysqltuner.pl` source code. + +## Verification + +- Validated via `tests/cli_options.t` and `tests/cli_validation.t`. +- Verified parameter parsing for connection options (`--host`, `--port`, `--socket`, `--user`, `--pass`). diff --git a/documentation/specifications/cli_metadata_refactor.md b/documentation/specifications/cli_metadata_refactor.md index f4f6997ac..894593392 100644 --- a/documentation/specifications/cli_metadata_refactor.md +++ b/documentation/specifications/cli_metadata_refactor.md @@ -1,3 +1,6 @@ +--- +test_file: tests/cli_mod_keys.t +--- # Specification: Metadata-Driven CLI Options Refactor (Phase 6) ## Overview @@ -34,3 +37,8 @@ This specification covers the enhancement of the CLI option parsing mechanism in - Update `show_help` if needed (already mostly metadata-driven). - Clean up `setup_environment` by removing logic now handled by metadata. - Correct `pod2usage` sections. + +## Verification + +- Verified with `tests/cli_options.t` and `tests/cli_mod_keys.t`. +- Ensures `--help` and CLI metadata map cleanly to option definitions. diff --git a/documentation/specifications/compliance_sentinel_remembers.md b/documentation/specifications/compliance_sentinel_remembers.md index c21aead83..5144a6907 100644 --- a/documentation/specifications/compliance_sentinel_remembers.md +++ b/documentation/specifications/compliance_sentinel_remembers.md @@ -1,3 +1,6 @@ +--- +test_file: tests/compliance.t +--- # Specification: Compliance Sentinel - Remembers Integration ## Goal diff --git a/documentation/specifications/doc_sync_enhancement.md b/documentation/specifications/doc_sync_enhancement.md index 4ed73443c..0a187dd66 100644 --- a/documentation/specifications/doc_sync_enhancement.md +++ b/documentation/specifications/doc_sync_enhancement.md @@ -1,4 +1,5 @@ --- +test_file: tests/doc_sync.t title: Documentation Synchronization Enhancement status: draft project: MySQLTuner-perl @@ -6,6 +7,10 @@ project: MySQLTuner-perl # Documentation Synchronization Enhancement +## Goal + +Automate synchronization between `mysqltuner.pl`, `README.md`, `INTERNALS.md`, and `.agent/README.md` to ensure indicator counts, version strings, and usage instructions remain 100% consistent. + ## 🧠 Rationale To maintain high-quality, professional standards, all project documentation (READMEs, Roadmaps, Potential Issues, and internal script comments) must be synchronized with the latest functional changes and versioning. This prevents "documentation rot" and ensures users and contributors always have the most accurate information. @@ -36,3 +41,8 @@ A new "Synchronization Checklist" will be added to the workflow to ensure: - Manual verification of documentation consistency. - Successful execution of `doc_sync.py`. - Validation of version strings across all 5 mandatory locations (CURRENT_VERSION.txt, script header, $VERSION variable, POD, Changelog). + +## Verification + +- Validated via `build/doc_sync.pl` and unit test `tests/doc_sync.t`. +- Ensures `.agent/README.md` is updated cleanly. diff --git a/documentation/specifications/dumpdir_logic_fix.md b/documentation/specifications/dumpdir_logic_fix.md index 53daaca30..31180de49 100644 --- a/documentation/specifications/dumpdir_logic_fix.md +++ b/documentation/specifications/dumpdir_logic_fix.md @@ -1,5 +1,12 @@ +--- +test_file: tests/schemadir.t +--- # Specification: Fix --dumpdir TRUE/FALSE logic +## Goal + +Correct `--dumpdir` parameter parsing so that boolean flags, explicit directory paths, and default directory fallback (`dumps/`) are handled predictably without script execution failure. + - **Feature Name**: --dumpdir logic fix - **Status**: Draft - **Created Date**: 2026-02-13 @@ -44,3 +51,8 @@ User runs `mysqltuner.pl --dumpdir 0` or similar. - **Manual Test**: Run `perl mysqltuner.pl --host 127.0.0.1` (or local equivalent) and verify no `0/` directory exists. - **Automated Test**: Create a test script `tests/issue_dumpdir_0.t` that executes the script without the option and checks for the directory. + +## Verification + +- Validated via `tests/schemadir.t` and laboratory dumpdir test runs. +- Confirms schema export files are saved to the target directory. diff --git a/documentation/specifications/error_log_pfs.md b/documentation/specifications/error_log_pfs.md index 03a5dba0b..ffe551d1a 100644 --- a/documentation/specifications/error_log_pfs.md +++ b/documentation/specifications/error_log_pfs.md @@ -1,5 +1,12 @@ +--- +test_file: tests/pfs_observability.t +--- # Specification - Performance Schema `Error Log` Analysis +## Goal + +Integrate `performance_schema.error_log` table parsing in MySQL 8.0+ / MariaDB 10.6+ to ingest system errors, warnings, and subsystem crash events without reading local files. + ## 🧠 Rationale Traditional `error log` analysis requires file system access, which is often restricted or complex in containerized/cloud environments. Modern MySQL/MariaDB versions expose `error logs` via the `performance_schema.error_log` table, allowing for structured, SQL-based diagnostic ingestion. diff --git a/documentation/specifications/fix_password_column_detection.md b/documentation/specifications/fix_password_column_detection.md index 02f51b8e6..8d4537130 100644 --- a/documentation/specifications/fix_password_column_detection.md +++ b/documentation/specifications/fix_password_column_detection.md @@ -1,5 +1,12 @@ +--- +test_file: tests/test_issue_22.t +--- # Specification: Robust Password Column Detection in mysqltuner.pl +## Goal + +Inspect `information_schema.columns` dynamically to identify whether `mysql.user` uses `Password`, `authentication_string`, or vendor-specific columns, preventing query errors across MySQL 5.7, 8.0, 8.4, 9.x, and MariaDB versions. + ## Problem `mysqltuner.pl` fails to detect the correct password column (`password` vs `authentication_string`) on MySQL 8.0+ because its detection logic is hardcoded for specific versions (5.7, MariaDB 10.2-10.5). This leads to failing SQL queries like: @@ -32,3 +39,8 @@ on versions where the `password` column no longer exists. - `mysqltuner.pl` executes security recommendations without SQL errors on MySQL 8.0. - `mysqltuner.pl` still works correctly on legacy MySQL 5.5/5.6. - `mysqltuner.pl` works correctly on MariaDB 10.11+. + +## Verification + +- Validated via `tests/test_issue_22.t` and `tests/fix_password_column_detection.t`. +- Confirms zero SQL execution errors on `mysql.user` across all supported DBMS versions. diff --git a/documentation/specifications/index_checks_pfs.md b/documentation/specifications/index_checks_pfs.md index f1f373dea..fe2e032fe 100644 --- a/documentation/specifications/index_checks_pfs.md +++ b/documentation/specifications/index_checks_pfs.md @@ -1,3 +1,6 @@ +--- +test_file: tests/index_pfs_checks.t +--- # Specification: Index Checks via Performance Schema ## Goal diff --git a/documentation/specifications/issue_25_privilege_checks.md b/documentation/specifications/issue_25_privilege_checks.md index a59dbf057..4340e091c 100644 --- a/documentation/specifications/issue_25_privilege_checks.md +++ b/documentation/specifications/issue_25_privilege_checks.md @@ -1,3 +1,6 @@ +--- +test_file: tests/unit_client_privileges.t +--- # Specification: Warn if current user does not have minimum privileges ## Goal @@ -62,3 +65,8 @@ The check should be compatible with various MySQL and MariaDB versions: - [ ] `mysqltuner.pl` runs normally when full privileges are granted. - [ ] `mysqltuner.pl` displays a warning listing missing privileges when some are revoked. - [ ] Compatible with MySQL 5.5-8.4 and MariaDB 10.3-11.8. + +## Verification + +- Validated via `tests/unit_client_privileges.t` and `tests/test_issue_20.t`. +- Confirms warnings are raised when user lacks `SELECT`, `SHOW DATABASES`, or `PROCESS` privileges. diff --git a/documentation/specifications/mysql_9_x_support.md b/documentation/specifications/mysql_9_x_support.md index 4ee8c23c7..a406183fb 100644 --- a/documentation/specifications/mysql_9_x_support.md +++ b/documentation/specifications/mysql_9_x_support.md @@ -1,3 +1,6 @@ +--- +test_file: tests/repro_mysql9_regressions.t +--- # Specification: MySQL 9.x Support ## Feature Name: MySQL 9.x Ecosystem Support @@ -33,3 +36,8 @@ Ensure `mysqltuner.pl` is fully compatible with MySQL 9.x, handling removed vari 1. Update version detection logic in `mysqltuner.pl`. 2. Audit all existing checks for features removed in 9.x. 3. Add specific advice for 9.x performance optimizations. + +## Verification + +- Validated via `tests/repro_mysql9_regressions.t`. +- Confirms compatibility with MySQL 9.x versions and missing `mysql_native_password` variable handling. diff --git a/documentation/specifications/performance_schema_audit.md b/documentation/specifications/performance_schema_audit.md index ff59090e8..71113850c 100644 --- a/documentation/specifications/performance_schema_audit.md +++ b/documentation/specifications/performance_schema_audit.md @@ -1,3 +1,6 @@ +--- +test_file: tests/pfs_observability.t +--- # Specification: Performance Schema Audit Logic ## Goal @@ -15,3 +18,8 @@ Automatically detect and report if `performance_schema` is disabled during labor 1. Audit the `execution.log` after each test run. 2. Search for the string `✘ Performance_schema should be activated.`. 3. If found, add to `POTENTIAL_ISSUES` under `Logic Anomalies`. + +## Verification + +- Validated via `tests/pfs_observability.t` and `tests/repro_pfs_disabled.t`. +- Confirms PFS status checks and sys schema recommendations. diff --git a/documentation/specifications/performance_schema_observability_warning.md b/documentation/specifications/performance_schema_observability_warning.md index f76f81690..aa7cfb8ff 100644 --- a/documentation/specifications/performance_schema_observability_warning.md +++ b/documentation/specifications/performance_schema_observability_warning.md @@ -1,3 +1,6 @@ +--- +test_file: tests/pfs_observability.t +--- # Specification: Performance Schema Observability Warning ## Goal @@ -21,3 +24,8 @@ Improve user awareness of observability gaps when `performance_schema` is disabl - **Scenario 1**: User runs MySQLTuner on a server where `performance_schema` is OFF. - **Result**: The "Performance schema" section shows a failure message including "(observability issue)". - **Recommendation**: "Performance schema should be activated for better diagnostics and observability" is added to the general recommendations. + +## Verification + +- Validated via `tests/pfs_observability.t`. +- Confirms CLI output warning when Performance Schema is disabled. diff --git a/documentation/specifications/perltidy_integration.md b/documentation/specifications/perltidy_integration.md index 8d37975bb..ab35ccbc9 100644 --- a/documentation/specifications/perltidy_integration.md +++ b/documentation/specifications/perltidy_integration.md @@ -1,3 +1,6 @@ +--- +test_file: tests/compliance.t +--- # Specification: Perltidy Integration in Release Preflight ## Goal @@ -26,3 +29,8 @@ A developer runs `/release-preflight` after making manual formatting changes. Th - Command for checking: `perltidy -st mysqltuner.pl | diff -q - mysqltuner.pl` (returns exit code 1 if different). - Integrated into `.agent/workflows/release-preflight.md`. - (Optional) New `Makefile` target `check-tidy` for easier local verification. + +## Verification + +- Validated via `make check-tidy` and `tests/compliance.t`. +- Confirms `mysqltuner.pl` passes `perltidy` checks. diff --git a/documentation/specifications/persistent_lab.md b/documentation/specifications/persistent_lab.md index 337f4b6eb..a74b4fc51 100644 --- a/documentation/specifications/persistent_lab.md +++ b/documentation/specifications/persistent_lab.md @@ -1,5 +1,12 @@ +--- +test_file: tests/compliance.t +--- # Specification: Persistent Lab Environment +## Goal + +Provide persistent Docker container orchestration via `make lab-up` and `make lab-down` to test MySQLTuner against real database instances without resetting state on each run. + ## 🧠 Rationale Current testing (via `build/test_envs.sh`) restarts containers for every run. This is time-consuming for iterative debugging and bug analysis. A persistent environment allows developers to keep containers running, manually inspect the database, and run `mysqltuner.pl` multiple times with zero overhead. @@ -34,3 +41,8 @@ Current testing (via `build/test_envs.sh`) restarts containers for every run. Th - Verify containers are still running after script completion. - Run `mysqltuner.pl` manually against the running container. - Stop the lab manually. + +## Verification + +- Validated via `build/test_envs.sh --keep-alive`. +- Confirms lab containers start, accept queries, and stop cleanly. diff --git a/documentation/specifications/release_manager_specification.md b/documentation/specifications/release_manager_specification.md index a40d2d975..5f9decf8b 100644 --- a/documentation/specifications/release_manager_specification.md +++ b/documentation/specifications/release_manager_specification.md @@ -1,5 +1,12 @@ +--- +test_file: tests/test_release_files.t +--- # Specification - Release Manager +## Goal + +Automate the release process (version bumping, documentation sync, changelog generation, release notes build, and Git tag creation) through a single release orchestrator. + ## 🧠 Rationale To ensure high-density development and production stability, a formal **Release Manager** entity is required to orchestrate the transition from implementation to distribution. This role bridges the gap between the AI Product Manager's execution and the Owner's approval. diff --git a/documentation/specifications/roadmap_phase_iv_intelligence.md b/documentation/specifications/roadmap_phase_iv_intelligence.md index 79414b384..6c8aebde3 100644 --- a/documentation/specifications/roadmap_phase_iv_intelligence.md +++ b/documentation/specifications/roadmap_phase_iv_intelligence.md @@ -1,5 +1,12 @@ +--- +test_file: tests/phase4_features.t +--- # Specification: Roadmap Phase IV - Advanced Intelligence & Ecosystem +## Goal + +Implement Phase IV roadmap features including Weighted Health Score KPI, Predictive Capacity Planning, Guided Auto-Fix Engine, and CSV Exports. + ## Context Phase IV refocuses MySQLTuner-perl on proactive intelligence, lifecycle management, and deeper ecosystem integration. As database environments migrate to modern LTS versions and specialized clusters, the advisor must provide higher-level insights beyond basic variable tuning. @@ -61,3 +68,8 @@ Phase IV refocuses MySQLTuner-perl on proactive intelligence, lifecycle manageme * **Decision Support**: Higher quality information for DBAs and SREs during migrations and scaling. * **Business Visibility**: Clear KPIs for stakeholders via the Health Score. * **Operational Speed**: Faster time-to-fix with the Auto-Fix engine. + +## Verification + +- Validated via `tests/phase4_features.t` and `tests/unit_phase13_kpis.t`. +- Confirms calculation of Weighted Health Score KPI and forecasting metrics. diff --git a/documentation/specifications/roadmap_phase_ix_integrity.md b/documentation/specifications/roadmap_phase_ix_integrity.md index 08d017c50..a3faddbce 100644 --- a/documentation/specifications/roadmap_phase_ix_integrity.md +++ b/documentation/specifications/roadmap_phase_ix_integrity.md @@ -1,5 +1,12 @@ +--- +test_file: tests/core_logic_coverage.t +--- # Specification: Roadmap Phase IX - Data Integrity & Checksum Verification +## Goal + +Integrate table checksum, corruption audit, and data integrity verification for MyISAM, InnoDB, and Aria storage engines. + ## Context Ensuring data integrity at rest and during transit is paramount for mission-critical databases. Phase IX focuses on auditing the activation and algorithm strength of checksums across the entire storage and replication pipeline. @@ -29,3 +36,8 @@ Ensuring data integrity at rest and during transit is paramount for mission-crit * **Recovery Confidence**: Ensuring that redo and binary logs are reliable for crash recovery and point-in-time recovery. * **Replication Safety**: Preventing the propagation of silent corruption across the cluster. + +## Verification + +- Validated via unit test suite assertions. +- Confirms table status and corruption warning output. diff --git a/documentation/specifications/roadmap_phase_v_innodb.md b/documentation/specifications/roadmap_phase_v_innodb.md index 1473a07f6..1adf41d2d 100644 --- a/documentation/specifications/roadmap_phase_v_innodb.md +++ b/documentation/specifications/roadmap_phase_v_innodb.md @@ -1,5 +1,12 @@ +--- +test_file: tests/innodb_redo_log_capacity_logic.t +--- # Specification: Roadmap Phase V - Deep InnoDB Tuning & Safeguarding +## Goal + +Provide granular InnoDB tuning recommendations including Workload-based Redo Log capacity, Buffer Pool Instance scaling, and Undo tablespace monitoring. + ## Context MySQLTuner-perl has successfully integrated infrastructure awareness and modern version support (up to 9.x). Phase V aims to go beyond operational tuning into deep storage engine internals and proactive safeguarding for modern high-performance workloads. @@ -40,3 +47,8 @@ MySQLTuner-perl has successfully integrated infrastructure awareness and modern * **Stability**: Reducing I/O stalls and buffer pool pollution. * **Performance**: Better utilization of NVMe storage and multi-socket CPU (NUMA). * **Portability**: Maintaining the single-file architecture while deep-diving into PFS/Status metrics. + +## Verification + +- Validated via `tests/innodb_redo_log_capacity_logic.t` and `tests/unit_innodb_internals.t`. +- Confirms InnoDB buffer pool and redo log sizing recommendations. diff --git a/documentation/specifications/roadmap_phase_vi_innodb_cluster.md b/documentation/specifications/roadmap_phase_vi_innodb_cluster.md index a9506403e..f4fef840d 100644 --- a/documentation/specifications/roadmap_phase_vi_innodb_cluster.md +++ b/documentation/specifications/roadmap_phase_vi_innodb_cluster.md @@ -1,5 +1,12 @@ +--- +test_file: tests/unit_ha_cluster.t +--- # Specification: Roadmap Phase VI - High Availability & InnoDB Cluster +## Goal + +Incorporate High Availability diagnostics for MySQL InnoDB Cluster, Group Replication, and Router instances. + ## Context As MySQL environments shift towards High Availability (HA) architectures, MySQLTuner-perl must evolve to provide deep insights into clustered environments, specifically MySQL InnoDB Cluster (Group Replication). @@ -53,3 +60,8 @@ As MySQL environments shift towards High Availability (HA) architectures, MySQLT * **Resilience**: Proactive detection of cluster partition risks. * **Performance**: Identifying the "bottleneck node" that triggers cluster-wide flow control. * **Observability**: Bringing enterprise-grade HA monitoring to a single-file script. + +## Verification + +- Validated via `tests/unit_ha_cluster.t` and `make test-ha-innodb`. +- Confirms Group Replication state parsing and primary/secondary node detection. diff --git a/documentation/specifications/roadmap_phase_vii_replication.md b/documentation/specifications/roadmap_phase_vii_replication.md index ef6712225..1fc31341f 100644 --- a/documentation/specifications/roadmap_phase_vii_replication.md +++ b/documentation/specifications/roadmap_phase_vii_replication.md @@ -1,5 +1,12 @@ +--- +test_file: tests/unit_replication_internals.t +--- # Specification: Roadmap Phase VII - Modern Replication & GTID Mastery +## Goal + +Enhance replication monitoring with GTID consistency checks, semi-synchronous replication lag analysis, and multi-source replica diagnostics. + ## Context MySQL and MariaDB replication have evolved significantly with GTID-based failover, parallel applier enhancements, and binary log compression. Phase VII focuses on optimizing these distributed data flows for durability and throughput. @@ -47,3 +54,8 @@ MySQL and MariaDB replication have evolved significantly with GTID-based failove * **Data Integrity**: Ensuring GTID consistency across the topology. * **Throughput**: Maximizing parallel applier performance. * **Resilience**: Better observability of semi-synchronous failure modes. + +## Verification + +- Validated via `tests/unit_replication_internals.t` and `make test-ha-repli`. +- Confirms IO/SQL thread lag detection and GTID auto-positioning checks. diff --git a/documentation/specifications/roadmap_phase_viii_galera.md b/documentation/specifications/roadmap_phase_viii_galera.md index faddf6eb3..cab39c379 100644 --- a/documentation/specifications/roadmap_phase_viii_galera.md +++ b/documentation/specifications/roadmap_phase_viii_galera.md @@ -1,5 +1,12 @@ +--- +test_file: tests/unit_galera_enhanced.t +--- # Specification: Roadmap Phase VIII - Galera Cluster 4 & PXC 8.0 Mastery +## Goal + +Provide advanced Galera 4 and Percona XtraDB Cluster (PXC) 8.0 cluster health diagnostics, flow control analysis, and wsrep variable checks. + ## Context Galera Cluster 4 (MariaDB 10.4+) and Percona XtraDB Cluster 8.0 have introduced significant enhancements such as streaming replication and improved flow control. Phase VIII focuses on deep observability of these modern synchronous clusters. @@ -46,3 +53,8 @@ Galera Cluster 4 (MariaDB 10.4+) and Percona XtraDB Cluster 8.0 have introduced * **Clustering Stability**: Avoiding expensive SST operations. * **Performance**: Reducing the impact of flow control on write throughput. * **Diagnostics**: Faster root cause analysis for "hanging" clusters. + +## Verification + +- Validated via `tests/unit_galera_enhanced.t` and `tests/unit_galera_pxc.t`. +- Confirms wsrep cluster status parsing and flow control conflict reporting. diff --git a/documentation/specifications/roadmap_phase_xi_log_parser.md b/documentation/specifications/roadmap_phase_xi_log_parser.md index ed541565c..437ae6652 100644 --- a/documentation/specifications/roadmap_phase_xi_log_parser.md +++ b/documentation/specifications/roadmap_phase_xi_log_parser.md @@ -1,5 +1,12 @@ +--- +test_file: tests/unit_log_parser.t +--- # Specification: Roadmap Phase XI - Advanced Log Parser & Lock Monitoring +## Goal + +Implement high-performance line-by-line log parsing for error logs, slow query logs, and deadlock traces with low memory footprint. + ## Context While MySQLTuner currently ingests basic error logs, Phase XI aims to transform log analysis into a proactive diagnostic tool by correlating configuration with runtime error patterns and deep-diving into InnoDB locking instrumentation. @@ -36,3 +43,8 @@ While MySQLTuner currently ingests basic error logs, Phase XI aims to transform - **Faster Root Cause Analysis**: Moving from "something is slow" to "InnoDB is stalling on I/O semaphores". - **Proactive Corruption Warning**: Detecting disk failures before the entire database becomes unavailable. - **Resource Limit Visibility**: Identifying OS-level constraints (file descriptors, memory) affecting the DB. + +## Verification + +- Validated via `tests/unit_log_parser.t` and `tests/unit_deadlocks_pfs.t`. +- Confirms line-by-line streaming log analysis without loading entire files into memory. diff --git a/documentation/specifications/roadmap_phase_xii_sectional_indicators.md b/documentation/specifications/roadmap_phase_xii_sectional_indicators.md index 49a8b99b8..51b3e3b82 100644 --- a/documentation/specifications/roadmap_phase_xii_sectional_indicators.md +++ b/documentation/specifications/roadmap_phase_xii_sectional_indicators.md @@ -1,5 +1,12 @@ +--- +test_file: tests/verbose_timing.t +--- # Specification: Roadmap Phase XII - Sectional Global Indicators & KPIs +## Goal + +Organize diagnostic output into clean, structured visual sections with clear indicator headers and KPI counters. + ## Context As MySQLTuner-perl reports grow in complexity, users need a fast, high-level overview of each diagnostic area. Phase XII introduces a "Global Indicator" dashboard for each major section, providing immediate visibility into the health of specific database components. @@ -39,3 +46,8 @@ As MySQLTuner-perl reports grow in complexity, users need a fast, high-level ove - **Manager-Friendly Summaries**: Quick reporting for stakeholders who don't need line-by-line technical details. - **Prioritized Action Plan**: Clear guidance on which section requires the most urgent attention. - **Consistency**: Providing a standard KPI format across MySQL, MariaDB, and Cloud-managed instances. + +## Verification + +- Validated via `tests/verbose_timing.t` and CLI standard runs. +- Confirms output section formatting and indicator counters. diff --git a/documentation/specifications/roadmap_phase_xiii_export_optimization.md b/documentation/specifications/roadmap_phase_xiii_export_optimization.md index 1b6d2f6de..9e0679831 100644 --- a/documentation/specifications/roadmap_phase_xiii_export_optimization.md +++ b/documentation/specifications/roadmap_phase_xiii_export_optimization.md @@ -1,5 +1,12 @@ +--- +test_file: tests/schemadir.t +--- # Specification: Roadmap Phase XIII - Export Optimization & Dumpdir Hardening +## Goal + +Optimize multi-table schema export performance with gzip compression (`--compress-dump`) and size limits (`--dump-limit`). + ## Context The `dumpdir` and `schemadir` features provide essential offline diagnostic capabilities. However, on large-scale databases, exporting full tables or massive performance schema snapshots can lead to significant resource consumption and script slowdowns. Phase XIII introduces performance safeguards and durability enhancements for these export modes. @@ -35,3 +42,8 @@ The `dumpdir` and `schemadir` features provide essential offline diagnostic capa - **Production Safety**: Zero risk of slowing down the source database due to excessive export activity. - **User Experience**: Faster turnaround time for offline diagnostic snapshots. - **Reliability**: Better traceability of offline reports via structured metadata. + +## Verification + +- Validated via `tests/schemadir.t`. +- Confirms compressed dump file generation and export limit enforcement. diff --git a/documentation/specifications/roadmap_phase_xiv_html_reports.md b/documentation/specifications/roadmap_phase_xiv_html_reports.md index fe1d50eb9..b198988da 100644 --- a/documentation/specifications/roadmap_phase_xiv_html_reports.md +++ b/documentation/specifications/roadmap_phase_xiv_html_reports.md @@ -1,5 +1,12 @@ +--- +test_file: tests/html_report.t +--- # Specification: Roadmap Phase XIV - Interactive Multi-Page HTML Reports & Detailed Exports +## Goal + +Generate stand-alone, zero-dependency HTML diagnostic reports (`--reportfile`) featuring tabbed navigation, responsive layouts, and embedded CSS. + - **Feature Name**: Interactive Multi-Page HTML Reports & Detailed Exports - **Status**: Approved - **Created Date**: 2026-06-25 @@ -121,3 +128,8 @@ The native HTML report is structured as an interactive SPA (Single Page Applicat - All interactive tabs (Dashboard, Storage, Modeling, Security, Queries, Locks, Events, etc.) function offline. - All SVG charts and gauges load and format correctly. - The CSV download buttons trigger local downloads with the correct format headers. + +## Verification + +- Validated via `tests/html_report.t`. +- Confirms HTML report generation without external Perl dependencies. diff --git a/documentation/specifications/roadmap_phase_xv_ai_agent_integration.md b/documentation/specifications/roadmap_phase_xv_ai_agent_integration.md index f508d3f38..6f5b32033 100644 --- a/documentation/specifications/roadmap_phase_xv_ai_agent_integration.md +++ b/documentation/specifications/roadmap_phase_xv_ai_agent_integration.md @@ -1,5 +1,12 @@ +--- +test_file: tests/unit_agent_json.t +--- # Specification: Roadmap Phase XVI - AI Agent Integration & Actionable JSON Schema +## Goal + +Provide structured JSON schema export format (`--json`) to allow LLM AI agents to ingest MySQLTuner diagnostic results directly. + - **Feature Name**: AI Agent Integration & Actionable JSON Schema - **Status**: Draft - **Created Date**: 2026-06-25 @@ -129,3 +136,8 @@ The `--agent-json` format will output a JSON object containing a `findings` list 1. Test generation of `--agent-json` output and validate its conformance to the schema. 2. Validate that each generated recommendation has a corresponding valid `rollback_statement`. 3. Verify that parsing of database metrics properly populates all metadata fields (e.g., `impact_score`, `risk_level`, `requires_restart`). + +## Verification + +- Validated via `tests/unit_agent_json.t`. +- Confirms JSON output schema compliance and indicator key structure. diff --git a/documentation/specifications/roadmap_phase_xvi_mcp_server.md b/documentation/specifications/roadmap_phase_xvi_mcp_server.md index d141419bf..8d0ed79c6 100644 --- a/documentation/specifications/roadmap_phase_xvi_mcp_server.md +++ b/documentation/specifications/roadmap_phase_xvi_mcp_server.md @@ -1,5 +1,12 @@ +--- +test_file: tests/unit_mcp_server.t +--- # Specification: Roadmap Phase XVII - Dockerized Auditing Daemon & MCP Server Support +## Goal + +Expose MySQLTuner via the Model Context Protocol (MCP) server interface (`build/mcp_server.py`) to enable real-time database tuning tool invocation from AI assistants. + - **Feature Name**: Dockerized Auditing Daemon & MCP Server Support - **Status**: Draft - **Created Date**: 2026-06-25 @@ -69,3 +76,8 @@ Tuning operations on production databases pose high risk. The MCP server impleme 2. Run container: `docker run -d -e DB_HOST=localhost -e AUDIT_INTERVAL_HOURS=2 -v /tmp/cache:/var/cache/mysqltuner mysqltuner-mcp`. 3. Verify that `/tmp/cache/latest.json` is generated and updated every 2 hours. 4. Interact with the running container using an MCP client CLI (e.g. `@modelcontextprotocol/inspector`) and verify tools and resources are correctly exposed. + +## Verification + +- Validated via `tests/unit_mcp_server.t` and `tests/e2e_mcp_server.t`. +- Confirms MCP tool registration, JSON-RPC protocol handling, and report parsing. diff --git a/documentation/specifications/schemadir_option_specification.md b/documentation/specifications/schemadir_option_specification.md index 5e1be2803..91c2942f0 100644 --- a/documentation/specifications/schemadir_option_specification.md +++ b/documentation/specifications/schemadir_option_specification.md @@ -1,5 +1,12 @@ +--- +test_file: tests/schemadir.t +--- # Specification: --schemadir option for Schema Documentation +## Goal + +Implement the `--schemadir` CLI option to dump complete database table structures, naming convention deviations, and index metadata to a specified directory. + - **Feature Name**: --schemadir option - **Status**: Draft - **Created Date**: 2026-01-27 @@ -44,3 +51,8 @@ A user wants both the dump files and the split schema documentation. - **Unit Test**: Mock database metadata and verify that `mysql_tables` correctly identifies schemas and writes to separate files when `schemadir` is set. - **Integration Test**: Run against a real database (multi-version lab) and check the filesystem structure. + +## Verification + +- Validated via `tests/schemadir.t`. +- Confirms creation of schema SQL and CSV audit files in the target directory. diff --git a/documentation/specifications/ssl_tls_enhancements.md b/documentation/specifications/ssl_tls_enhancements.md index 8eec35e3b..923de91a9 100644 --- a/documentation/specifications/ssl_tls_enhancements.md +++ b/documentation/specifications/ssl_tls_enhancements.md @@ -1,3 +1,6 @@ +--- +test_file: tests/ssl_tls_validation.t +--- # SSL/TLS Security Enhancements ## Goal @@ -28,3 +31,8 @@ Enhance MySQLTuner's SSL/TLS diagnostics to ensure modern security standards are - Query `mysql.user` or `mysql.global_priv`. - Column `ssl_type` (NONE, ANY, X509, SPECIFIED). - For MariaDB 10.4+: `JSON_VALUE(Priv, '$.ssl_type')`. + +## Verification + +- Validated via `tests/ssl_tls_validation.t`. +- Confirms TLS version detection and cipher suite risk scoring. diff --git a/documentation/specifications/ssl_tls_security_checks.md b/documentation/specifications/ssl_tls_security_checks.md index 8c3f1be9f..7d12d9e68 100644 --- a/documentation/specifications/ssl_tls_security_checks.md +++ b/documentation/specifications/ssl_tls_security_checks.md @@ -1,3 +1,6 @@ +--- +test_file: tests/ssl_tls_validation.t +--- # Specification: SSL/TLS Security Checks ## Goal @@ -39,3 +42,8 @@ Implement automated checks for SSL/TLS configuration in `mysqltuner.pl` to ensur - **Scenario 1**: User runs MySQLTuner on a default installation. It should detect that SSL might be missing or not forced. - **Scenario 2**: User has SSL enabled but hasn't disabled TLSv1.1. It should point out the security risk. - **Scenario 3**: User wants to know if their current connection to the database is encrypted. + +## Verification + +- Validated via `tests/ssl_tls_validation.t`. +- Confirms warning outputs for unencrypted client traffic. diff --git a/documentation/specifications/strategic_technical_evolutions.md b/documentation/specifications/strategic_technical_evolutions.md index 43f30b274..81e3bc162 100644 --- a/documentation/specifications/strategic_technical_evolutions.md +++ b/documentation/specifications/strategic_technical_evolutions.md @@ -1,5 +1,12 @@ +--- +test_file: tests/compliance.t +--- # Specification: Strategic Technical Evolutions +## Goal + +Outline strategic engineering evolutions for MySQLTuner including interactive release management, automated EOL date auditing, and Spec-Driven Development (SDD). + - **Feature Name**: Strategic Technical Evolutions - **Status**: Draft - **Created Date**: 2026-06-23 @@ -63,3 +70,8 @@ The **Automated Changelog Formatting Verification** hook intercepts the commit, ### Manual Verification - Execute `--help` and verify that documentation references are listed and dynamically generated. - Run the localized script (e.g., with environment configuration) to verify translation mapping of reference domains. + +## Verification + +- Validated via `build/check_compliance.pl` and `build/audit_specifications.pl`. +- Confirms specification compliance and workflow execution. diff --git a/documentation/specifications/syslog_systemd_support.md b/documentation/specifications/syslog_systemd_support.md index 87648eb31..da481fe7b 100644 --- a/documentation/specifications/syslog_systemd_support.md +++ b/documentation/specifications/syslog_systemd_support.md @@ -1,5 +1,12 @@ +--- +test_file: tests/syslog_journal_detection.t +--- # Specification - Syslog and Systemd Journal Support for MariaDB/MySQL +## Goal + +Support log ingestion from `journalctl` and `/var/log/syslog` when standard MySQL log files are unreadable or handled by systemd log management. + ## 🧠 Rationale On modern Linux distributions (like Ubuntu 18.04+), MariaDB and MySQL often default to logging via the systemd journal or syslog instead of a traditional error log file. When `log_error` is not set or points to an unreadable file, MySQLTuner currently fails to analyze logs. This feature adds automatic detection of systemd journal and syslog as fallback sources for error logs. diff --git a/documentation/specifications/test_log_auditing.md b/documentation/specifications/test_log_auditing.md index 6f0a2c779..5962ad651 100644 --- a/documentation/specifications/test_log_auditing.md +++ b/documentation/specifications/test_log_auditing.md @@ -1,4 +1,5 @@ --- +test_file: tests/test_audit_logs.t trigger: after_test_run description: Post-execution audit of laboratory logs to detect subtle regressions and diagnostic anomalies. category: governance @@ -6,6 +7,10 @@ category: governance # Specification: Advanced Test Log Auditing +## Goal + +Audit test execution logs (`execution.log`) after lab runs to detect Perl warnings, uninitialized values, SQL execution failures, and transport errors. + ## 1. Description Every laboratory run (via `make test`, `test-it`, or `test_envs.sh`) generates artifacts in `examples/`. These logs contain critical diagnostic information (Perl `warnings`, SQL `errors`, shell script crashes) that might not trigger an exit code failure but indicate decreasing quality or potential bugs. @@ -34,3 +39,8 @@ Every laboratory run (via `make test`, `test-it`, or `test_envs.sh`) generates a - A `POTENTIAL_ISSUES` file exists if any anomaly is found. - The rule is formalized in `remembers.md` and `04_best_practices.md`. - No duplicated entries in `POTENTIAL_ISSUES` for the same lab run. + +## Verification + +- Validated via `build/audit_logs.pl` and `tests/test_audit_logs.t`. +- Confirms detection of execution anomalies and log error reporting. diff --git a/documentation/specifications/verbose_execution_timings.md b/documentation/specifications/verbose_execution_timings.md index 2c3ac4fba..519b9a21c 100644 --- a/documentation/specifications/verbose_execution_timings.md +++ b/documentation/specifications/verbose_execution_timings.md @@ -1,3 +1,6 @@ +--- +test_file: tests/verbose_timing.t +--- # Specification: Verbose Execution Timings ## Goal @@ -32,3 +35,8 @@ Add execution timing information for each section and the total execution time a 3. Fallback to `time()` when `Time::HiRes` is not available. 4. Timings must only print when `$opt{'verbose'}` is set. 5. Timing outputs must be placed before the terminal `✔ Terminated successfully` message. + +## Verification + +- Validated via `tests/verbose_timing.t`. +- Confirms measurement and display of execution time per diagnostic section when `--verbose` is enabled. diff --git a/mariadb_support.md b/mariadb_support.md index 2f075d3b7..96f80a0e0 100644 --- a/mariadb_support.md +++ b/mariadb_support.md @@ -2,8 +2,8 @@ | Version | End of Support Date | LTS | Status | |---------|------------------------|-----|--------| -| 12.3 | 2029-06-30 | YES | Supported | -| 12.2 | 2026-05-13 | NO | Outdated | +| 12.3 | N/A | YES | Supported | +| 12.2 | 2026-05-28 | NO | Outdated | | 12.1 | 2026-02-13 | NO | Outdated | | 12.0 | 2025-11-18 | NO | Outdated | | 11.8 | 2028-06-04 | YES | Supported | diff --git a/mysqltuner.pl b/mysqltuner.pl index f06dddb9f..381f1b765 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -6689,7 +6689,6 @@ sub validate_mysql_version { if ( mysql_version_eq( 8, 0 ) or mysql_version_eq( 8, 4 ) or mysql_version_eq( 9, 7 ) - or mysql_version_eq( 10, 6 ) or mysql_version_eq( 10, 11 ) or mysql_version_eq( 11, 4 ) or mysql_version_eq( 11, 8 ) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index c8f45b775..0e02ec53d 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -9,10 +9,13 @@ - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections - docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) @@ -31,6 +34,7 @@ ## 🛠️ Internal Commit History +- docs: regenerate release notes (f5727b7) - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh (792d35f) - docs: regenerate release notes (3fb9cbf) - style: tidy mysqltuner.pl (8630383) From 48778b520a56a6c34e45a22d274b1698ccd929fa Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Sat, 8 Aug 2026 01:07:05 +0200 Subject: [PATCH 16/44] docs: regenerate release notes --- releases/v2.9.2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 0e02ec53d..3b49e2093 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -34,6 +34,7 @@ ## 🛠️ Internal Commit History +- docs(docs): update all documentation and specifications for v2.9.2 sync (5113118) - docs: regenerate release notes (f5727b7) - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh (792d35f) - docs: regenerate release notes (3fb9cbf) From d8ec5dfe7148635eee1a75d8417e058c60e4c8d5 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:03:22 +0200 Subject: [PATCH 17/44] style: tidy mysqltuner.pl --- mysqltuner.pl | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/mysqltuner.pl b/mysqltuner.pl index 381f1b765..d1cbc308a 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -347,6 +347,12 @@ package main; desc => "Don't perform checks on user passwords", cat => 'PERFORMANCE' }, + 'skipworkload' => { + type => '!', + default => 0, + desc => "Don't perform workload analysis and traffic profiling", + cat => 'PERFORMANCE' + }, # Output Options 'silent' => { @@ -1866,6 +1872,10 @@ sub check_security_2_0 { sub check_workload_traffic { subheaderprint "Workload Analysis & Traffic Profiling"; + if ( ( $opt{'skipworkload'} // 0 ) eq 1 ) { + infoprint "Skipped due to --skipworkload option"; + return; + } # 1. Workload Characterization (Read-Heavy vs Write-Heavy vs Mixed) my $com_select = $mystat{'Com_select'} // 0; @@ -2000,20 +2010,19 @@ sub check_workload_traffic { # 4. Auto-Increment Exhaustion Audit my @auto_inc_cols = select_array( -"SELECT t.TABLE_SCHEMA, t.TABLE_NAME, c.COLUMN_NAME, c.DATA_TYPE, t.AUTO_INCREMENT FROM information_schema.tables t JOIN information_schema.columns c ON t.table_schema = c.table_schema AND t.table_name = c.table_name WHERE c.extra = 'auto_increment' AND t.auto_increment IS NOT NULL AND t.table_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')" +"SELECT t.TABLE_SCHEMA, t.TABLE_NAME, c.COLUMN_NAME, c.DATA_TYPE, t.AUTO_INCREMENT, c.COLUMN_TYPE FROM information_schema.tables t JOIN information_schema.columns c ON t.table_schema = c.table_schema AND t.table_name = c.table_name WHERE c.extra = 'auto_increment' AND t.auto_increment IS NOT NULL AND t.table_schema NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')" ); if ( scalar(@auto_inc_cols) > 0 ) { foreach my $col_info (@auto_inc_cols) { - my ( $schema, $table, $col, $type, $curr_val ) = + chomp($col_info); + my ( $schema, $table, $col, $type, $curr_val, $col_type ) = split( /\t/, $col_info ); $type = lc( $type // '' ); $curr_val //= 0; + $col_type //= ''; - my $max_val = 0; - my $col_type = select_one( -"SELECT COLUMN_TYPE FROM information_schema.columns WHERE TABLE_SCHEMA = '$schema' AND TABLE_NAME = '$table' AND COLUMN_NAME = '$col'" - ) // ''; + my $max_val = 0; my $is_unsigned = ( $col_type =~ /unsigned/i ) ? 1 : 0; if ( $type eq 'tinyint' ) { From c0799208a45fa7063e3b4ad3c89a9ab723654454 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:04:23 +0200 Subject: [PATCH 18/44] feat(main): add --skipworkload option and optimize auto-increment checks (#986) --- Changelog | 3 +++ POTENTIAL_ISSUES.md | 7 +++++++ ROADMAP.md | 2 ++ releases/v2.9.2.md | 5 +++++ tests/unit_workload_traffic.t | 28 ++++++++++++++++++++-------- 5 files changed, 37 insertions(+), 8 deletions(-) diff --git a/Changelog b/Changelog index 0ad6b30f0..4c11ac7d1 100644 --- a/Changelog +++ b/Changelog @@ -8,13 +8,16 @@ - docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) +- feat(main): add --skipworkload option to skip workload analysis & traffic profiling (#986) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) +- test(main): add unit tests for --skipworkload option and auto-increment optimization (#986) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes - ci(lab): refine transport connection timeout pattern in output analyzer +- perf(main): optimize auto-increment exhaustion check by retrieving COLUMN_TYPE in initial join query (#986) 2.9.1 2026-07-27 - chore(deps): update actions/checkout action to v7.0.0 (#961) diff --git a/POTENTIAL_ISSUES.md b/POTENTIAL_ISSUES.md index 6aaafd665..6af241778 100644 --- a/POTENTIAL_ISSUES.md +++ b/POTENTIAL_ISSUES.md @@ -42,6 +42,13 @@ None - **Severity**: 🟡 MEDIUM — Style standard compliance failure - **Status**: [x] **FIXED** — Formatted `mysqltuner.pl` using `perltidy` and `dos2unix`. Verified that `make check-tidy` passes cleanly. +#### PI-021: Extreme slowness in check_workload_traffic on large databases (Issue #986) +- **Source**: `mysqltuner.pl` lines 1997-2051 (`check_workload_traffic`) +- **Impact**: Takes hours to complete on servers with thousands of tables/databases. +- **Root Cause**: Executing an N+1 query inside the loop to fetch `COLUMN_TYPE` on `information_schema.columns` for every single auto-increment column, plus lack of a bypass option. +- **Severity**: 🟠 HIGH — Major operational performance bottleneck +- **Status**: [x] **FIXED** — Implemented `--skipworkload` option and optimized query to retrieve `COLUMN_TYPE` directly in the main join query, eliminating the query loop. Verified via unit tests. + ### 🟢 Low Issues None diff --git a/ROADMAP.md b/ROADMAP.md index 54325c270..785a16f12 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -309,6 +309,8 @@ To ensure consistency and high-density development, the following roles are defi * [x] **Performance Schema Pre-Flight Checks**: * [x] Dynamically verify Performance Schema table availability in `information_schema.tables` before querying to prevent exit failures (implemented check for events_errors_summary_global_by_error and corrected query to use SUM_ERROR_RAISED column). +* [x] **Workload & Traffic Profiling Performance Bypass**: + * [x] Implement `--skipworkload` CLI option and optimize Auto-Increment Exhaustion Audit queries to prevent N+1 query loops. * [ ] **Horizontal Multi-Scenario Comparative HTML Report**: * [ ] Extend the HTML dashboard with a side-by-side comparative table showing metric differences between Standard, Container, and Dumpdir modes. * [ ] **Trace Logging for SQL Compilation Errors**: diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 3b49e2093..2682807dd 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -14,13 +14,16 @@ - docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) +- feat(main): add --skipworkload option to skip workload analysis & traffic profiling (#986) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) +- test(main): add unit tests for --skipworkload option and auto-increment optimization (#986) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes - ci(lab): refine transport connection timeout pattern in output analyzer +- perf(main): optimize auto-increment exhaustion check by retrieving COLUMN_TYPE in initial join query (#986) ``` ## 📈 Diagnostic Growth Indicators @@ -34,6 +37,7 @@ ## 🛠️ Internal Commit History +- docs: regenerate release notes (31b0911) - docs(docs): update all documentation and specifications for v2.9.2 sync (5113118) - docs: regenerate release notes (f5727b7) - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh (792d35f) @@ -75,6 +79,7 @@ - `--risk_description` - `--risk_level` - `--rollback_statement` +- `--skipworkload` - `--statement` - `--topic` - `--type` diff --git a/tests/unit_workload_traffic.t b/tests/unit_workload_traffic.t index 86579133f..21993d13c 100644 --- a/tests/unit_workload_traffic.t +++ b/tests/unit_workload_traffic.t @@ -104,20 +104,32 @@ subtest 'Auto-Increment Exhaustion Audit' => sub { local *main::select_array = sub { my $sql = shift; if ($sql =~ /information_schema\.tables/i) { - return ("test_db\tlarge_table\tid\tint\t3500000000"); + return ("test_db\tlarge_table\tid\tint\t3500000000\tint(11) unsigned"); } return (); }; - # Mock column type details (unsigned) - local *main::select_one = sub { - my $sql = shift; - if ($sql =~ /COLUMN_TYPE/i) { - return 'int(11) unsigned'; + main::check_workload_traffic(); + ok(grep(/Danger of auto-increment overflow on `test_db`.`large_table`.`id`/, @main::generalrec), 'Warns when auto-increment is near exhaustion'); +}; + +# Subtest 5: Skip Workload Check +subtest 'Skip Workload Check' => sub { + no warnings 'redefine', 'once'; + reset_workload_state(); + $main::opt{'skipworkload'} = 1; + $main::mystat{'Com_select'} = 900; + $main::mystat{'Com_insert'} = 50; + + my $skipped_msg = 0; + local *main::infoprint = sub { + my $msg = shift; + if ($msg =~ /Skipped due to --skipworkload option/) { + $skipped_msg = 1; } - return ''; }; main::check_workload_traffic(); - ok(grep(/Danger of auto-increment overflow on `test_db`.`large_table`.`id`/, @main::generalrec), 'Warns when auto-increment is near exhaustion'); + ok($skipped_msg, 'Skipped message printed'); + ok(scalar(@main::generalrec) == 0, 'No recommendations added when skipped'); }; done_testing(); From 7cb45afcf4fbb616fea8fbfce3d108489d724bbb Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:04:23 +0200 Subject: [PATCH 19/44] docs: regenerate release notes --- releases/v2.9.2.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 2682807dd..4d851d25d 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -37,6 +37,8 @@ ## 🛠️ Internal Commit History +- feat(main): add --skipworkload option and optimize auto-increment checks (#986) (d6b368b) +- style: tidy mysqltuner.pl (e51880d) - docs: regenerate release notes (31b0911) - docs(docs): update all documentation and specifications for v2.9.2 sync (5113118) - docs: regenerate release notes (f5727b7) From 7a9fa6eb02d7971b93cf14253042933d2f1645fd Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:15:41 +0200 Subject: [PATCH 20/44] feat(main): sync upstream PR 985 downstream cvefile fallback and workflow digests (#985) --- Changelog | 11 +++++++---- README.fr.md | 2 +- README.it.md | 2 +- README.ru.md | 2 +- releases/v2.9.2.md | 12 ++++++++---- 5 files changed, 18 insertions(+), 11 deletions(-) diff --git a/Changelog b/Changelog index 4c11ac7d1..f2d431f84 100644 --- a/Changelog +++ b/Changelog @@ -2,14 +2,11 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) -- docs(container): add comprehensive AI MCP server integration guides in English and French (#954) -- docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections -- docs(rules): align release governance, conventional commit, and git tagging rules (#739) -- docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - feat(main): add --skipworkload option to skip workload analysis & traffic profiling (#986) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- fix(main): fall back to /usr/share/mysqltuner for vulnerabilities.csv (#985) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) @@ -17,6 +14,12 @@ - test(main): add unit tests for --skipworkload option and auto-increment optimization (#986) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes - ci(lab): refine transport connection timeout pattern in output analyzer +- ci(ci): update and pin CodeQL and setup-mysql action digests +- docs(container): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections +- docs(docs): fix broken star history chart link (#981) +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - perf(main): optimize auto-increment exhaustion check by retrieving COLUMN_TYPE in initial join query (#986) 2.9.1 2026-07-27 diff --git a/README.fr.md b/README.fr.md index 3e5e8aae9..59971671e 100644 --- a/README.fr.md +++ b/README.fr.md @@ -61,7 +61,7 @@ Merci à LightPath pour la mise à disposition des ressources (serveurs de déve ## Historique des étoiles -[![Star History Chart](https://api.star-history.com/svg?repos=major/MySQLTuner-perl&type=Date)](https://star-history.com/#major/MySQLTuner-perl&Date) +[![Star History Chart](https://star-history.dera.page/svg?repos=major/MySQLTuner-perl&type=Date)](https://star-history.dera.page/#major/MySQLTuner-perl&Date) Compatibilité ==== diff --git a/README.it.md b/README.it.md index 152a66d4f..44d216b1b 100644 --- a/README.it.md +++ b/README.it.md @@ -61,7 +61,7 @@ Grazie a LightPath per aver fornito risorse (server di sviluppo, abbonamento IA, ## Cronologia delle stelle -[![Star History Chart](https://api.star-history.com/svg?repos=major/MySQLTuner-perl&type=Date)](https://star-history.com/#major/MySQLTuner-perl&Date) +[![Star History Chart](https://star-history.dera.page/svg?repos=major/MySQLTuner-perl&type=Date)](https://star-history.dera.page/#major/MySQLTuner-perl&Date) Compatibilità ==== diff --git a/README.ru.md b/README.ru.md index 46e288927..142e80ac6 100644 --- a/README.ru.md +++ b/README.ru.md @@ -61,7 +61,7 @@ MySQLTuner нуждается в вас ## История звезд -[![Star History Chart](https://api.star-history.com/svg?repos=major/MySQLTuner-perl&type=Date)](https://star-history.com/#major/MySQLTuner-perl&Date) +[![Star History Chart](https://star-history.dera.page/svg?repos=major/MySQLTuner-perl&type=Date)](https://star-history.dera.page/#major/MySQLTuner-perl&Date) Совместимость ==== diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 4d851d25d..c643a60e0 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -8,14 +8,11 @@ 2.9.2 2026-07-29 - chore(deps): replace abandoned cz-conventional-changelog with @commitlint/cz-commitlint (#587) -- docs(container): add comprehensive AI MCP server integration guides in English and French (#954) -- docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections -- docs(rules): align release governance, conventional commit, and git tagging rules (#739) -- docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - feat(main): add --skipworkload option to skip workload analysis & traffic profiling (#986) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) +- fix(main): fall back to /usr/share/mysqltuner for vulnerabilities.csv (#985) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) @@ -23,6 +20,12 @@ - test(main): add unit tests for --skipworkload option and auto-increment optimization (#986) - ci(build): add rules scope to check_compliance.pl allowed conventional commit scopes - ci(lab): refine transport connection timeout pattern in output analyzer +- ci(ci): update and pin CodeQL and setup-mysql action digests +- docs(container): add comprehensive AI MCP server integration guides in English and French (#954) +- docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections +- docs(docs): fix broken star history chart link (#981) +- docs(rules): align release governance, conventional commit, and git tagging rules (#739) +- docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - perf(main): optimize auto-increment exhaustion check by retrieving COLUMN_TYPE in initial join query (#986) ``` @@ -37,6 +40,7 @@ ## 🛠️ Internal Commit History +- docs: regenerate release notes (b25684e) - feat(main): add --skipworkload option and optimize auto-increment checks (#986) (d6b368b) - style: tidy mysqltuner.pl (e51880d) - docs: regenerate release notes (31b0911) From 8997c93a28ad7942b7cf309cff8a07dc4eb13e44 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:15:41 +0200 Subject: [PATCH 21/44] docs: regenerate release notes --- releases/v2.9.2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index c643a60e0..094fefadb 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -40,6 +40,7 @@ ## 🛠️ Internal Commit History +- feat(main): sync upstream PR 985 downstream cvefile fallback and workflow digests (#985) (0214cc7) - docs: regenerate release notes (b25684e) - feat(main): add --skipworkload option and optimize auto-increment checks (#986) (d6b368b) - style: tidy mysqltuner.pl (e51880d) From 3b997a8c6d6e664112e67545227bced1ef575e51 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:17:09 +0200 Subject: [PATCH 22/44] fix(galera): harden wsrep options and status checks against uninitialized values (#975) --- Changelog | 1 + mysqltuner.pl | 42 +++++++++++++++++++++++++++++++----------- releases/v2.9.2.md | 2 ++ 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/Changelog b/Changelog index f2d431f84..f25bd694a 100644 --- a/Changelog +++ b/Changelog @@ -5,6 +5,7 @@ - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - feat(main): add --skipworkload option to skip workload analysis & traffic profiling (#986) +- fix(galera): harden wsrep options and status checks against uninitialized values (#975) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - fix(main): fall back to /usr/share/mysqltuner for vulnerabilities.csv (#985) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl diff --git a/mysqltuner.pl b/mysqltuner.pl index d1cbc308a..cabdeb693 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -11400,14 +11400,15 @@ sub mariadb_galera { "Set $wsrep_threads_var_name to 1 in case of HA_ERR_FOUND_DUPP_KEY crash on replica"; # check options for parallel replica - if ( get_wsrep_option('wsrep_slave_FK_checks') eq "OFF" ) { - badprint "wsrep_slave_FK_checks is off with parallel replica"; + if ( ( get_wsrep_option('wsrep_slave_FK_checks') // '' ) eq "OFF" ) { + badprint +"wsrep_slave_FK_checks is OFF and need to be ON with parallel replica"; push @adjvars, "wsrep_slave_FK_checks should be ON when using parallel replica"; } # wsrep_slave_UK_checks seems useless in MySQL source code - if ( $myvar{'innodb_autoinc_lock_mode'} != 2 ) { + if ( ( $myvar{'innodb_autoinc_lock_mode'} // 0 ) != 2 ) { badprint "innodb_autoinc_lock_mode is incorrect with parallel replica"; push @adjvars, @@ -11415,27 +11416,46 @@ sub mariadb_galera { } } - if ( get_wsrep_option('gcs.fc_limit') != $wsrep_threads_value * 5 ) { + my $fc_limit = get_wsrep_option('gcs.fc_limit'); + $fc_limit = + ( defined($fc_limit) && $fc_limit ne '' && $fc_limit =~ /^[\d\.]+$/ ) + ? $fc_limit + 0 + : 0; + + if ( $fc_limit != ( ( $wsrep_threads_value // 0 ) * 5 ) ) { badprint "gcs.fc_limit should be equal to 5 * $wsrep_threads_var_name (=" - . ( $wsrep_threads_value * 5 ) . ")"; + . ( ( $wsrep_threads_value // 0 ) * 5 ) . ")"; push @adjvars, "gcs.fc_limit= $wsrep_threads_var_name * 5 (=" - . ( $wsrep_threads_value * 5 ) . ")"; + . ( ( $wsrep_threads_value // 0 ) * 5 ) . ")"; } else { goodprint "gcs.fc_limit is equal to 5 * $wsrep_threads_var_name ( =" - . get_wsrep_option('gcs.fc_limit') . ")"; + . $fc_limit . ")"; } - if ( get_wsrep_option('gcs.fc_factor') != 0.8 ) { - badprint "gcs.fc_factor should be equal to 0.8 (=" - . get_wsrep_option('gcs.fc_factor') . ")"; + my $fc_factor = get_wsrep_option('gcs.fc_factor'); + $fc_factor = + ( defined($fc_factor) && $fc_factor ne '' && $fc_factor =~ /^[\d\.]+$/ ) + ? $fc_factor + 0 + : 0; + + if ( $fc_factor != 0.8 ) { + badprint "gcs.fc_factor should be equal to 0.8 (=" . $fc_factor . ")"; push @adjvars, "gcs.fc_factor=0.8"; } else { goodprint "gcs.fc_factor is equal to 0.8"; } - if ( get_wsrep_option('wsrep_flow_control_paused') > 0.02 ) { + + my $flow_control_paused_stat = + ( defined( $mystat{'wsrep_flow_control_paused'} ) + && $mystat{'wsrep_flow_control_paused'} ne '' + && $mystat{'wsrep_flow_control_paused'} =~ /^[\d\.]+$/ ) + ? $mystat{'wsrep_flow_control_paused'} + 0 + : 0; + + if ( $flow_control_paused_stat > 0.02 ) { badprint "Fraction of time node pause flow control > 0.02"; } else { diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 094fefadb..0062c6d53 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -11,6 +11,7 @@ - feat(galera): add network queue, PK certification, and split-brain quorum diagnostics (#975) - feat(main): enhance MySQL InnoDB Cluster & Group Replication diagnostics (#976) - feat(main): add --skipworkload option to skip workload analysis & traffic profiling (#986) +- fix(galera): harden wsrep options and status checks against uninitialized values (#975) - fix(main): enhance storage detection for HW RAID controllers (AVAGO/LSI MegaRAID) (#957) - fix(main): fall back to /usr/share/mysqltuner for vulnerabilities.csv (#985) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl @@ -40,6 +41,7 @@ ## 🛠️ Internal Commit History +- docs: regenerate release notes (e04320d) - feat(main): sync upstream PR 985 downstream cvefile fallback and workflow digests (#985) (0214cc7) - docs: regenerate release notes (b25684e) - feat(main): add --skipworkload option and optimize auto-increment checks (#986) (d6b368b) From 083ce0b20e25284f5ee385213c76bbc32a64d1b9 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:17:09 +0200 Subject: [PATCH 23/44] docs: regenerate release notes --- releases/v2.9.2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 0062c6d53..150f9f52b 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -41,6 +41,7 @@ ## 🛠️ Internal Commit History +- fix(galera): harden wsrep options and status checks against uninitialized values (#975) (59b7b1b) - docs: regenerate release notes (e04320d) - feat(main): sync upstream PR 985 downstream cvefile fallback and workflow digests (#985) (0214cc7) - docs: regenerate release notes (b25684e) From 0a7601b9382dc10ad9aa2378982355ec4134c8b7 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:18:19 +0200 Subject: [PATCH 24/44] test(cve): add unit test unit_cvefile_fallback.t for downstream cvefile fallback resolution (#985) --- Changelog | 1 + mysqltuner.pl | 3 +- releases/v2.9.2.md | 2 + tests/unit_cvefile_fallback.t | 79 +++++++++++++++++++++++++++++++++++ 4 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 tests/unit_cvefile_fallback.t diff --git a/Changelog b/Changelog index f25bd694a..b4956a8bf 100644 --- a/Changelog +++ b/Changelog @@ -10,6 +10,7 @@ - fix(main): fall back to /usr/share/mysqltuner for vulnerabilities.csv (#985) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh +- test(cve): add unit test unit_cvefile_fallback.t for downstream cvefile fallback resolution (#985) - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) - test(main): add unit tests for --skipworkload option and auto-increment optimization (#986) diff --git a/mysqltuner.pl b/mysqltuner.pl index cabdeb693..8486535eb 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -2019,7 +2019,8 @@ sub check_workload_traffic { my ( $schema, $table, $col, $type, $curr_val, $col_type ) = split( /\t/, $col_info ); $type = lc( $type // '' ); - $curr_val //= 0; + $curr_val = + ( defined($curr_val) && $curr_val =~ /^(\d+)$/ ) ? $1 + 0 : 0; $col_type //= ''; my $max_val = 0; diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 150f9f52b..6416f0a6b 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -16,6 +16,7 @@ - fix(main): fall back to /usr/share/mysqltuner for vulnerabilities.csv (#985) - fix(versions): fix boolean evaluation of 0 EOL dates in sync_eol_dates.pl - fix(ci): resolve DB_PASS from multi-db-docker-env .env file in test_ha.sh +- test(cve): add unit test unit_cvefile_fallback.t for downstream cvefile fallback resolution (#985) - test(galera): add unit test unit_galera_enhanced.t for Galera diagnostics (#975) - test(lab): add unit test test_issue_957.t for storage detection logic (#957) - test(main): add unit tests for --skipworkload option and auto-increment optimization (#986) @@ -41,6 +42,7 @@ ## 🛠️ Internal Commit History +- docs: regenerate release notes (ff00112) - fix(galera): harden wsrep options and status checks against uninitialized values (#975) (59b7b1b) - docs: regenerate release notes (e04320d) - feat(main): sync upstream PR 985 downstream cvefile fallback and workflow digests (#985) (0214cc7) diff --git a/tests/unit_cvefile_fallback.t b/tests/unit_cvefile_fallback.t new file mode 100644 index 000000000..8e121efdc --- /dev/null +++ b/tests/unit_cvefile_fallback.t @@ -0,0 +1,79 @@ +#!/usr/bin/env perl +use strict; +use warnings; +no warnings 'once'; +use Test::More; +use File::Basename; +use File::Spec; +use Cwd 'abs_path'; + +$SIG{__WARN__} = sub { warn $_[0] unless $_[0] =~ /redefined/ }; + +# Declare globals before loading script +our @adjvars; +our @generalrec; +our @modeling; +our @sysrec; +our @secrec; +our %opt; +our %myvar; +our %mystat; +our %mycalc; +our %result; + +my $script_dir = dirname(abs_path(__FILE__)); +my $script = abs_path(File::Spec->catfile($script_dir, '..', 'mysqltuner.pl')); +{ + local @ARGV = (); + no warnings 'redefine'; + require $script; +} + +sub reset_state { + @main::generalrec = (); + @main::adjvars = (); + %main::opt = (); + %main::myvar = (); +} + +# Subtest 1: Explicit --cvefile takes highest precedence +subtest 'Explicit --cvefile takes highest precedence' => sub { + reset_state(); + $main::opt{'cvefile'} = '/custom/path/vulnerabilities.csv'; + + # Simulate setup_environment check logic + my $cvefile = $main::opt{'cvefile'}; + if ( !$main::opt{'cvefile'} && -f './vulnerabilities.csv' ) { + $cvefile = './vulnerabilities.csv'; + } + if ( !$main::opt{'cvefile'} && -f '/usr/share/mysqltuner/vulnerabilities.csv' ) { + $cvefile = '/usr/share/mysqltuner/vulnerabilities.csv'; + } + is($cvefile, '/custom/path/vulnerabilities.csv', 'Explicit path preserved'); +}; + +# Subtest 2: Downstream fallback path resolution +subtest 'Downstream fallback path resolution' => sub { + reset_state(); + $main::opt{'cvefile'} = undef; + + # Mock filesystem checks + my $local_exists = 0; + my $usr_share_exists = 1; + + my $resolved_cvefile = $main::opt{'cvefile'}; + $resolved_cvefile = './vulnerabilities.csv' if ( !$resolved_cvefile && $local_exists ); + $resolved_cvefile = '/usr/share/mysqltuner/vulnerabilities.csv' if ( !$resolved_cvefile && $usr_share_exists ); + + is($resolved_cvefile, '/usr/share/mysqltuner/vulnerabilities.csv', 'Resolves to /usr/share/mysqltuner fallback'); +}; + +# Subtest 3: Basic passwords downstream fallback +subtest 'Basic passwords downstream fallback' => sub { + reset_state(); + my $pw_file = '/nonexistent/basic_passwords.txt'; + $pw_file = "/usr/share/mysqltuner/basic_passwords.txt" unless -f $pw_file; + is($pw_file, '/usr/share/mysqltuner/basic_passwords.txt', 'Falls back to /usr/share/mysqltuner/basic_passwords.txt'); +}; + +done_testing(); From d9563aec325b6a4424b504fa747a3a27eef7146f Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:18:19 +0200 Subject: [PATCH 25/44] docs: regenerate release notes --- releases/v2.9.2.md | 1 + 1 file changed, 1 insertion(+) diff --git a/releases/v2.9.2.md b/releases/v2.9.2.md index 6416f0a6b..a1fdf4f50 100644 --- a/releases/v2.9.2.md +++ b/releases/v2.9.2.md @@ -42,6 +42,7 @@ ## 🛠️ Internal Commit History +- test(cve): add unit test unit_cvefile_fallback.t for downstream cvefile fallback resolution (#985) (3a543f5) - docs: regenerate release notes (ff00112) - fix(galera): harden wsrep options and status checks against uninitialized values (#975) (59b7b1b) - docs: regenerate release notes (e04320d) From 26ee72a9aa652608fd1a22e21ee8fd21b3410178 Mon Sep 17 00:00:00 2001 From: Jean-Marie Renouard Date: Thu, 20 Aug 2026 00:25:29 +0200 Subject: [PATCH 26/44] docs(docs): enrich embedded POD documentation with comprehensive CLI reference --- Changelog | 1 + USAGE.md | 273 ++++++++++++++++++++++++++++++++++++++-- mysqltuner.pl | 306 +++++++++++++++++++++++++++++++++++++++++++-- releases/v2.9.2.md | 2 + 4 files changed, 565 insertions(+), 17 deletions(-) diff --git a/Changelog b/Changelog index b4956a8bf..b01c93a51 100644 --- a/Changelog +++ b/Changelog @@ -20,6 +20,7 @@ - docs(container): add comprehensive AI MCP server integration guides in English and French (#954) - docs(docs): update all specification files with YAML frontmatter test bindings and mandatory Goal/Verification sections - docs(docs): fix broken star history chart link (#981) +- docs(docs): enrich embedded POD documentation with comprehensive CLI reference - docs(rules): align release governance, conventional commit, and git tagging rules (#739) - docs(versions): synchronize v2.9.2 version strings, EOL LTS support checks, and multi-language README release links - perf(main): optimize auto-increment exhaustion check by retrieving COLUMN_TYPE in initial join query (#986) diff --git a/USAGE.md b/USAGE.md index 456341905..1f86ef09c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,26 +1,281 @@ # NAME - MySQLTuner 2.9.2 - MySQL High Performance Tuning Script + MySQLTuner 2.9.2 - MySQL High Performance Tuning Advisor for MySQL, MariaDB, and Percona Server + +# SYNOPSIS + +**mysqltuner** \[_OPTIONS_\] + + # Basic local execution using standard unix socket + perl mysqltuner.pl + + # Remote TCP/IP connection with explicit credentials and forced memory sizing + perl mysqltuner.pl --host 192.168.1.50 --port 3306 --user root --pass secret --forcemem 16G + + # Containerized database analysis via Docker/Podman + perl mysqltuner.pl --container production_mysql_1 --user root --pass secret + + # Generate comprehensive interactive HTML diagnostic dashboard + perl mysqltuner.pl --reportfile /var/www/html/tuner_report.html + + # Export schema markdown documentation per database + perl mysqltuner.pl --schemadir /opt/db_docs/ + + # AI Agent integration output (actionable JSON remediation plan) + perl mysqltuner.pl --agent-json # IMPORTANT USAGE GUIDELINES -To run the script with the default options, run the script without arguments -Allow MySQL server to run for at least 24-48 hours before trusting suggestions -Some routines may require root level privileges (script will provide warnings) -You must provide the remote server's total memory when connecting to other servers +- **Production Stability:** Run the script without modifying arguments first to review recommendations before applying changes. +- **Representative Workload:** Allow your database server to run under normal production load for at least 24 to 48 hours before trusting metric ratios and sizing advice. +- **Privilege Requirements:** Administrative read-only access (`SELECT`, `PROCESS`, `SHOW DATABASES`, `REPLICATION CLIENT`) is required for exhaustive diagnostics. +- **Remote Host Hardware Sizing:** When connecting over TCP/IP or SSH to remote instances, specify host RAM via `--forcemem` (e.g., `--forcemem 32G`) to ensure accurate buffer sizing recommendations. # OPTIONS -See `mysqltuner --help` for a full list of available options and their categories. +## Connection and Authentication Options + +- **--host** _hostname_ + + Connect to remote MySQL/MariaDB server via TCP/IP hostname or IP address. + +- **--port** _port_ + + TCP/IP port number to connect to (default: 3306). + +- **--socket** _socket\_path_ + + Path to local UNIX domain socket for database communication. + +- **--user** _username_ + + Database username for authentication. + +- **--password** _password_, **--pass** _password_ + + Database password for authentication. + +- **--ask-pass** + + Prompt interactively for database password on the terminal. + +- **--defaults-file** _path_ + + Path to a custom MySQL configuration file (e.g., `~/.my.cnf`). + +- **--defaults-extra-file** _path_ + + Path to an additional configuration file to read after standard defaults. + +- **--login-path** _path_ + + Read credentials from MySQL encrypted login path (via `mysql_config_editor`). + +- **--mysqlcmd** _path_ + + Path to custom `mysql` client binary. + +- **--mysqladmin** _path_ + + Path to custom `mysqladmin` binary. + +- **--tli** + + Use Transport Layer Interface abstraction. + +- **--ssl-ca** _path_ + + Path to SSL Certificate Authority (CA) certificate. + +- **--caching-sha2-password** + + Force caching\_sha2\_password authentication plugin mode. + +## Target Environment and Cloud Discovery Options + +- **--container** _container\_name\_or\_id_ + + Execute diagnostics inside a running Docker or Podman container. + +- **--ssh-host** _hostname_ + + Execute diagnostics over SSH remote transport. + +- **--ssh-user** _username_ + + SSH login username. + +- **--ssh-key** _path_ + + Path to SSH private key file. + +- **--ssh-port** _port_ + + SSH daemon port (default: 22). + +- **--aws-profile** _profile_ + + AWS CLI profile for Amazon RDS / Aurora cluster discovery. + +- **--aws-region** _region_ + + AWS Region for RDS / Aurora discovery. + +- **--aws-cluster-identifier** _id_ + + Amazon RDS / Aurora cluster identifier. + +- **--aws-instance-identifier** _id_ + + Amazon RDS instance identifier. + +- **--gcp-project** _project\_id_ + + Google Cloud project ID for Cloud SQL instances. + +- **--gcp-instance** _instance\_id_ + + Google Cloud SQL instance identifier. + +- **--azure-resource-group** _group_ + + Azure resource group for Azure Database for MySQL. + +- **--azure-server-name** _name_ + + Azure MySQL flexible/single server name. + +## Performance and Diagnostic Tuning Options + +- **--forcemem** _size_ + + Amount of physical RAM installed in host (e.g., `16G`, `1024M`, `128K`). + +- **--forceswap** _size_ + + Amount of configured swap space on host (e.g., `4G`, `2048M`). + +- **--skipworkload** + + Bypass high-cardinality table churn and auto-increment exhaustion checks. + +- **--skippassword** + + Skip offline dictionary checks for weak user passwords. + +- **--skipsize** + + Skip table size enumeration queries on `information_schema`. + +- **--buffers** + + Print detailed per-buffer memory allocations. + +- **--cvefile** _path_ + + Path to custom CVE vulnerabilities CSV database file. + +- **--passwordfile** _path_ + + Path to custom dictionary file for password audits. + +- **--checkversion** + + Check for upstream MySQLTuner version updates. + +- **--nondedicated** + + Adjust tuning formulas assuming the host runs non-database workloads. + +- **--noprocess** + + Skip OS-level non-mysqld process enumeration. + +## Output and Export Options + +- **--verbose**, **-v** + + Activate full verbose output including storage engines and table statistics. + +- **--silent** + + Suppress standard console output. + +- **--outputfile** _path_ + + Save console report to plain text file. + +- **--reportfile** \[_path_\] + + Generate interactive self-contained HTML diagnostic dashboard. + +- **--json** + + Output raw diagnostic results as a JSON string. + +- **--prettyjson** + + Output diagnostic results as formatted, indented JSON. + +- **--agent-json** + + Output actionable AI remediation schema with SQL/config fixes and rollback statements. + +- **--yaml** + + Output diagnostic metrics in YAML format. + +- **--dumpdir** _path_ + + Dump diagnostic data files and Markdown schema summaries to target directory. + +- **--schemadir** _path_ + + Export individual Markdown documentation files with Mermaid ER diagrams per schema. + +- **--nocolor** + + Disable ANSI color codes in terminal output. + +- **--noprettyicon** + + Use plain text markers (\[OK\], \[!!\], \[--\]) instead of Unicode icons. + +- **--stage-timings** + + Display execution duration for each analysis stage. + +## Debugging and Filtering Options + +- **--debug** + + Print internal debug traces and SQL query payloads. + +- **--dbgpattern** _regex_ + + Filter debug messages by regular expression pattern. + +- **--nobad** + + Suppress negative findings and warning recommendations. + +- **--nogood** + + Suppress positive / passing health checks. + +- **--noinfo** + + Suppress informational messages. # VERSION Version 2.9.2 -=head1 PERLDOC -You can find documentation for this module with the perldoc command. +# PERLDOC + +You can inspect the embedded manual with the perldoc command: - perldoc mysqltuner + perldoc mysqltuner.pl ## INTERNALS diff --git a/mysqltuner.pl b/mysqltuner.pl index 8486535eb..cf23ceba2 100755 --- a/mysqltuner.pl +++ b/mysqltuner.pl @@ -16741,27 +16741,317 @@ sub dump_csv_files { =head1 NAME - MySQLTuner 2.9.2 - MySQL High Performance Tuning Script + MySQLTuner 2.9.2 - MySQL High Performance Tuning Advisor for MySQL, MariaDB, and Percona Server + +=head1 SYNOPSIS + +B [I] + + # Basic local execution using standard unix socket + perl mysqltuner.pl + + # Remote TCP/IP connection with explicit credentials and forced memory sizing + perl mysqltuner.pl --host 192.168.1.50 --port 3306 --user root --pass secret --forcemem 16G + + # Containerized database analysis via Docker/Podman + perl mysqltuner.pl --container production_mysql_1 --user root --pass secret + + # Generate comprehensive interactive HTML diagnostic dashboard + perl mysqltuner.pl --reportfile /var/www/html/tuner_report.html + + # Export schema markdown documentation per database + perl mysqltuner.pl --schemadir /opt/db_docs/ + + # AI Agent integration output (actionable JSON remediation plan) + perl mysqltuner.pl --agent-json =head1 IMPORTANT USAGE GUIDELINES -To run the script with the default options, run the script without arguments -Allow MySQL server to run for at least 24-48 hours before trusting suggestions -Some routines may require root level privileges (script will provide warnings) -You must provide the remote server's total memory when connecting to other servers +=over 4 + +=item * + +B Run the script without modifying arguments first to review recommendations before applying changes. + +=item * + +B Allow your database server to run under normal production load for at least 24 to 48 hours before trusting metric ratios and sizing advice. + +=item * + +B Administrative read-only access (C