blueits-sqlapi

Version: 1.0.31 Last Updated: 2025-10-06 Repository: https://github.com/BLUEITS-GmbH/blueits-sqlapi

A production-ready MySQL/SQL API server with REST endpoints, semantic versioning, request tracing, and comprehensive developer tooling.

Features

• 🔄 API Versioning: Per-method semantic versioning with tolerance
• 📊 Request Tracing: Correlation-ID support for distributed tracing
• 🔍 Debug Mode: Connection info, timing metrics, query analysis
• 🔐 Security: Prepared statements, password masking, error sanitization
• 🌐 Web Interface: Interactive query testing in the browser
• ⚙️ Systemd Integration: Production-ready Linux service deployment
• 📝 Comprehensive Logging: Structured logs with configurable levels and formats

Quick Start

Run Immediately with npx

# Run with default settings (localhost:3307)
npx blueits-sqlapi

# Run with custom port and bind address
npx blueits-sqlapi --port=8000 --bind=0.0.0.0

Global Installation

# Install globally
npm install -g blueits-sqlapi

# Run
blueits-sqlapi

Production Deployment (Linux)

# Interactive systemd service installation
sudo npx blueits-sqlapi --install-service

# Unattended installation (for automation)
sudo npx blueits-sqlapi --install-service --unattended \
  --db-host=localhost \
  --db-name=myapp \
  --db-user=root \
  --db-password=secret

Prerequisites

• Node.js: v14 or higher
• MySQL: v5.7/v8.0 or MariaDB
• Linux with systemd: For service installation (Debian/Ubuntu tested)

Installing Node.js on Debian/Ubuntu

# Update package index
sudo apt update

# Install Node.js (recommended: use NodeSource for latest LTS)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install nodejs

# Verify installation
node --version
npm --version
npx --version

Basic Usage

API Request Example

curl -X POST http://localhost:3307/api/sql/query \
  -H "Content-Type: application/vnd.blueits.sql.query+json;version=1.0" \
  -H "X-Correlation-ID: $(uuidgen)" \
  -d '{
    "user": "root",
    "password": "secret",
    "database": "mydb",
    "query": "SELECT * FROM users WHERE age > ?",
    "params": [18]
  }'

Web Interface

Open your browser and navigate to:

http://localhost:3307/api/sql/query

CLI Options

# Server options
--port=NUMBER         # Server port (default: 3307)
--bind=STRING         # Bind address (default: 127.0.0.1)

# Database options
--db-host=STRING      # Database host
--db-port=NUMBER      # Database port (default: 3306)
--db-user=STRING      # Database user
--db-password=STRING  # Database password
--db-name=STRING      # Database name

# Service options (Linux only)
--install-service     # Install as systemd service
--uninstall-service   # Remove systemd service
--unattended          # Skip prompts (for automation)
--skip-service-check  # Skip service installation prompt

# General
--help, -h           # Show help message

Service Management (Linux)

# View logs
sudo journalctl -u blueits-sqlapi -f

# Restart service
sudo systemctl restart blueits-sqlapi

# Stop service
sudo systemctl stop blueits-sqlapi

# Check status
sudo systemctl status blueits-sqlapi

# Uninstall service
sudo npx blueits-sqlapi --uninstall-service

Documentation

• 📖 DEVELOPER.md - Complete technical documentation, API reference, versioning guide
• 🤝 CONTRIBUTING.md - Development setup, release process, contribution guidelines
• 📝 CHANGELOG.md - Version history and release notes

API Versioning

This project uses semantic versioning with per-method version tolerance. Clients can specify API versions via:

• Content-Type header: application/vnd.blueits.sql.query+json;version=1.0
• Accept header: application/vnd.blueits.sql.query+json;version=1.0
• Custom header: X-API-Version: 1.0

Version tolerance allows partial versions (e.g., 1.0) to automatically resolve to the latest patch (e.g., 1.0.2).

See DEVELOPER.md for complete versioning specifications and examples.

Request Tracing

All requests support Correlation-ID for distributed tracing:

# Provide your own Correlation-ID
curl -H "X-Correlation-ID: your-uuid-here" ...

# Server generates one if not provided
# Check response header: X-Correlation-ID

Debug Mode

Enable debug information via headers:

curl -H "X-SQL-Debug: true" \
     -H "X-Connection-Info: true" \
     -H "X-Query-Analysis: true" ...

Response includes:

• Connection details (mysql://user:***@host:port/db)
• Query execution timing
• Query analysis and optimization hints

See DEVELOPER.md for complete debug documentation.

Security

• ✅ Prepared Statements: Prevent SQL injection
• ✅ Password Masking: Automatic masking in logs
• ✅ Connection Isolation: Per-request database connections
• ✅ Error Sanitization: Safe error messages
• ✅ Request Validation: Input validation on all endpoints
• ✅ Systemd Hardening: Service runs as unprivileged user with restrictions

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development workflow and setup
• Building and testing locally
• Release process and versioning
• Code standards and commit conventions
• How to submit pull requests

Support

• Issues: GitHub Issues
• Documentation: DEVELOPER.md for technical details
• Changelog: CHANGELOG.md for version history

License

ISC License - see LICENSE file for details.

Project Links

• GitHub: BLUEITS-GmbH/blueits-sqlapi
• npm: blueits-sqlapi