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?

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

                                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

Dual-Port Architecture

Port	Protocol	Purpose
8080	HTTP	REST API, health checks, AI endpoints
8081	gRPC	Flight SQL queries

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

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

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

• 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

import { Card, CardGrid } from ‘@astrojs/starlight/components’;

Deploy and connect to your first database.

[Get started →](/proxy/getting-started/)

YAML configuration, environment variables, container settings.

[Configure →](/proxy/configuration/)

Query multiple databases with Flight SQL.

[Learn more →](/proxy/cross-database-queries/)

Docker Compose, production setup, scaling.

[Deploy →](/proxy/deployment/)