mdishtiaque/sql-shield repository overview

⁠SQL-Shield — Self-Healing Database Proxy

A high-performance, transparent database proxy that sits between your application and MySQL. It automatically caches SELECT queries in Redis and intelligently invalidates caches on INSERT, UPDATE, and DELETE — with zero code changes in your application.

Built with PHP 8.2+ and ReactPHP for non-blocking, asynchronous I/O.

⁠Features

• Transparent Proxy — Drop-in replacement. Just change your DB port from 3306 to 4000
• Automatic SELECT Caching — All read queries are cached in Redis with smart TTL
• Self-Healing Invalidation — Write queries automatically purge related cached data using table-level tagging
• Real-time Dashboard — Enterprise-grade monitoring UI with live charts, query analysis, and system health
• Zero Code Changes — No SDK, no library, no configuration in your app. Works with Laravel, WordPress, any MySQL client
• Production Ready — Docker image with compiled PHAR archives (source code protected)
• 7-Day Free Trial — Try it instantly with no license key required

⁠Quick Start (Docker)

⁠Prerequisites

• Docker installed
• A running MySQL server (v5.7+ or 8.x)
• A running Redis server (v6+)

⁠1. Pull the Image

docker pull mdishtiaque/sql-shield:latest

⁠2. Run SQL-Shield

Choose the method that matches your operating system:

⁠Linux / VPS (Recommended)

docker run -d \
  --name sql-shield \
  --network host \
  -e REAL_DB_HOST=127.0.0.1 \
  -e REAL_DB_PORT=3306 \
  -e REDIS_HOST=127.0.0.1 \
  -e REDIS_PORT=6379 \
  mdishtiaque/sql-shield:latest

--network host gives the container direct access to your machine's network. No port mapping needed — the proxy is available at localhost:4000 and the dashboard at localhost:8080.

⁠macOS / Windows (Docker Desktop)

docker run -d \
  --name sql-shield \
  -p 4000:4000 \
  -p 8080:8080 \
  -e REAL_DB_HOST=host.docker.internal \
  -e REAL_DB_PORT=3306 \
  -e REDIS_HOST=host.docker.internal \
  -e REDIS_PORT=6379 \
  mdishtiaque/sql-shield:latest

host.docker.internal is a special DNS name that points to your host machine from inside the container. This works automatically on Docker Desktop for Mac and Windows.

⁠Cloud / Remote Database

If your MySQL and Redis are on separate servers (e.g., AWS RDS, Redis Cloud):

docker run -d \
  --name sql-shield \
  -p 4000:4000 \
  -p 8080:8080 \
  -e REAL_DB_HOST=your-db-server.example.com \
  -e REAL_DB_PORT=3306 \
  -e REDIS_HOST=your-redis-server.example.com \
  -e REDIS_PORT=6379 \
  mdishtiaque/sql-shield:latest

Replace the hostnames with your actual database and Redis server addresses.

⁠3. Verify It's Running

# Check logs — you should see "TRIAL (7 days left)" and "Proxy listening"
docker logs sql-shield

# Test proxy connection
mysql -h 127.0.0.1 -P 4000 -u your_user -p

# Open the dashboard in your browser
# http://localhost:8080

⁠4. Point Your App to SQL-Shield

In your application's database config, change the port from 3306 to 4000. That's it.

Laravel .env example:

DB_HOST=127.0.0.1
DB_PORT=4000

WordPress wp-config.php example:

define('DB_HOST', '127.0.0.1:4000');

Node.js example:

const connection = mysql.createConnection({
  host: '127.0.0.1',
  port: 4000,
  user: 'your_user',
  password: 'your_password',
  database: 'your_db'
});

No other code changes needed. SQL-Shield works transparently with any MySQL client.

⁠Licensing

SQL-Shield includes a 7-day free trial that starts automatically when you first run the container — no license key required.

After the trial, you'll need a license key to continue using SQL-Shield. Purchase one at sql-shield.dev/pricing⁠.

⁠Running with a License Key

docker run -d \
  --name sql-shield \
  --network host \
  -e REAL_DB_HOST=127.0.0.1 \
  -e REAL_DB_PORT=3306 \
  -e REDIS_HOST=127.0.0.1 \
  -e REDIS_PORT=6379 \
  -e LICENSE_KEY="your-license-key-here" \
  mdishtiaque/sql-shield:latest

You'll receive your license key via email within 10 minutes of purchase.

⁠Manage the Container

# Stop the proxy
docker stop sql-shield

# Start it again
docker start sql-shield

# Restart
docker restart sql-shield

# View live logs
docker logs -f sql-shield

# Remove completely
docker rm -f sql-shield

⁠Environment Variables

⁠Exposed Ports

⁠How It Works

Your App (:4000)  ──►  SQL-Shield Proxy  ──►  MySQL (:3306)
                            │
                            ▼
                        Redis Cache

1. SELECT queries — Checked against Redis first. On cache HIT, the response is served directly from Redis (~0.3ms). On MISS, the query goes to MySQL, and the response is cached for future requests.

2. INSERT / UPDATE / DELETE — Forwarded to MySQL immediately, then SQL-Shield invalidates all cached queries related to the affected table(s).

3. Ignored queries — FOR UPDATE, FOR SHARE, Laravel Telescope tables, and prepared statements are passed through without caching.

⁠Dashboard

Access the enterprise monitoring dashboard at http://localhost:8080:

• System Health — MySQL and Redis connection status with latency
• KPI Metrics — Total queries, cache hits, misses, invalidations, time saved
• Efficiency Score — Real-time cache performance gauge (0-100)
• Live Throughput Chart — Hits vs Misses over time
• Query Mix — SELECT / INSERT / UPDATE / DELETE distribution
• Recent Queries Table — Last 50 queries with type, table, status badges, and duration
• Query Inspector — Click any query to view the full SQL
• Live Event Feed — Scrollable terminal log of all proxy events

⁠Laravel Integration (Recommended Settings)

For best caching performance with Laravel, enable emulated prepares in config/database.php:

'mysql' => [
    // ... existing config
    'options' => [
        PDO::ATTR_EMULATE_PREPARES => true,
    ],
],

This ensures SQL-Shield can intercept and cache all queries (including those using prepared statements).

⁠Docker Compose Example

For a complete setup with MySQL, Redis, and SQL-Shield all in one:

services:
  sql-shield:
    image: mdishtiaque/sql-shield:latest
    ports:
      - "4000:4000"
      - "8080:8080"
    environment:
      REAL_DB_HOST: mysql
      REAL_DB_PORT: "3306"
      REDIS_HOST: redis
      REDIS_PORT: "6379"
      LICENSE_KEY: "${LICENSE_KEY:-}"
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: myapp
    ports:
      - "3306:3306"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Run with: docker compose up -d

Your app connects to localhost:4000 instead of localhost:3306. Everything else stays the same.

⁠Architecture

• Runtime: PHP 8.2 CLI (Alpine Linux)
• Async I/O: ReactPHP event loop
• Cache: Redis via Predis
• Protocol: MySQL binary protocol (COM_QUERY interception)
• Process Manager: supervisord (proxy + dashboard)
• Code Protection: Compiled PHAR archives

⁠Support

• Email: [email protected]⁠
• Website: sql-shield.dev⁠

⁠License

Proprietary. All rights reserved.