feat: implement data replication plugin for external database sync

[MAVRICK-1]

Closes #72 /claim #72

Purpose

Implement a comprehensive data replication plugin for StarbaseDB that enables users to pull data from external databases (PostgreSQL, MySQL, etc.) into the internal SQLite database with configurable sync intervals and incremental updates.

This addresses the request for creating a "pull mechanism" to replicate data from external sources like Supabase PostgreSQL into StarbaseDB's edge-close SQLite replica.

https://github.com/user-attachments/assets/b44e78c6-0e76-4cde-a489-e4ab87e23a96

Tasks

• [x] Create DataReplicationPlugin following StarbaseDB plugin architecture
• [x] Implement external database connection support (PostgreSQL, MySQL, Hyperdrive)
• [x] Add incremental sync mechanism using tracking columns (id, created_at, updated_at)
• [x] Create configurable sync intervals per replication configuration
• [x] Build comprehensive REST API for replication management
• [x] Add real-time logging and monitoring system
• [x] Implement event callback system for external integrations
• [x] Create internal database tables for configuration and logs storage
• [x] Add proper error handling and graceful degradation
• [x] Write unit tests and comprehensive documentation
• [x] Register plugin in main application with event handling
• [x] Deploy and test on live Cloudflare Workers environment

Verify

🔍 Code Review Checklist

• Plugin Architecture: Verify adherence to StarbaseDB plugin patterns in plugins/data-replication/index.ts
• External Database Security: Review credential handling and SQL injection prevention
• API Endpoints: Test all 7 REST endpoints with proper authentication
• TypeScript Types: Validate type safety and interface compliance
• Error Handling: Ensure graceful degradation and comprehensive logging

🧪 Testing Steps

1. Build & Deploy: npm run build && npx wrangler deploy
2. Configure Replication:

   curl -X POST https://starbasedb.mavrickrishi.workers.dev/data-replication/configure \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ABC123" \
     -d '{"name":"test","sourceConfig":{"dialect":"postgresql","host":"demo.supabase.co","port":5432,"user":"postgres","password":"demo-pass","database":"postgres"},"targetTable":"users","sourceTable":"users","syncIntervalMinutes":30,"trackingColumn":"updated_at"}'
   

3. Check Status: curl -X GET https://starbasedb.mavrickrishi.workers.dev/data-replication/status -H "Authorization: Bearer ABC123"
4. Monitor Logs: View Cloudflare Workers dashboard for real-time sync events

📊 Performance Verification

• Memory: Plugin reuses existing connection infrastructure (minimal overhead)
• Scalability: Supports multiple concurrent replication configurations
• Efficiency: Incremental sync with WHERE clause filtering

Before

GitHub Issue #72 Request:

• No data replication functionality
• No external database sync capability
• Manual data management required
• No edge-close replica creation

StarbaseDB Plugin Ecosystem:

plugins/
├── cdc/           # Change Data Capture
├── cron/          # Scheduled tasks  
├── query-log/     # Query logging
├── stats/         # System statistics
└── [missing data replication]

After

✅ Complete Data Replication System:

🔌 New Plugin Added

plugins/data-replication/
├── index.ts       # Main plugin (475+ lines)
├── index.test.ts  # Unit tests (3 passing)
├── meta.json      # Plugin metadata
└── README.md      # Comprehensive docs

🚀 Live Deployment

• URL: https://starbasedb.mavrickrishi.workers.dev
• Status: ✅ Successfully deployed and tested
• Plugin: ✅ Registered and running

📡 7 New API Endpoints

• POST /data-replication/configure - Set up replication
• POST /data-replication/start/:name - Start specific replication
• POST /data-replication/stop/:name - Stop specific replication
• POST /data-replication/sync/:name - Manual sync trigger
• GET /data-replication/status - View all configurations
• GET /data-replication/logs - Sync operation logs
• DELETE /data-replication/configure/:name - Remove config

💾 Database Schema

Two new internal tables created:

• tmp_replication_configs - Store replication settings
• tmp_replication_logs - Track sync operations and performance

🔄 Working Demo

# ✅ TESTED: Configuration successful
{"result":{"success":true,"message":"Replication configured successfully"}}

# ✅ TESTED: Status shows active replication
{"result":{"configs":[{"name":"supabase-users","is_running":true,"sync_interval_minutes":30}]}}

🎯 Issue Requirements Met

✅ Pull mechanism for external databases
✅ Configurable sync intervals
✅ Table-specific replication
✅ Incremental updates via tracking columns
✅ Supabase PostgreSQL support
✅ Edge-close SQLite replica creation
✅ wrangler.toml configuration support

[MAVRICK-1]

cc @Brayden

[MAVRICK-1]