sagrmore/indexpilot

Framework-independent SQL index analysis and query optimization toolkit with first-class Laravel integration

v1.0.0 2026-07-15 12:48 UTC

Requires

• php: ^8.1
• greenlion/php-sql-parser: ^4.7
• illuminate/support: ^10.0|^11.0|^12.0|^13.0
• psr/log: ^3.0
• symfony/console: ^6.4 || ^7.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.0
• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.5.35|^11.5
• rector/rector: ^2.0

Suggests

• ext-pdo: Required for database driver implementations
• ext-pdo_mysql: Required for MySQL and MariaDB drivers
• ext-pdo_pgsql: Required for the PostgreSQL driver
• ext-pdo_sqlite: Required for the SQLite driver
• ext-pdo_sqlsrv: Required for the SQL Server driver (with ODBC Driver 18)

MIT

• Sagar

• database
• performance
• cli
• mysql
• sqlite
• postgresql
• sqlserver
• optimization
• laravel
• index
• mariadb
• explain
• sarif
• query-analysis

Published on Packagist.org on 2026-07-16 05:23 UTC

README

Framework-independent SQL index analysis and query optimization toolkit with first-class Laravel integration.

IndexPilot analyzes SQL workloads, applies explainable recommendation rules, and renders reports (JSON, Markdown, HTML, SARIF, console) for local development and CI.

User documentation: start with the Enterprise User Guide — install, DB connection, Eloquent vs plain SQL, reports, CI, and production posture.

Requirements

Component	Version
PHP	8.1, 8.2, 8.3, 8.4
Laravel (optional)	10.x, 11.x, 12.x, 13.x

Database engines

Engine	Status
MySQL 8+	Production (reference driver)
MariaDB 10.5+	Production (first-class driver)
PostgreSQL 13+	Production
SQLite 3.35+	Production (embedded / local)
SQL Server 2019+	Production (pdo_sqlsrv)

See docs/engineering/DATABASE_SUPPORT_MATRIX.md and docs/certification/.

Installation

composer require sagrmore/indexpilot

Laravel auto-discovers the service provider and IndexPilot facade.

Publish config (optional):

php artisan vendor:publish --tag=indexpilot-config

Standalone CLI (Composer bin):

vendor/bin/indexpilot version
vendor/bin/indexpilot doctor

Quick Start

PHP API

use IndexPilot\Laravel\Facades\IndexPilot;

$result = IndexPilot::analyze('SELECT id FROM users WHERE email = ?', ['[e-mail]']);
echo $result->getScore();

$report = IndexPilot::builder()
    ->queries(['SELECT * FROM orders WHERE status = ?'])
    ->toReport('markdown');

Artisan

php artisan indexpilot:analyze "SELECT * FROM users WHERE email = ?" --format=json
php artisan indexpilot:report --file=workload.sql --format=sarif --output=storage/app/indexpilot.sarif
php artisan indexpilot:doctor
php artisan indexpilot:rules

Standalone CLI

vendor/bin/indexpilot analyze --file=queries.sql --format=sarif --fail-on-findings
vendor/bin/indexpilot report --stdin --format=html --output=report.html

Configuration

Variable	Default	Description
INDEXPILOT_ENABLED	true	Master package switch
INDEXPILOT_CONNECTION	null	Database connection for analysis
INDEXPILOT_COLLECTOR_ENABLED	false	Enable Laravel query listener
INDEXPILOT_MIN_CONFIDENCE	0.5	Minimum recommendation confidence
INDEXPILOT_REDACT_BINDINGS	true	Redact sensitive binding values

Full schema: config/indexpilot.php.
Operators: see the Enterprise User Guide for end-to-end usage.

Documentation

Guide	Path
Enterprise User Guide	docs/user-guide.md
Laravel integration	docs/laravel-integration.md
CLI design	docs/engineering/cli-design.md
Reporting	docs/engineering/reporting-engine.md
Release readiness	docs/engineering/release-readiness-review.md
Database support matrix	docs/engineering/DATABASE_SUPPORT_MATRIX.md
MySQL certification	docs/certification/mysql.md
MariaDB certification	docs/certification/mariadb.md
PostgreSQL certification	docs/certification/postgresql.md
SQLite certification	docs/certification/sqlite.md
SQL Server certification	docs/certification/sqlserver.md
Troubleshooting	docs/troubleshooting.md
Upgrade notes	docs/UPGRADE.md
Architecture / ADRs	docs/ · docs/adr/

Architecture

Hexagonal layout: framework-agnostic core + thin Laravel/CLI adapters. Architecture status: FROZEN (see docs/engineering/PROJECT_STATE.md).

Testing

composer test              # Unit + Feature + Contract + Integration + Architecture + Regression
composer test:unit
composer test:feature
composer test:architecture
composer test:regression   # Golden recommendation suite
composer test:benchmark    # Opt-in: INDEXPILOT_RUN_BENCHMARKS=true
composer quality           # Local maintainer gate (includes Pint)
composer quality:ci        # CI-oriented gate without format rewrites

CI matrix: PHP 8.1–8.4 × Laravel 10–13, plus mandatory database integration gates:

Job	Service / notes
MySQL 8 Integration	mysql:8.0
MariaDB 10.11 Integration	mariadb:10.11
PostgreSQL 16 Integration	postgres:16
SQLite Integration	pdo_sqlite (:memory: / DSN)
SQL Server 2022 Integration	mcr.microsoft.com/mssql/server:2022-CU25-ubuntu-22.04 + pdo_sqlsrv

Live DB tests require:

Engine	Variables
MySQL	INDEXPILOT_TEST_MYSQL_DSN, INDEXPILOT_TEST_MYSQL_USER, INDEXPILOT_TEST_MYSQL_PASSWORD
MariaDB	INDEXPILOT_TEST_MARIADB_DSN, INDEXPILOT_TEST_MARIADB_USER, INDEXPILOT_TEST_MARIADB_PASSWORD
PostgreSQL	INDEXPILOT_TEST_PGSQL_DSN, INDEXPILOT_TEST_PGSQL_USER, INDEXPILOT_TEST_PGSQL_PASSWORD
SQLite	INDEXPILOT_TEST_SQLITE_DSN (optional; default sqlite::memory:)
SQL Server	INDEXPILOT_TEST_SQLSRV_DSN, INDEXPILOT_TEST_SQLSRV_USER, INDEXPILOT_TEST_SQLSRV_PASSWORD, INDEXPILOT_TEST_SQLSRV_DATABASE

Known limitations (v1.0.0)

• IndexPilot::extend() is not implemented yet
• Standalone CLI --engine is a connection hint without opening a live PDO driver by itself
• PHP CLI config files are executed via require and must be trusted (prefer JSON in CI)

Contributing

Please read CONTRIBUTING.md before submitting a pull request.

Security

If you discover a security vulnerability, please review our SECURITY.md policy.

License

The MIT License (MIT). See LICENSE for details.