FEATURE: Add SQL plugin support

Signed-off-by: Pascal Zimmermann <pascal.zimmermann@theiotstudio.com>

Author: ZPascal

sql/Makefile

@@ -0,0 +1,113 @@
+# Makefile for SQL Plugin Testing
+
+.PHONY: help test test-watch test-coverage db-up db-down db-restart db-logs db-clean unit-tests integration-tests
+
+help: ## Show this help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+# Database Management
+db-up: ## Start all test databases
+	docker-compose -f docker-compose.test.yaml up -d
+	@echo "Waiting for databases to be ready..."
+	@sleep 10
+	@echo "Databases are ready!"
+	@echo ""
+	@echo "PostgreSQL: localhost:5432"
+	@echo "MySQL:      localhost:3306"
+	@echo "MariaDB:    localhost:3307"
+	@echo "Adminer UI: http://localhost:8080"
+
+db-down: ## Stop all test databases
+	docker-compose -f docker-compose.test.yaml down
+
+db-restart: ## Restart all test databases
+	docker-compose -f docker-compose.test.yaml restart
+
+db-logs: ## Show database logs
+	docker-compose -f docker-compose.test.yaml logs -f
+
+db-clean: ## Stop and remove all databases and volumes
+	docker-compose -f docker-compose.test.yaml down -v
+	@echo "All database containers and volumes removed"
+
+db-status: ## Show status of database containers
+	docker-compose -f docker-compose.test.yaml ps
+
+# Testing
+unit-tests: ## Run unit tests
+	npm test -- replace-sql-builtin-variables.test.ts
+
+test: ## Run all tests
+	npm test
+
+test-watch: ## Run tests in watch mode
+	npm test -- --watch
+
+test-coverage: ## Run tests with coverage report
+	npm test -- --coverage
+
+test-verbose: ## Run tests with verbose output
+	npm test -- --verbose
+
+# Database Verification
+verify-postgres: ## Verify PostgreSQL test data
+	docker exec -it perses-sql-test-postgres psql -U perses -d perses_test -c "\
+		SELECT 'system_metrics' as table_name, COUNT(*) as row_count FROM system_metrics \
+		UNION ALL SELECT 'sensor_readings', COUNT(*) FROM sensor_readings \
+		UNION ALL SELECT 'http_requests', COUNT(*) FROM http_requests \
+		UNION ALL SELECT 'transactions', COUNT(*) FROM transactions;"
+
+verify-mysql: ## Verify MySQL test data
+	docker exec -it perses-sql-test-mysql mysql -u perses -pperses_test_password perses_test -e "\
+		SELECT 'system_metrics' as table_name, COUNT(*) as row_count FROM system_metrics \
+		UNION ALL SELECT 'sensor_readings', COUNT(*) FROM sensor_readings \
+		UNION ALL SELECT 'http_requests', COUNT(*) FROM http_requests \
+		UNION ALL SELECT 'transactions', COUNT(*) FROM transactions;"
+
+verify-mariadb: ## Verify MariaDB test data
+	docker exec -it perses-sql-test-mariadb mysql -u perses -pperses_test_password perses_test -e "\
+		SELECT 'system_metrics' as table_name, COUNT(*) as row_count FROM system_metrics \
+		UNION ALL SELECT 'sensor_readings', COUNT(*) FROM sensor_readings \
+		UNION ALL SELECT 'http_requests', COUNT(*) FROM http_requests \
+		UNION ALL SELECT 'transactions', COUNT(*) FROM transactions;"
+
+verify-all: verify-postgres verify-mysql verify-mariadb ## Verify all databases
+
+# Development
+dev-setup: db-up ## Complete development setup
+	npm install
+	@echo ""
+	@echo "✅ Development environment ready!"
+	@echo "Run 'make test' to run tests"
+	@echo "Run 'make test-watch' for watch mode"
+
+clean-all: db-clean ## Clean everything (databases, node_modules, dist)
+	rm -rf node_modules dist
+
+# Quick commands
+quick-test: db-up test ## Start databases and run tests
+
+integration: db-up verify-all ## Start databases and verify data
+	@echo ""
+	@echo "✅ Integration test environment ready!"
+
+# Install dependencies
+install: ## Install npm dependencies
+	npm install
+
+build: ## Build the plugin
+	npm run build
+
+lint: ## Run linter
+	npm run lint
+
+type-check: ## Run TypeScript type checking
+	npm run type-check
+
+# Complete test workflow
+full-test: clean-all install db-up verify-all test test-coverage ## Complete test workflow
+	@echo ""
+	@echo "✅ Full test workflow completed!"

sql/PR_READINESS.md

@@ -0,0 +1,220 @@
+# SQL Plugin
+
+A SQL datasource plugin for Perses that supports multiple SQL databases with interactive querying capabilities.
+
+## Supported Databases
+
+- **PostgreSQL** (with TimescaleDB support)
+- **MySQL**
+- **MariaDB**
+
+## Features
+
+- **SQL Datasource**: Configure connections to SQL databases via Perses proxy
+- **Time Series Queries**: Query time-series data with automatic visualization
+- **Explore Mode**: Interactive SQL query builder with Table and Graph views (Prometheus-style)
+- **SQL Macros**: Use `$__timeFilter`, `$__timeFrom`, `$__timeTo`, `$__interval` in queries
+- **Multi-Database Support**: Connect to PostgreSQL, MySQL, and MariaDB
+- **TLS/SSL Support**: Secure connections with customizable SSL modes and certificate management
+- **Secret Management**: Store credentials securely using Perses secrets
+- **Connection Pooling**: Efficient connection management via backend proxy
+
+## Installation
+
+This plugin is part of the Perses plugins monorepo. Install dependencies:
+
+```bash
+cd perses/plugins/sql
+npm install
+```
+
+## Usage
+
+### Creating a SQL Datasource
+
+1. Navigate to **Configuration → Datasources** in Perses UI
+2. Click **Add Datasource**
+3. Select **SQL Datasource**
+4. Configure:
+   - **Driver**: Choose database type (PostgreSQL, MySQL, or MariaDB)
+   - **Host**: Database host and port (e.g., `localhost:5432`)
+   - **Database**: Database name
+   - **Secret**: Select a secret containing credentials (BasicAuth)
+   - **SSL Mode** (PostgreSQL): `disable`, `require`, `verify-ca`, or `verify-full`
+   - **TLS Certificates** (optional): CA cert, client cert, client key
+
+### Using the Explore Mode
+
+1. Navigate to **Explore** in Perses UI
+2. Select **SQL Explorer**
+3. Choose your SQL datasource
+4. Write your SQL query in the editor
+5. Switch between **Table** and **Graph** views
+6. Click **Run Query** to execute
+
+Example query:
+```sql
+SELECT 
+  timestamp AS time,
+  cpu_percent AS value,
+  host
+FROM system_metrics
+WHERE $__timeFilter(timestamp)
+ORDER BY timestamp DESC
+LIMIT 100
+```
+
+### Time Series Queries in Dashboards
+
+Add a panel to your dashboard:
+
+1. **Add Panel**
+2. Select **Query Type**: Time Series Query
+3. Select **Plugin**: SQL Time Series Query
+4. Select **Datasource**: Your SQL datasource
+5. Write your query:
+
+```sql
+SELECT 
+  time_bucket('$__interval seconds', timestamp) AS time,
+  host AS label,
+  AVG(cpu_percent) AS value
+FROM system_metrics
+WHERE $__timeFilter(timestamp)
+GROUP BY time, host
+ORDER BY time
+```
+
+### Available SQL Macros
+
+The plugin automatically replaces these macros in your queries:
+
+- **`$__timeFilter(column)`**: Generates `column >= 'start' AND column <= 'end'`
+- **`$__timeFrom`**: Start timestamp of the time range
+- **`$__timeTo`**: End timestamp of the time range  
+- **`$__interval`**: Calculated interval in seconds (for time bucketing)
+- **`$__interval_ms`**: Calculated interval in milliseconds
+
+Example with macros:
+```sql
+SELECT 
+  time_bucket('$__interval seconds', created_at) AS time,
+  category,
+  COUNT(*) AS count
+FROM transactions
+WHERE $__timeFilter(created_at)
+  AND status = 'completed'
+GROUP BY time, category
+ORDER BY time
+```
+
+Gets transformed to:
+```sql
+SELECT 
+  time_bucket('300 seconds', created_at) AS time,
+  category,
+  COUNT(*) AS count
+FROM transactions
+WHERE created_at >= '2026-01-25T10:00:00Z' AND created_at <= '2026-01-25T11:00:00Z'
+  AND status = 'completed'
+GROUP BY time, category
+ORDER BY time
+```
+
+## Query Requirements
+
+### For Time Series Visualization
+
+Your query must return:
+- **Time column**: Named `time` or aliased as `time` (timestamp format)
+- **Value column**: Named `value` or aliased as `value` (numeric)
+- **Label columns** (optional): For series differentiation (e.g., `host`, `sensor_id`)
+
+### Supported Time Formats
+
+- ISO 8601: `2026-01-25T10:00:00Z`
+- Unix timestamp (seconds): `1706176800`
+- Unix timestamp (milliseconds): `1706176800000`
+
+## Database-Specific Features
+
+### PostgreSQL / TimescaleDB
+
+- Supports `time_bucket()` for time aggregation
+- SSL modes: `disable`, `require`, `verify-ca`, `verify-full`
+- Advanced connection options via PostgreSQL config
+
+### MySQL / MariaDB
+
+- Standard SQL queries
+- TLS/SSL support
+- Connection timeout and max connections configuration
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 22
+- npm >= 10
+- Docker (for test databases)
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Start test databases
+make db-up
+
+# Run tests
+npm test
+
+# Type checking
+npm run type-check
+
+# Start development server
+percli plugin start .
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+
+# Start test databases
+make db-up
+
+# Verify test data
+make verify-all
+
+# Stop databases
+make db-down
+```
+
+## Architecture
+
+- **Frontend** (TypeScript/React): Datasource editor, query editor, explore mode
+- **Backend** (Go): SQL proxy in Perses core (`internal/api/impl/proxy/`)
+- **Schemas** (CUE): Configuration validation
+
+All database connections and query execution happen server-side via the Perses backend proxy for security.
+
+## Examples
+
+See `test-data/` directory for sample database schemas and queries:
+- `test-data/postgres/` - PostgreSQL with TimescaleDB examples
+- `test-data/mysql/` - MySQL examples  
+- `test-data/mariadb/` - MariaDB examples
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+## License
+
+Apache License 2.0

sql/README.md

@@ -0,0 +1,17 @@
+module: "github.com/perses/plugin/sql@v0"
+language: {
+	version: "v0.9.2"
+}
+source: {
+	kind: "git"
+}
+deps: {
+	"github.com/perses/perses/cue@v0": {
+		v:       "v0.53.0-rc.0"
+		default: true
+	}
+	"github.com/perses/shared/cue@v0": {
+		v:       "v0.53.0-rc.1"
+		default: true
+	}
+}