diff --git a/.agent/rules/00_constitution.md b/.agent/rules/00_constitution.md new file mode 100644 index 000000000..6ac84000a --- /dev/null +++ b/.agent/rules/00_constitution.md @@ -0,0 +1,30 @@ +--- +trigger: always_on +description: Absolute source of truth for the MT-site project. +category: governance +--- +# **AI CONTEXT SPECIFICATIONS & PROJECT CONSTITUTION** + +## 🧠 Rationale + +Establishing an absolute source of truth is critical for maintaining consistency and quality. This constitution ensures all documentation remains professional, beautiful, and highly portable. + +## πŸ› οΈ Implementation + +$$SYSTEM\_CRITICAL$$ +Notice to the Agent: This document constitutes the unique and absolute source of truth for the MT-site project. + +**Core Mission:** +Make `MT-site` the most beautiful, accessible, and high-performance documentation hub for MySQLTuner. + +**Key Pillars:** + +- **Visual Excellence**: Every page must feel premium, using modern dark-mode aesthetics and smooth interactions. +- **Extreme Portability**: The site must remain executable on any standard web server with PHP support. Zero complexity in deployment. +- **Actionable Documentation**: Content must be clear, well-structured, and automatically synchronized with the core script. +- **Production Performance**: Zero layout shifts and sub-100ms navigation for a "native app" feel. + +## βœ… Verification + +- All UI/UX changes must be reviewed for aesthetic compliance. +- Use `/compliance-sentinel` to audit deviations. diff --git a/.agent/rules/01_objective.md b/.agent/rules/01_objective.md new file mode 100644 index 000000000..36bb44a61 --- /dev/null +++ b/.agent/rules/01_objective.md @@ -0,0 +1,28 @@ +--- +trigger: always_on +description: Identity and Mission of the MT-site project. +category: governance +--- +# **1. 🎯 OPERATIONAL OBJECTIVE** + +## 🧠 Rationale + +Dynamic context tracking allows the agent to focus on making the documentation site a world-class resource. + +## πŸ› οΈ Implementation + +$$DYNAMIC\_CONTEXT$$ + +* **Status:** [IN PROGRESS] +* **Priority Task:** Transform MT-site into a premium documentation hub with server-side Markdown rendering and a technical dark-mode aesthetic. + +**Success Criteria:** + +1. **Aesthetics:** 100% "WOW" factor. Dark mode with glassmorphism and premium typography (Inter/Outfit). +2. **Architecture:** PHP-based zero-dependency router. No heavy frameworks. +3. **Synchronization:** Automated doc synchronization with `MySQLTuner-perl`. +4. **Resiliency:** 100% functional on standard PHP hosting (IONOS, etc.). + +## βœ… Verification + +- Run `/local-preview` to verify visual standards. diff --git a/.agent/rules/02_architecture.md b/.agent/rules/02_architecture.md new file mode 100644 index 000000000..9a487d4ec --- /dev/null +++ b/.agent/rules/02_architecture.md @@ -0,0 +1,34 @@ +--- +trigger: always_on +description: Technical environment and architecture map. +category: governance +--- +# **2. πŸ—οΈ TECHNICAL ENVIRONMENT & ARCHITECTURE** + +## 🧠 Rationale + +Preserving the lightweight PHP architecture ensures maximum portability and speed. + +## πŸ› οΈ Implementation + +$$IMMUTABLE$$ + +| File/Folder | Functionality | Criticality | +| :--- | :--- | :--- | +| index.php | Main router and entry point | πŸ”΄ CRITICAL | +| includes/ | Core layouts (header, footer, sidebar) | πŸ”΄ CRITICAL | +| public/docs/ | Markdown documentation sources | πŸ”΄ CRITICAL | +| assets/css/ | Global styling and design system | 🟑 HIGH | +| scripts/ | Automation scripts (sync_docs.py) | 🟑 HIGH | + +**Technology Stack:** + +- **Language**: PHP (Server-side rendering) +- **Engine**: Parsedown (Markdown processing) +- **Styling**: Vanilla CSS (Modern technical aesthetic) +- **Typography**: Inter & Outfit (Google Fonts) +- **Icons**: Emoji & Custom SVG + +## βœ… Verification + +- Ensure any new library is single-file and PHP-based. diff --git a/.agent/rules/03_execution_rules.md b/.agent/rules/03_execution_rules.md new file mode 100644 index 000000000..81f9d7aa8 --- /dev/null +++ b/.agent/rules/03_execution_rules.md @@ -0,0 +1,25 @@ +--- +trigger: always_on +description: Execution rules and constraints for MT-site. +category: governance +--- +# **3. βš™οΈ EXECUTION RULES & CONSTRAINTS** + +## **3.1. Formal Prohibitions** + +1. **NO FRAMEWORKS**: Use of heavy JS frameworks (React/Vue) is prohibited. Stick to PHP + Vanilla JS. +2. **ZERO DEPENDENCY**: No NPM/Node.js dependencies in production. +3. **PORTABILITY FIRST**: All paths must be relative or dynamically determined to work across different hostings. +4. **NO CONTENT DELETION**: Documentation content should only be updated or archived, never deleted without cause. + +## **3.2. Aesthetic Guidelines** + +1. **DARK MODE ONLY**: The site is primary dark-mode. High contrast but easy on the eyes. +2. **GLASSMORPHISM**: Use subtle background blurs and borders for overlays and headers. +3. **TYPOGRAPHY**: Titles in `Outfit`, body in `Inter`. +4. **ANIMATIONS**: Use CSS transitions for page loads and hover states (`fade-in`, `slide-up`). + +## **3.3. Development Workflow** + +1. **TDD (Visual)**: Before finalizing a UI change, verify it via `/local-preview`. +2. **SYNC CHECK**: After updating documentation, ensure the sync script is functional. diff --git a/.agent/rules/04_best_practices.md b/.agent/rules/04_best_practices.md new file mode 100644 index 000000000..4eeda65b4 --- /dev/null +++ b/.agent/rules/04_best_practices.md @@ -0,0 +1,40 @@ +--- +trigger: always_on +description: Best practices for MT-site development and aesthetics. +category: governance +--- +# **4. 🌟 CORE BEST PRACTICES** + +## 🧠 Rationale + +Consistent high standards ensure the site remains premium and maintainable. + +## πŸ› οΈ Implementation + +### 1. Visual "Aesthetic" Audit + +- Use the **Browser Agent** to check: + - Contrast ratios. + - Hover animations. + - Responsive layout (Mobile/Desktop). + - Loading states (no white flashes). + +### 2. Micro-Animations + +- Apply `transition: all 0.3s ease;` to interactive elements. +- Use `opacity` and `transform: translateY` for entrance animations. + +### 3. SEO & Accessibility + +- Every page must have a unique `` and `meta description`. +- Semantic HTML (`<main>`, `<article>`, `<nav>`) is mandatory. + +### 4. Performance + +- Optimize images (WebP preferred). +- Minimal external requests (Google Fonts are the exception). +- CSS should be under 50KB. + +## βœ… Verification + +- Use `visual-audit` skill for automated compliance checks. diff --git a/.agent/rules/05_memory_protocol.md b/.agent/rules/05_memory_protocol.md new file mode 100644 index 000000000..897096852 --- /dev/null +++ b/.agent/rules/05_memory_protocol.md @@ -0,0 +1,18 @@ +--- +trigger: always_on +description: Contextual consistency and history protocols. +category: governance +--- +# **5. πŸ“œ STATE MEMORY & HISTORY** + +## **Contextual Consistency Protocols** + +1. **History Update**: Add new entries to the top of `Changelog` if the action is correct and tested. +2. **Rotation**: FIFO Rotation (Max 600 lines). Remove oldest entries beyond 600 lines. +3. **Changelog**: All changes MUST be traced and documented inside `Changelog`. + +### **History Entry example** + +1.0.1 2026-02-01 + +- feat: establish .agent governance and aesthetic verification. diff --git a/.agent/rules/remembers.md b/.agent/rules/remembers.md new file mode 100644 index 000000000..60f13b833 --- /dev/null +++ b/.agent/rules/remembers.md @@ -0,0 +1,10 @@ +# **Session Memory Buffer** + +## 🧠 Rationale + +Tracks transient session context and lessons learned to maintain alignment between manual interventions. + +## πŸ› οΈ Implementation + +- [2026-02-01] Established initial .agent governance for MT-site. +- [2026-02-01] Defined "clean and aesthetic" standards. diff --git a/.agent/skills/visual-audit/SKILL.md b/.agent/skills/visual-audit/SKILL.md new file mode 100644 index 000000000..16b405aee --- /dev/null +++ b/.agent/skills/visual-audit/SKILL.md @@ -0,0 +1,25 @@ +--- +trigger: explicit_call +description: Use the browser agent to audit the site's aesthetics. +category: skill +--- +# Skill: Visual Audit + +## 🧠 Rationale + +Ensures the site meets the visual standards defined in the project constitution. + +## πŸ› οΈ Implementation + +1. **Initialize Preview**: Run `/local-preview` to ensure the site is running. +2. **Browser Audit**: Open `http://localhost:8080` using the `browser_subagent`. +3. **Checks**: + - Verify dark mode color palette (e.g., `#0f172a` background). + - Check for glassmorphism effects (backdrop-filter). + - Verify font loading (Inter/Outfit). + - Check responsive behavior. +4. **Report**: Summarize findings and suggest improvements if "WOW" factor is missing. + +## βœ… Verification + +- Compare visual results with `specification.md` design goals. diff --git a/.agent/workflows/doc-sync.md b/.agent/workflows/doc-sync.md new file mode 100644 index 000000000..87440c165 --- /dev/null +++ b/.agent/workflows/doc-sync.md @@ -0,0 +1,18 @@ +--- +description: Synchronize .agent/README.md with current Rules, Skills, and Workflows +--- +# Doc-Sync Workflow + +## 🧠 Rationale + +Keeps the project's technical summary up-to-date with all available governance assets. + +## πŸ› οΈ Implementation + +1. Scan `.agent/rules/`, `.agent/skills/`, and `.agent/workflows/`. +2. Update `.agent/README.md` with a structured list of these items. +3. Ensure absolute paths are converted to relative paths for portability. + +## βœ… Verification + +- Verify `.agent/README.md` is updated and matches the filesystem. diff --git a/.agent/workflows/git-flow.md b/.agent/workflows/git-flow.md new file mode 100644 index 000000000..251f44f45 --- /dev/null +++ b/.agent/workflows/git-flow.md @@ -0,0 +1,51 @@ +--- +description: Automate git-flow release process for MT-site +--- +# Git-Flow Release Workflow (MT-site) + +1. **Run Release Preflight Workflow** + - Execute the `/release-preflight` workflow. + + ```bash + /release-preflight + ``` + +2. **Commit Current Changes** + - Commit pending changes including governance and fixes. + + ```bash + git add . + # Use conventional commit + git commit -m "feat: release $CURRENT_VER" + ``` + +3. **Create Tag for Current Version** + + ```bash + TAG_MSG=$(awk "/^$CURRENT_VER/,/^([0-9]+\.[0-9]+\.[0-9]+)/ {if (\$0 !~ /^([0-9]+\.[0-9]+\.[0-9]+)/) print}" Changelog | sed '/^$/d') + git tag -a v$CURRENT_VER -m "Release $CURRENT_VER" -m "$TAG_MSG" + ``` + +4. **Push Branch and Tag** + + ```bash + git push origin main + git push origin v$CURRENT_VER + ``` + +5. **Post-Push: Increment Version** + + ```bash + NEW_VER=$(echo $CURRENT_VER | awk -F. '{print $1"."$2"."($3+1)}') + echo $NEW_VER > CURRENT_VERSION.txt + DATE=$(date +%Y-%m-%d) + echo -e "$NEW_VER $DATE\n\n- \n" > tmp_changelog && cat Changelog >> tmp_changelog && mv tmp_changelog Changelog + ``` + +6. **Commit Version Bump** + + ```bash + git add CURRENT_VERSION.txt Changelog + git commit -m "chore: bump version to $NEW_VER" + git push origin main + ``` diff --git a/.agent/workflows/local-preview.md b/.agent/workflows/local-preview.md new file mode 100644 index 000000000..9fce3b729 --- /dev/null +++ b/.agent/workflows/local-preview.md @@ -0,0 +1,27 @@ +--- +description: Start a local PHP development server to preview the site. +--- +# Local Preview Workflow + +1. Start the PHP built-in server in the background: +// turbo + +```bash +php -S localhost:8000 > /tmp/php_mt_site.log 2>&1 & +``` + +1. Wait for the server to initialize. + +2. Provide the user with the preview link: +<http://localhost:8000> + +3. To stop the server: +// turbo + +```bash +pkill -f "php -S localhost:8000" +``` + +## βœ… Verification + +- Use `read_url_content` or `browser_subagent` to confirm the server is responsive. diff --git a/.agent/workflows/release-preflight.md b/.agent/workflows/release-preflight.md new file mode 100644 index 000000000..b04769ea6 --- /dev/null +++ b/.agent/workflows/release-preflight.md @@ -0,0 +1,39 @@ +--- +trigger: explicit_call +description: Pre-flight checks before triggering a git-flow release +category: tool +--- +# Release Preflight Workflow (MT-site) + +## 1. Extract Versions + +```bash +TXT_VER=$(cat CURRENT_VERSION.txt | tr -d '[:space:]') +LOG_VER=$(head -n 1 Changelog | awk '{print $1}') +``` + +## 2. Validate Consistency + +```bash +if [ "$LOG_VER" != "$TXT_VER" ]; then + echo "FAIL: Version Mismatch detected!" + echo "Txt: $TXT_VER" + echo "Changelog: $LOG_VER" + exit 1 +else + echo "SUCCESS: Versions match ($TXT_VER)." +fi +``` + +## 3. Aesthetic Sanity Check + +- Run `/local-preview` and check for 404s. +- Run `/visual-audit` and confirm "PASS". + +## 4. Documentation Sync + +- Run `/doc-sync` to ensure .agent/README.md is up-to-date. + +## 5. Proceed to Release + +If all checks pass, proceed with `/git-flow`. diff --git a/.github/workflows/deploy-ionos.yml b/.github/workflows/deploy-ionos.yml new file mode 100644 index 000000000..5480e18de --- /dev/null +++ b/.github/workflows/deploy-ionos.yml @@ -0,0 +1,46 @@ +name: Deploy to IONOS + +# DΓ©clenche le workflow Γ  chaque push sur la branche 'main' +# Adaptez 'main' si votre branche principale a un autre nom (ex: master, prod) +on: + push: + branches: + - gh-pages # ou master, prod, etc. + +jobs: + deploy: + name: Deploy PHP Site to IONOS + runs-on: ubuntu-latest # Utilise la derniΓ¨re version d'Ubuntu disponible + + steps: + - name: Checkout de votre code + uses: actions/checkout@v4 # Action pour rΓ©cupΓ©rer le code de votre dΓ©pΓ΄t + + # Optionnel: Si vous avez des dΓ©pendances PHP gΓ©rΓ©es avec Composer + # Si votre site est purement statique ou PHP simple sans composer, cette Γ©tape n'est pas nΓ©cessaire. + # - name: Set up PHP + # uses: shivammathur/setup-php@v2 + # with: + # php-version: '8.1' # SpΓ©cifiez votre version de PHP + # extensions: mbstring, xml, curl, zip # Ajoutez les extensions PHP nΓ©cessaires + # tools: composer # Si vous utilisez Composer + + # Optionnel: Installer les dΓ©pendances Composer + # - name: Install Composer dependencies + # if: steps.setup-php.outputs.php-version != '' # S'exΓ©cute seulement si PHP est configurΓ© + # run: composer install --prefer-dist --no-progress --no-dev + + - name: Deploy files via SFTP/FTP to IONOS + uses: wlixcc/SFTP-Deploy-Action@v1.2.6 + with: + server: ${{ secrets.IONOS_FTP_SERVER }} + username: ${{ secrets.IONOS_FTP_USERNAME }} + password: ${{ secrets.IONOS_FTP_PASSWORD }} + sftp_only: true + port: ${{ secrets.IONOS_FTP_PORT || '22' }} # Utilise le port 22 par dΓ©faut pour SFTP si IONOS_FTP_PORT n'est pas dΓ©fini. Mettre '21' pour FTP. + local_path: ./ # Dossier local Γ  tΓ©lΓ©verser. './' pour la racine du dΓ©pΓ΄t. Adaptez si votre site est dans un sous-dossier (ex: ./public/, ./dist/). + remote_path: ${{ secrets.IONOS_REMOTE_PATH }}/ + rsyncArgs: "--delete --exclude=.git --exclude=.github --exclude=.agent" + sftpArgs: "-o ConnectTimeout=5" + + # Note: IONOS might have cached DirectoryIndex. Explicitly check if index.html is gone. diff --git a/.htaccess b/.htaccess new file mode 100644 index 000000000..448c5db4a --- /dev/null +++ b/.htaccess @@ -0,0 +1,35 @@ +# MySQLTuner Documentation Site - Apache Configuration + +# Set index.php as the primary entry point +DirectoryIndex index.php index.html + +<IfModule mod_rewrite.c> + RewriteEngine On + RewriteBase / + + # 1. Redirect index.html to root / + RewriteRule ^index\.html$ / [R=301,L] + + # 2. Redirect index.php to root / (only if no query string to avoid infinite loops) + RewriteCond %{THE_REQUEST} ^[A-Z]{3,9}\ /index\.php\ HTTP/ + RewriteCond %{QUERY_STRING} ^$ + RewriteRule ^index\.php$ / [R=301,L] + + # 3. Handle Pretty URLs: map /pagename to index.php?p=pagename + RewriteCond %{REQUEST_FILENAME} !-d + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule ^([^/]+)/?$ index.php?p=$1 [L,QSA] +</IfModule> + +# Prevent access to .git and other sensitive files (Safety) +<IfModule mod_authz_core.c> + <Files ".git"> + Require all denied + </Files> + <Files ".agent"> + Require all denied + </Files> +</IfModule> + +# Handle common asset paths +# No specific rules needed for assets/ or public/ as they are real directories/files diff --git a/CNAME b/CNAME index 2318b83f8..4c6769fcf 100644 --- a/CNAME +++ b/CNAME @@ -1 +1 @@ -mysqltuner.com +mysqltuner.lightpath.fr \ No newline at end of file diff --git a/CURRENT_VERSION.txt b/CURRENT_VERSION.txt new file mode 100644 index 000000000..02754b2d6 --- /dev/null +++ b/CURRENT_VERSION.txt @@ -0,0 +1 @@ +2.8.33 \ No newline at end of file diff --git a/Changelog b/Changelog new file mode 100644 index 000000000..a549dc6ed --- /dev/null +++ b/Changelog @@ -0,0 +1,38 @@ +2.8.33 2026-02-01 + +- feat: synchronize site versioning with core script logic (2.8.33). +- feat: implement robust Pretty URLs logic and routing in index.php. +- feat: fix link variable shadowing in header/sidebar components. +- feat: implement automated redirect from index.html to root. +- chore: establish .agent governance and aesthetic verification. + +1.0.3 2026-02-01 + +- feat: established project governance with 7-tier AFF structure. +- feat: implemented local verification tools (`/local-preview`, `/visual-audit`). +- fix: repaired broken image icons and badges in `overview.md`. + +1.0.2 2026-02-01 + +- feat: migrated architecture to standalone PHP for zero-dependency portability. +- feat: implemented server-side Markdown rendering using Parsedown. +- feat: integrated official `mtlogo2.png` brand asset into header and sidebar. +- refactor: extracted layout components into PHP includes (header, sidebar, footer). +- chore: removed Node.js/Vite build artifacts and dependencies. +- docs: updated specification to codify PHP architecture and brand assets. + +1.0.1 2026-02-01 + +- feat: comprehensive modern redesign of the UI (Navy & Cyan technical aesthetic). +- feat: implementation of glassmorphism effects on cards and sidebar. +- feat: redesigned Hero section with dynamic typography and glow effects. +- feat: enhanced mobile responsiveness and navigation logic. +- feat: added smooth transitions and scroll-to-top on route changes. + +1.0.0 2026-02-01 + +- feat: complete overhaul of the MySQLTuner website. +- feat: implementation of a modern documentation hub with sidebar navigation. +- feat: automated synchronization of docs from the perl repository. +- feat: dynamic release notes archive and FAQ section. +- feat: premium dark mode aesthetics and high-performance Vite build system. diff --git a/assets/css/style.css b/assets/css/style.css new file mode 100644 index 000000000..7ad8ee783 --- /dev/null +++ b/assets/css/style.css @@ -0,0 +1,530 @@ +@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;600;800&display=swap'); + +:root { + /* Colors - Sleek Technical Dark */ + --bg-color: #020617; + --bg-card: rgba(15, 23, 42, 0.6); + --text-main: #f8fafc; + --text-muted: #94a3b8; + --accent-primary: #38bdf8; + /* Modern Cyan */ + --accent-secondary: #818cf8; + /* Indigo */ + --accent-success: #10b981; + /* Emerald */ + --accent-glow: rgba(56, 189, 248, 0.15); + + --border-color: rgba(255, 255, 255, 0.08); + --glass-bg: rgba(15, 23, 42, 0.8); + + /* Typography */ + --font-sans: 'Inter', system-ui, -apple-system, sans-serif; + --font-heading: 'Outfit', var(--font-sans); + --font-mono: 'Fira Code', monospace; + + /* Spacing */ + --section-padding: 6rem 1rem; + --card-radius: 16px; + --container-max: 1200px; +} + +* { + margin: 0; + padding: 0; + box-sizing: border-box; +} + +html { + scroll-behavior: smooth; +} + +body { + background-color: var(--bg-color); + color: var(--text-main); + font-family: var(--font-sans); + line-height: 1.6; + overflow-x: hidden; + -webkit-font-smoothing: antialiased; +} + +/* Typography */ +h1, +h2, +h3, +h4 { + font-family: var(--font-heading); + font-weight: 800; + letter-spacing: -0.02em; + margin-bottom: 1.5rem; + line-height: 1.1; +} + +.gradient-text { + background: linear-gradient(135deg, #fff 30%, var(--accent-primary) 100%); + -webkit-background-clip: text; + background-clip: text; + -webkit-text-fill-color: transparent; +} + +/* Layout Utilities */ +.container { + max-width: var(--container-max); + margin: 0 auto; + padding: 0 2rem; +} + +.grid { + display: grid; + gap: 2.5rem; +} + +.grid-3 { + grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); +} + +/* Glassmorphism */ +.glass { + background: var(--glass-bg); + backdrop-filter: blur(12px); + -webkit-backdrop-filter: blur(12px); + border: 1px solid var(--border-color); +} + +/* Components */ +.btn { + display: inline-flex; + align-items: center; + padding: 0.875rem 2rem; + border-radius: 12px; + font-weight: 600; + text-decoration: none; + transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1); + cursor: pointer; + font-size: 0.95rem; + letter-spacing: 0.01em; +} + +.btn-primary { + background: var(--accent-primary); + color: #020617; + box-shadow: 0 4px 20px -4px var(--accent-glow); +} + +.btn-primary:hover { + transform: translateY(-2px) scale(1.02); + box-shadow: 0 8px 30px -4px var(--accent-glow); + filter: brightness(1.1); +} + +.btn-outline { + border: 1px solid var(--border-color); + color: var(--text-main); + background: rgba(255, 255, 255, 0.03); +} + +.btn-outline:hover { + background: rgba(255, 255, 255, 0.1); + border-color: var(--accent-primary); + transform: translateY(-2px); +} + +/* Cards */ +.card { + background: var(--bg-card); + border-radius: var(--card-radius); + padding: 2.5rem; + border: 1px solid var(--border-color); + transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1); + position: relative; + overflow: hidden; +} + +.card:hover { + transform: translateY(-8px); + border-color: rgba(56, 189, 248, 0.4); + box-shadow: 0 20px 40px -20px rgba(0, 0, 0, 0.5); +} + +.card::before { + content: ''; + position: absolute; + top: 0; + left: 0; + width: 100%; + height: 100%; + background: radial-gradient(circle at top right, rgba(56, 189, 248, 0.1), transparent 50%); + opacity: 0; + transition: opacity 0.4s; +} + +.card:hover::before { + opacity: 1; +} + +/* Hero bg */ +.hero { + position: relative; + min-height: 90vh; + display: flex; + flex-direction: column; + justify-content: center; + overflow: hidden; +} + +.hero-bg { + position: absolute; + top: 0; + left: 0; + width: 100%; + height: 100%; + z-index: -1; + background: radial-gradient(circle at 50% -20%, rgba(56, 189, 248, 0.15), transparent 70%), + radial-gradient(circle at bottom right, rgba(129, 140, 248, 0.1), transparent 50%); +} + +.hero-glow { + position: absolute; + top: -10%; + left: 50%; + transform: translateX(-50%); + width: 80%; + height: 40%; + background: var(--accent-primary); + filter: blur(150px); + opacity: 0.1; + pointer-events: none; +} + +/* Sections */ +section { + padding: var(--section-padding); +} + +/* Documentation Content Styling */ +.doc-content { + color: var(--text-main); + line-height: 1.8; +} + +.doc-content h1 { + font-size: clamp(2.5rem, 5vw, 3.5rem); + color: #fff; + margin-bottom: 2rem; +} + +.doc-content h2 { + font-size: 1.875rem; + margin-top: 4rem; + margin-bottom: 1.5rem; + padding-bottom: 0.75rem; + border-bottom: 1px solid var(--border-color); +} + +.doc-content h3 { + font-size: 1.5rem; + margin-top: 3rem; + color: var(--accent-primary); +} + +.doc-content p { + margin-bottom: 1.5rem; + color: var(--text-muted); + font-size: 1.1rem; +} + +.doc-content ul, +.doc-content ol { + margin-bottom: 1.5rem; + padding-left: 1.5rem; + color: var(--text-muted); +} + +.doc-content li { + margin-bottom: 0.75rem; +} + +.doc-content code { + background: rgba(255, 255, 255, 0.08); + padding: 0.2rem 0.5rem; + border-radius: 6px; + font-family: var(--font-mono); + font-size: 0.9em; + color: var(--accent-primary); +} + +.doc-content pre { + background: #0b1120; + padding: 1.75rem; + border-radius: 12px; + margin: 2rem 0; + overflow-x: auto; + border: 1px solid var(--border-color); + box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.3); +} + +.doc-content pre code { + background: transparent; + padding: 0; + color: #e2e8f0; +} + +.doc-content a { + color: var(--accent-primary); + text-decoration: none; + border-bottom: 1px solid transparent; + transition: border-color 0.2s; +} + +.doc-content a:hover { + border-color: var(--accent-primary); +} + +/* Responsive fixes */ +@media (max-width: 768px) { + :root { + --section-padding: 4rem 1rem; + } + + .container { + padding: 0 1.5rem; + } +} + +/* Animation */ +@keyframes fadeIn { + from { + opacity: 0; + transform: translateY(20px); + } + + to { + opacity: 1; + transform: translateY(0); + } +} + +.fade-in { + animation: fadeIn 0.8s cubic-bezier(0.4, 0, 0.2, 1) forwards; +} + +/* Navigation & Branding */ +.top-nav { + display: flex; + justify-content: space-between; + align-items: center; + padding: 2rem 0; + position: absolute; + top: 0; + left: 50%; + transform: translateX(-50%); + width: 100%; + z-index: 10; +} + +.logo-wrap { + display: flex; + align-items: center; + gap: 1rem; +} + +.nav-actions { + display: flex; + gap: 1.5rem; +} + +/* Badge */ +.badge { + display: inline-block; + padding: 0.4rem 1rem; + background: rgba(56, 189, 248, 0.1); + border: 1px solid rgba(56, 189, 248, 0.2); + border-radius: 100px; + color: var(--accent-primary); + font-size: 0.8rem; + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.05em; + margin-bottom: 2rem; +} + +/* Card Improvements */ +.card-icon { + font-size: 2.5rem; + margin-bottom: 1.5rem; + display: inline-block; +} + +/* Footer Adjustments */ +footer p { + opacity: 0.6; +} + +/* Doc Page Layout Adjustments */ +body.is-docs .hero { + display: none; +} + +body.is-docs #home-view { + display: none; +} + +body.is-docs #doc-view { + display: block; +}.sidebar { + width: 280px; + height: 100vh; + position: sticky; + top: 0; + padding: 3rem 1.5rem; + overflow-y: auto; + display: none; + z-index: 50; + transition: all 0.3s ease; +} + +body.is-docs .sidebar { + display: flex; + flex-direction: column; +} + +body.is-docs #app { + display: flex; +} + +.sidebar-brand { + display: flex; + align-items: center; + gap: 1rem; + margin-bottom: 3.5rem; + text-decoration: none; + color: var(--text-main); +} + +.logo-icon { + width: 32px; + height: 32px; + background: var(--accent-primary); + border-radius: 8px; + display: flex; + align-items: center; + justify-content: center; + color: #020617; + font-weight: 800; + font-family: var(--font-heading); +} + +.sidebar-brand span { + font-family: var(--font-heading); + font-weight: 800; + font-size: 1.1rem; +} + +.sidebar-nav { + list-style: none; + flex: 1; +} + +.nav-group { + margin-bottom: 2.5rem; +} + +.nav-group-title { + font-size: 0.7rem; + text-transform: uppercase; + color: var(--text-muted); + letter-spacing: 0.1em; + margin-bottom: 1rem; + font-weight: 700; + opacity: 0.8; +} + +.nav-item { + margin-bottom: 0.4rem; +} + +.nav-link { + display: block; + padding: 0.6rem 1rem; + border-radius: 10px; + color: var(--text-muted); + text-decoration: none; + font-size: 0.9rem; + font-weight: 500; + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); + border: 1px solid transparent; +} + +.nav-link:hover { + color: var(--text-main); + background: rgba(255, 255, 255, 0.05); + transform: translateX(4px); +} + +.nav-link.active { + color: var(--accent-primary); + background: rgba(56, 189, 248, 0.08); + border-color: rgba(56, 189, 248, 0.2); + font-weight: 600; +} + +.sidebar-footer { + margin-top: auto; + padding-top: 2rem; + border-top: 1px solid var(--border-color); +} + +.github-link { + display: flex; + align-items: center; + gap: 0.75rem; + color: var(--text-muted); + text-decoration: none; + font-size: 0.875rem; + transition: color 0.2s; +} + +.github-link:hover { + color: var(--text-main); +} + +/* Mobile Toggle */ +.mobile-nav-toggle { + position: fixed; + bottom: 2rem; + right: 2rem; + z-index: 100; + background: var(--accent-primary); + color: #020617; + width: 3.5rem; + height: 3.5rem; + border-radius: 16px; + display: none; + align-items: center; + justify-content: center; + box-shadow: 0 10px 25px -5px var(--accent-glow); + cursor: pointer; + transition: transform 0.2s; +} + +.mobile-nav-toggle:active { + transform: scale(0.9); +} + +@media (max-width: 768px) { + .sidebar { + position: fixed; + left: -280px; + height: 100vh; + display: flex !important; + /* Force flex for mobile interaction */ + } + + .sidebar.open { + transform: translateX(280px); + box-shadow: 20px 0 50px rgba(0, 0, 0, 0.5); + } + + body.is-docs .mobile-nav-toggle { + display: flex; + } +} \ No newline at end of file diff --git a/assets/img/hero-bg.png b/assets/img/hero-bg.png new file mode 100644 index 000000000..213af10d6 Binary files /dev/null and b/assets/img/hero-bg.png differ diff --git a/assets/img/logo.png b/assets/img/logo.png new file mode 100644 index 000000000..92b4a234f Binary files /dev/null and b/assets/img/logo.png differ diff --git a/assets/img/mtlogo2.png b/assets/img/mtlogo2.png new file mode 100644 index 000000000..92b4a234f Binary files /dev/null and b/assets/img/mtlogo2.png differ diff --git a/assets/js/app.js b/assets/js/app.js new file mode 100644 index 000000000..dd300ca43 --- /dev/null +++ b/assets/js/app.js @@ -0,0 +1,30 @@ +document.addEventListener('DOMContentLoaded', () => { + console.log('MySQLTuner Website Initialized (PHP Version)'); + + // Sidebar toggle for mobile + const toggle = document.getElementById('sidebar-toggle'); + const sidebar = document.querySelector('.sidebar'); + + if (toggle && sidebar) { + toggle.addEventListener('click', () => { + sidebar.classList.toggle('open'); + }); + } + + // Auto-close sidebar on mobile after clicking a link + document.querySelectorAll('.nav-link').forEach(link => { + link.addEventListener('click', () => { + if (sidebar) sidebar.classList.remove('open'); + }); + }); + + // Smooth scroll for anchors + document.querySelectorAll('a[href^="#"]').forEach(anchor => { + anchor.addEventListener('click', function (e) { + e.preventDefault(); + document.querySelector(this.getAttribute('href')).scrollIntoView({ + behavior: 'smooth' + }); + }); + }); +}); diff --git a/includes/Parsedown.php b/includes/Parsedown.php new file mode 100644 index 000000000..38edfe92e --- /dev/null +++ b/includes/Parsedown.php @@ -0,0 +1,1994 @@ +<?php + +# +# +# Parsedown +# http://parsedown.org +# +# (c) Emanuil Rusev +# http://erusev.com +# +# For the full license information, view the LICENSE file that was distributed +# with this source code. +# +# + +class Parsedown +{ + # ~ + + const version = '1.8.0'; + + # ~ + + function text($text) + { + $Elements = $this->textElements($text); + + # convert to markup + $markup = $this->elements($Elements); + + # trim line breaks + $markup = trim($markup, "\n"); + + return $markup; + } + + protected function textElements($text) + { + # make sure no definitions are set + $this->DefinitionData = array(); + + # standardize line breaks + $text = str_replace(array("\r\n", "\r"), "\n", $text); + + # remove surrounding line breaks + $text = trim($text, "\n"); + + # split text into lines + $lines = explode("\n", $text); + + # iterate through lines to identify blocks + return $this->linesElements($lines); + } + + # + # Setters + # + + function setBreaksEnabled($breaksEnabled) + { + $this->breaksEnabled = $breaksEnabled; + + return $this; + } + + protected $breaksEnabled; + + function setMarkupEscaped($markupEscaped) + { + $this->markupEscaped = $markupEscaped; + + return $this; + } + + protected $markupEscaped; + + function setUrlsLinked($urlsLinked) + { + $this->urlsLinked = $urlsLinked; + + return $this; + } + + protected $urlsLinked = true; + + function setSafeMode($safeMode) + { + $this->safeMode = (bool) $safeMode; + + return $this; + } + + protected $safeMode; + + function setStrictMode($strictMode) + { + $this->strictMode = (bool) $strictMode; + + return $this; + } + + protected $strictMode; + + protected $safeLinksWhitelist = array( + 'http://', + 'https://', + 'ftp://', + 'ftps://', + 'mailto:', + 'tel:', + 'data:image/png;base64,', + 'data:image/gif;base64,', + 'data:image/jpeg;base64,', + 'irc:', + 'ircs:', + 'git:', + 'ssh:', + 'news:', + 'steam:', + ); + + # + # Lines + # + + protected $BlockTypes = array( + '#' => array('Header'), + '*' => array('Rule', 'List'), + '+' => array('List'), + '-' => array('SetextHeader', 'Table', 'Rule', 'List'), + '0' => array('List'), + '1' => array('List'), + '2' => array('List'), + '3' => array('List'), + '4' => array('List'), + '5' => array('List'), + '6' => array('List'), + '7' => array('List'), + '8' => array('List'), + '9' => array('List'), + ':' => array('Table'), + '<' => array('Comment', 'Markup'), + '=' => array('SetextHeader'), + '>' => array('Quote'), + '[' => array('Reference'), + '_' => array('Rule'), + '`' => array('FencedCode'), + '|' => array('Table'), + '~' => array('FencedCode'), + ); + + # ~ + + protected $unmarkedBlockTypes = array( + 'Code', + ); + + # + # Blocks + # + + protected function lines(array $lines) + { + return $this->elements($this->linesElements($lines)); + } + + protected function linesElements(array $lines) + { + $Elements = array(); + $CurrentBlock = null; + + foreach ($lines as $line) + { + if (chop($line) === '') + { + if (isset($CurrentBlock)) + { + $CurrentBlock['interrupted'] = (isset($CurrentBlock['interrupted']) + ? $CurrentBlock['interrupted'] + 1 : 1 + ); + } + + continue; + } + + while (($beforeTab = strstr($line, "\t", true)) !== false) + { + $shortage = 4 - mb_strlen($beforeTab, 'utf-8') % 4; + + $line = $beforeTab + . str_repeat(' ', $shortage) + . substr($line, strlen($beforeTab) + 1) + ; + } + + $indent = strspn($line, ' '); + + $text = $indent > 0 ? substr($line, $indent) : $line; + + # ~ + + $Line = array('body' => $line, 'indent' => $indent, 'text' => $text); + + # ~ + + if (isset($CurrentBlock['continuable'])) + { + $methodName = 'block' . $CurrentBlock['type'] . 'Continue'; + $Block = $this->$methodName($Line, $CurrentBlock); + + if (isset($Block)) + { + $CurrentBlock = $Block; + + continue; + } + else + { + if ($this->isBlockCompletable($CurrentBlock['type'])) + { + $methodName = 'block' . $CurrentBlock['type'] . 'Complete'; + $CurrentBlock = $this->$methodName($CurrentBlock); + } + } + } + + # ~ + + $marker = $text[0]; + + # ~ + + $blockTypes = $this->unmarkedBlockTypes; + + if (isset($this->BlockTypes[$marker])) + { + foreach ($this->BlockTypes[$marker] as $blockType) + { + $blockTypes []= $blockType; + } + } + + # + # ~ + + foreach ($blockTypes as $blockType) + { + $Block = $this->{"block$blockType"}($Line, $CurrentBlock); + + if (isset($Block)) + { + $Block['type'] = $blockType; + + if ( ! isset($Block['identified'])) + { + if (isset($CurrentBlock)) + { + $Elements[] = $this->extractElement($CurrentBlock); + } + + $Block['identified'] = true; + } + + if ($this->isBlockContinuable($blockType)) + { + $Block['continuable'] = true; + } + + $CurrentBlock = $Block; + + continue 2; + } + } + + # ~ + + if (isset($CurrentBlock) and $CurrentBlock['type'] === 'Paragraph') + { + $Block = $this->paragraphContinue($Line, $CurrentBlock); + } + + if (isset($Block)) + { + $CurrentBlock = $Block; + } + else + { + if (isset($CurrentBlock)) + { + $Elements[] = $this->extractElement($CurrentBlock); + } + + $CurrentBlock = $this->paragraph($Line); + + $CurrentBlock['identified'] = true; + } + } + + # ~ + + if (isset($CurrentBlock['continuable']) and $this->isBlockCompletable($CurrentBlock['type'])) + { + $methodName = 'block' . $CurrentBlock['type'] . 'Complete'; + $CurrentBlock = $this->$methodName($CurrentBlock); + } + + # ~ + + if (isset($CurrentBlock)) + { + $Elements[] = $this->extractElement($CurrentBlock); + } + + # ~ + + return $Elements; + } + + protected function extractElement(array $Component) + { + if ( ! isset($Component['element'])) + { + if (isset($Component['markup'])) + { + $Component['element'] = array('rawHtml' => $Component['markup']); + } + elseif (isset($Component['hidden'])) + { + $Component['element'] = array(); + } + } + + return $Component['element']; + } + + protected function isBlockContinuable($Type) + { + return method_exists($this, 'block' . $Type . 'Continue'); + } + + protected function isBlockCompletable($Type) + { + return method_exists($this, 'block' . $Type . 'Complete'); + } + + # + # Code + + protected function blockCode($Line, $Block = null) + { + if (isset($Block) and $Block['type'] === 'Paragraph' and ! isset($Block['interrupted'])) + { + return; + } + + if ($Line['indent'] >= 4) + { + $text = substr($Line['body'], 4); + + $Block = array( + 'element' => array( + 'name' => 'pre', + 'element' => array( + 'name' => 'code', + 'text' => $text, + ), + ), + ); + + return $Block; + } + } + + protected function blockCodeContinue($Line, $Block) + { + if ($Line['indent'] >= 4) + { + if (isset($Block['interrupted'])) + { + $Block['element']['element']['text'] .= str_repeat("\n", $Block['interrupted']); + + unset($Block['interrupted']); + } + + $Block['element']['element']['text'] .= "\n"; + + $text = substr($Line['body'], 4); + + $Block['element']['element']['text'] .= $text; + + return $Block; + } + } + + protected function blockCodeComplete($Block) + { + return $Block; + } + + # + # Comment + + protected function blockComment($Line) + { + if ($this->markupEscaped or $this->safeMode) + { + return; + } + + if (strpos($Line['text'], '<!--') === 0) + { + $Block = array( + 'element' => array( + 'rawHtml' => $Line['body'], + 'autobreak' => true, + ), + ); + + if (strpos($Line['text'], '-->') !== false) + { + $Block['closed'] = true; + } + + return $Block; + } + } + + protected function blockCommentContinue($Line, array $Block) + { + if (isset($Block['closed'])) + { + return; + } + + $Block['element']['rawHtml'] .= "\n" . $Line['body']; + + if (strpos($Line['text'], '-->') !== false) + { + $Block['closed'] = true; + } + + return $Block; + } + + # + # Fenced Code + + protected function blockFencedCode($Line) + { + $marker = $Line['text'][0]; + + $openerLength = strspn($Line['text'], $marker); + + if ($openerLength < 3) + { + return; + } + + $infostring = trim(substr($Line['text'], $openerLength), "\t "); + + if (strpos($infostring, '`') !== false) + { + return; + } + + $Element = array( + 'name' => 'code', + 'text' => '', + ); + + if ($infostring !== '') + { + /** + * https://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes + * Every HTML element may have a class attribute specified. + * The attribute, if specified, must have a value that is a set + * of space-separated tokens representing the various classes + * that the element belongs to. + * [...] + * The space characters, for the purposes of this specification, + * are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), + * U+000A LINE FEED (LF), U+000C FORM FEED (FF), and + * U+000D CARRIAGE RETURN (CR). + */ + $language = substr($infostring, 0, strcspn($infostring, " \t\n\f\r")); + + $Element['attributes'] = array('class' => "language-$language"); + } + + $Block = array( + 'char' => $marker, + 'openerLength' => $openerLength, + 'element' => array( + 'name' => 'pre', + 'element' => $Element, + ), + ); + + return $Block; + } + + protected function blockFencedCodeContinue($Line, $Block) + { + if (isset($Block['complete'])) + { + return; + } + + if (isset($Block['interrupted'])) + { + $Block['element']['element']['text'] .= str_repeat("\n", $Block['interrupted']); + + unset($Block['interrupted']); + } + + if (($len = strspn($Line['text'], $Block['char'])) >= $Block['openerLength'] + and chop(substr($Line['text'], $len), ' ') === '' + ) { + $Block['element']['element']['text'] = substr($Block['element']['element']['text'], 1); + + $Block['complete'] = true; + + return $Block; + } + + $Block['element']['element']['text'] .= "\n" . $Line['body']; + + return $Block; + } + + protected function blockFencedCodeComplete($Block) + { + return $Block; + } + + # + # Header + + protected function blockHeader($Line) + { + $level = strspn($Line['text'], '#'); + + if ($level > 6) + { + return; + } + + $text = trim($Line['text'], '#'); + + if ($this->strictMode and isset($text[0]) and $text[0] !== ' ') + { + return; + } + + $text = trim($text, ' '); + + $Block = array( + 'element' => array( + 'name' => 'h' . $level, + 'handler' => array( + 'function' => 'lineElements', + 'argument' => $text, + 'destination' => 'elements', + ) + ), + ); + + return $Block; + } + + # + # List + + protected function blockList($Line, ?array $CurrentBlock = null) + { + list($name, $pattern) = $Line['text'][0] <= '-' ? array('ul', '[*+-]') : array('ol', '[0-9]{1,9}+[.\)]'); + + if (preg_match('/^('.$pattern.'([ ]++|$))(.*+)/', $Line['text'], $matches)) + { + $contentIndent = strlen($matches[2]); + + if ($contentIndent >= 5) + { + $contentIndent -= 1; + $matches[1] = substr($matches[1], 0, -$contentIndent); + $matches[3] = str_repeat(' ', $contentIndent) . $matches[3]; + } + elseif ($contentIndent === 0) + { + $matches[1] .= ' '; + } + + $markerWithoutWhitespace = strstr($matches[1], ' ', true); + + $Block = array( + 'indent' => $Line['indent'], + 'pattern' => $pattern, + 'data' => array( + 'type' => $name, + 'marker' => $matches[1], + 'markerType' => ($name === 'ul' ? $markerWithoutWhitespace : substr($markerWithoutWhitespace, -1)), + ), + 'element' => array( + 'name' => $name, + 'elements' => array(), + ), + ); + $Block['data']['markerTypeRegex'] = preg_quote($Block['data']['markerType'], '/'); + + if ($name === 'ol') + { + $listStart = ltrim(strstr($matches[1], $Block['data']['markerType'], true), '0') ?: '0'; + + if ($listStart !== '1') + { + if ( + isset($CurrentBlock) + and $CurrentBlock['type'] === 'Paragraph' + and ! isset($CurrentBlock['interrupted']) + ) { + return; + } + + $Block['element']['attributes'] = array('start' => $listStart); + } + } + + $Block['li'] = array( + 'name' => 'li', + 'handler' => array( + 'function' => 'li', + 'argument' => !empty($matches[3]) ? array($matches[3]) : array(), + 'destination' => 'elements' + ) + ); + + $Block['element']['elements'] []= & $Block['li']; + + return $Block; + } + } + + protected function blockListContinue($Line, array $Block) + { + if (isset($Block['interrupted']) and empty($Block['li']['handler']['argument'])) + { + return null; + } + + $requiredIndent = ($Block['indent'] + strlen($Block['data']['marker'])); + + if ($Line['indent'] < $requiredIndent + and ( + ( + $Block['data']['type'] === 'ol' + and preg_match('/^[0-9]++'.$Block['data']['markerTypeRegex'].'(?:[ ]++(.*)|$)/', $Line['text'], $matches) + ) or ( + $Block['data']['type'] === 'ul' + and preg_match('/^'.$Block['data']['markerTypeRegex'].'(?:[ ]++(.*)|$)/', $Line['text'], $matches) + ) + ) + ) { + if (isset($Block['interrupted'])) + { + $Block['li']['handler']['argument'] []= ''; + + $Block['loose'] = true; + + unset($Block['interrupted']); + } + + unset($Block['li']); + + $text = isset($matches[1]) ? $matches[1] : ''; + + $Block['indent'] = $Line['indent']; + + $Block['li'] = array( + 'name' => 'li', + 'handler' => array( + 'function' => 'li', + 'argument' => array($text), + 'destination' => 'elements' + ) + ); + + $Block['element']['elements'] []= & $Block['li']; + + return $Block; + } + elseif ($Line['indent'] < $requiredIndent and $this->blockList($Line)) + { + return null; + } + + if ($Line['text'][0] === '[' and $this->blockReference($Line)) + { + return $Block; + } + + if ($Line['indent'] >= $requiredIndent) + { + if (isset($Block['interrupted'])) + { + $Block['li']['handler']['argument'] []= ''; + + $Block['loose'] = true; + + unset($Block['interrupted']); + } + + $text = substr($Line['body'], $requiredIndent); + + $Block['li']['handler']['argument'] []= $text; + + return $Block; + } + + if ( ! isset($Block['interrupted'])) + { + $text = preg_replace('/^[ ]{0,'.$requiredIndent.'}+/', '', $Line['body']); + + $Block['li']['handler']['argument'] []= $text; + + return $Block; + } + } + + protected function blockListComplete(array $Block) + { + if (isset($Block['loose'])) + { + foreach ($Block['element']['elements'] as &$li) + { + if (end($li['handler']['argument']) !== '') + { + $li['handler']['argument'] []= ''; + } + } + } + + return $Block; + } + + # + # Quote + + protected function blockQuote($Line) + { + if (preg_match('/^>[ ]?+(.*+)/', $Line['text'], $matches)) + { + $Block = array( + 'element' => array( + 'name' => 'blockquote', + 'handler' => array( + 'function' => 'linesElements', + 'argument' => (array) $matches[1], + 'destination' => 'elements', + ) + ), + ); + + return $Block; + } + } + + protected function blockQuoteContinue($Line, array $Block) + { + if (isset($Block['interrupted'])) + { + return; + } + + if ($Line['text'][0] === '>' and preg_match('/^>[ ]?+(.*+)/', $Line['text'], $matches)) + { + $Block['element']['handler']['argument'] []= $matches[1]; + + return $Block; + } + + if ( ! isset($Block['interrupted'])) + { + $Block['element']['handler']['argument'] []= $Line['text']; + + return $Block; + } + } + + # + # Rule + + protected function blockRule($Line) + { + $marker = $Line['text'][0]; + + if (substr_count($Line['text'], $marker) >= 3 and chop($Line['text'], " $marker") === '') + { + $Block = array( + 'element' => array( + 'name' => 'hr', + ), + ); + + return $Block; + } + } + + # + # Setext + + protected function blockSetextHeader($Line, ?array $Block = null) + { + if ( ! isset($Block) or $Block['type'] !== 'Paragraph' or isset($Block['interrupted'])) + { + return; + } + + if ($Line['indent'] < 4 and chop(chop($Line['text'], ' '), $Line['text'][0]) === '') + { + $Block['element']['name'] = $Line['text'][0] === '=' ? 'h1' : 'h2'; + + return $Block; + } + } + + # + # Markup + + protected function blockMarkup($Line) + { + if ($this->markupEscaped or $this->safeMode) + { + return; + } + + if (preg_match('/^<[\/]?+(\w*)(?:[ ]*+'.$this->regexHtmlAttribute.')*+[ ]*+(\/)?>/', $Line['text'], $matches)) + { + $element = strtolower($matches[1]); + + if (in_array($element, $this->textLevelElements)) + { + return; + } + + $Block = array( + 'name' => $matches[1], + 'element' => array( + 'rawHtml' => $Line['text'], + 'autobreak' => true, + ), + ); + + return $Block; + } + } + + protected function blockMarkupContinue($Line, array $Block) + { + if (isset($Block['closed']) or isset($Block['interrupted'])) + { + return; + } + + $Block['element']['rawHtml'] .= "\n" . $Line['body']; + + return $Block; + } + + # + # Reference + + protected function blockReference($Line) + { + if (strpos($Line['text'], ']') !== false + and preg_match('/^\[(.+?)\]:[ ]*+<?(\S+?)>?(?:[ ]+["\'(](.+)["\')])?[ ]*+$/', $Line['text'], $matches) + ) { + $id = strtolower($matches[1]); + + $Data = array( + 'url' => $matches[2], + 'title' => isset($matches[3]) ? $matches[3] : null, + ); + + $this->DefinitionData['Reference'][$id] = $Data; + + $Block = array( + 'element' => array(), + ); + + return $Block; + } + } + + # + # Table + + protected function blockTable($Line, ?array $Block = null) + { + if ( ! isset($Block) or $Block['type'] !== 'Paragraph' or isset($Block['interrupted'])) + { + return; + } + + if ( + strpos($Block['element']['handler']['argument'], '|') === false + and strpos($Line['text'], '|') === false + and strpos($Line['text'], ':') === false + or strpos($Block['element']['handler']['argument'], "\n") !== false + ) { + return; + } + + if (chop($Line['text'], ' -:|') !== '') + { + return; + } + + $alignments = array(); + + $divider = $Line['text']; + + $divider = trim($divider); + $divider = trim($divider, '|'); + + $dividerCells = explode('|', $divider); + + foreach ($dividerCells as $dividerCell) + { + $dividerCell = trim($dividerCell); + + if ($dividerCell === '') + { + return; + } + + $alignment = null; + + if ($dividerCell[0] === ':') + { + $alignment = 'left'; + } + + if (substr($dividerCell, - 1) === ':') + { + $alignment = $alignment === 'left' ? 'center' : 'right'; + } + + $alignments []= $alignment; + } + + # ~ + + $HeaderElements = array(); + + $header = $Block['element']['handler']['argument']; + + $header = trim($header); + $header = trim($header, '|'); + + $headerCells = explode('|', $header); + + if (count($headerCells) !== count($alignments)) + { + return; + } + + foreach ($headerCells as $index => $headerCell) + { + $headerCell = trim($headerCell); + + $HeaderElement = array( + 'name' => 'th', + 'handler' => array( + 'function' => 'lineElements', + 'argument' => $headerCell, + 'destination' => 'elements', + ) + ); + + if (isset($alignments[$index])) + { + $alignment = $alignments[$index]; + + $HeaderElement['attributes'] = array( + 'style' => "text-align: $alignment;", + ); + } + + $HeaderElements []= $HeaderElement; + } + + # ~ + + $Block = array( + 'alignments' => $alignments, + 'identified' => true, + 'element' => array( + 'name' => 'table', + 'elements' => array(), + ), + ); + + $Block['element']['elements'] []= array( + 'name' => 'thead', + ); + + $Block['element']['elements'] []= array( + 'name' => 'tbody', + 'elements' => array(), + ); + + $Block['element']['elements'][0]['elements'] []= array( + 'name' => 'tr', + 'elements' => $HeaderElements, + ); + + return $Block; + } + + protected function blockTableContinue($Line, array $Block) + { + if (isset($Block['interrupted'])) + { + return; + } + + if (count($Block['alignments']) === 1 or $Line['text'][0] === '|' or strpos($Line['text'], '|')) + { + $Elements = array(); + + $row = $Line['text']; + + $row = trim($row); + $row = trim($row, '|'); + + preg_match_all('/(?:(\\\\[|])|[^|`]|`[^`]++`|`)++/', $row, $matches); + + $cells = array_slice($matches[0], 0, count($Block['alignments'])); + + foreach ($cells as $index => $cell) + { + $cell = trim($cell); + + $Element = array( + 'name' => 'td', + 'handler' => array( + 'function' => 'lineElements', + 'argument' => $cell, + 'destination' => 'elements', + ) + ); + + if (isset($Block['alignments'][$index])) + { + $Element['attributes'] = array( + 'style' => 'text-align: ' . $Block['alignments'][$index] . ';', + ); + } + + $Elements []= $Element; + } + + $Element = array( + 'name' => 'tr', + 'elements' => $Elements, + ); + + $Block['element']['elements'][1]['elements'] []= $Element; + + return $Block; + } + } + + # + # ~ + # + + protected function paragraph($Line) + { + return array( + 'type' => 'Paragraph', + 'element' => array( + 'name' => 'p', + 'handler' => array( + 'function' => 'lineElements', + 'argument' => $Line['text'], + 'destination' => 'elements', + ), + ), + ); + } + + protected function paragraphContinue($Line, array $Block) + { + if (isset($Block['interrupted'])) + { + return; + } + + $Block['element']['handler']['argument'] .= "\n".$Line['text']; + + return $Block; + } + + # + # Inline Elements + # + + protected $InlineTypes = array( + '!' => array('Image'), + '&' => array('SpecialCharacter'), + '*' => array('Emphasis'), + ':' => array('Url'), + '<' => array('UrlTag', 'EmailTag', 'Markup'), + '[' => array('Link'), + '_' => array('Emphasis'), + '`' => array('Code'), + '~' => array('Strikethrough'), + '\\' => array('EscapeSequence'), + ); + + # ~ + + protected $inlineMarkerList = '!*_&[:<`~\\'; + + # + # ~ + # + + public function line($text, $nonNestables = array()) + { + return $this->elements($this->lineElements($text, $nonNestables)); + } + + protected function lineElements($text, $nonNestables = array()) + { + # standardize line breaks + $text = str_replace(array("\r\n", "\r"), "\n", $text); + + $Elements = array(); + + $nonNestables = (empty($nonNestables) + ? array() + : array_combine($nonNestables, $nonNestables) + ); + + # $excerpt is based on the first occurrence of a marker + + while ($excerpt = strpbrk($text, $this->inlineMarkerList)) + { + $marker = $excerpt[0]; + + $markerPosition = strlen($text) - strlen($excerpt); + + $Excerpt = array('text' => $excerpt, 'context' => $text); + + foreach ($this->InlineTypes[$marker] as $inlineType) + { + # check to see if the current inline type is nestable in the current context + + if (isset($nonNestables[$inlineType])) + { + continue; + } + + $Inline = $this->{"inline$inlineType"}($Excerpt); + + if ( ! isset($Inline)) + { + continue; + } + + # makes sure that the inline belongs to "our" marker + + if (isset($Inline['position']) and $Inline['position'] > $markerPosition) + { + continue; + } + + # sets a default inline position + + if ( ! isset($Inline['position'])) + { + $Inline['position'] = $markerPosition; + } + + # cause the new element to 'inherit' our non nestables + + + $Inline['element']['nonNestables'] = isset($Inline['element']['nonNestables']) + ? array_merge($Inline['element']['nonNestables'], $nonNestables) + : $nonNestables + ; + + # the text that comes before the inline + $unmarkedText = substr($text, 0, $Inline['position']); + + # compile the unmarked text + $InlineText = $this->inlineText($unmarkedText); + $Elements[] = $InlineText['element']; + + # compile the inline + $Elements[] = $this->extractElement($Inline); + + # remove the examined text + $text = substr($text, $Inline['position'] + $Inline['extent']); + + continue 2; + } + + # the marker does not belong to an inline + + $unmarkedText = substr($text, 0, $markerPosition + 1); + + $InlineText = $this->inlineText($unmarkedText); + $Elements[] = $InlineText['element']; + + $text = substr($text, $markerPosition + 1); + } + + $InlineText = $this->inlineText($text); + $Elements[] = $InlineText['element']; + + foreach ($Elements as &$Element) + { + if ( ! isset($Element['autobreak'])) + { + $Element['autobreak'] = false; + } + } + + return $Elements; + } + + # + # ~ + # + + protected function inlineText($text) + { + $Inline = array( + 'extent' => strlen($text), + 'element' => array(), + ); + + $Inline['element']['elements'] = self::pregReplaceElements( + $this->breaksEnabled ? '/[ ]*+\n/' : '/(?:[ ]*+\\\\|[ ]{2,}+)\n/', + array( + array('name' => 'br'), + array('text' => "\n"), + ), + $text + ); + + return $Inline; + } + + protected function inlineCode($Excerpt) + { + $marker = $Excerpt['text'][0]; + + if (preg_match('/^(['.$marker.']++)[ ]*+(.+?)[ ]*+(?<!['.$marker.'])\1(?!'.$marker.')/s', $Excerpt['text'], $matches)) + { + $text = $matches[2]; + $text = preg_replace('/[ ]*+\n/', ' ', $text); + + return array( + 'extent' => strlen($matches[0]), + 'element' => array( + 'name' => 'code', + 'text' => $text, + ), + ); + } + } + + protected function inlineEmailTag($Excerpt) + { + $hostnameLabel = '[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?'; + + $commonMarkEmail = '[a-zA-Z0-9.!#$%&\'*+\/=?^_`{|}~-]++@' + . $hostnameLabel . '(?:\.' . $hostnameLabel . ')*'; + + if (strpos($Excerpt['text'], '>') !== false + and preg_match("/^<((mailto:)?$commonMarkEmail)>/i", $Excerpt['text'], $matches) + ){ + $url = $matches[1]; + + if ( ! isset($matches[2])) + { + $url = "mailto:$url"; + } + + return array( + 'extent' => strlen($matches[0]), + 'element' => array( + 'name' => 'a', + 'text' => $matches[1], + 'attributes' => array( + 'href' => $url, + ), + ), + ); + } + } + + protected function inlineEmphasis($Excerpt) + { + if ( ! isset($Excerpt['text'][1])) + { + return; + } + + $marker = $Excerpt['text'][0]; + + if ($Excerpt['text'][1] === $marker and preg_match($this->StrongRegex[$marker], $Excerpt['text'], $matches)) + { + $emphasis = 'strong'; + } + elseif (preg_match($this->EmRegex[$marker], $Excerpt['text'], $matches)) + { + $emphasis = 'em'; + } + else + { + return; + } + + return array( + 'extent' => strlen($matches[0]), + 'element' => array( + 'name' => $emphasis, + 'handler' => array( + 'function' => 'lineElements', + 'argument' => $matches[1], + 'destination' => 'elements', + ) + ), + ); + } + + protected function inlineEscapeSequence($Excerpt) + { + if (isset($Excerpt['text'][1]) and in_array($Excerpt['text'][1], $this->specialCharacters)) + { + return array( + 'element' => array('rawHtml' => $Excerpt['text'][1]), + 'extent' => 2, + ); + } + } + + protected function inlineImage($Excerpt) + { + if ( ! isset($Excerpt['text'][1]) or $Excerpt['text'][1] !== '[') + { + return; + } + + $Excerpt['text']= substr($Excerpt['text'], 1); + + $Link = $this->inlineLink($Excerpt); + + if ($Link === null) + { + return; + } + + $Inline = array( + 'extent' => $Link['extent'] + 1, + 'element' => array( + 'name' => 'img', + 'attributes' => array( + 'src' => $Link['element']['attributes']['href'], + 'alt' => $Link['element']['handler']['argument'], + ), + 'autobreak' => true, + ), + ); + + $Inline['element']['attributes'] += $Link['element']['attributes']; + + unset($Inline['element']['attributes']['href']); + + return $Inline; + } + + protected function inlineLink($Excerpt) + { + $Element = array( + 'name' => 'a', + 'handler' => array( + 'function' => 'lineElements', + 'argument' => null, + 'destination' => 'elements', + ), + 'nonNestables' => array('Url', 'Link'), + 'attributes' => array( + 'href' => null, + 'title' => null, + ), + ); + + $extent = 0; + + $remainder = $Excerpt['text']; + + if (preg_match('/\[((?:[^][]++|(?R))*+)\]/', $remainder, $matches)) + { + $Element['handler']['argument'] = $matches[1]; + + $extent += strlen($matches[0]); + + $remainder = substr($remainder, $extent); + } + else + { + return; + } + + if (preg_match('/^[(]\s*+((?:[^ ()]++|[(][^ )]+[)])++)(?:[ ]+("[^"]*+"|\'[^\']*+\'))?\s*+[)]/', $remainder, $matches)) + { + $Element['attributes']['href'] = $matches[1]; + + if (isset($matches[2])) + { + $Element['attributes']['title'] = substr($matches[2], 1, - 1); + } + + $extent += strlen($matches[0]); + } + else + { + if (preg_match('/^\s*\[(.*?)\]/', $remainder, $matches)) + { + $definition = strlen($matches[1]) ? $matches[1] : $Element['handler']['argument']; + $definition = strtolower($definition); + + $extent += strlen($matches[0]); + } + else + { + $definition = strtolower($Element['handler']['argument']); + } + + if ( ! isset($this->DefinitionData['Reference'][$definition])) + { + return; + } + + $Definition = $this->DefinitionData['Reference'][$definition]; + + $Element['attributes']['href'] = $Definition['url']; + $Element['attributes']['title'] = $Definition['title']; + } + + return array( + 'extent' => $extent, + 'element' => $Element, + ); + } + + protected function inlineMarkup($Excerpt) + { + if ($this->markupEscaped or $this->safeMode or strpos($Excerpt['text'], '>') === false) + { + return; + } + + if ($Excerpt['text'][1] === '/' and preg_match('/^<\/\w[\w-]*+[ ]*+>/s', $Excerpt['text'], $matches)) + { + return array( + 'element' => array('rawHtml' => $matches[0]), + 'extent' => strlen($matches[0]), + ); + } + + if ($Excerpt['text'][1] === '!' and preg_match('/^<!---?[^>-](?:-?+[^-])*-->/s', $Excerpt['text'], $matches)) + { + return array( + 'element' => array('rawHtml' => $matches[0]), + 'extent' => strlen($matches[0]), + ); + } + + if ($Excerpt['text'][1] !== ' ' and preg_match('/^<\w[\w-]*+(?:[ ]*+'.$this->regexHtmlAttribute.')*+[ ]*+\/?>/s', $Excerpt['text'], $matches)) + { + return array( + 'element' => array('rawHtml' => $matches[0]), + 'extent' => strlen($matches[0]), + ); + } + } + + protected function inlineSpecialCharacter($Excerpt) + { + if (substr($Excerpt['text'], 1, 1) !== ' ' and strpos($Excerpt['text'], ';') !== false + and preg_match('/^&(#?+[0-9a-zA-Z]++);/', $Excerpt['text'], $matches) + ) { + return array( + 'element' => array('rawHtml' => '&' . $matches[1] . ';'), + 'extent' => strlen($matches[0]), + ); + } + + return; + } + + protected function inlineStrikethrough($Excerpt) + { + if ( ! isset($Excerpt['text'][1])) + { + return; + } + + if ($Excerpt['text'][1] === '~' and preg_match('/^~~(?=\S)(.+?)(?<=\S)~~/', $Excerpt['text'], $matches)) + { + return array( + 'extent' => strlen($matches[0]), + 'element' => array( + 'name' => 'del', + 'handler' => array( + 'function' => 'lineElements', + 'argument' => $matches[1], + 'destination' => 'elements', + ) + ), + ); + } + } + + protected function inlineUrl($Excerpt) + { + if ($this->urlsLinked !== true or ! isset($Excerpt['text'][2]) or $Excerpt['text'][2] !== '/') + { + return; + } + + if (strpos($Excerpt['context'], 'http') !== false + and preg_match('/\bhttps?+:[\/]{2}[^\s<]+\b\/*+/ui', $Excerpt['context'], $matches, PREG_OFFSET_CAPTURE) + ) { + $url = $matches[0][0]; + + $Inline = array( + 'extent' => strlen($matches[0][0]), + 'position' => $matches[0][1], + 'element' => array( + 'name' => 'a', + 'text' => $url, + 'attributes' => array( + 'href' => $url, + ), + ), + ); + + return $Inline; + } + } + + protected function inlineUrlTag($Excerpt) + { + if (strpos($Excerpt['text'], '>') !== false and preg_match('/^<(\w++:\/{2}[^ >]++)>/i', $Excerpt['text'], $matches)) + { + $url = $matches[1]; + + return array( + 'extent' => strlen($matches[0]), + 'element' => array( + 'name' => 'a', + 'text' => $url, + 'attributes' => array( + 'href' => $url, + ), + ), + ); + } + } + + # ~ + + protected function unmarkedText($text) + { + $Inline = $this->inlineText($text); + return $this->element($Inline['element']); + } + + # + # Handlers + # + + protected function handle(array $Element) + { + if (isset($Element['handler'])) + { + if (!isset($Element['nonNestables'])) + { + $Element['nonNestables'] = array(); + } + + if (is_string($Element['handler'])) + { + $function = $Element['handler']; + $argument = $Element['text']; + unset($Element['text']); + $destination = 'rawHtml'; + } + else + { + $function = $Element['handler']['function']; + $argument = $Element['handler']['argument']; + $destination = $Element['handler']['destination']; + } + + $Element[$destination] = $this->{$function}($argument, $Element['nonNestables']); + + if ($destination === 'handler') + { + $Element = $this->handle($Element); + } + + unset($Element['handler']); + } + + return $Element; + } + + protected function handleElementRecursive(array $Element) + { + return $this->elementApplyRecursive(array($this, 'handle'), $Element); + } + + protected function handleElementsRecursive(array $Elements) + { + return $this->elementsApplyRecursive(array($this, 'handle'), $Elements); + } + + protected function elementApplyRecursive($closure, array $Element) + { + $Element = call_user_func($closure, $Element); + + if (isset($Element['elements'])) + { + $Element['elements'] = $this->elementsApplyRecursive($closure, $Element['elements']); + } + elseif (isset($Element['element'])) + { + $Element['element'] = $this->elementApplyRecursive($closure, $Element['element']); + } + + return $Element; + } + + protected function elementApplyRecursiveDepthFirst($closure, array $Element) + { + if (isset($Element['elements'])) + { + $Element['elements'] = $this->elementsApplyRecursiveDepthFirst($closure, $Element['elements']); + } + elseif (isset($Element['element'])) + { + $Element['element'] = $this->elementsApplyRecursiveDepthFirst($closure, $Element['element']); + } + + $Element = call_user_func($closure, $Element); + + return $Element; + } + + protected function elementsApplyRecursive($closure, array $Elements) + { + foreach ($Elements as &$Element) + { + $Element = $this->elementApplyRecursive($closure, $Element); + } + + return $Elements; + } + + protected function elementsApplyRecursiveDepthFirst($closure, array $Elements) + { + foreach ($Elements as &$Element) + { + $Element = $this->elementApplyRecursiveDepthFirst($closure, $Element); + } + + return $Elements; + } + + protected function element(array $Element) + { + if ($this->safeMode) + { + $Element = $this->sanitiseElement($Element); + } + + # identity map if element has no handler + $Element = $this->handle($Element); + + $hasName = isset($Element['name']); + + $markup = ''; + + if ($hasName) + { + $markup .= '<' . $Element['name']; + + if (isset($Element['attributes'])) + { + foreach ($Element['attributes'] as $name => $value) + { + if ($value === null) + { + continue; + } + + $markup .= " $name=\"".self::escape($value).'"'; + } + } + } + + $permitRawHtml = false; + + if (isset($Element['text'])) + { + $text = $Element['text']; + } + // very strongly consider an alternative if you're writing an + // extension + elseif (isset($Element['rawHtml'])) + { + $text = $Element['rawHtml']; + + $allowRawHtmlInSafeMode = isset($Element['allowRawHtmlInSafeMode']) && $Element['allowRawHtmlInSafeMode']; + $permitRawHtml = !$this->safeMode || $allowRawHtmlInSafeMode; + } + + $hasContent = isset($text) || isset($Element['element']) || isset($Element['elements']); + + if ($hasContent) + { + $markup .= $hasName ? '>' : ''; + + if (isset($Element['elements'])) + { + $markup .= $this->elements($Element['elements']); + } + elseif (isset($Element['element'])) + { + $markup .= $this->element($Element['element']); + } + else + { + if (!$permitRawHtml) + { + $markup .= self::escape($text, true); + } + else + { + $markup .= $text; + } + } + + $markup .= $hasName ? '</' . $Element['name'] . '>' : ''; + } + elseif ($hasName) + { + $markup .= ' />'; + } + + return $markup; + } + + protected function elements(array $Elements) + { + $markup = ''; + + $autoBreak = true; + + foreach ($Elements as $Element) + { + if (empty($Element)) + { + continue; + } + + $autoBreakNext = (isset($Element['autobreak']) + ? $Element['autobreak'] : isset($Element['name']) + ); + // (autobreak === false) covers both sides of an element + $autoBreak = !$autoBreak ? $autoBreak : $autoBreakNext; + + $markup .= ($autoBreak ? "\n" : '') . $this->element($Element); + $autoBreak = $autoBreakNext; + } + + $markup .= $autoBreak ? "\n" : ''; + + return $markup; + } + + # ~ + + protected function li($lines) + { + $Elements = $this->linesElements($lines); + + if ( ! in_array('', $lines) + and isset($Elements[0]) and isset($Elements[0]['name']) + and $Elements[0]['name'] === 'p' + ) { + unset($Elements[0]['name']); + } + + return $Elements; + } + + # + # AST Convenience + # + + /** + * Replace occurrences $regexp with $Elements in $text. Return an array of + * elements representing the replacement. + */ + protected static function pregReplaceElements($regexp, $Elements, $text) + { + $newElements = array(); + + while (preg_match($regexp, $text, $matches, PREG_OFFSET_CAPTURE)) + { + $offset = $matches[0][1]; + $before = substr($text, 0, $offset); + $after = substr($text, $offset + strlen($matches[0][0])); + + $newElements[] = array('text' => $before); + + foreach ($Elements as $Element) + { + $newElements[] = $Element; + } + + $text = $after; + } + + $newElements[] = array('text' => $text); + + return $newElements; + } + + # + # Deprecated Methods + # + + function parse($text) + { + $markup = $this->text($text); + + return $markup; + } + + protected function sanitiseElement(array $Element) + { + static $goodAttribute = '/^[a-zA-Z0-9][a-zA-Z0-9-_]*+$/'; + static $safeUrlNameToAtt = array( + 'a' => 'href', + 'img' => 'src', + ); + + if ( ! isset($Element['name'])) + { + unset($Element['attributes']); + return $Element; + } + + if (isset($safeUrlNameToAtt[$Element['name']])) + { + $Element = $this->filterUnsafeUrlInAttribute($Element, $safeUrlNameToAtt[$Element['name']]); + } + + if ( ! empty($Element['attributes'])) + { + foreach ($Element['attributes'] as $att => $val) + { + # filter out badly parsed attribute + if ( ! preg_match($goodAttribute, $att)) + { + unset($Element['attributes'][$att]); + } + # dump onevent attribute + elseif (self::striAtStart($att, 'on')) + { + unset($Element['attributes'][$att]); + } + } + } + + return $Element; + } + + protected function filterUnsafeUrlInAttribute(array $Element, $attribute) + { + foreach ($this->safeLinksWhitelist as $scheme) + { + if (self::striAtStart($Element['attributes'][$attribute], $scheme)) + { + return $Element; + } + } + + $Element['attributes'][$attribute] = str_replace(':', '%3A', $Element['attributes'][$attribute]); + + return $Element; + } + + # + # Static Methods + # + + protected static function escape($text, $allowQuotes = false) + { + return htmlspecialchars($text, $allowQuotes ? ENT_NOQUOTES : ENT_QUOTES, 'UTF-8'); + } + + protected static function striAtStart($string, $needle) + { + $len = strlen($needle); + + if ($len > strlen($string)) + { + return false; + } + else + { + return strtolower(substr($string, 0, $len)) === strtolower($needle); + } + } + + static function instance($name = 'default') + { + if (isset(self::$instances[$name])) + { + return self::$instances[$name]; + } + + $instance = new static(); + + self::$instances[$name] = $instance; + + return $instance; + } + + private static $instances = array(); + + # + # Fields + # + + protected $DefinitionData; + + # + # Read-Only + + protected $specialCharacters = array( + '\\', '`', '*', '_', '{', '}', '[', ']', '(', ')', '>', '#', '+', '-', '.', '!', '|', '~' + ); + + protected $StrongRegex = array( + '*' => '/^[*]{2}((?:\\\\\*|[^*]|[*][^*]*+[*])+?)[*]{2}(?![*])/s', + '_' => '/^__((?:\\\\_|[^_]|_[^_]*+_)+?)__(?!_)/us', + ); + + protected $EmRegex = array( + '*' => '/^[*]((?:\\\\\*|[^*]|[*][*][^*]+?[*][*])+?)[*](?![*])/s', + '_' => '/^_((?:\\\\_|[^_]|__[^_]*__)+?)_(?!_)\b/us', + ); + + protected $regexHtmlAttribute = '[a-zA-Z_:][\w:.-]*+(?:\s*+=\s*+(?:[^"\'=<>`\s]+|"[^"]*+"|\'[^\']*+\'))?+'; + + protected $voidElements = array( + 'area', 'base', 'br', 'col', 'command', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', + ); + + protected $textLevelElements = array( + 'a', 'br', 'bdo', 'abbr', 'blink', 'nextid', 'acronym', 'basefont', + 'b', 'em', 'big', 'cite', 'small', 'spacer', 'listing', + 'i', 'rp', 'del', 'code', 'strike', 'marquee', + 'q', 'rt', 'ins', 'font', 'strong', + 's', 'tt', 'kbd', 'mark', + 'u', 'xm', 'sub', 'nobr', + 'sup', 'ruby', + 'var', 'span', + 'wbr', 'time', + ); +} diff --git a/includes/footer.php b/includes/footer.php new file mode 100644 index 000000000..5ad6fd7d4 --- /dev/null +++ b/includes/footer.php @@ -0,0 +1,14 @@ +<?php +// footer.php +?> + <div class="mobile-nav-toggle" id="sidebar-toggle"> + <svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" fill="none" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> + <line x1="3" y1="12" x2="21" y2="12"></line> + <line x1="3" y1="6" x2="21" y2="6"></line> + <line x1="3" y1="18" x2="21" y2="18"></line> + </svg> + </div> +</div> <!-- #app --> +<script src="assets/js/app.js"></script> +</body> +</html> diff --git a/includes/header.php b/includes/header.php new file mode 100644 index 000000000..819fba384 --- /dev/null +++ b/includes/header.php @@ -0,0 +1,21 @@ +<?php +// header.php +// $is_home should be inherited from index.php +if (!isset($is_home)) { + $is_home = (!isset($_GET['p']) || $_GET['p'] === 'home'); +} +?> +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>MySQLTuner | The Gold Standard Database Tuning Advisor + + + + + + + +
diff --git a/includes/sidebar.php b/includes/sidebar.php new file mode 100644 index 000000000..281f466ed --- /dev/null +++ b/includes/sidebar.php @@ -0,0 +1,49 @@ + + diff --git a/index.html b/index.html deleted file mode 100644 index dad79f6b3..000000000 --- a/index.html +++ /dev/null @@ -1,182 +0,0 @@ - - - - - - MySQLTuner-perl by major - - - - - - - -
-
-

MySQLTuner-perl

-

MySQLTuner is a script written in Perl that will assist you with your MySQL configuration and make recommendations for increased performance and stability.

- -

View the Project on GitHub major/MySQLTuner-perl

- - - - -
-
-

-MySQLTuner-perl

- -

MySQLTuner is a script written in Perl that allows you to review a MySQL installation quickly and make adjustments to increase performance and stability. The current configuration variables and status data is retrieved and presented in a brief format along with some basic performance suggestions.

- -mysqltuner -

Compatibility:

- -
    - -
  • MySQL 3.23, 4.0, 4.1, 5.0, 5.1, 5.5, 5.6, 5.7 (full support)
    • -
  • MariaDB 5.5, 10.0, 10.1 (full support)
    • -
  • MySQL 3.23, 4.0, 4.1, 5.0, 5.1 (deprecated editor support)
    • -
  • Perl 5.6 or later (with perl-doc package)
    • -
  • Unix/Linux based operating system (tested on Linux, BSD variants, and Solaris variants)
    • -
  • Windows is not supported at this time
    • -
  • Unrestricted read access to the MySQL server (OS root access recommended for MySQL < 5.0)
    • -

-WARNING -

- -

It is extremely important for you to fully understand each change -you make to a MySQL database server. If you don't understand portions -of the script's output, or if you don't understand the recommendations, -you should consult a knowledgeable DBA or system administrator -that you trust. Always test your changes on staging environments, and -always keep in mind that improvements in one area can negatively affect -MySQL in other areas.

- -

Seriously - please review the FAQ section below.

- -

Checks performed by MySQLTuner

-

-All checks done by MySQLTuner are documented in MySQLTuner Internals documentation. -

- -

-Download/Installation

- -

You can download the entire repository by using 'git clone' followed by the cloning URL above. The simplest and shortest method is:

- -
wget http://mysqltuner.pl/ -O mysqltuner.pl
-wget https://raw.githubusercontent.com/major/MySQLTuner-perl/master/basic_passwords.txt -O basic_passwords.txt
-perl mysqltuner.pl
-
- -

Of course, you can add the execute bit (chmod +x mysqltuner.pl) so you can execute it without calling perl directly.

- - -

Specific usage

- -

Usage: Minimal usage locally

- -
perl mysqltuner.pl 
-
- -

Usage: Minimal usage remotely

- -
perl mysqltuner.pl --host targetDNS_IP --user admin_user --password admin_password
-
- -

Usage: Enable maximum output information around MySQL/MariaDb without debugging

- -
perl mysqltuner.pl --buffers --dbstat --idxstat
-
- -

Usage: Write your result in a file with information displayed

- -
perl mysqltuner.pl --outputfile /tmp/result_mysqltuner.txt
-
- -

Usage: Write your result in a file without outputting information

- -
perl mysqltuner.pl --silent --outputfile /tmp/result_mysqltuner.txt
-
- -

Usage: Using template model to customize your reporting file based on Text::Template syntax.

- -
perl mysqltuner.pl --silent --reportfile /tmp/result_mysqltuner.txt --template=/tmp/mymodel.tmpl
-
- -

Usage: Enable debugging information

- -
perl mysqltuner.pl --debug
-
- -

-FAQ

- -

Question: Will MySQLTuner fix my slow MySQL server?

- -

No. MySQLTuner is a read only script. It won't write to any configuration files, change the status of any daemons, or call your mother to wish her a happy birthday. It will give you an overview of your server's performance and make some basic recommendations about improvements that you can make after it completes. Make sure you read the warning above prior to following any recommendations.

- -

Question: Can I fire my DBA now?

- -

MySQLTuner will not replace your DBA in any form or fashion. If your DBA constantly takes your parking spot and steals your lunch from the fridge, then you may want to consider it - but that's your call.

- -

Question: Why does MySQLTuner keep asking me the login credentials for MySQL over and over?

- -

The script will try its best to log in via any means possible. It will check for ~/.my.cnf files, Plesk password files, and empty password root logins. If none of those are available, then you'll be prompted for a password. If you'd like the script to run in an automated fashion without user intervention, then create a .my.cnf file in your home directory which contains:

- -
[client]
-user=someusername
-pass=thatuserspassword
-
- -

Once you create it, make sure it's owned by your user and the mode on the file is 0600. This should prevent the prying eyes from getting your database login credentials under normal conditions. If a T-1000 shows up in a LAPD uniform and demands your database credentials, you won't have much of an option.

- -

Question: It's not working on my OS! What gives?!

- -

These kinds of things are bound to happen. Here are the details I need from you in order to research the problem thoroughly:

- -
* OS and OS version
-* Architecture (x86, x86_64, IA64, Commodore 64)
-* Exact MySQL version
-* Where you obtained your MySQL version (OS package, source, etc)
-* The full text of the error
-* A copy of SHOW VARIABLES and SHOW GLOBAL STATUS output (if possible)
-
- -

MySQLTuner-perl needs you

-

MySQLTuner needs contributors for documentation, code and feedbacks..

- - - - -
-
-

This project is maintained by major

-

Hosted on GitHub Pages — Theme by orderedlist

-
-
- - - - - - diff --git a/index.php b/index.php new file mode 100644 index 000000000..e7116ef43 --- /dev/null +++ b/index.php @@ -0,0 +1,179 @@ + 'docs/overview.md', + 'usage' => 'docs/usage.md', + 'internals' => 'docs/internals.md', + 'mysql_support' => 'docs/mysql_support.md', + 'mariadb_support' => 'docs/mariadb_support.md', + 'releases' => 'docs/releases/index.md', + 'faq' => 'docs/faq.md' +]; + +// --- Diagnostic Header (to confirm PHP is active) --- +header('X-Router: MySQLTuner-PHP-Router'); + +$page = $_GET['p'] ?? 'home'; + +// --- Robust Routing (Pretty URLs fallback) --- +$request_uri = $_SERVER['REQUEST_URI'] ?? '/'; +$script_name = $_SERVER['SCRIPT_NAME'] ?? ''; +$script_dir = dirname($script_name); + +// Clean up the path relative to the script's directory +$path = parse_url($request_uri, PHP_URL_PATH); +if (strpos($path, $script_dir) === 0) { + $path = substr($path, strlen($script_dir)); +} +$path = trim($path, '/'); + +// Skip index.php or index.html in path +if ($path === 'index.php' || $path === 'index.html') { + $path = ''; +} + +if ($page === 'home' && !empty($path)) { + // Check if the path directly matches a valid page + if (isset($valid_pages[$path])) { + $page = $path; + } else { + // Handle sub-parts (e.g., /docs/overview) + $parts = explode('/', $path); + $last_part = end($parts); + if (isset($valid_pages[$last_part])) { + $page = $last_part; + } + } +} +$is_home = ($page === 'home'); + +// --- Remote Version Sync --- +$version_file = 'CURRENT_VERSION.txt'; +$remote_version_url = 'https://raw.githubusercontent.com/jmrenouard/MySQLTuner-perl/refs/heads/master/CURRENT_VERSION.txt'; + +// Read local version +$current_version = file_exists($version_file) ? trim(file_get_contents($version_file)) : 'Unknown'; + +// Force refresh if it looks like a placeholder or is too old +$force_refresh = ($current_version === 'Unknown' || $current_version === '1.0.4'); // 1.0.4 seems to be a sticky local placeholder +if ($force_refresh || !file_exists($version_file) || (time() - filemtime($version_file) > 3600)) { + $remote_version = @file_get_contents($remote_version_url); + if ($remote_version) { + $remote_version = trim($remote_version); + if ($remote_version !== $current_version) { + file_put_contents($version_file, $remote_version); + $current_version = $remote_version; + } + } +} + +// Ensure includes have the expected variables +$current_page = $page; + +// --- PHP-level redirect for index.html --- +if (strpos($_SERVER['REQUEST_URI'], '/index.html') !== false) { + header("Location: /", true, 301); + exit; +} + +// Header +include 'includes/header.php'; + +// Sidebar +include 'includes/sidebar.php'; +?> + + +
+ + + +
+
+
+
+ + + +
+
V GA Available
+

+ Database Tuning
Reimagined. +

+

+ The gold standard advisor for MySQL, MariaDB, and Percona. + Gain deep insights with 300+ performance indicators + delivered in a zero-dependency Perl script. +

+ +
+
+ +
+
+
+
⚑
+

300+ Indicators

+

Deep analysis spanning memory allocation, storage engines, security vulnerabilities, and performance schema.

+
+
+
🌐
+

Universal Scope

+

Optimized for everything from Legacy 5.5 to Modern 8.4+, including MariaDB 11.x and Cloud DBs (RDS, Azure, GCP).

+
+
+
πŸ› οΈ
+

Pure Portability

+

Zero external CPAN dependencies. Execute instantly on any server with a base Perl installation.

+
+
+
+ +
+

Β© 2026 MySQLTuner Project. Released under GPLv3.

+
+
+ + +
+
+
+ text(file_get_contents($md_file)); + } else { + echo "

404

Documentation file not found.

"; + } + } else { + echo "

404

Page not found.

"; + } + ?> +
+
+
+ + +
+ + diff --git a/javascripts/scale.fix.js b/javascripts/scale.fix.js deleted file mode 100644 index 87a40ca71..000000000 --- a/javascripts/scale.fix.js +++ /dev/null @@ -1,17 +0,0 @@ -var metas = document.getElementsByTagName('meta'); -var i; -if (navigator.userAgent.match(/iPhone/i)) { - for (i=0; i +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful — thank you! + +Guidelines for bug reports: + +1. **Use the [GitHub issue search]** — check if the issue has already been + reported. + +2. **Check if the bug has already been fixed** — try to reproduce it using the + repository's latest `master` changes. + +3. **Isolate the problem** — ideally create a [reduced test + case](http://css-tricks.com/6263-reduced-test-cases/) and a live example + (perhaps a [fiddle](http://jsfiddle.net)). + +A good bug report shouldn't leave others needing to contact you for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What outcome did you expect, and how did it differ from +what you actually saw? All these details will help people to fix any potential +bugs. + +Example: + +> Short and descriptive example bug report title +> +> A summary of the issue and the browser/OS environment in which it occurs. If +> suitable, include the steps required to reproduce the bug. +> +> 1. This is the first step +> 2. This is the second step +> 3. Further steps, etc. +> +> `` - a link to the reduced test case +> +> Any other information you want to share that is relevant to the issue being +> reported. This might include the lines of code that you have identified as +> causing the bug, and potential solutions (and your opinions on their +> merits). + +**Note:** In an effort to keep open issues to a manageable number, we will close any issues +that do not provide enough information for us to be able to work on a solution. +You will be encouraged to provide the necessary details, after which we will reopen the issue. + + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to *you* to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +Building something great means choosing features carefully especially because it +is much, much easier to add features than it is to take them away. Additions +to MySQLTuner will be evaluated on a combination of scope (how well it fits into the +project), maintenance burden and general usefulness. + +Creating something great often means saying no to seemingly good ideas. Don't +despair if your feature request isn't accepted, take action! Fork the +repository, build your idea and share it with others. We released MySQLTuner under +the MIT License for this purpose precisely. Open source works best when smart +and dedicated people riff off of each others' ideas to make even greater things. + +## New feature request +You can find Enhancement asked by community at [Enhancement issue] + + +## Pull requests + +Good pull requests — patches, improvements, new features — are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. You can solicit +feedback and opinions in an open feature request thread or create a new one. + +Please use the [git flow for pull requests](#git-flow) and follow MySQLTuner's +[code conventions](#code-conventions) before submitting your work. Adhering to +these guidelines is the best way to get your work included in MySQLTuner. + + +#### Git Flow for pull requests + +1. [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the project, clone your fork, + and configure the remotes: + + ```bash + # Clone your fork of the repo into the current directory + git clone git@github.com:/MySQLTuner-perl.git + # Navigate to the newly cloned directory + cd MySQLTuner-perl + # Assign the original repo to a remote called "upstream" + git remote add upstream https://github.com/jmrenouard/MySQLTuner-perl/ + ``` + +2. If you cloned a while ago, get the latest changes from upstream: + + ```bash + git checkout master + git pull upstream master + ``` + +3. Create a new topic branch (off the main project development branch) to + contain your feature, change, or fix: + + ```bash + git checkout -b + ``` + +4. Commit your changes in logical chunks. Please adhere to these [git commit message guidelines] + or your code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/interactive-rebase) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream development branch into your topic branch: + + ```bash + git pull [--rebase] upstream master + ``` + +6. Push your topic branch up to your fork: + + ```bash + git push origin + ``` + +7. [Open a Pull Request] with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owner to +license your work under the [GPLv3 License]. + +Copy of the license is available at [LICENSE] + + +## MySQLTuner Code Conventions + +1. Check code convention using **perltidy** and **perlcritic** +2. Don't manually update the version number in `mysqltuner.pl`. + + +[Enhancement issue]:https://github.com/jmrenouard/MySQLTuner-perl/labels/enhancement +[GitHub issue search]:https://github.com/jmrenouard/MySQLTuner-perl/search?type=Issues +[git commit message guidelines]:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +[Open a Pull Request]:https://help.github.com/articles/using-pull-requests/ +[GPLv3 License]:https://en.wikipedia.org/wiki/GNU_General_Public_License +[LICENSE]:https://github.com/jmrenouard/MySQLTuner-perl/blob/master/LICENSE diff --git a/public/docs/faq.md b/public/docs/faq.md new file mode 100644 index 000000000..804116789 --- /dev/null +++ b/public/docs/faq.md @@ -0,0 +1,154 @@ +# Frequently Asked Questions + +-- + +**Question: What are the prerequisites for running MySQL tuner ?** + +Before running MySQL tuner, you should have the following: + +* A MySQL server installation +* Perl installed on your system +* Administrative access to your MySQL server + +**Question: Can MySQL tuner make changes to my configuration automatically ?** + +**No.**, MySQL tuner only provides recommendations. It does not make any changes to your configuration files automatically. It is up to the user to review the suggestions and implement them as needed. + +**Question: How often should I run MySQL tuner ?** + +It is recommended to run MySQL tuner periodically, especially after significant changes to your MySQL server or its workload. + +For optimal results, run the script after your server has been running for at least 24 hours to gather sufficient performance data. + +**Question: How do I interpret the results from MySQL tuner ?** + +MySQL tuner provides output in the form of suggestions and warnings. + +Review each recommendation and consider implementing the changes in your MySQL configuration file (usually 'my.cnf' or 'my.ini'). + +Be cautious when making changes and always backup your configuration file before making any modifications. + +**Question: Can MySQL tuner cause harm to my database or server ?** + +While MySQL tuner itself will not make any changes to your server, blindly implementing its recommendations without understanding the impact can cause issues. + +Always ensure you understand the implications of each suggestion before applying it to your server. + +**Question: Does MySQL tuner support MariaDB and Percona Server ?** + +Yes, MySQL tuner supports MariaDB and Percona Server since they are derivatives of MySQL and share a similar architecture. The script can analyze and provide recommendations for these systems as well. + +**Question: What should I do if I need help with MySQL tuner or have questions about the recommendations ?** + +If you need help with MySQL tuner or have questions about the recommendations provided by the script, you can consult the MySQL tuner documentation, seek advice from online forums, or consult a MySQL expert. + +Be cautious when implementing changes to ensure the stability and performance of your server. + +**Question: Will MySQLTuner fix my slow MySQL server ?** + +**No.** MySQLTuner is a read only script. It won't write to any configuration files, change the status of any daemons. It will give you an overview of your server's performance and make some basic recommendations for improvements that you can make after it completes. + +**Question: Can I fire my DBA now?** + +**MySQLTuner will not replace your DBA in any form or fashion.** + +If your DBA constantly takes your parking spot and steals your lunch from the fridge, then you may want to consider it - but that's your call. + +Once you create it, make sure it's owned by your user and the mode on the file is 0600. This should prevent the prying eyes from getting your database login credentials under normal conditions. + +**Question: I get "ERROR 1524 (HY000): Plugin 'unix_socket' is not loaded" even with unix_socket=OFF. How to fix?** + +This occurs because the MariaDB client attempts to use the `unix_socket` plugin by default when no user/password is provided. + +* **Solution 1 (Recommended):** Use a `~/.my.cnf` file as described above to provide explicit credentials. +* **Solution 2:** Pass credentials directly: `perl mysqltuner.pl --user root --pass your_password`. + +**Question: How to securely re-enable `unix_socket` authentication?** + +If you decide to use `unix_socket` (which allows the OS `root` user to log in to MariaDB `root` without a password), follow these steps: + +1. Ensure the plugin is enabled in `/etc/my.cnf`: `unix_socket=ON` (or remove `OFF`). +2. In MariaDB, set the authentication plugin for the root user: + + ```sql + ALTER USER 'root'@'localhost' IDENTIFIED VIA unix_socket; + ``` + +3. Verify that the `auth_socket` or `unix_socket` plugin is ACTIVE in `SHOW PLUGINS`. + +**Question: Is there another way to secure credentials on latest MySQL and MariaDB distributions ?** + +You could use mysql_config_editor utilities. + +~~~bash + $ mysql_config_editor set --login-path=client --user=someusername --password --host=localhost + Enter password: ******** +~~~ + +After which, `~/.mylogin.cnf` will be created with the appropriate access. + +To get information about stored credentials, use the following command: + +```bash +$mysql_config_editor print +[client] +user = someusername +password = ***** +host = localhost +``` + +**Question: What's minimum privileges needed by a specific mysqltuner user in database ?** + +```bash + mysql>GRANT SELECT, PROCESS,EXECUTE, REPLICATION CLIENT, + SHOW DATABASES,SHOW VIEW + ON *.* + TO 'mysqltuner'@'localhost' identified by pwd1234; +``` + +**Question: It's not working on my OS! What gives?!** + +These kinds of things are bound to happen. Here are the details I need from you to investigate the issue: + +* OS and OS version +* Architecture (x86, x86_64, IA64, Commodore 64) +* Exact MySQL version +* Where you obtained your MySQL version (OS package, source, etc) +* The full text of the error +* A copy of SHOW VARIABLES and SHOW GLOBAL STATUS output (if possible) + +**Question: How to perform CVE vulnerability checks?** + +* Download vulnerabilities.csv from this repository. +* use option --cvefile to perform CVE checks + +**Question: How to use mysqltuner from a remote host?** +Thanks to [@rolandomysqldba](https://dba.stackexchange.com/users/877/rolandomysqldba) + +* You will still have to connect like a mysql client: + +Connection and Authentication + + --host Connect to a remote host to perform tests (default: localhost) + --socket Use a different socket for a local connection + --port Port to use for connection (default: 3306) + --user Username to use for authentication + --pass Password to use for authentication + --defaults-file defaults file for credentials + +Since you are using a remote host, use parameters to supply values from the OS + + --forcemem Amount of RAM installed in megabytes + --forceswap Amount of swap memory configured in megabytes + +* You may have to contact your remote SysAdmin to ask how much RAM and swap you have + +If the database has too many tables, or very large table, use this: + + --skipsize Don't enumerate tables and their types/sizes (default: on) + (Recommended for servers with many tables) + +**Question: Can I install this project using homebrew on Apple Macintosh?** + +Yes! `brew install mysqltuner` can be used to install this application using [homebrew](https://brew.sh/) on Apple Macintosh. + diff --git a/public/docs/internals.md b/public/docs/internals.md new file mode 100644 index 000000000..479857c92 --- /dev/null +++ b/public/docs/internals.md @@ -0,0 +1,471 @@ +## MySQLTuner Internals + +[!["Buy Us A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/jmrenouard) + +## Table of contents + +- [MySQLTuner Internals](#mysqltuner-internals) +- [Table of contents](#table-of-contents) +- [MySQLTuner steps](#mysqltuner-steps) +- [MySQLTuner get login information steps](#mysqltuner-get-login-information-steps) +- [MySQLTuner system checks](#mysqltuner-system-checks) +- [MySQLTuner Server version checks](#mysqltuner-server-version-checks) +- [Mysql error log file analysis](#mysql-error-log-file-analysis) +- [MySQL Storage engine general information](#mysql-storage-engine-general-information) +- [MySQLTuner security checks](#mysqltuner-security-checks) +- [MySQLTuner CVE vulnerabilities detection](#mysqltuner-cve-vulnerabilities-detection) +- [MySQLTuner database information](#mysqltuner-database-information) +- [MySQLTuner index information](#mysqltuner-index-information) +- [MySQLTuner Connections information](#mysqltuner-connections-information) +- [MySQLTuner server information](#mysqltuner-server-information) +- [MySQLTuner sort, join and temp table information](#mysqltuner-sort-join-and-temp-table-information) +- [MySQLTuner global buffer information](#mysqltuner-global-buffer-information) +- [MySQLTuner query cache checks](#mysqltuner-query-cache-checks) +- [MySQLTuner memory checks](#mysqltuner-memory-checks) +- [MySQLTuner slow queries checks](#mysqltuner-slow-queries-checks) +- [MySQLTuner replication checks](#mysqltuner-replication-checks) +- [MySQLTuner InnoDB information](#mysqltuner-innodb-information) +- [MySQLTuner AriaDB information](#mysqltuner-ariadb-information) +- [MySQLTuner MyISAM information](#mysqltuner-myisam-information) +- [MySQLTuner Galera information](#mysqltuner-galera-information) +- [MySQLTuner TokuDB information](#mysqltuner-tokudb-information) +- [MySQLTuner XtraDB information](#mysqltuner-xtradb-information) +- [MySQLTuner Connect information](#mysqltuner-connect-information) +- [MySQLTuner Spider information](#mysqltuner-spider-information) +- [MySQLTuner RocksDb information](#mysqltuner-rocksdb-information) +- [MySQLTuner Thread pool information](#mysqltuner-thread-pool-information) +- [MySQLTuner performance schema and sysschema information](#mysqltuner-performance-schema-and-sysschema-information) +- [MySQLTuner Cloud and SSH integration](#mysqltuner-cloud-and-ssh-integration) +- [MySQLTuner Container and Systemd log integration](#mysqltuner-container-and-systemd-log-integration) + +## MySQLTuner steps + +- Header Print +- Validate MySQLTuner version (check for updates) +- Setup Cloud mode (Azure/AWS) and SSH if needed +- Setup OS variables and commands (SSH prefixing) +- Get login information and setup MySQL connection +- Toss variables/status into hashes +- Validate MySQL and MariaDB versions (EOL check) +- Suggest 64-bit upgrade and architecture check +- Analyze mysqld error log file (Local, Docker, Podman, Kubectl, Systemd) +- Show parameters impacting performance during analysis +- Show information about databases (option: --dbstat) +- Show information about tables (option: --tbstat) +- Show information about indexes (option: --idxstat) +- Show information about views, triggers, and routines +- Show information about plugins (option: --plugininfo) +- Show enabled storage engines +- Display some security recommendations +- CVE vulnerabilities detection +- Calculate everything we need +- Print the server stats +- Print MyISAM stats +- Print InnoDB stats +- Print AriaDB stats +- Print Galera cluster stats +- Print replication info +- Print Storage Engine specific stats (TokuDB, RocksDB, Spider, etc.) +- Print Performance Schema stats +- Make recommendations based on stats +- Close reportfile if needed +- Dump result if debug is on + +## MySQLTuner get login information steps + +- Is a login possible? + - Cloud setup (Azure/AWS)? + - SSH prefixing? + - Force socket, pipe, or specific protocol? + - Remote connection? + - _Specifying available RAM/Swap is required_ + - _Automatic detection if SSH is used_ + - SSL CA certificate? + - Got user/pass on command line? + - mysql-quickbackup credentials available? + - Plesk credentials available? + - DirectAdmin credentials available? + - Debian maintenance account credentials available? + - Defaults file or defaults extra file? + - Just try a login + - If working, and .my.cnf isn't there, **WARNING** + - If working, and .my.cnf is there, okay + - Prompt for creds on the console + +## MySQLTuner system checks + +* Check whether more than 2GB RAM present if on 32-bit OS +- Check number of opened ports (warn when more than 9 ports opened) +- Check 80, 8080, 443 and 8443 ports if warning is raised if they are opened +- Check if some banned ports are not opened (option --bannedports separated by comma) +- Check if non kernel and user process except mysqld are not using more than 15% of total physical memory +- Check vm.swapiness +- Check /etc/security/limit.conf +- Check sysctl entries: sunrpc.tcp_slot_entries, vm.swappiness, fs.aio-fs-nr +- Check mount point +- Check Ethernet card +- Check load average + +## MySQLTuner Server version checks + +* EOL MySQL version check +- Currently MySQL < 5.1 are considered EOL +- Using 5.5+ version of MySQL for performance issue (asynchronous IO) + +## Mysql error log file analysis + +* Look for potential current error log file name +- Automatic detection for: + - Docker containers + - Podman containers + - Kubectl/Kubernetes pods + - Systemd journal (journalctl) +- Check permission on error log file +- Check size on error log file (warning if > 32MB) +- Check error and warning on error log file +- Find last start and shutdown on error log file + +## MySQL Storage engine general information + +- Get storage engine counts/stats + - Check for DB engines that are enabled but unused + - Look for fragmented tables + - Look for auto-increments near capacity + - Look for tables with auto-increment with value near max capacity + +## MySQLTuner security checks + +- Is anonymous user present? +- Users without passwords +- Users with username as password +- Users without host restriction +- Weak password check (possibly using cracklib later?) +- Using basic_passwords.txt as password database +- Password list checks can be avoided (option: --skippassword) + +## MySQLTuner CVE vulnerabilities detection + +- option: --cvefile +- Check if your MariaDB or MySQL version contains CVE entries. + +## MySQLTuner database information + +* Performance analysis parameter checks (metadata performance) +- Per database information + * Tables number + - Rows number + - Total size + - Data size + - Percentage of data size + - Index size + - Percentage of index size + - Views number + - Triggers number + - Routines number + - Collation number + - Check that there is only one collation for all tables in database + - Check that there is only one collation for all table columns in database + - Check that there is only one storage engine per user database + +## MySQLTuner index information + +- Top 10 worth selectivity index +- Per index information + - Index Cardinality + - Index Selectivity + - Misc information about index definition + - Misc information about index size + +## MySQLTuner Connections information + +- Highest usage of available connections +- Percentage of used connections (<85%) +- Percentage of aborted connections (<3%) + +## MySQLTuner server information + +- Uptime: whether MySQL started within last 24 hours +- Bytes received and sent +- Number of connections +- Percentage between reads and writes +- Is binary log activated? + - Is GTID mode activated? + +## MySQLTuner sort, join and temp table information + +- Max memory temporary table size allowed. +- Percentage of sort using temporary table (<10%) +- Number of join performed without using indexes (<250) +- Percentage of temporary table written on disk (<25%) +- Thread cache (=4) +- Thread cache hit ratio (>50%) if thread_handling is different of pools-of-threads +- Table cache hit ratio (>2Β°%) +- Table cache definition should be upper that total number of tables or in autoresizing mode +- Percentage of open file and open file limit (<85%) +- Percentage of table locks (<95%) +- Percentage of binlog cache lock (<90%) + +## MySQLTuner global buffer information + +- Key Buffer +- Max Tmp Table +- Per Thread Buffer + - Read Buffer + - Read RND Buffer + - Sort Buffer + - Thread stack + - Join Buffer + - Binlog Cache Buffers size if activated + +## MySQLTuner query cache checks + +- Is Query cache activated? + - Query Cache Buffers + - Query Cache DISABLED, ALL REQUEST or ON DEMAND + - Query Cache Size + - Query cache hit ratio (cache efficiency) + +## MySQLTuner memory checks + +- Get total RAM/swap +- Is there enough memory for max connections reached by MySQL? +- Is there enough memory for max connections allowed by MySQL? +- Max percentage of memory used (<85%) + +## MySQLTuner slow queries checks + +- Percentage of Slow queries (<5%) + +## MySQLTuner replication checks + +- Is server replication configured as slave? +- SQL replication thread running? +- IO replication thread running? +- Replication lag in seconds (Seconds_behind_master) +- Is Slave configured in read only? +- Replication type ROW, MIX, STMT +- Replication Semisync master +- Replication Semisync slave +- XA support activated +- Replication started? + +## MySQLTuner InnoDB information + +- InnoDB Buffer Pool Size + - If possible, innodb_buffer_pool_size should be greater than data and index size for Innodb Table + - Innodb_buffer_pool_size should be around 75% to 80% of the available system memory. +- InnoDB Buffer Pool Instances + - MySQL needs 1 instance per 1Go of Buffer Pool + - innodb_buffer_pool instances = round(innodb_buffer_pool_size / 1Go) + - innodb_buffer_pool instances must be equal to or lower than 64 + + - A bug in MySQL 5.6 causes SHOW VARIABLES to report an innodb_buffer_pool_instances value of 8 when innodb_buffer_pool_size is less than 1GB and only one buffer pool instance is present (Bug #18343670). + +- InnoDB Buffer Pool Usage + - If more than 20% of InnoDB buffer pool is not used, raise an alert. +- InnoDB Buffer Pool Log Size + - InnoDB total log file size should be 25% of innodb_buffer_pool_size +- InnoDB Read efficiency + - Ratio of read without locks +- InnoDB Write efficiency + - Ratio of write without locks +- InnoDB Log Waits + - Checks that no lock is used on Innodb Log. +- InnoDB Chunk Size + - Check InnoDB Buffer Pool size is a multiple of InnoDB Buffer Pool chunk size * InnoDB Buffer Pool instances + +## MySQLTuner AriaDB information + +- Is Aria indexes size greater than page cache size? +- Page cache read hit ratio (>95%) +- Page cache write hit ratio (>95%) + +## MySQLTuner MyISAM information + +- Key buffer usage (>90%) +- Is MyISAM indexes size is greater than key buffer size ? +- Key buffer read hit ratio (>95%) +- Key buffer write hit ratio (>95%) + +## MySQLTuner Galera information + +- wsrep_ready cluster is ready +- wsrep_connected node is connected to other nodes +- wsrep_cluster_name is defined. +- wsrep_node_name is defined. +- Check thet notification script wsrep_notify_cmd is defined +- wsrep_cluster_status PRIMARY /NON PRIMARY. + - PRIMARY : Coherent cluster + - NO PRIMARY : cluster gets several states +- wsrep_local_state_comment: Node state + - SYNCED (uptodate), + - DONOR (sending information to another node) + - Joiner (try to reach cluster group) + - SYNCED state able to read/write +- wsrep_cluster_conf_id configuration level must be identical in all nodes +- wsrep_slave_thread is between 3 or 4 times number of CPU core. +- gcs.limit should be equal to wsrep_slave_threads * 5 +- gcs.fc_factor should be equal to 0.8 +- Flow control fraction should be lower than 0.02 (wsrep_flow_control_paused < 0.02) +- wsrep_last_commited committed level must be identical in all nodes +- Look for tables without primary keys +- Look for non InnoDB tables for Galera +- Variable innodb_flush_log_at_trx_commit should be set to 0. +- Check that there are 3 or 5 members in Galera cluster. +- Check that xtrabackup is used for SST method with wsrep_sst_method variable. +- Check variables wsrep_OSU_method is defined to TOI for updates. +- Check that there is no certification failures controlling wsrep_local_cert_failures status. + +## MySQLTuner TokuDB information + +- tokudb_cache_size +- tokudb_directio +- tokudb_empty_scan +- tokudb_read_block_size +- tokudb_commit_sync +- tokudb_checkpointing_period +- tokudb_block_size +- tokudb_cleaner_iterations +- tokudb_fanout + +## MySQLTuner XtraDB information + +- wsrep_node_name +- wsrep_cluster_name +- wsrep_cluster_address + +## MySQLTuner Connect information + +- connect_type +- connect_user +- connect_host + +## MySQLTuner Spider information + +- spider_nodes +- spider_direct_io + +## MySQLTuner RocksDb information + +- rocksdb_block_cache_size +- rocksdb_max_open_files + +## MySQLTuner Thread pool information + +- thread_pool_size between 16 to 36 for Innodb usage +- thread_pool_size between 4 to 8 for MyISAM usage + +## MySQLTuner performance schema and sysschema information + +- Check that Performance schema is activated for 5.6+ version +- Check that Performance schema is deactivated for 5.5- version +- Check that Sys schema is installed +- Sys Schema version +- Top user per connection +- Top user per statement +- Top user per statement latency +- Top user per lock latency +- Top user per full scans +- Top user per row_sent +- Top user per row modified +- Top user per io +- Top user per io latency +- Top host per connection +- Top host per statement +- Top host per statement latency +- Top host per lock latency +- Top host per full scans +- Top host per rows sent +- Top host per rows modified +- Top host per io +- Top 5 host per io latency +- Top IO type order by total io +- Top IO type order by total latency +- Top IO type order by max latency +- Top Stages order by total io +- Top Stages order by total latency +- Top Stages order by avg latency +- Top host per table scans +- InnoDB Buffer Pool by schema +- InnoDB Buffer Pool by table +- Process per allocated memory +- InnoDB Lock Waits +- Threads IO Latency +- High Cost SQL statements +- Top 5% slower queries +- Top 10 nb statement type +- Top statement by total latency +- Top statement by lock latency +- Top statement by full scans +- Top statement by rows sent +- Top statement by rows modified +- Use temporary tables +- Unused Indexes +- Full table scans +- Latest file IO by latency +- File by IO read bytes +- File by IO written bytes +- File per IO total latency +- File per IO read latency +- File per IO write latency +- Event Wait by read bytes +- Event Wait by write bytes +- Event per wait total latency +- Event per wait read latency +- Event per wait write latency +- Top 15 most read indexes +- Top 15 most modified indexes +- Top 15 high select latency index +- Top 15 high insert latency index +- Top 15 high update latency index +- Top 15 high delete latency index +- Top 15 most read tables +- Top 15 most modified tables +- Top 15 high select latency tables +- Top 15 high insert latency tables +- Top 15 high update latency tables +- Top 15 high delete latency tables +- Redundant indexes +- Tables not using InnoDb buffer +- Top 15 Tables using InnoDb buffer +- Top 15 Tables with InnoDb buffer free +- Top 15 Most executed queries +- Latest SQL queries in errors or warnings +- Top 20 queries with full table scans +- Top 15 reader queries (95% percentile) +- Top 15 row look queries (95% percentile) +- Top 15 total latency queries (95% percentile) +- Top 15 max latency queries (95% percentile) +- Top 15 average latency queries (95% percentile) +- Top 20 queries with sort +- Last 50 queries with sort +- Top 15 row sorting queries with sort +- Top 15 total latency queries with sort +- Top 15 merge queries with sort +- Top 15 average sort merges queries with sort +- Top 15 scans queries with sort +- Top 15 range queries with sort +- Top 20 queries with temp table +- Last 50 queries with temp table +- Top 15 total latency queries with temp table +- Top 15 queries with temp table to disk +- Top 15 class events by number +- Top 30 events by number +- Top 15 class events by total latency +- Top 30 events by total latency +- Top 15 class events by max latency +- Top 30 events by max latency + +## MySQLTuner Cloud and SSH integration + +- **Cloud mode**: Activated with `--cloud` or `--azure`. +- **SSH Support**: Allows running system commands on a remote host via SSH. +- **SSH Authentication**: Supports identity files (`--ssh-identity-file`) and passwords (`--ssh-password` using `sshpass`). +- **Remote Resource Detection**: Automatically detects RAM and Swap on the remote host if SSH is used. + +## MySQLTuner Container and Systemd log integration + +- **Docker/Podman**: Automatically detects logs from the most relevant database container based on ports and names. +- **Kubectl**: Supports retrieving logs from Kubernetes pods. +- **Systemd**: Supports retrieving logs from the systemd journal using `journalctl`. +- **Explicit Container**: Can be specified using `--container :`. diff --git a/public/docs/mariadb_support.md b/public/docs/mariadb_support.md new file mode 100644 index 000000000..22f54350b --- /dev/null +++ b/public/docs/mariadb_support.md @@ -0,0 +1,30 @@ +# Version Support for mariadb + +| Version | End of Support Date | LTS | Status | +|---------|------------------------|-----|--------| +| 12.0 | 2025-11-18 | NO | Outdated | +| 11.8 | 2028-06-04 | YES | Supported | +| 11.7 | 2025-05-12 | NO | Outdated | +| 11.6 | 2025-02-13 | NO | Outdated | +| 11.5 | 2024-11-21 | NO | Outdated | +| 11.4 | 2029-05-29 | YES | Supported | +| 11.3 | 2024-05-29 | NO | Outdated | +| 11.2 | 2024-11-21 | NO | Outdated | +| 11.1 | 2024-08-21 | NO | Outdated | +| 11.0 | 2024-06-06 | NO | Outdated | +| 10.11 | 2028-02-16 | YES | Supported | +| 10.10 | 2023-11-17 | NO | Outdated | +| 10.9 | 2023-08-22 | NO | Outdated | +| 10.8 | 2023-05-20 | NO | Outdated | +| 10.7 | 2023-02-09 | NO | Outdated | +| 10.6 | 2026-07-06 | YES | Supported | +| 10.5 | 2025-06-24 | YES | Outdated | +| 10.4 | 2024-06-18 | YES | Outdated | +| 10.3 | 2023-05-25 | NO | Outdated | +| 10.2 | 2022-05-23 | NO | Outdated | +| 10.1 | 2020-10-17 | NO | Outdated | +| 10.0 | 2019-03-31 | NO | Outdated | +| 5.5 | 2020-04-11 | YES | Outdated | +| 5.3 | 2017-03-01 | NO | Outdated | +| 5.2 | 2015-11-10 | NO | Outdated | +| 5.1 | 2015-02-01 | NO | Outdated | diff --git a/public/docs/mysql_support.md b/public/docs/mysql_support.md new file mode 100644 index 000000000..c3cee1796 --- /dev/null +++ b/public/docs/mysql_support.md @@ -0,0 +1,18 @@ +# Version Support for mysql + +| Version | End of Support Date | LTS | Status | +|---------|------------------------|-----|--------| +| 9.6 | N/A | NO | Supported | +| 9.4 | 2025-10-21 | NO | Outdated | +| 9.3 | 2025-07-22 | NO | Outdated | +| 9.2 | 2025-04-15 | NO | Outdated | +| 9.1 | 2025-01-21 | NO | Outdated | +| 9.0 | 2024-10-15 | NO | Outdated | +| 8.4 | 2032-04-30 | YES | Supported | +| 8.3 | 2024-04-10 | NO | Outdated | +| 8.2 | 2023-12-14 | NO | Outdated | +| 8.1 | 2023-10-25 | NO | Outdated | +| 8.0 | 2026-04-30 | NO | Supported | +| 5.7 | 2023-10-31 | NO | Outdated | +| 5.6 | 2021-02-28 | NO | Outdated | +| 5.5 | 2018-12-31 | NO | Outdated | diff --git a/public/docs/overview.md b/public/docs/overview.md new file mode 100644 index 000000000..812b15ad1 --- /dev/null +++ b/public/docs/overview.md @@ -0,0 +1,636 @@ +![MySQLTuner-perl](assets/img/mtlogo2.png) + +[!["Buy Us A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/jmrenouard) + +[![Project Status](https://opensource.box.com/badges/active.svg)](https://opensource.box.com/badges) +[![Test Status](https://github.com/anuraghazra/github-readme-stats/workflows/Test/badge.svg)](https://github.com/anuraghazra/github-readme-stats/) +[![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/jmrenouard/MySQLTuner-perl.svg)](https://isitmaintained.com/project/jmrenouard/MySQLTuner-perl "Average time to resolve an issue") +[![Percentage of open issues](https://isitmaintained.com/badge/open/jmrenouard/MySQLTuner-perl.svg)](https://isitmaintained.com/project/jmrenouard/MySQLTuner-perl "Percentage of issues still open") +[![GPL License](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://opensource.org/licenses/GPL-3.0/) + +**MySQLTuner** is a script written in Perl that allows you to review a MySQL installation quickly and make adjustments to increase performance and stability. The current configuration variables and status data is retrieved and presented in a brief format along with some basic performance suggestions. + +**MySQLTuner** supports ~300 indicators for MySQL/MariaDB/Percona Server in this latest version. + +**MySQLTuner** is actively maintained supporting many configurations such as [Galera Cluster](https://galeracluster.com/), [TokuDB](https://www.percona.com/software/mysql-database/percona-tokudb), [Performance schema](https://github.com/mysql/mysql-sys), Linux OS metrics, [InnoDB](https://dev.mysql.com/doc/refman/5.7/en/innodb-storage-engine.html), [MyISAM](https://dev.mysql.com/doc/refman/5.7/en/myisam-storage-engine.html), [Aria](https://mariadb.com/docs/server/server-usage/storage-engines/aria/aria-storage-engine), ... + +You can find more details on these indicators here: +[Indicators description](https://github.com/jmrenouard/MySQLTuner-perl/blob/master/INTERNALS.md). + +![MysqlTuner](https://raw.githubusercontent.com/jmrenouard/MySQLTuner-perl/master/mysqltuner.png) + +Useful Links +== + +* **Active Development:** [https://github.com/jmrenouard/MySQLTuner-perl](https://github.com/jmrenouard/MySQLTuner-perl) +* **Releases/Tags:** [https://github.com/jmrenouard/MySQLTuner-perl/tags](https://github.com/jmrenouard/MySQLTuner-perl/tags) +* **Changelog:** [https://github.com/jmrenouard/MySQLTuner-perl/blob/master/Changelog](https://github.com/jmrenouard/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) + +MySQLTuner needs you +=== + +**MySQLTuner** needs contributors for documentation, code and feedback: + +* Please join us on our issue tracker at [GitHub tracker](https://github.com/jmrenouard/MySQLTuner-perl/issues). +* Contribution guide is available following [MySQLTuner contributing guide](https://github.com/jmrenouard/MySQLTuner-perl/blob/master/CONTRIBUTING.md) +* Star **MySQLTuner project** at [MySQLTuner Git Hub Project](https://github.com/jmrenouard/MySQLTuner-perl/) +* Paid support for LightPath here: [jmrenouard@lightpath.fr](jmrenouard@lightpath.fr) +* Paid support for Releem available here: [Releem App](https://releem.com/) + + + +## Stargazers over time + +[![Stargazers over time](https://starchart.cc/jmrenouard/MySQLTuner-perl.svg)](https://starchart.cc/jmrenouard/MySQLTuner-perl) + +Compatibility +==== + +Test result are available here for LTS only: + +* MySQL (full support) +* Percona Server (full support) +* MariaDB (full support) +* Galera replication (full support) +* Percona XtraDB cluster (full support) +* MySQL Replication (partial support, no test environment) + +Thanks to [endoflife.date](endoflife.date) + +* Refer to [MariaDB Supported versions](https://github.com/jmrenouard/MySQLTuner-perl/blob/master/mariadb_support.md). +* Refer to [MySQL Supported versions](https://github.com/jmrenouard/MySQLTuner-perl/blob/master/mysql_support.md). + +***Windows Support is partial*** + +* Windows is now supported at this time +* Successfully run MySQLtuner across WSL2 (Windows Subsystem Linux) +* [https://docs.microsoft.com/en-us/windows/wsl/](https://docs.microsoft.com/en-us/windows/wsl/) + +***UNSUPPORTED ENVIRONMENTS - NEED HELP WITH THAT*** + +* Cloud based is not supported at this time (Help wanted! GCP, AWS, Azure support requested) + +***Unsupported storage engines: PRs welcome*** +-- + +* NDB is not supported feel free to create a Pull Request +* Archive +* Spider +* ColummStore +* Connect + +Unmaintenained stuff from MySQL or MariaDB +-- + +* MyISAM is too old and no longer active +* RockDB is not maintained anymore +* TokuDB is not maintained anymore +* XtraDB is not maintained anymore + +* CVE vulnerabilities detection support from [https://cve.mitre.org](https://cve.mitre.org) + +***MINIMAL REQUIREMENTS*** + +* Perl 5.6 or later (with [perl-doc](https://metacpan.org/release/DAPM/perl-5.14.4/view/pod/perldoc.pod) package) +* Unix/Linux based operating system (tested on Linux, BSD variants, and Solaris variants) +* Unrestricted read access to the MySQL server +OS root access recommended for MySQL < 5.1 + +***WARNING*** +-- + +It is **important** for you to fully understand each change +you make to a MySQL database server. If you don't understand portions +of the script's output, or if you don't understand the recommendations, +**you should consult** a knowledgeable DBA or system administrator +that you trust. **Always** test your changes on staging environments, and +always keep in mind that improvements in one area can **adversely affect** +MySQL in other areas. + +It's **also important** to wait at least 24 hours of uptime to get accurate results. In fact, running +**mysqltuner** on a fresh restarted server is completely useless. + +**Also review the FAQ section below.** + +Security recommendations +-- + +Hi directadmin user! +We detected that you run mysqltuner with da_admin's credentials taken from `/usr/local/directadmin/conf/my.cnf`, which might bring to a password discovery! +Read link for more details [Issue #289](https://github.com/jmrenouard/MySQLTuner-perl/issues/289). + +What is MySQLTuner checking exactly ? +-- + +All checks done by **MySQLTuner** are documented in [MySQLTuner Internals](https://github.com/jmrenouard/MySQLTuner-perl/blob/master/INTERNALS.md) documentation. + +Download/Installation +-- + +Choose one of these methods: + +1) Script direct download (the simplest and shortest method): + +```bash +wget http://mysqltuner.pl/ -O mysqltuner.pl +wget https://raw.githubusercontent.com/jmrenouard/MySQLTuner-perl/master/basic_passwords.txt -O basic_passwords.txt +wget https://raw.githubusercontent.com/jmrenouard/MySQLTuner-perl/master/vulnerabilities.csv -O vulnerabilities.csv +``` + +1) You can download the entire repository by using `git clone` or `git clone --depth 1 -b master` followed by the cloning URL above. + +Optional Sysschema installation for MySQL 5.6 +-- + +Sysschema is installed by default under MySQL 5.7 and MySQL 8 from Oracle. +By default, on MySQL 5.6/5.7/8, performance schema is enabled. +For previous MySQL 5.6 version, you can follow this command to create a new database sys containing very useful view on Performance schema: + +Sysschema for MySQL old version +-- + +```bash +curl "https://codeload.github.com/mysql/mysql-sys/zip/master" > sysschema.zip +# check zip file +unzip -l sysschema.zip +unzip sysschema.zip +cd mysql-sys-master +mysql -uroot -p < sys_56.sql +``` + +Sysschema for MariaDB old version +-- + +```bash +curl "https://github.com/FromDual/mariadb-sys/archive/refs/heads/master.zip" > sysschema.zip +# check zip file +unzip -l sysschema.zip +unzip sysschema.zip +cd mariadb-sys-master +mysql -u root -p < ./sys_10.sql +``` + +Performance schema setup +-- + +By default, performance_schema is enabled and sysschema is installed on latest version. + +By default, on MariaDB, performance schema is disabled (MariaDB<10.6). + +Consider activating performance schema across your my.cnf configuration file: + +```ini +[mysqld] +performance_schema = on +performance-schema-consumer-events-statements-history-long = ON +performance-schema-consumer-events-statements-history = ON +performance-schema-consumer-events-statements-current = ON +performance-schema-consumer-events-stages-current=ON +performance-schema-consumer-events-stages-history=ON +performance-schema-consumer-events-stages-history-long=ON +performance-schema-consumer-events-transactions-current=ON +performance-schema-consumer-events-transactions-history=ON +performance-schema-consumer-events-transactions-history-long=ON +performance-schema-consumer-events-waits-current=ON +performance-schema-consumer-events-waits-history=ON +performance-schema-consumer-events-waits-history-long=ON +performance-schema-instrument='%=ON' +max-digest-length=2048 +performance-schema-max-digest-length=2018 +``` + +Sysschema installation for MariaDB < 10.6 +-- + +Sysschema is not installed by default under MariaDB prior to 10.6 [MariaDB sys](https://mariadb.com/kb/en/sys-schema/) + +You can follow this command to create a new database sys containing a useful view on Performance schema: + +```bash +curl "https://codeload.github.com/FromDual/mariadb-sys/zip/master" > mariadb-sys.zip +# check zip file +unzip -l mariadb-sys.zip +unzip mariadb-sys.zip +cd mariadb-sys-master/ +mysql -u root -p < ./sys_10.sql +``` + +Errors & solutions for performance schema installation +-- + +ERROR 1054 (42S22) at line 78 in file: './views/p_s/metrics_56.sql': Unknown column 'STATUS' in 'field list' +-- + +This error can be safely ignored +Consider using a recent MySQL/MariaDB version to avoid this kind of issue during sysschema installation + +In recent versions, sysschema is installed and integrated by default as sys schema (SHOW DATABASES) + +ERROR at line 21: Failed to open file './tables/sys_config_data_10.sql -- ported', error: 2 +Have a look at #452 solution given by @ericx +-- + +Fixing sysctl configuration (/etc/sysctl.conf) + +-- +It is a system wide setting and not a database setting: [Linux FS Kernel settings](https://www.kernel.org/doc/html/latest/admin-guide/sysctl/fs.html#id1) + +You can check its values via: + +```bash +$ cat /proc/sys/fs/aio-* +65536 +2305 +``` + +For example, to set the aio-max-nr value, add the following line to the /etc/sysctl.conf file: + +```bash +fs.aio-max-nr = 1048576 +``` + +To activate the new setting: + +```bash +sysctl -p /etc/sysctl.conf +``` + +Specific usage +-- + +**Usage:** Minimal usage locally + +```bash +perl mysqltuner.pl --host 127.0.0.1 +``` + +Of course, you can add the execute bit (`chmod +x mysqltuner.pl`) so you can execute it without calling Perl directly. + +**Usage:** Minimal usage remotely + +In previous version, --forcemem shoud be set manually, in order to be able to run an MySQLTuner analysis + +Since 2.1.10, memory and swap are defined to 1Gb by default. + +If you want a more accurate value according to your remote server, feel free to setup --forcemem and --forceswap to real RAM value + +```bash +perl mysqltuner.pl --host targetDNS_IP --user admin_user --pass admin_password +``` + +**Usage:** Enable maximum output information around MySQL/MariaDb without debugging + +```bash +perl mysqltuner.pl --verbose +perl mysqltuner.pl --buffers --dbstat --idxstat --sysstat --pfstat --tbstat +``` + +**Usage:** Enable CVE vulnerabilities check for your MariaDB or MySQL version + +```bash +perl mysqltuner.pl --cvefile=vulnerabilities.csv +``` + +**Usage:** Write your result in a file with information displayed + +```bash +perl mysqltuner.pl --outputfile /tmp/result_mysqltuner.txt +``` + +**Usage:** Write your result in a file **without outputting information** + +```bash +perl mysqltuner.pl --silent --outputfile /tmp/result_mysqltuner.txt +``` + +**Usage:** Using template model to customize your reporting file based on [Text::Template](https://metacpan.org/pod/Text::Template) syntax. + +```bash +perl mysqltuner.pl --silent --reportfile /tmp/result_mysqltuner.txt --template=/tmp/mymodel.tmpl +``` + +**Important**: [Text::Template](https://metacpan.org/pod/Text::Template) module is mandatory for `--reportfile` and/or `--template` options, because this module is needed to generate appropriate output based on a text template. + +**Usage:** Dumping all information_schema and sysschema views as csv file into results subdirectory + +```bash +perl mysqltuner.pl --verbose --dumpdir=./result +``` + +**Usage:** Enable debugging information + +```bash +perl mysqltuner.pl --debug +``` + +**Usage:** Update MySQLTuner and data files (password and cve) if needed + +```bash +perl mysqltuner.pl --checkversion --updateversion +``` + +Cloud Support +-- + +MySQLTuner now has experimental support for cloud-based MySQL services. + +* `--cloud`: Enable cloud mode. This is a generic flag for any cloud provider. +* `--azure`: Enable Azure-specific support. +* `--ssh-host `: The SSH host for cloud connections. +* `--ssh-user `: The SSH user for cloud connections. +* `--ssh-password `: The SSH password for cloud connections. +* `--ssh-identity-file `: The path to the SSH identity file for cloud connections. + +HTML reports based on Python Jinja2 +-- + +HTML generation is based on Python/Jinja2 + +**HTML generation Procedure** + +* Generate mysqltuner.pl report using JSON format (--json) +* Generate HTML report using j2 python tools + +**Jinja2 Templates are located under templates sub directory** + +A basic example is called basic.html.j2 + +**Installation Python j2** + +```bash +python -mvenv j2 +source ./j2/bin/activate +(j2) pip install j2 +``` + +**Using Html report generation** + +```bash +perl mysqltuner.pl --verbose --json > reports.json +cat reports.json j2 -f json MySQLTuner-perl/templates/basic.html.j2 > variables.html +``` + +or + +```bash +perl mysqltuner.pl --verbose --json | j2 -f json MySQLTuner-perl/templates/basic.html.j2 > variables.html +``` + +HTML reports based on AHA +-- + +HTML generation is based on AHA + +**HTML generation Procedure** + +* Generate mysqltuner.pl report using standard text reports +* Generate HTML report using aha + +**Installation Aha** + +Follow instructions from Github repo + +[GitHub AHA main repository](https://github.com/theZiz/aha) + +**Using AHA Html report generation** + + perl mysqltuner.pl --verbose --color > reports.txt + aha --black --title "MySQLTuner" -f "reports.txt" > "reports.html" + +or + + perl mysqltuner.pl --verbose --color | aha --black --title "MySQLTuner" > reports.html + +FAQ +-- + +**Question: What are the prerequisites for running MySQL tuner ?** + +Before running MySQL tuner, you should have the following: + +* A MySQL server installation +* Perl installed on your system +* Administrative access to your MySQL server + +**Question: Can MySQL tuner make changes to my configuration automatically ?** + +**No.**, MySQL tuner only provides recommendations. It does not make any changes to your configuration files automatically. It is up to the user to review the suggestions and implement them as needed. + +**Question: How often should I run MySQL tuner ?** + +It is recommended to run MySQL tuner periodically, especially after significant changes to your MySQL server or its workload. + +For optimal results, run the script after your server has been running for at least 24 hours to gather sufficient performance data. + +**Question: How do I interpret the results from MySQL tuner ?** + +MySQL tuner provides output in the form of suggestions and warnings. + +Review each recommendation and consider implementing the changes in your MySQL configuration file (usually 'my.cnf' or 'my.ini'). + +Be cautious when making changes and always backup your configuration file before making any modifications. + +**Question: Can MySQL tuner cause harm to my database or server ?** + +While MySQL tuner itself will not make any changes to your server, blindly implementing its recommendations without understanding the impact can cause issues. + +Always ensure you understand the implications of each suggestion before applying it to your server. + +**Question: Does MySQL tuner support MariaDB and Percona Server ?** + +Yes, MySQL tuner supports MariaDB and Percona Server since they are derivatives of MySQL and share a similar architecture. The script can analyze and provide recommendations for these systems as well. + +**Question: What should I do if I need help with MySQL tuner or have questions about the recommendations ?** + +If you need help with MySQL tuner or have questions about the recommendations provided by the script, you can consult the MySQL tuner documentation, seek advice from online forums, or consult a MySQL expert. + +Be cautious when implementing changes to ensure the stability and performance of your server. + +**Question: Will MySQLTuner fix my slow MySQL server ?** + +**No.** MySQLTuner is a read only script. It won't write to any configuration files, change the status of any daemons. It will give you an overview of your server's performance and make some basic recommendations for improvements that you can make after it completes. + +**Question: Can I fire my DBA now?** + +**MySQLTuner will not replace your DBA in any form or fashion.** + +If your DBA constantly takes your parking spot and steals your lunch from the fridge, then you may want to consider it - but that's your call. + +Once you create it, make sure it's owned by your user and the mode on the file is 0600. This should prevent the prying eyes from getting your database login credentials under normal conditions. + +**Question: I get "ERROR 1524 (HY000): Plugin 'unix_socket' is not loaded" even with unix_socket=OFF. How to fix?** + +This occurs because the MariaDB client attempts to use the `unix_socket` plugin by default when no user/password is provided. + +* **Solution 1 (Recommended):** Use a `~/.my.cnf` file as described above to provide explicit credentials. +* **Solution 2:** Pass credentials directly: `perl mysqltuner.pl --user root --pass your_password`. + +**Question: How to securely re-enable `unix_socket` authentication?** + +If you decide to use `unix_socket` (which allows the OS `root` user to log in to MariaDB `root` without a password), follow these steps: + +1. Ensure the plugin is enabled in `/etc/my.cnf`: `unix_socket=ON` (or remove `OFF`). +2. In MariaDB, set the authentication plugin for the root user: + + ```sql + ALTER USER 'root'@'localhost' IDENTIFIED VIA unix_socket; + ``` + +3. Verify that the `auth_socket` or `unix_socket` plugin is ACTIVE in `SHOW PLUGINS`. + +**Question: Is there another way to secure credentials on latest MySQL and MariaDB distributions ?** + +You could use mysql_config_editor utilities. + +~~~bash + $ mysql_config_editor set --login-path=client --user=someusername --password --host=localhost + Enter password: ******** +~~~ + +After which, `~/.mylogin.cnf` will be created with the appropriate access. + +To get information about stored credentials, use the following command: + +```bash +$mysql_config_editor print +[client] +user = someusername +password = ***** +host = localhost +``` + +**Question: What's minimum privileges needed by a specific mysqltuner user in database ?** + +```bash + mysql>GRANT SELECT, PROCESS,EXECUTE, REPLICATION CLIENT, + SHOW DATABASES,SHOW VIEW + ON *.* + TO 'mysqltuner'@'localhost' identified by pwd1234; +``` + +**Question: It's not working on my OS! What gives?!** + +These kinds of things are bound to happen. Here are the details I need from you to investigate the issue: + +* OS and OS version +* Architecture (x86, x86_64, IA64, Commodore 64) +* Exact MySQL version +* Where you obtained your MySQL version (OS package, source, etc) +* The full text of the error +* A copy of SHOW VARIABLES and SHOW GLOBAL STATUS output (if possible) + +**Question: How to perform CVE vulnerability checks?** + +* Download vulnerabilities.csv from this repository. +* use option --cvefile to perform CVE checks + +**Question: How to use mysqltuner from a remote host?** +Thanks to [@rolandomysqldba](https://dba.stackexchange.com/users/877/rolandomysqldba) + +* You will still have to connect like a mysql client: + +Connection and Authentication + + --host Connect to a remote host to perform tests (default: localhost) + --socket Use a different socket for a local connection + --port Port to use for connection (default: 3306) + --user Username to use for authentication + --pass Password to use for authentication + --defaults-file defaults file for credentials + +Since you are using a remote host, use parameters to supply values from the OS + + --forcemem Amount of RAM installed in megabytes + --forceswap Amount of swap memory configured in megabytes + +* You may have to contact your remote SysAdmin to ask how much RAM and swap you have + +If the database has too many tables, or very large table, use this: + + --skipsize Don't enumerate tables and their types/sizes (default: on) + (Recommended for servers with many tables) + +**Question: Can I install this project using homebrew on Apple Macintosh?** + +Yes! `brew install mysqltuner` can be used to install this application using [homebrew](https://brew.sh/) on Apple Macintosh. + +MySQLTuner and Vagrant +-- + +**MySQLTuner** contains following Vagrant configurations: + +* Fedora Core 30 / Docker + +**Vagrant File** is stored in Vagrant subdirectory. + +* Follow following step after vagrant installation: + $ vagrant up + +**MySQLTuner** contains a Vagrant configurations for test purpose and development + +* Install VirtualBox and Vagrant + * + * +* Clone repository + * git clone +* Install Vagrant plugins vagrant-hostmanager and vagrant-vbguest + * vagrant plugin install vagrant-hostmanager + * vagrant plugin install vagrant-vbguest +* Add Fedora Core 30 box for official Fedora Download Website + * vagrant box add --name generic/fedora30 +* Create a data directory + * mkdir data + +## setup test environments + + $ sh build/createTestEnvs.sh + + $ source build/bashrc + $ mysql_percona80 sakila + sakila> ... + + $ docker images + mariadb 10.1 fc612450e1f1 12 days ago 352MB + mariadb 10.2 027b7c57b8c6 12 days ago 340MB + mariadb 10.3 47dff68107c4 12 days ago 343MB + mariadb 10.4 92495405fc36 12 days ago 356MB + mysql 5.6 95e0fc47b096 2 weeks ago 257MB + mysql 8.0 b8fd9553f1f0 2 weeks ago 445MB + percona/percona-server 5.7 ddd245ed3496 5 weeks ago 585MB + percona/percona-server 5.6 ed0a36e0cf1b 6 weeks ago 421MB + percona/percona-server 8.0 390ae97d57c6 6 weeks ago 697MB + mariadb 5.5 c7bf316a4325 4 months ago 352MB + mariadb 10.0 d1bde56970c6 4 months ago 353MB + mysql 5.5 d404d78aa797 4 months ago 205MB + + $ docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + da2be9b050c9 mariadb:5.5 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:5311->3306/tcp mariadb55 + 5deca25d5ac8 mariadb:10.0 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:5310->3306/tcp mariadb100 + 73aaeb37e2c2 mariadb:10.1 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:5309->3306/tcp mariadb101 + 72ffa77e01ec mariadb:10.2 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:5308->3306/tcp mariadb102 + f5996f2041df mariadb:10.3 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:5307->3306/tcp mariadb103 + 4890c52372bb mariadb:10.4 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:5306->3306/tcp mariadb104 + 6b9dc078e921 percona/percona-server:5.6 "/docker-entrypoint.…" 7 hours ago Up 7 hours 0.0.0.0:4308->3306/tcp percona56 + 3a4c7c826d4c percona/percona-server:5.7 "/docker-entrypoint.…" 7 hours ago Up 7 hours 0.0.0.0:4307->3306/tcp percona57 + 3dda408c91b0 percona/percona-server:8.0 "/docker-entrypoint.…" 7 hours ago Up 7 hours 33060/tcp, 0.0.0.0:4306->3306/tcp percona80 + 600a4e7e9dcd mysql:5.5 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:3309->3306/tcp mysql55 + 4bbe54342e5d mysql:5.6 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:3308->3306/tcp mysql56 + d985820667c2 mysql:8.0 "docker-entrypoint.s…" 7 hours ago Up 7 hours 0.0.0.0:3306->3306/tcp, 33060/tcp mysql 8 0 + +Contributions welcome +-- + +How to contribute using Pull Request ? Follow this guide : [Pull request creation](https://opensource.com/article/19/7/create-pull-request-github) + +Simple steps to create a pull request +-- + +* Fork this Github project +* Clone it to your local system +* Make a new branch +* Make your changes +* Push it back to your repo +* Click the Compare & pull request button +* Click Create pull request to open a new pull request diff --git a/public/docs/releases/index.md b/public/docs/releases/index.md new file mode 100644 index 000000000..5091e785e --- /dev/null +++ b/public/docs/releases/index.md @@ -0,0 +1,35 @@ +# Release Notes Archive + +Stay up to date with the latest improvements and fixes in MySQLTuner. + +- [v2.8.9](index.php?p=releases&file=v2.8.9.md) +- [v2.8.8](index.php?p=releases&file=v2.8.8.md) +- [v2.8.7](index.php?p=releases&file=v2.8.7.md) +- [v2.8.6](index.php?p=releases&file=v2.8.6.md) +- [v2.8.5](index.php?p=releases&file=v2.8.5.md) +- [v2.8.4](index.php?p=releases&file=v2.8.4.md) +- [v2.8.33](index.php?p=releases&file=v2.8.33.md) +- [v2.8.32](index.php?p=releases&file=v2.8.32.md) +- [v2.8.31](index.php?p=releases&file=v2.8.31.md) +- [v2.8.30](index.php?p=releases&file=v2.8.30.md) +- [v2.8.3](index.php?p=releases&file=v2.8.3.md) +- [v2.8.29](index.php?p=releases&file=v2.8.29.md) +- [v2.8.28](index.php?p=releases&file=v2.8.28.md) +- [v2.8.27](index.php?p=releases&file=v2.8.27.md) +- [v2.8.26](index.php?p=releases&file=v2.8.26.md) +- [v2.8.24](index.php?p=releases&file=v2.8.24.md) +- [v2.8.23](index.php?p=releases&file=v2.8.23.md) +- [v2.8.22](index.php?p=releases&file=v2.8.22.md) +- [v2.8.21](index.php?p=releases&file=v2.8.21.md) +- [v2.8.20](index.php?p=releases&file=v2.8.20.md) +- [v2.8.2](index.php?p=releases&file=v2.8.2.md) +- [v2.8.18](index.php?p=releases&file=v2.8.18.md) +- [v2.8.17](index.php?p=releases&file=v2.8.17.md) +- [v2.8.16](index.php?p=releases&file=v2.8.16.md) +- [v2.8.15](index.php?p=releases&file=v2.8.15.md) +- [v2.8.13](index.php?p=releases&file=v2.8.13.md) +- [v2.8.12](index.php?p=releases&file=v2.8.12.md) +- [v2.8.11](index.php?p=releases&file=v2.8.11.md) +- [v2.8.10](index.php?p=releases&file=v2.8.10.md) +- [v2.8.1](index.php?p=releases&file=v2.8.1.md) +- [v2.8.0](index.php?p=releases&file=v2.8.0.md) diff --git a/public/docs/releases/v2.8.0.md b/public/docs/releases/v2.8.0.md new file mode 100644 index 000000000..08726ed64 --- /dev/null +++ b/public/docs/releases/v2.8.0.md @@ -0,0 +1,36 @@ +# Release Notes - v2.8.0 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.0 2026-01-17 + +- Bump version to 2.8.0 +- enhance user hostname restriction checks +- feat: Translate comments and messages in updateCVElist.py to English +- chore: ignore VS Code workspace files +- build: update Debian File::Util dependency installation +- cleanup: MariaDB and MySQL support documentation (focus on LTS) +``` + +## πŸ› οΈ Internal Commit History + +- chore(release): update changelog for version 2.8.0 (32f9ca0) +- Bump version to 2.7.3 and enhance user hostname restriction checks (9542ed0) +- feat: Translate comments and messages in updateCVElist.py to English (afb56a8) +- Merge pull request #865 from jmrenouard/master (0b4d8ae) +- Remove an empty line from .gitignore. (2a2aaf3) +- chore: ignore VS Code workspace files by adding `*.code-workspace` to `.gitignore`. (803b452) +- Generate CVE list at 2025-12-03T00:08:06+01:00 (7800098) +- build: update Debian `File::Util` dependency installation and commit generated `CURRENT_VERSION.txt` (018bb67) +- Generate CURRENT_VERSION.txt at 2025-12-03T00:00:51+01:00 (af60084) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.1.md b/public/docs/releases/v2.8.1.md new file mode 100644 index 000000000..d1cc4bb51 --- /dev/null +++ b/public/docs/releases/v2.8.1.md @@ -0,0 +1,23 @@ +# Release Notes - v2.8.1 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.1 2026-01-17 + +- fix: resilient memory checks with /proc fallback on Linux and silencing expected ps failures +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.10.md b/public/docs/releases/v2.8.10.md new file mode 100644 index 000000000..0f9884b47 --- /dev/null +++ b/public/docs/releases/v2.8.10.md @@ -0,0 +1,25 @@ +# Release Notes - v2.8.10 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.10 2026-01-17 + +- feat: add dates and commands to log files in test_envs.sh +- feat: add separators (=) at the end of log files in test_envs.sh +- chore: synchronize version strings across script, POD, and version file +``` + +## πŸ› οΈ Internal Commit History + +- feat: add timestamps and separators to test_envs.sh logs and bump version to 2.8.10 (80dc37e) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.11.md b/public/docs/releases/v2.8.11.md new file mode 100644 index 000000000..541686997 --- /dev/null +++ b/public/docs/releases/v2.8.11.md @@ -0,0 +1,29 @@ +# Release Notes - v2.8.11 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.11 2026-01-17 + +- docs: update INTERNALS.md with information about Cloud, SSH, Containers, and Plugins +- chore: bump version to 2.8.11 +``` + +## πŸ› οΈ Internal Commit History + +- docs: update INTERNALS.md with Cloud, SSH, Container and Plugin info (6cf3a5a) +- docs: update INTERNALS.md with cloud and container integration details (4e06aec) +- Generate End Of Life (endoflive.date) at 2026-01-17T23:54:14+01:00 (4435f4b) +- Generate FEATURES.md at 2026-01-17T23:54:04+01:00 (ed32722) +- Generate USAGE.md at 2026-01-17T23:54:04+01:00 (6e940b9) +- docs: Add agent trigger metadata and warnings for version incrementing based on remote tags. (6961356) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.12.md b/public/docs/releases/v2.8.12.md new file mode 100644 index 000000000..ec4184dbf --- /dev/null +++ b/public/docs/releases/v2.8.12.md @@ -0,0 +1,24 @@ +# Release Notes - v2.8.12 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.12 2026-01-17 + +- feat: update is_docker() to detect containerd and podman runtimes +- chore: bump version to 2.8.12 +``` + +## πŸ› οΈ Internal Commit History + +- feat: improve machine type detection for containers (Version 2.8.12) (2945c12) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.13.md b/public/docs/releases/v2.8.13.md new file mode 100644 index 000000000..0960a78e0 --- /dev/null +++ b/public/docs/releases/v2.8.13.md @@ -0,0 +1,26 @@ +# Release Notes - v2.8.13 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.13 2026-01-18 + +- docs: add Useful Links section to all README files (English, French, Russian, Italian) +- chore: bump version to 2.8.13 +``` + +## πŸ› οΈ Internal Commit History + +- docs: add Useful Links to READMEs and bump version to 2.8.13 (e1049be) +- Generate USAGE.md at 2026-01-18T00:16:31+01:00 (983dffc) +- chore: Ignore the examples directory in .gitignore. (3e6ae6b) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.15.md b/public/docs/releases/v2.8.15.md new file mode 100644 index 000000000..3fbf5df6b --- /dev/null +++ b/public/docs/releases/v2.8.15.md @@ -0,0 +1,27 @@ +# Release Notes - v2.8.15 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.15 2026-01-18 + +- feat: update all GitHub links from 'major' to 'jmrenouard' organization +- feat: refactor plugin information to filter ACTIVE status and display specific columns grouped by type +- chore: bump version to 2.8.15 +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.15 (d9d8cb1) +- feat: refactor plugin information display and filtering (8323079) +- Generate USAGE.md at 2026-01-18T00:33:10+01:00 (c11e87b) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.16.md b/public/docs/releases/v2.8.16.md new file mode 100644 index 000000000..eee01574c --- /dev/null +++ b/public/docs/releases/v2.8.16.md @@ -0,0 +1,23 @@ +# Release Notes - v2.8.16 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.16 2026-01-18 + +- chore: bump version to 2.8.16 +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.17.md b/public/docs/releases/v2.8.17.md new file mode 100644 index 000000000..a8610551d --- /dev/null +++ b/public/docs/releases/v2.8.17.md @@ -0,0 +1,24 @@ +# Release Notes - v2.8.17 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.17 2026-01-18 + +- feat: implementation of issue #403 to check weak passwords on MySQL 8.0+ and flush hosts every 100 attempts +- chore: bump version to 2.8.17 +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.18.md b/public/docs/releases/v2.8.18.md new file mode 100644 index 000000000..4fdbaba31 --- /dev/null +++ b/public/docs/releases/v2.8.18.md @@ -0,0 +1,25 @@ +# Release Notes - v2.8.18 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.18 2026-01-18 + +- feat: add --max-password-checks option to limit dictionary checks (default: 100) +- fix: ensure Machine type is reported as 'Container' when --container option is used +- chore: bump version to 2.8.18 +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.2.md b/public/docs/releases/v2.8.2.md new file mode 100644 index 000000000..cb87092c1 --- /dev/null +++ b/public/docs/releases/v2.8.2.md @@ -0,0 +1,25 @@ +# Release Notes - v2.8.2 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.2 2026-01-17 + +- fix: system command failures (ping/ifconfig/redirection) on modern Linux (Ubuntu 22.04/WSL2) +- feat: integrate external test dependencies (multi-db-docker-env, test_db) and automated employees database injection +``` + +## πŸ› οΈ Internal Commit History + +- chore(release): update changelog for version 2.8.2 + fix: system command failures (ping/ifconfig/redirection) on modern Linux + feat: integrate external test dependencies (151c45e) +- chore(release): update header version and agent release rules/workflows (b740d7f) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.20.md b/public/docs/releases/v2.8.20.md new file mode 100644 index 000000000..d24c7a2f8 --- /dev/null +++ b/public/docs/releases/v2.8.20.md @@ -0,0 +1,24 @@ +# Release Notes - v2.8.20 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.20 2026-01-18 + +- feat: add automated regression test for forcemem MB interpretation (issues #780, #810) +- chore: bump version to 2.8.20 +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.20 (4d82060) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.21.md b/public/docs/releases/v2.8.21.md new file mode 100644 index 000000000..c435db1b7 --- /dev/null +++ b/public/docs/releases/v2.8.21.md @@ -0,0 +1,25 @@ +# Release Notes - v2.8.21 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.21 2026-01-18 + +- fix: remove contradictory query_cache_limit recommendation when disabling query cache (issue #671) +- fix: cap join_buffer_size recommendation at 4MB and prefer index optimization (issue #671) +- chore: bump version to 2.8.21 +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.22.md b/public/docs/releases/v2.8.22.md new file mode 100644 index 000000000..419649b6e --- /dev/null +++ b/public/docs/releases/v2.8.22.md @@ -0,0 +1,32 @@ +# Release Notes - v2.8.22 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.22 2026-01-18 + +- feat: update all repository links from 'major' to 'jmrenouard' (issue #410) +- docs: add Changelog information and Useful Links to all README files (issue #411) +- feat: improve thread_pool_size recommendations based on logical CPU count (issue #404) +- feat: suggest enabling thread pool for servers with max_connections >= 512 (issue #404) +- fix: hide ThreadPool metrics when thread pool is not enabled to avoid noise (issue #404) +- feat: add logical_cpu_cores function to accurately detect threads including HT +- chore: bump version to 2.8.22 +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.22 (49271e5) +- chore: add version 2.8.21 to Changelog (64419c3) +- chore: bump version to 2.8.21 (f232b4c) +- chore: bump version to 2.8.20 (d92a05a) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.23.md b/public/docs/releases/v2.8.23.md new file mode 100644 index 000000000..22020d410 --- /dev/null +++ b/public/docs/releases/v2.8.23.md @@ -0,0 +1,24 @@ +# Release Notes - v2.8.23 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.23 2026-01-18 + +- feat: add --ignore-tables CLI option to filter specific tables from analysis (#749) +- chore: bump version to 2.8.23 +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.24.md b/public/docs/releases/v2.8.24.md new file mode 100644 index 000000000..80f68414d --- /dev/null +++ b/public/docs/releases/v2.8.24.md @@ -0,0 +1,33 @@ +# Release Notes - v2.8.24 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.24 2026-01-18 + +- fix: improve MariaDB 11+ detection by checking version_comment (issue #869) +- fix: handle innodb_buffer_pool_chunk_size=0 (autosize) in MariaDB 10.8+ (#869) +- chore: bump version to 2.8.24 +``` + +## πŸ› οΈ Internal Commit History + +- Merge remote-tracking branch 'origin/master' (3184eab) +- fix: MariaDB 11+ detection and InnoDB chunk breakdown (issue #869) (3a2cb4a) +- Merge pull request #868 from major/copilot/add-default-prompt-username-password (a8ede22) +- Merge pull request #871 from jmrenouard/master (b873cb8) +- chore: bump version to 2.8.23 (f603d77) +- Merge pull request #870 from jmrenouard/master (2ee602f) +- Refactor: consolidate duplicate error handling in password prompt (180a5d6) +- Add password prompting when --user provided without --pass (26dd18d) +- Initial plan (83a6413) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.26.md b/public/docs/releases/v2.8.26.md new file mode 100644 index 000000000..e989e3669 --- /dev/null +++ b/public/docs/releases/v2.8.26.md @@ -0,0 +1,28 @@ +# Release Notes - v2.8.26 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.26 2026-01-18 + +- fix: inverted replication command logic causing wrong SQL on MySQL 8.0+/MariaDB 10.5+ (issue #553) +- feat: add MySQL/MariaDB version detection to prevent version number conflicts in replication logic +- test: add comprehensive test suite (test_issue_553.t) for replication command compatibility +- chore: bump version to 2.8.26 +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.26 (63d0e2a) +- feat: release 2.8.26 (507a2f2) +- chore: bump version to 2.8.25 (27422ea) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.27.md b/public/docs/releases/v2.8.27.md new file mode 100644 index 000000000..5d705f66a --- /dev/null +++ b/public/docs/releases/v2.8.27.md @@ -0,0 +1,29 @@ +# Release Notes - v2.8.27 + +**Date**: 2026-01-18 + +## πŸ“ Executive Summary + +```text +2.8.27 2026-01-18 + +- refactor: replace massive raw backtick usage with execute_system_command wrapper for better security and compliance (Compliance Sentinel) +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.27 (b21a411) +- feat: add new agent skills for database versioning and Perl patterns, development workflows, and a temporary changelog. (933476d) +- chore: bump version to 2.8.26 (7d3f617) +- feat: release 2.8.26 (c54ddb0) +- feat: release 2.8.26 (b4f0d66) +- Update Buy Me a Coffee username in FUNDING.yml (3e8a36c) +- chore: bump version to 2.8.25 (27422ea) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.28.md b/public/docs/releases/v2.8.28.md new file mode 100644 index 000000000..87fa86b5e --- /dev/null +++ b/public/docs/releases/v2.8.28.md @@ -0,0 +1,28 @@ +# Release Notes - v2.8.28 + +**Date**: 2026-01-22 + +## πŸ“ Executive Summary + +```text +2.8.28 2026-01-22 + +- feat: ajoute l'option --no-pfstat pour la partie performance schema +- feat: ajoute l'option --no-colstat pour la partie colonne stat +- fix: skip innodb_buffer_stats during sys schema dump to avoid performance issues +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.28 (8df44a5) +- Merge pull request #873 from jmrenouard/master (0696e8a) +- chore: bump version to 2.8.27 (3f740fc) +- Merge pull request #872 from jmrenouard/master (71f5a41) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.29.md b/public/docs/releases/v2.8.29.md new file mode 100644 index 000000000..740c7412c --- /dev/null +++ b/public/docs/releases/v2.8.29.md @@ -0,0 +1,26 @@ +# Release Notes - v2.8.29 + +**Date**: 2026-01-24 + +## πŸ“ Executive Summary + +```text +2.8.29 2026-01-24 + +- fix: synchronize all version occurrences in mysqltuner.pl and update release workflows (issue #15) +- feat: add version consistency check to release-preflight and git-flow workflows +- docs: update copyright years to 2026 +``` + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.29 (d56b288) +- chore: bump version to 2.8.29 (b0b52db) + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.3.md b/public/docs/releases/v2.8.3.md new file mode 100644 index 000000000..8dd4d260a --- /dev/null +++ b/public/docs/releases/v2.8.3.md @@ -0,0 +1,24 @@ +# Release Notes - v2.8.3 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.3 2026-01-17 + +- feat: detect docker/podman environment and automatically grab logs from container if local log file is not found +- feat: add --container option to manually specify a container for log retrieval +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.30.md b/public/docs/releases/v2.8.30.md new file mode 100644 index 000000000..140162f9c --- /dev/null +++ b/public/docs/releases/v2.8.30.md @@ -0,0 +1,147 @@ +# Release Notes - v2.8.30 + +**Date**: 2026-01-24 + +## πŸ“ Executive Summary + +```text +2.8.30 2026-01-24 + +- feat: add InnoDB transaction isolation levels and metrics (active count, longest duration) +- feat: add MariaDB innodb_snapshot_isolation detection and recommendation +- feat: implement robust container transport support (--container) +- feat: skip kernel tuning recommendations in container mode or when running in Docker +- feat: dynamic MySQL/MariaDB client detection in containers/remote hosts +- feat: automatic database password retrieval from container environment (MYSQL_ROOT_PASSWORD/MARIADB_ROOT_PASSWORD) +- fix: incorrect skip-name-resolve recommendations for cPanel systems (issue #863) +- fix: noisy system command failures when absolute paths are used for whitelisted commands (issue #874) +- fix: resolve syntax error and Perl compilation warnings in `mysqltuner.pl` +- fix: ensure shell commands (pipes, redirections) work correctly in containers using `sh -c` +- docs: synchronize all README files with authentication mismatch troubleshooting guide +- ci: update package.json test script and create remember workflow +- ci: consolidate testing laboratory scripts into unified build/test_envs.sh and update Makefile +- ci: enhance `build/test_envs.sh` to capture and link all infrastructure logs (Docker start, DB injection, container logs, inspect data) in HTML reports for full audit traceability +- ci: make HTML reports self-sufficient by embedding logs directly and reordering sections +- ci: implement tripartite testing scenarios (Standard, Container, Dumpdir) per configuration with horizontal scenario selector in HTML reports +- ci: normalize HTML log panels with consistent Raw/Log links and improved UI layout +- ci: harden laboratory execution script with rigorous return code checking and log portability (copy vs symlink) +- ci: automate cleanup of `examples/` directory to keep only the 10 most recent results +- ci: add `/examples-cleanup` workflow for manual laboratory maintenance +- ci: implement automated technical release notes system via `build/release_gen.py` and `/release-notes-gen` workflow +- ci: add automated `.agent/README.md` synchronization via `build/doc_sync.py` and `/doc-sync` workflow +- test: add unit test tests/innodb_isolation.t for new transaction metrics +- test: add regression test tests/repro_issue_863.t for cPanel name resolution logic +- test: add unit test tests/test_issue_874.t to verify system command whitelisting and unix_socket logic +- test: add unit test tests/issue_869.t to verify InnoDB chunk breakdown on MariaDB 11.4+ (issue #869) +- test: validate MySQLTuner compatibility with MariaDB 11.8 (detected 11.8.5) +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 8 | +8 | πŸš€ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | +1 | πŸš€ | +| Information Points | 7 | +7 | πŸš€ | + +## πŸ§ͺ New Diagnostic Capabilities + +### πŸ›‘ New Risk Detections +- Table $dbname.$tbname has no index defined +- innodb_snapshot_isolation is OFF with REPEATABLE-READ (Stricter snapshot isolation is disabled) + +### ℹ️ New Information Points +- Dumpdir: $opt{dumpdir} +- Dumping information schema +- Dumping performance schema +- Dumping sys schema +- General MyIsam metrics: +- InnoDB Snapshot Isolation: +- SKIPPING $sys_view +- Transaction Isolation Level: $isolation +- table_definition_cache ( + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +### βž• CLI Options Added +- `--azure` +- `--bannedports` +- `--buffers` +- `--checkversion` +- `--cloud` +- `--color` +- `--colstat` +- `--container` +- `--dbgpattern` +- `--dbstat` +- `--debug` +- `--defaultarch` +- `--defaults-extra-file` +- `--defaults-file` +- `--dumpdir` +- `--experimental` +- `--feature` +- `--forcemem` +- `--forceswap` +- `--host` +- `--idxstat` +- `--ignore-tables` +- `--json` +- `--max-password-checks` +- `--maxportallowed` +- `--noask` +- `--nobad` +- `--nocolor` +- `--nocolstat` +- `--nodbstat` +- `--nogood` +- `--noidxstat` +- `--noinfo` +- `--nomyisamstat` +- `--nondedicated` +- `--nopfstat` +- `--noplugininfo` +- `--noprettyicon` +- `--noprocess` +- `--nostructstat` +- `--nosysstat` +- `--notbstat` +- `--outputfile` +- `--pass` +- `--password` +- `--passwordfile` +- `--pfstat` +- `--pipe` +- `--pipe_name` +- `--plugininfo` +- `--port` +- `--prettyjson` +- `--protocol` +- `--reportfile` +- `--server-log` +- `--silent` +- `--skippassword` +- `--skipsize` +- `--socket` +- `--ssh-host` +- `--ssh-identity-file` +- `--ssh-password` +- `--ssh-user` +- `--ssl-ca` +- `--sysstat` +- `--tbstat` +- `--template` +- `--updateversion` +- `--user` +- `--verbose` + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.31.md b/public/docs/releases/v2.8.31.md new file mode 100644 index 000000000..eb8363f53 --- /dev/null +++ b/public/docs/releases/v2.8.31.md @@ -0,0 +1,80 @@ +# Release Notes - v2.8.31 + +**Date**: 2026-01-27 + +## πŸ“ Executive Summary + +```text +2.8.31 2026-01-27 + +- chore: uncomment examples directory in .gitignore. +- chore: bump version to 2.8.31. +- feat: add `--schemadir ` option to generate per-schema markdown documentation. +- feat: support independent schema documentation generation without requiring `--dumpdir`. +- feat: restructure specifications into `documentation/specifications/` (/hey-agent). +- feat: add specification for Performance Schema Error Log analysis. +- feat: add unused and redundant index checks via Performance Schema (sys schema) with recommendations and modeling findings. +- feat: modernize CVE retrieval script `build/updateCVElist.pl` with NVD API 2.0 (JSON-based) (Fix #867). +- feat: implement SQL modeling best practice checks (Primary Keys, Foreign Keys, Naming Conventions, Data Types). +- feat: add MySQL 8.0+ specific modeling checks (JSON indexing, Invisible Indexes). +- fix: resolve CLI option ambiguity and duplicate specification errors via unified Getopt::Long binding. +- fix: resolve tab delimiter mismatch in `tests/sql_modeling.t` mock data. +- fix: noisy system command failures when absolute paths are used for whitelisted commands (issue #874). +- fix: resolve syntax error and Perl compilation warnings in `mysqltuner.pl`. +- fix: ensure shell commands (pipes, redirections) work correctly in containers using `sh -c`. +- test: add unit test `tests/schemadir.t` to verify schema documentation logic. +- test: add unit test [tests/index_pfs_checks.t](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/tests/index_pfs_checks.t) for Performance Schema index verification. +- test: add unit test [tests/sql_modeling.t](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/tests/sql_modeling.t) for comprehensive schema analysis verification. +- ci: update `build/test_envs.sh` with `Schemadir` test scenario and fix logic ordering. +- ci: establish formal "Advanced Test Log Auditing" protocol and anomaly tracking. +- ci: enhance lab reports with integrated `execution.log` and collapsible panels for better readability. +- ci: harden testing suite with rigorous return code checking across all test modes (lab, container, remote). +- ci: improve laboratory error reporting to generate diagnostic reports even on startup failures. +- ci: verify MySQL 8.0 integration post-CLI refactoring. +- ci: reintroduce CVE analysis in Dockerfile with `--cvefile` support. +- ci: cleanup all `examples/` and execute full LTS test suite (MySQL, MariaDB, Percona). +- ci: update package.json test script and create remember workflow. +- ci: consolidate testing laboratory scripts into unified [build/test_envs.sh](file:///home/jmren/GIT_REPOS/MySQLTuner-perl/build/test_envs.sh) and update Makefile. +- docs: formalize tracking of Makefile and build script changes +- docs: formalize test and ci requirements in Changelog and rules +- docs: update Changelog and relax rules for docs-only updates +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 9 | +9 | πŸš€ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | +1 | πŸš€ | +| Information Points | 8 | +8 | πŸš€ | + +## πŸ§ͺ New Diagnostic Capabilities + +### πŸ›‘ New Risk Detections +- Table $dbname.$tbname has no index defined +- innodb_snapshot_isolation is OFF with REPEATABLE-READ (Stricter snapshot isolation is disabled) + +### ℹ️ New Information Points +- Auto-generating raw output file: $raw_output_file +- Dumpdir: $opt{dumpdir} +- Dumping information schema +- Dumping performance schema +- Dumping sys schema +- General MyIsam metrics: +- InnoDB Snapshot Isolation: +- SKIPPING $sys_view +- Transaction Isolation Level: $isolation +- table_definition_cache ( + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.32.md b/public/docs/releases/v2.8.32.md new file mode 100644 index 000000000..2261a9be4 --- /dev/null +++ b/public/docs/releases/v2.8.32.md @@ -0,0 +1,92 @@ +# Release Notes - v2.8.32 + +**Date**: 2026-01-30 + +## πŸ“ Executive Summary + +```text +2.8.32 2026-01-30 + +- chore: rename release manager specification to a more generic name. +- chore: update `multi-db-docker-env` and `test_db` vendors. +- feat: remove `--skippassword` from test laboratory to enable security checks. +- fix: resolve false positive weak password warnings on MariaDB socket authentication (issue #875) and prevent dictionary corruption by silencing `curl`/`wget` output. +- test: add unit test [tests/test_issue_875.t](file:///tests/test_issue_875.t) to verify socket authentication detection. +- style: enforce artifact path hygiene (hide absolute workstation paths) in agent-generated reports. +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 9 | +1 | πŸš€ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | 0 | πŸ›‘οΈ | +| Information Points | 8 | +1 | πŸš€ | + +## πŸ§ͺ New Diagnostic Capabilities + +### πŸ›‘ New Risk Detections +- innodb_snapshot_isolation is OFF with REPEATABLE-READ (Stricter snapshot isolation is disabled) + +### ℹ️ New Information Points +- Auto-generating raw output file: $raw_output_file +- InnoDB Snapshot Isolation: +- Transaction Isolation Level: $isolation + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.32 (a48c024) +- docs: document removal of --skippassword in Changelog (84df3e8) +- feat: remove --skippassword from test laboratory to enable security checks (85b42ec) +- chore: update multi-db-docker-env and test_db vendors (f14118f) +- chore: uncomment examples directory in .gitignore (8fe8fa2) +- feat: release 2.8.30 (fb45fd0) +- docs: formalize tracking of Makefile and build script changes (72b162f) +- docs: formalize test and ci requirements in Changelog and rules (b7d23f6) +- feat(workflow): add remember workflow and consolidate autolearning (f1fb317) +- docs: update Changelog and relax rules for docs-only updates (603c18b) +- fix(core): noisy system command failures with absolute paths (issue #874) (94f4e25) +- chore: bump version to 2.8.30 (f3372db) + +## βš™οΈ Technical Evolutions + +### βž• CLI Options Added +- `--Modeling` +- `--Performance` +- `--Security` +- `--System` +- `--cvefile` +- `--myisamstat` +- `--mysqladmin` +- `--mysqlcmd` +- `--passenv` +- `--schemadir` +- `--structstat` +- `--userenv` + +### βž– CLI Options Deprecated +- `--color` +- `--no-colstat` +- `--no-pfstat` +- `--nocolor` +- `--nocolstat` +- `--nodbstat` +- `--noidxstat` +- `--nomyisamstat` +- `--nopfstat` +- `--noplugininfo` +- `--nostructstat` +- `--nosysstat` +- `--notbstat` +- `--pass` +- `--password` +- `--server-log` +- `--user` +- `--verbose` + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.33.md b/public/docs/releases/v2.8.33.md new file mode 100644 index 000000000..da330df09 --- /dev/null +++ b/public/docs/releases/v2.8.33.md @@ -0,0 +1,23 @@ +# Release Notes - v2.8.33 + +**Date**: 2026-01-30 + +## πŸ“ Executive Summary + +```text +2.8.33 2026-01-30 + +- +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.4.md b/public/docs/releases/v2.8.4.md new file mode 100644 index 000000000..cd8e0e7e6 --- /dev/null +++ b/public/docs/releases/v2.8.4.md @@ -0,0 +1,37 @@ +# Release Notes - v2.8.4 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.4 2026-01-17 + +- fix: database injection failing to find dump files due to incorrect working directory +- fix: ensure correct path handling for 'source' commands in employees.sql +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 7 | 0 | πŸ›‘οΈ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | 0 | πŸ›‘οΈ | +| Information Points | 6 | 0 | πŸ›‘οΈ | + +## πŸ› οΈ Internal Commit History + +- fix: database injection working directory and bump version to 2.8.4 (4747c7d) +- chore: ignore vendor/ directory (fe330fb) + +## βš™οΈ Technical Evolutions + +### βž• CLI Options Added +- `--container` + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.5.md b/public/docs/releases/v2.8.5.md new file mode 100644 index 000000000..178dc01f5 --- /dev/null +++ b/public/docs/releases/v2.8.5.md @@ -0,0 +1,24 @@ +# Release Notes - v2.8.5 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.5 2026-01-17 + +- fix: noisy sysctl errors for sunrpc parameters when kernel module is not loaded +- fix: refactor get_kernel_info to handle missing sysctl parameters gracefully +``` + +## πŸ› οΈ Internal Commit History + +Initial release or no previous tag found. + +## βš™οΈ Technical Evolutions + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.6.md b/public/docs/releases/v2.8.6.md new file mode 100644 index 000000000..48d5de064 --- /dev/null +++ b/public/docs/releases/v2.8.6.md @@ -0,0 +1,41 @@ +# Release Notes - v2.8.6 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.6 2026-01-17 + +- chore: synchronize version strings across script, POD, and version file +- feat: add Plugin Information section and --plugininfo flag (#794) +- fix: memory calculation bug in system_recommendations (1.5GB check) +- fix: ensure forcemem is correctly interpreted and displayed as MB in os_setup +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 7 | 0 | πŸ›‘οΈ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | 0 | πŸ›‘οΈ | +| Information Points | 6 | 0 | πŸ›‘οΈ | + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.7 (8d3a98f) +- Big cleanup (a502b18) +- cleanup file (8b2a3cc) + +## βš™οΈ Technical Evolutions + +### βž• CLI Options Added +- `--noplugininfo` +- `--plugininfo` + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.7.md b/public/docs/releases/v2.8.7.md new file mode 100644 index 000000000..913419ca8 --- /dev/null +++ b/public/docs/releases/v2.8.7.md @@ -0,0 +1,40 @@ +# Release Notes - v2.8.7 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.7 2026-01-17 + +- chore: synchronize version strings across script, POD, and version file +- fix: ensure version consistency between Changelog and CURRENT_VERSION.txt +- docs: add standardized comment headers to all build shell scripts +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 7 | 0 | πŸ›‘οΈ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | 0 | πŸ›‘οΈ | +| Information Points | 6 | 0 | πŸ›‘οΈ | + +## πŸ› οΈ Internal Commit History + +- feat: release 2.8.7 (8d3a98f) +- Big cleanup (a502b18) +- cleanup file (8b2a3cc) + +## βš™οΈ Technical Evolutions + +### βž• CLI Options Added +- `--noplugininfo` +- `--plugininfo` + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.8.md b/public/docs/releases/v2.8.8.md new file mode 100644 index 000000000..b10a15712 --- /dev/null +++ b/public/docs/releases/v2.8.8.md @@ -0,0 +1,39 @@ +# Release Notes - v2.8.8 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.8 2026-01-17 + +- chore: bump version to 2.8.8 +- feat: add -d/--database parameter to test_envs.sh to tune specific databases +- feat: add -c/--configs parameter to test_envs.sh for easier configuration selection +- feat: add timestamps to major steps in test_envs.sh logs +- feat: add execution header to test_envs.sh output showing the full command +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 7 | 0 | πŸ›‘οΈ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | 0 | πŸ›‘οΈ | +| Information Points | 6 | 0 | πŸ›‘οΈ | + +## πŸ› οΈ Internal Commit History + +- feat: enhance test_envs.sh with database parameter and timestamped logs (2b7a041) +- fix: Dockerfile can be built without vulnerabiliteis.csv (be0856a) + +## βš™οΈ Technical Evolutions + +*Internal logic hardening (no interface or diagnostic changes).* + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/releases/v2.8.9.md b/public/docs/releases/v2.8.9.md new file mode 100644 index 000000000..2ea70b2ff --- /dev/null +++ b/public/docs/releases/v2.8.9.md @@ -0,0 +1,36 @@ +# Release Notes - v2.8.9 + +**Date**: 2026-01-17 + +## πŸ“ Executive Summary + +```text +2.8.9 2026-01-17 + +- chore: bump version to 2.8.9 +- feat: improve container log detection by excluding proxy containers (traefik, haproxy, maxscale, proxy) +- feat: prioritize database-related container names (mysql, mariadb, percona, db, database) +``` + +## πŸ“ˆ Diagnostic Growth Indicators + +| Metric | Current | Progress | Status | +| :--- | :--- | :--- | :--- | +| Total Indicators | 7 | 0 | πŸ›‘οΈ | +| Efficiency Checks | 0 | 0 | πŸ›‘οΈ | +| Risk Detections | 1 | 0 | πŸ›‘οΈ | +| Information Points | 6 | 0 | πŸ›‘οΈ | + +## πŸ› οΈ Internal Commit History + +- feat: improve container log detection and bump version to 2.8.9 (b4155b2) + +## βš™οΈ Technical Evolutions + +*Internal logic hardening (no interface or diagnostic changes).* + +## βœ… Laboratory Verification Results + +- [x] Automated TDD suite passed. +- [x] Multi-DB version laboratory execution validated. +- [x] Performance indicator delta analysis completed. diff --git a/public/docs/usage.md b/public/docs/usage.md new file mode 100644 index 000000000..43c81ec21 --- /dev/null +++ b/public/docs/usage.md @@ -0,0 +1,188 @@ +# NAME + + MySQLTuner 2.8.10 - MySQL High Performance Tuning Script + +# 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 + +# CONNECTION AND AUTHENTICATION + + --host Connect to a remote host to perform tests (default: localhost) + --socket Use a different socket for a local connection + --pipe Connect to a local Windows database using named pipes + --pipe_name Use a different pipe name for a local connection + --port Port to use for connection (default: 3306) + --protocol tcp Force TCP connection instead of socket + --user Username to use for authentication + --userenv Name of env variable which contains username to use for authentication + --pass Password to use for authentication + --passenv Name of env variable which contains password to use for authentication + --ssl-ca Path to public key + --mysqladmin Path to a custom mysqladmin executable + --mysqlcmd Path to a custom mysql executable + --defaults-file Path to a custom .my.cnf + --defaults-extra-file Path to an extra custom config file + --server-log Path to explicit log file (error_log) + +# CLOUD SUPPORT + + --cloud Enable cloud mode. This is a generic flag for any cloud provider. + --azure Enable Azure-specific support. + --ssh-host The SSH host for cloud connections. + --ssh-user The SSH user for cloud connections. + --ssh-password The SSH password for cloud connections. + --ssh-identity-file The path to the SSH identity file for cloud connections. + +# PERFORMANCE AND REPORTING OPTIONS + + --skipsize Don't enumerate tables and their types/sizes (default: on) + (Recommended for servers with many tables) + --json Print result as JSON string + --prettyjson Print result as JSON formatted string + --skippassword Don't perform checks on user passwords (default: off) + --checkversion Check for updates to MySQLTuner (default: don't check) + --updateversion Check for updates to MySQLTuner and update when newer version is available (default: don't check) + --forcemem Amount of RAM installed in megabytes + --forceswap Amount of swap memory configured in megabytes + --passwordfile Path to a password file list (one password by line) + --cvefile CVE File for vulnerability checks + --outputfile Path to a output txt file + --reportfile Path to a report txt file + --template Path to a template file + --dumpdir Path to a directory where to dump information files + --feature Run a specific feature (see FEATURES section) + --dumpdir information_schema tables and sys views are dumped in CSV in this path + +# OUTPUT OPTIONS + + --silent Don't output anything on screen + --verbose Print out all options (default: no verbose, dbstat, idxstat, sysstat, tbstat, pfstat) + --color Print output in color + --nocolor Don't print output in color + --noprettyicon Print output with legacy tag [OK], [!!], [--], [CMD], ... + --nogood Remove OK responses + --nobad Remove negative/suggestion responses + --noinfo Remove informational responses + --debug Print debug information + --experimental Print experimental analysis (may fail) + --nondedicated Consider server is not dedicated to Db server usage only + --noprocess Consider no other process is running + --dbstat Print database information + --nodbstat Don't print database information + --tbstat Print table information + --notbstat Don't print table information + --colstat Print column information + --nocolstat Don't print column information + --idxstat Print index information + --noidxstat Don't print index information + --nomyisamstat Don't print MyIsam information + --sysstat Print system information + --nosysstat Don't print system information + --nostructstat Don't print table structures information + --pfstat Print Performance schema + --nopfstat Don't print Performance schema + --plugininfo Print Plugin information + --noplugininfo Don't print Plugin information + --bannedports Ports banned separated by comma (,) + --server-log Define specific error_log to analyze + --maxportallowed Number of open ports allowable on this host + --buffers Print global and per-thread buffer values + +# VERSION + +Version 2.8.17 +=head1 PERLDOC + +You can find documentation for this module with the perldoc command. + + perldoc mysqltuner + +## INTERNALS + +[https://github.com/jmrenouard/MySQLTuner-perl/blob/master/INTERNALS.md](https://github.com/jmrenouard/MySQLTuner-perl/blob/master/INTERNALS.md) + + Internal documentation + +# AUTHORS + +Major Hayden - major@mhtx.net +Jean-Marie Renouard - jmrenouard@gmail.com + +# CONTRIBUTORS + +- Matthew Montgomery +- Paul Kehrer +- Dave Burgess +- Jonathan Hinds +- Mike Jackson +- Nils Breunese +- Shawn Ashlee +- Luuk Vosslamber +- Ville Skytta +- Trent Hornibrook +- Jason Gill +- Mark Imbriaco +- Greg Eden +- Aubin Galinotti +- Giovanni Bechis +- Bill Bradford +- Ryan Novosielski +- Michael Scheidell +- Blair Christensen +- Hans du Plooy +- Victor Trac +- Everett Barnes +- Tom Krouper +- Gary Barrueto +- Simon Greenaway +- Adam Stein +- Isart Montane +- Baptiste M. +- Cole Turner +- Major Hayden +- Joe Ashcraft +- Jean-Marie Renouard +- Stephan GroBberndt +- Christian Loos +- Long Radix + +# SUPPORT + +Bug reports, feature requests, and downloads at http://mysqltuner.pl/ + +Bug tracker can be found at https://github.com/jmrenouard/MySQLTuner-perl/issues + +Maintained by Jean-Marie Renouard (jmrenouard\\@gmail.com) - Licensed under GPL + +# SOURCE CODE + +[https://github.com/jmrenouard/MySQLTuner-perl/](https://github.com/jmrenouard/MySQLTuner-perl/) + + git clone https://github.com/jmrenouard/MySQLTuner-perl/.git + +# COPYRIGHT AND LICENSE + +Copyright (C) 2006-2023 Major Hayden - major@mhtx.net +\# Copyright (C) 2015-2023 Jean-Marie Renouard - jmrenouard@gmail.com + +For the latest updates, please visit http://mysqltuner.pl/ + +Git repository available at https://github.com/jmrenouard/MySQLTuner-perl/ + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + + See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. diff --git a/scripts/sync_docs.py b/scripts/sync_docs.py new file mode 100644 index 000000000..49b20a167 --- /dev/null +++ b/scripts/sync_docs.py @@ -0,0 +1,82 @@ +import os +import shutil +import glob + +SOURCE_DIR = '../MySQLTuner-perl' +TARGET_DIR = './public/docs' +RELEASES_TARGET = os.path.join(TARGET_DIR, 'releases') + +def sync(): + if not os.path.exists(TARGET_DIR): + os.makedirs(TARGET_DIR) + if not os.path.exists(RELEASES_TARGET): + os.makedirs(RELEASES_TARGET) + + # Core files + files_to_sync = { + 'README.md': 'overview.md', + 'INTERNALS.md': 'internals.md', + 'USAGE.md': 'usage.md', + 'CONTRIBUTING.md': 'contributing.md', + 'mariadb_support.md': 'mariadb_support.md', + 'mysql_support.md': 'mysql_support.md' + } + + for src_name, dest_name in files_to_sync.items(): + src_path = os.path.join(SOURCE_DIR, src_name) + if os.path.exists(src_path): + shutil.copy(src_path, os.path.join(TARGET_DIR, dest_name)) + print(f"Synced {src_name}") + + # Release notes + release_files = glob.glob(os.path.join(SOURCE_DIR, 'releases', 'v*.md')) + release_list = [] + for rel_file in release_files: + basename = os.path.basename(rel_file) + shutil.copy(rel_file, RELEASES_TARGET) + release_list.append(basename) + print(f"Synced release {basename}") + + # Generate Release Index + release_list.sort(reverse=True) + with open(os.path.join(RELEASES_TARGET, 'index.md'), 'w') as f: + f.write("# Release Notes Archive\n\n") + f.write("Stay up to date with the latest improvements and fixes in MySQLTuner.\n\n") + for rel in release_list: + v = rel.replace('.md', '') + # PHP router uses p=releases to show index, then specific files aren't directly routed in index.php + # so we'll just link them for now knowing we might need a sub-routing logic later or just let PHP handle it. + # For now, keeping the link structure simple. + f.write(f"- [{v}](index.php?p=releases&file={rel})\n") + + # FAQ and other files + # ... extraction logic remains same + + # Extract FAQ from README + readme_path = os.path.join(SOURCE_DIR, 'README.md') + if os.path.exists(readme_path): + with open(readme_path, 'r') as f: + lines = f.readlines() + + faq_lines = [] + is_faq = False + for i, line in enumerate(lines): + # Check for "FAQ" followed by a underline + if "FAQ" in line and i + 1 < len(lines) and ("--" in lines[i+1] or "==" in lines[i+1]): + is_faq = True + continue + + if is_faq: + if "MySQLTuner and Vagrant" in line or "Contributions welcome" in line: + is_faq = False + break + faq_lines.append(line) + + if faq_lines: + with open(os.path.join(TARGET_DIR, 'faq.md'), 'w') as f: + f.write("# Frequently Asked Questions\n\n") + f.writelines(faq_lines) + print("Extracted FAQ") + +if __name__ == "__main__": + sync() diff --git a/specification.md b/specification.md new file mode 100644 index 000000000..c1a07d2af --- /dev/null +++ b/specification.md @@ -0,0 +1,92 @@ +# Specification: MySQLTuner Full Documentation Website + +## 1. Overview + +Transform `MT-site` into a comprehensive documentation hub. The site will transition from a single landing page to a multi-section knowledge base while maintaining the premium dark-mode aesthetic. + +## 2. Information Architecture + +### 2.1. Home Page (Existing) + +- High-impact landing page (Hero, terminal mockup, value props). + +### 2.2. Documentation Hub (New) + +- **Sidebar**: Sticky navigation with hierarchical grouping. +- **Search**: Client-side full-text search (Fuse.js). +- **Sections**: + - **Getting Started**: Installation, quick start, common options. + - **Technical Internals**: Detailed breakdown of `INTERNALS.md` (Steps, Checks, System calls). + - **Usage Guide**: Comprehensive flag reference from `USAGE.md`. + - **Support Matrix**: Visual tables for MySQL/MariaDB version compatibility. + +### 2.3. Release Notes Archive + +- List of all releases from `releases/*.md`. +- Grouped by major version. +- Permalink for each release. + +### 2.4. FAQ & Troubleshooting + +- Dedicated page for FAQ (extracted from `README.md` and repo history). +- Categories: Connections, Performance, Troubleshooting, Errors. + +### 2.5. Contribution Guide + +- Content from `CONTRIBUTING.md`. +- Automated link to "Open Issues" on GitHub. + +## 3. Design & UI Components + +### 3.1. Sidebar Layout + +- Left-hand navigation (desktop) with mobile hamburger menu. +- Active state highlighting. +- Collapsible categories. + +### 3.2. Content Area + +- Clean typography for long-form reading. +- Syntax highlighting for code blocks (using Prism.js or similar). +- Copy-to-clipboard buttons for every command. +- "Edit this page" link pointing to the source in `MySQLTuner-perl`. + +### 3.3. Search Overlay + +- Command+K shortcut to open. +- Real-time result filtering. + +### 3.4. Brand Assets + +- **Primary Logo**: `assets/img/mtlogo2.png` is the official brand asset for the header branding. +- **Secondary Assets**: `assets/img/logo.png` (legacy) and `assets/img/hero-bg.png` (hero background). + +### 4.1. Tech Stack (PHP + Vanilla) + +- **Language**: PHP 7.4+ (Standard web server support). +- **Routing**: Server-side routing via `index.php` using query parameters (e.g., `?p=overview`). +- **Markdown Processing**: Server-side rendering using `Parsedown.php` (single-file library). +- **Styling**: Vanilla CSS with modern technical dark-mode aesthetic. +- **Interactivity**: Minimal vanilla JavaScript for mobile navigation and smooth scrolling. + +### 4.2. Layout Engine + +- Unified layout template for all doc pages. +- Dynamic content injection into `#main-content`. + +## 5. Content Mapping (Source -> Site) + +| Source File | Site Path | +| :--- | :--- | +| `MySQLTuner-perl/README.md` | `/docs/overview` | +| `MySQLTuner-perl/INTERNALS.md` | `/docs/internals` | +| `MySQLTuner-perl/USAGE.md` | `/docs/usage` | +| `MySQLTuner-perl/releases/*.md` | `/releases/[v]` | +| `MySQLTuner-perl/mariadb_support.md` | `/support/mariadb` | +| `MySQLTuner-perl/mysql_support.md` | `/support/mysql` | + +## 6. Success Criteria + +- Instant navigation between documentation sections (LCP < 100ms for subpages). +- Search results appear in < 50ms. +- 100% of technical content from the perl repo is accessible on the site. diff --git a/stylesheets/pygment_trac.css b/stylesheets/pygment_trac.css deleted file mode 100644 index c6a6452d2..000000000 --- a/stylesheets/pygment_trac.css +++ /dev/null @@ -1,69 +0,0 @@ -.highlight { background: #ffffff; } -.highlight .c { color: #999988; font-style: italic } /* Comment */ -.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ -.highlight .k { font-weight: bold } /* Keyword */ -.highlight .o { font-weight: bold } /* Operator */ -.highlight .cm { color: #999988; font-style: italic } /* Comment.Multiline */ -.highlight .cp { color: #999999; font-weight: bold } /* Comment.Preproc */ -.highlight .c1 { color: #999988; font-style: italic } /* Comment.Single */ -.highlight .cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */ -.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */ -.highlight .gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */ -.highlight .ge { font-style: italic } /* Generic.Emph */ -.highlight .gr { color: #aa0000 } /* Generic.Error */ -.highlight .gh { color: #999999 } /* Generic.Heading */ -.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */ -.highlight .gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */ -.highlight .go { color: #888888 } /* Generic.Output */ -.highlight .gp { color: #555555 } /* Generic.Prompt */ -.highlight .gs { font-weight: bold } /* Generic.Strong */ -.highlight .gu { color: #800080; font-weight: bold; } /* Generic.Subheading */ -.highlight .gt { color: #aa0000 } /* Generic.Traceback */ -.highlight .kc { font-weight: bold } /* Keyword.Constant */ -.highlight .kd { font-weight: bold } /* Keyword.Declaration */ -.highlight .kn { font-weight: bold } /* Keyword.Namespace */ -.highlight .kp { font-weight: bold } /* Keyword.Pseudo */ -.highlight .kr { font-weight: bold } /* Keyword.Reserved */ -.highlight .kt { color: #445588; font-weight: bold } /* Keyword.Type */ -.highlight .m { color: #009999 } /* Literal.Number */ -.highlight .s { color: #d14 } /* Literal.String */ -.highlight .na { color: #008080 } /* Name.Attribute */ -.highlight .nb { color: #0086B3 } /* Name.Builtin */ -.highlight .nc { color: #445588; font-weight: bold } /* Name.Class */ -.highlight .no { color: #008080 } /* Name.Constant */ -.highlight .ni { color: #800080 } /* Name.Entity */ -.highlight .ne { color: #990000; font-weight: bold } /* Name.Exception */ -.highlight .nf { color: #990000; font-weight: bold } /* Name.Function */ -.highlight .nn { color: #555555 } /* Name.Namespace */ -.highlight .nt { color: #000080 } /* Name.Tag */ -.highlight .nv { color: #008080 } /* Name.Variable */ -.highlight .ow { font-weight: bold } /* Operator.Word */ -.highlight .w { color: #bbbbbb } /* Text.Whitespace */ -.highlight .mf { color: #009999 } /* Literal.Number.Float */ -.highlight .mh { color: #009999 } /* Literal.Number.Hex */ -.highlight .mi { color: #009999 } /* Literal.Number.Integer */ -.highlight .mo { color: #009999 } /* Literal.Number.Oct */ -.highlight .sb { color: #d14 } /* Literal.String.Backtick */ -.highlight .sc { color: #d14 } /* Literal.String.Char */ -.highlight .sd { color: #d14 } /* Literal.String.Doc */ -.highlight .s2 { color: #d14 } /* Literal.String.Double */ -.highlight .se { color: #d14 } /* Literal.String.Escape */ -.highlight .sh { color: #d14 } /* Literal.String.Heredoc */ -.highlight .si { color: #d14 } /* Literal.String.Interpol */ -.highlight .sx { color: #d14 } /* Literal.String.Other */ -.highlight .sr { color: #009926 } /* Literal.String.Regex */ -.highlight .s1 { color: #d14 } /* Literal.String.Single */ -.highlight .ss { color: #990073 } /* Literal.String.Symbol */ -.highlight .bp { color: #999999 } /* Name.Builtin.Pseudo */ -.highlight .vc { color: #008080 } /* Name.Variable.Class */ -.highlight .vg { color: #008080 } /* Name.Variable.Global */ -.highlight .vi { color: #008080 } /* Name.Variable.Instance */ -.highlight .il { color: #009999 } /* Literal.Number.Integer.Long */ - -.type-csharp .highlight .k { color: #0000FF } -.type-csharp .highlight .kt { color: #0000FF } -.type-csharp .highlight .nf { color: #000000; font-weight: normal } -.type-csharp .highlight .nc { color: #2B91AF } -.type-csharp .highlight .nn { color: #000000 } -.type-csharp .highlight .s { color: #A31515 } -.type-csharp .highlight .sc { color: #A31515 } diff --git a/stylesheets/styles.css b/stylesheets/styles.css deleted file mode 100644 index 79afa9b88..000000000 --- a/stylesheets/styles.css +++ /dev/null @@ -1,255 +0,0 @@ -@import url(https://fonts.googleapis.com/css?family=Lato:300italic,700italic,300,700); - -body { - padding:50px; - font:14px/1.5 Lato, "Helvetica Neue", Helvetica, Arial, sans-serif; - color:#000; - font-weight:300; -} - -h1, h2, h3, h4, h5, h6 { - color:#222; - margin:0 0 20px; -} - -p, ul, ol, table, pre, dl { - margin:0 0 20px; -} - -h1, h2, h3 { - line-height:1.1; -} - -h1 { - font-size:28px; -} - -h2 { - color:#393939; -} - -h3, h4, h5, h6 { - color:#494949; -} - -a { - color:#39c; - font-weight:400; - text-decoration:none; -} - -a small { - font-size:11px; - color:#777; - margin-top:-0.6em; - display:block; -} - -.wrapper { - width:860px; - margin:0 auto; -} - -blockquote { - border-left:1px solid #e5e5e5; - margin:0; - padding:0 0 0 20px; - font-style:italic; -} - -code, pre { - font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal; - color:#333; - font-size:12px; -} - -pre { - padding:8px 15px; - background: #f8f8f8; - border-radius:5px; - border:1px solid #e5e5e5; - overflow-x: auto; -} - -table { - width:100%; - border-collapse:collapse; -} - -th, td { - text-align:left; - padding:5px 10px; - border-bottom:1px solid #e5e5e5; -} - -dt { - color:#444; - font-weight:700; -} - -th { - color:#444; -} - -img { - max-width:100%; -} - -header { - width:270px; - float:left; - position:fixed; -} - -header ul { - list-style:none; - height:40px; - - padding:0; - - background: #eee; - background: -moz-linear-gradient(top, #f8f8f8 0%, #dddddd 100%); - background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#f8f8f8), color-stop(100%,#dddddd)); - background: -webkit-linear-gradient(top, #f8f8f8 0%,#dddddd 100%); - background: -o-linear-gradient(top, #f8f8f8 0%,#dddddd 100%); - background: -ms-linear-gradient(top, #f8f8f8 0%,#dddddd 100%); - background: linear-gradient(top, #f8f8f8 0%,#dddddd 100%); - - border-radius:5px; - border:1px solid #d2d2d2; - box-shadow:inset #fff 0 1px 0, inset rgba(0,0,0,0.03) 0 -1px 0; - width:270px; -} - -header li { - width:89px; - float:left; - border-right:1px solid #d2d2d2; - height:40px; -} - -header ul a { - line-height:1; - font-size:11px; - color:#999; - display:block; - text-align:center; - padding-top:6px; - height:40px; -} - -strong { - color:#222; - font-weight:700; -} - -header ul li + li { - width:88px; - border-left:1px solid #fff; -} - -header ul li + li + li { - border-right:none; - width:89px; -} - -header ul a strong { - font-size:14px; - display:block; - color:#222; -} - -section { - width:500px; - float:right; - padding-bottom:50px; -} - -small { - font-size:11px; -} - -hr { - border:0; - background:#e5e5e5; - height:1px; - margin:0 0 20px; -} - -footer { - width:270px; - float:left; - position:fixed; - bottom:50px; -} - -@media print, screen and (max-width: 960px) { - - div.wrapper { - width:auto; - margin:0; - } - - header, section, footer { - float:none; - position:static; - width:auto; - } - - header { - padding-right:320px; - } - - section { - border:1px solid #e5e5e5; - border-width:1px 0; - padding:20px 0; - margin:0 0 20px; - } - - header a small { - display:inline; - } - - header ul { - position:absolute; - right:50px; - top:52px; - } -} - -@media print, screen and (max-width: 720px) { - body { - word-wrap:break-word; - } - - header { - padding:0; - } - - header ul, header p.view { - position:static; - } - - pre, code { - word-wrap:normal; - } -} - -@media print, screen and (max-width: 480px) { - body { - padding:15px; - } - - header ul { - display:none; - } -} - -@media print { - body { - padding:0.4in; - font-size:12pt; - color:#444; - } -}