Getting Started
Deploy and connect to your first database.
PondPilot Proxy
PondPilot Proxy enables clients to execute SQL queries against multiple data sources through a unified interface. Each user gets an isolated DuckDB instance running in a Docker container, with queries proxied via the Apache Arrow Flight SQL protocol.
What is PondPilot Proxy?
Section titled “What is PondPilot Proxy?”PondPilot Proxy is a multi-tenant data proxy that provides:
- Per-user isolation — Each user gets their own DuckDB instance in a dedicated Docker container
- Flight SQL protocol — High-performance columnar data streaming via Apache Arrow
- Cross-database queries — Join data across PostgreSQL, MySQL, and SQLite in a single query
- AI integration — Built-in endpoints for chat completions and embeddings
Architecture Overview
Section titled “Architecture Overview” PondPilot Proxy ┌─────────────────────────────────────────────────┐ │ │ HTTP :8080 │ ┌──────────┐ ┌────────────────────────┐ │ ──────────────┼─▶│ Router │───▶│ Middleware Pipeline │ │ │ └──────────┘ │ - Auth (JWT) │ │ │ │ - RateLimiter │ │ │ └────────────────────────┘ │ │ │ │ │ ┌──────────────┴──────────────┐ │ │ ▼ ▼ │ │ ┌──────────────┐ ┌───────────┐ │ │ │ AI Handlers │ │ Health │ │ │ │ /ai/chat │ │ Endpoints │ │ │ │ /ai/embed │ └───────────┘ │ │ └──────────────┘ │ │ │ gRPC :8081 │ ┌───────────────────────────────────────────┐ │ ──────────────┼─▶│ Flight SQL Server │ │ │ │ (JWT Auth via gRPC Interceptors) │ │ │ └───────────────────┬───────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────┐ │ │ │ Container Manager │ │ │ │ - Per-user isolation │ │ │ │ - Idle container reaping │ │ │ │ - Resource limits (CPU, memory) │ │ │ └───────────────────┬───────────────────────┘ │ │ │ │ └──────────────────────┼─────────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ Docker Network │ │ │ ▼ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │Container│ │Container│ │Container│ ... │ │ │ User A │ │ User B │ │ User C │ │ │ │ SQLFlite│ │ SQLFlite│ │ SQLFlite│ │ │ │ DuckDB │ │ DuckDB │ │ DuckDB │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ └───────┼────────────┼────────────┼──────────┘ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │PostgreSQL│ │ MySQL │ │ SQLite │ │ Database │ │ Database │ │ Files │ └──────────┘ └──────────┘ └──────────┘Key Components
Section titled “Key Components”Dual-Port Architecture
Section titled “Dual-Port Architecture”| Port | Protocol | Purpose |
|---|---|---|
| 8080 | HTTP | REST API, health checks, AI endpoints |
| 8081 | gRPC | Flight SQL queries |
Container Isolation
Section titled “Container Isolation”Each user gets a dedicated Docker container running:
- SQLFlite — Flight SQL server backed by DuckDB
- DuckDB — With extensions for PostgreSQL, MySQL, SQLite connectivity
- Pre-attached databases — Configured at container startup
Containers are:
- Spawned on first request
- Cached for subsequent requests (~10-50ms latency)
- Automatically stopped after idle timeout (default: 5 minutes)
Security
Section titled “Security”| Layer | Mechanism |
|---|---|
| Authentication | JWT tokens (required) |
| Process isolation | Separate container per user |
| Network isolation | Containers on isolated Docker network |
| Resource limits | CPU and memory limits enforced |
| Privileges | Non-root user, capabilities dropped |
Supported Databases
Section titled “Supported Databases”| Database | Extension | Notes |
|---|---|---|
| PostgreSQL | postgres | Full read access with schema support |
| MySQL | mysql | MySQL and MariaDB compatible |
| SQLite | sqlite | Local or remote SQLite files |
| DuckDB | native | In-memory and persistent tables |
Use Cases
Section titled “Use Cases”- PondPilot App — Backend for the PondPilot data exploration tool
- Cross-database analytics — JOIN across different database systems
- Data federation — Query microservice databases without tight coupling
- AI-powered queries — Natural language to SQL with integrated AI endpoints
Quick Links
Section titled “Quick Links”Configuration
YAML configuration, environment variables, container settings.
Cross-Database Queries
Query multiple databases with Flight SQL.
Deployment
Docker Compose, production setup, scaling.