Add comprehensive README documentation for MariaDB Profiler

.github/workflows/demo-e2e.yml

@@ -17,8 +17,13 @@ on:
       - '.github/workflows/demo-e2e.yml'
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   demo-e2e:
+    if: github.event_name != 'pull_request' || !contains(github.event.pull_request.labels.*.name, 'no_run')
     name: Demo E2E (Docker + Selenium)
     runs-on: ubuntu-latest
     timeout-minutes: 20

.github/workflows/plugin-build.yml

@@ -12,8 +12,13 @@ on:
       - 'jetbrains-plugin/**'
       - '.github/workflows/plugin-build.yml'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
+    if: github.event_name != 'pull_request' || !contains(github.event.pull_request.labels.*.name, 'no_run')
     name: Build & Test Plugin
     runs-on: ubuntu-latest
 

.github/workflows/release.yml

@@ -160,12 +160,45 @@ jobs:
           name: php_mariadb_profiler-php${{ matrix.php }}-${{ matrix.ts }}-${{ matrix.arch }}
           path: dist\*.dll
 
+  # ---------------------------------------------------------------------------
+  # JetBrains Plugin build
+  # ---------------------------------------------------------------------------
+  build-plugin:
+    name: JetBrains Plugin
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Run tests
+        working-directory: jetbrains-plugin
+        run: ./gradlew test
+
+      - name: Build plugin
+        working-directory: jetbrains-plugin
+        run: ./gradlew buildPlugin
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: mariadb-profiler-viewer-plugin
+          path: jetbrains-plugin/build/distributions/*.zip
+          if-no-files-found: error
+
   # ---------------------------------------------------------------------------
   # Create GitHub Release
   # ---------------------------------------------------------------------------
   release:
     name: Create Release
-    needs: [build-linux, build-windows]
+    needs: [build-linux, build-windows, build-plugin]
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -181,7 +214,7 @@ jobs:
       - name: Collect release assets
         run: |
           mkdir -p release
-          find artifacts -type f \( -name "*.so" -o -name "*.dll" \) -exec cp {} release/ \;
+          find artifacts -type f \( -name "*.so" -o -name "*.dll" -o -name "*.zip" \) -exec cp {} release/ \;
           echo "=== Release assets ==="
           ls -lh release/
 

.github/workflows/tests.yml

@@ -6,8 +6,13 @@ on:
   pull_request:
     branches: ['**']
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test-cli:
+    if: github.event_name != 'pull_request' || !contains(github.event.pull_request.labels.*.name, 'no_run')
     name: CLI Tests (PHP ${{ matrix.php-version }})
     runs-on: ubuntu-latest
     strategy:
@@ -42,6 +47,7 @@ jobs:
         run: php tests/test_integration.php
 
   build-extension:
+    if: github.event_name != 'pull_request' || !contains(github.event.pull_request.labels.*.name, 'no_run')
     name: Build Extension (PHP ${{ matrix.php-version }})
     runs-on: ubuntu-latest
     strategy:

.github/workflows/windows-build.yml

@@ -12,8 +12,13 @@ on:
       - 'ext/**'
       - '.github/workflows/windows-build.yml'
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-windows:
+    if: github.event_name != 'pull_request' || !contains(github.event.pull_request.labels.*.name, 'no_run')
     name: Windows - PHP ${{ matrix.php }} ${{ matrix.ts }} ${{ matrix.arch }}
     runs-on: windows-${{ matrix.os }}
     defaults:

README.md

@@ -0,0 +1,147 @@
+# MariaDB Profiler for PHP
+
+A MariaDB/MySQL query profiler that runs as a PHP extension. It hooks into PHP's `mysqlnd` driver to intercept, record, and analyze all executed SQL queries.
+
+Works with any database access method that uses mysqlnd, including PDO, mysqli, and Laravel Eloquent.
+
+## IntelliJ Plugin Ready
+<img width="4012" height="2800" alt="ss0" src="https://github.com/user-attachments/assets/a38dbc5f-69ee-4f48-9aa1-e3fb0eb07de8" /><BR>
+<img width="3996" height="2436" alt="ss1" src="https://github.com/user-attachments/assets/460b75a9-996e-4c20-8e6f-818b4550f5d6" /><BR>
+<img width="3996" height="2436" alt="ss2" src="https://github.com/user-attachments/assets/78388037-728d-477b-bfba-1c3f75e0e1b0" />
+
+
+
+## Components
+
+| Component | Description |
+|---|---|
+| `ext/mariadb_profiler/` | PHP extension (C) |
+| `cli/` | CLI profiler management tool (PHP) |
+| `demo/` | Docker-based web demo (Laravel + WebSocket) |
+| `jetbrains-plugin/` | JetBrains IDE plugin (Kotlin) |
+
+## Features
+
+- **Query interception** — Captures all SQL queries at the mysqlnd level
+- **Context tags** — Stack-based tags to group queries by business logic
+- **PHP backtrace** — Records call stacks at configurable depth
+- **Prepared statement support** — Logs bound parameters (PHP 7.0+)
+- **SQL analysis** — Automatic extraction of table and column names
+- **Job management** — Concurrent profiling sessions with parent-child relationships
+- **Cross-platform** — Linux / macOS / Windows
+
+## Requirements
+
+| Component | Requirements |
+|---|---|
+| Extension | PHP 5.3 – 8.4+, mysqlnd |
+| CLI tool | PHP 5.3+, Composer |
+| Demo | Docker, Docker Compose |
+
+## Installation
+
+### Building the Extension
+
+```bash
+cd ext/mariadb_profiler
+phpize
+./configure --enable-mariadb_profiler
+make
+sudo make install
+```
+
+Add the following to php.ini:
+
+```ini
+extension=mariadb_profiler.so
+mariadb_profiler.enabled=1
+mariadb_profiler.log_dir=/var/log/mariadb_profiler
+```
+
+### CLI Tool
+
+```bash
+composer install
+```
+
+## Configuration (php.ini)
+
+```ini
+mariadb_profiler.enabled = 1            ; Enable the extension
+mariadb_profiler.log_dir = /tmp/mariadb_profiler  ; Log output directory
+mariadb_profiler.raw_log = 1            ; Write raw text logs
+mariadb_profiler.job_check_interval = 1 ; Interval to check jobs.json (seconds)
+mariadb_profiler.trace_depth = 0        ; Backtrace depth (0 = disabled)
+```
+
+## Usage
+
+### Managing Profiling Jobs
+
+```bash
+# Start a job
+php cli/mariadb_profiler.php job start [<key>]
+
+# End a job
+php cli/mariadb_profiler.php job end <key>
+
+# List jobs
+php cli/mariadb_profiler.php job list
+
+# Show parsed queries
+php cli/mariadb_profiler.php job show <key> [--tag=<tag>]
+
+# Show raw log
+php cli/mariadb_profiler.php job raw <key>
+
+# Export as JSON
+php cli/mariadb_profiler.php job export <key>
+
+# Show tag summary
+php cli/mariadb_profiler.php job tags <key>
+
+# Show caller summary
+php cli/mariadb_profiler.php job callers <key>
+
+# Purge completed jobs
+php cli/mariadb_profiler.php job purge
+```
+
+### Tagging Queries in PHP
+
+```php
+// Push a tag
+mariadb_profiler_tag('checkout_flow');
+
+// Queries executed here are tagged with 'checkout_flow'
+$db->query('SELECT * FROM orders WHERE user_id = ?');
+
+// Get the current tag
+$tag = mariadb_profiler_get_tag(); // 'checkout_flow'
+
+// Pop the tag
+mariadb_profiler_untag();
+```
+
+### Demo
+
+```bash
+cd demo
+docker compose up --build
+# Open http://localhost:8080
+```
+
+## PHP Function Reference
+
+| Function | Description |
+|---|---|
+| `mariadb_profiler_tag(string $tag): void` | Push a context tag onto the stack |
+| `mariadb_profiler_untag(?string $tag = null): ?string` | Pop a tag (optionally unwind to a specific tag) |
+| `mariadb_profiler_get_tag(): ?string` | Get the current tag (null if none) |
+
+## Log Formats
+
+Two files are generated per job:
+
+- `{job_key}.raw.log` — One query per line in text format (with timestamp, status, tag, and trace)
+- `{job_key}.jsonl` — Parsed JSON format with extracted table and column names