WorkerSQL

WorkerSQL Logo

MySQL-compatible edge database platform built on Cloudflare Workers

Features • Quick Start • API Reference • Documentation • Contributing

Overview

WorkerSQL is a high-performance, MySQL-compatible edge database platform that brings your data closer to your users. Built on Cloudflare Workers, it provides:

Edge-native architecture with sub-50ms query latency globally
MySQL compatibility for seamless migration from existing applications
Automatic scaling with zero cold starts
Multi-tenant isolation with built-in security
Real-time caching with cache-aside pattern implementation
ACID transactions via Durable Objects

Features

🚀 Performance

Sub-50ms latency globally via Cloudflare’s edge network
Intelligent caching with configurable TTL and stale-while-revalidate
Connection pooling and query optimization
Automatic shard management based on data size and access patterns

🔒 Security

JWT-based authentication with role-based access control (RBAC)
Tenant isolation ensuring complete data separation
SQL injection prevention with parameterized queries
Encryption at rest and in transit using industry standards
Audit logging for compliance and monitoring

🛠 Developer Experience

MySQL-compatible SQL - use existing tools and knowledge
RESTful API with comprehensive OpenAPI specification
WebSocket support for real-time updates
Multi-language SDKs (JavaScript/TypeScript, Python, PHP)
Local development tools with Miniflare integration

📊 Monitoring & Observability

Real-time metrics and performance monitoring
Health checks and status endpoints
Detailed logging with configurable levels
Integration ready for external monitoring tools

Quick Start

Prerequisites

Node.js 18+ and npm
Cloudflare account with Workers enabled
Wrangler CLI installed globally

Installation

# Clone the repository
git clone https://github.com/healthfees-org/workersql.git
cd workersql

# Install dependencies
npm install

# Set up development environment
npm run setup:dev

# Start local development server
npm run dev

Basic Usage

# Test the health endpoint
curl http://localhost:8787/health

# Execute a SQL query
curl -X POST http://localhost:8787/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "sql": "SELECT * FROM users WHERE active = ?",
    "params": [true]
  }'

API Reference

Authentication

All API requests require a valid JWT token:

Authorization: Bearer <jwt_token>

Core Endpoints

Method	Endpoint	Description
`POST`	`/v1/query`	Execute SQL query
`POST`	`/v1/query/batch`	Execute multiple queries
`POST`	`/v1/transactions`	Begin transaction
`POST`	`/v1/transactions/{id}/commit`	Commit transaction
`POST`	`/v1/transactions/{id}/rollback`	Rollback transaction
`GET`	`/v1/schema`	Get database schema
`GET`	`/v1/health`	Health check
`GET`	`/v1/metrics`	Performance metrics

Example Query

{
  "sql": "SELECT * FROM products WHERE price > ? AND category = ?",
  "params": [100, "electronics"],
  "hints": {
    "consistency": "strong",
    "cacheTtl": 300000,
    "shardKey": "tenant_123"
  }
}

Response Format

{
  "success": true,
  "data": {
    "rows": [...],
    "rowsAffected": 1,
    "insertId": 123,
    "metadata": {
      "fromCache": false,
      "shardId": "shard_0",
      "executionTimeMs": 15
    }
  }
}

Client SDKs

JavaScript/TypeScript

import { WorkerSQL } from '@workersql/client';

const db = new WorkerSQL({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.workersql.com',
});

const users = await db.query('SELECT * FROM users WHERE id = ?', [123]);

Python

from workersql import Client

db = Client(api_key='your-api-key')
result = db.query('SELECT * FROM users WHERE id = %s', [123])

PHP

<?php
use WorkerSQL\Client;

$db = new Client(['api_key' => 'your-api-key']);
$result = $db->query('SELECT * FROM users WHERE id = ?', [123]);

Architecture

WorkerSQL is built on a distributed architecture optimized for edge computing:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client SDK    │────│  Edge Gateway   │────│  Durable Object │
│                 │    │   (Workers)     │    │     Shards      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                       ┌─────────────────┐
                       │   KV Cache      │
                       │   & Queues      │
                       └─────────────────┘

Key Components

Edge Gateway: Request routing, authentication, and caching
Durable Object Shards: ACID-compliant data storage
KV Cache: High-performance query result caching
Event Queues: Asynchronous operations and cache invalidation
Connection Manager: Efficient connection pooling and management

Development

Setup Development Environment

# Install dependencies
npm install

# Set up pre-commit hooks
npm run prepare

# Configure Wrangler
cp wrangler.toml.template wrangler.toml
wrangler auth login

# Create Cloudflare resources
npm run setup:cloudflare

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Code Quality

# Lint code
npm run lint

# Format code
npm run format

# Type checking
npm run type-check

# Complete quality check
npm run workflow:check

Local Development

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Deploy to staging
npm run deploy:staging

Documentation

Deployment

Environment Setup

Development: Local testing with Miniflare
Staging: Pre-production testing environment
Production: Live production deployment

Deployment Commands

# Deploy to staging
wrangler deploy --env staging

# Deploy to production
wrangler deploy --env production

# View deployment logs
wrangler tail --env production

Environment Variables

Variable	Description	Default
`ENVIRONMENT`	Deployment environment	`development`
`LOG_LEVEL`	Logging verbosity	`info`
`MAX_SHARD_SIZE_GB`	Maximum shard size	`10`
`CACHE_TTL_MS`	Cache TTL in milliseconds	`300000`
`JWT_SECRET`	JWT signing secret	(required)

Performance

Benchmarks

Query Latency: <50ms globally (p95)
Throughput: 10,000+ queries/second per edge location
Cache Hit Rate: 85%+ for typical workloads
Cold Start: 0ms (edge-native architecture)

Optimization Tips

Use appropriate cache TTL for your data freshness requirements
Optimize shard keys for even data distribution
Batch related queries to reduce round trips
Use read replicas for analytics workloads

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch
Make your changes with tests
Run npm run workflow:check
Submit a pull request

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

Community

Commercial Support

For enterprise support, SLA guarantees, and custom development:

📧 Sales: [email protected]
📧 Support: [email protected]
🔒 Security: [email protected]

Roadmap

Current (Q3 2025)

✅ Core SQL compatibility
✅ Authentication & authorization
✅ Multi-tenant isolation
✅ Real-time caching

Upcoming (Q4 2025)

🔄 Advanced analytics queries
🔄 Cross-region replication
🔄 GraphQL API support
🔄 Enhanced monitoring dashboard

Future (Q1+ 2026)

📋 Full-text search capabilities
📋 Advanced encryption features
📋 Machine learning integrations

Acknowledgments

Built on Cloudflare Workers
Inspired by PlanetScale and Neon
Thanks to all contributors

Made with ❤️ by the HealthFees team

Website • Blog • Twitter