🧪 SandboxDB — Portable Micro-Databases

SandboxDB is a CLI-first SaaS for extracting safe, minimal, and shareable database slices.

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Quick setup - installs dependencies and builds all packages
npm run setup

# Start development servers (both web app and API server)
npm run dev
# Web app: http://localhost:3000
# API server: http://localhost:3001

# Test CLI
npm run test-cli

CLI Usage

# Use the CLI directly
npm run cli -- --help
npm run cli -- source add prod --url "postgres://readonly@db.prod"
npm run cli -- extract --source prod --tables users,orders --limit-per-table 100
npm run cli -- share slice.duckdb --ttl 24h --mode writable

Development

# Start web dashboard only
npm run dev:web
# Open http://localhost:3000

# Start API server only
npm run dev:server
# Server runs on http://localhost:3001

# Build all packages
npm run build

# Type check all packages
npm run type-check

📁 Project Structure

sandboxdb/
├── packages/
│   ├── cli/                 # Commander.js CLI tool
│   ├── web/                 # Next.js dashboard with shadcn/ui
│   ├── core/                # Business logic (extraction, masking, etc.)
│   └── types/               # Shared TypeScript definitions
├── apps/
│   └── server/              # Fastify API server
└── docs/                    # Documentation

🛠 Development

Build System

• Turborepo for monorepo management
• TypeScript for type safety
• tsup for CLI bundling
• Next.js for web app
• Fastify for API server

CLI Stack

• Commander.js - Command framework
• enquirer - Interactive prompts
• keytar - Secure credential storage
• chalk + ora - Beautiful output

Web Stack

• Next.js 14 with App Router
• shadcn/ui components
• Tailwind CSS styling
• Zustand state management
• Monaco Editor for SQL

Backend Stack

• Fastify web framework
• Drizzle ORM + PostgreSQL
• Bull job queues
• JWT authentication

🎯 Key Features

Database Extraction

• ✅ Multi-database support (Postgres, MySQL, SQLite)
• ✅ Schema discovery with relationship mapping
• ✅ Referential integrity preservation
• ✅ Configurable row limits and filtering

Data Privacy

• ✅ PII masking with configurable profiles
• ✅ Read-only source connections
• ✅ Data transformation pipeline

Sharing & Collaboration

• ✅ Portable file exports (DuckDB, SQLite)
• ✅ Ephemeral hosted Postgres sandboxes
• ✅ TTL-based cleanup
• ✅ Role-based access control

Version Control

• ✅ Sandbox snapshots
• ✅ Diff visualization
• ✅ Rollback capabilities
• ✅ Promotion to reusable slices

🔧 Configuration

CLI Config (~/.sandboxdb/config.json)

{
  "apiUrl": "https://api.sandboxdb.com",
  "defaultMaskingProfile": "pii-defaults",
  "defaultOutputFormat": "duckdb"
}

Project Config (.sandboxdbrc)

{
  "defaultSource": "production",
  "defaultTables": ["users", "orders"],
  "maskingProfile": "demo-friendly"
}

📚 Commands

Core Workflow

• sandboxdb source add/list/remove/test - Manage database sources
• sandboxdb plan - Preview extraction plan
• sandboxdb extract - Extract database slice
• sandboxdb share - Create shareable sandbox

Sandbox Operations

• sandboxdb connect - Get connection details
• sandboxdb sql - Execute SQL queries
• sandboxdb seed - Generate synthetic data
• sandboxdb import - Import CSV data

Version Control

• sandboxdb snapshot - Create snapshot
• sandboxdb diff - Compare changes
• sandboxdb reset - Rollback to snapshot
• sandboxdb promote - Create reusable slice

🧪 Example Use Cases

Debugging Production Issues

sandboxdb extract \\
  --source prod \\
  --tables users,orders,payments \\
  --where "users.created_at > '2025-01-01'" \\
  --limit-per-table 100 \\
  --include-related \\
  --mask pii-defaults

sandboxdb share debug.duckdb --ttl 12h --name "checkout-bug-repro"

Demo Environment Setup

sandboxdb extract --source staging --tables products,categories
sandboxdb share products.duckdb --mode writable --ttl 72h
sandboxdb seed sbx_demo --table products --rows 50 --profile photogenic
sandboxdb snapshot sbx_demo --note "Demo ready state"
sandboxdb promote sbx_demo --as "sales-demo-v2"

🔒 Security

• Read-only sources strongly recommended
• PII masking before upload
• TTL enforcement for sandboxes
• Access control with user roles
• Audit logging for all operations
• Rate limiting and quotas

📊 Supported Databases

Sources

• ✅ PostgreSQL
• ✅ MySQL
• 🚧 SQLite
• 🚧 SQL Server
• 🚧 Oracle

Outputs

• ✅ DuckDB (default)
• ✅ SQLite
• 🚧 Parquet
• 🚧 CSV

🚀 Deployment

CLI Distribution

npm run build
npm publish @sandboxdb/cli

Web App (Vercel)

cd packages/web
vercel deploy

API Server (Docker)

cd apps/server
docker build -t sandboxdb-server .
docker run -p 3001:3001 sandboxdb-server

📈 Roadmap

• v0.2: Snowflake/BigQuery sources, MongoDB support
• v0.3: On-premise gateway, advanced synthetic data
• v1.0: Query parity checks, data refresh streams

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

---

SandboxDB - Making database slices first-class citizens! 🎯