Skip to content

FEATURES.md

Latest commit

 

History

History
171 lines (144 loc) · 6.21 KB

FEATURES.md

File metadata and controls

171 lines (144 loc) · 6.21 KB
Raw

DuckDB Tileserver Features

A lightweight MVT (Mapbox Vector Tile) server for DuckDB with spatial extension support.

API

  • Determine response format from request headers Content-Type, Accept
  • CORS support (configurable origins)
  • GZIP encoding (via compress handler)
  • HTTPS support (optional TLS configuration)
  • Proxy support via configurable base URL and base path

Endpoints

Core Endpoints

  • / - Interactive map viewer (HTML landing page)
  • /index.html, /home.html - Alternative routes to landing page
  • /health - Health check endpoint
  • /layers - List all available spatial layers (JSON)
  • /layers.json - Alternative route to layers endpoint

Tile Endpoints

  • /tiles/{layer}.json - TileJSON metadata endpoint
  • /tiles/{layer}/{z}/{x}/{y}.mvt - MVT tile endpoint
  • /tiles/{layer}/{z}/{x}/{y}.pbf - MVT tile endpoint (alternative extension)

Cache Management Endpoints

  • /cache/stats - GET cache statistics (hits, misses, hit rate, size, memory, evictions)
  • /cache/clear - DELETE entire cache
  • /cache/layer/{layer} - DELETE layer-specific tiles
  • Optional API key authentication via X-API-Key header
  • Configurable enable/disable of cache management endpoints

Tile Features

  • MVT (Mapbox Vector Tile) generation using DuckDB's ST_AsMVT function
  • Auto-discovery of all tables with geometry columns
  • Multi-SRID support with automatic transformation to Web Mercator (EPSG:3857)
  • Validation of tile coordinates (z, x, y ranges)
  • Empty tile handling (returns 204 No Content when no features in tile)
  • TileJSON 2.2.0 specification support
  • Geometry type detection and metadata
  • Table schema and column metadata in TileJSON

Cache Features

  • LRU tile cache with configurable size and memory limits
  • Cache statistics tracking (hits, misses, hit rate, evictions)
  • Periodic cache statistics logging (every 5 minutes)
  • Cache middleware for tile endpoints
  • Browser cache control via Cache-Control headers
  • Configurable cache enable/disable
  • Memory-based eviction when cache exceeds limits
  • Layer-specific cache clearing
  • Full cache clearing
  • Cache management API authentication with configurable API key
  • Public and authenticated modes for cache endpoints

Configuration

  • Read config from TOML file
  • Configuration file search paths (/etc, ./config, /config)
  • Environment variable configuration with DUCKDBTS_ prefix
  • Database connection path configuration
  • Table include/exclude filters
  • HTTP/HTTPS server settings (host, ports)
  • TLS certificate and key file paths
  • URL base and base path configuration
  • CORS origins configuration
  • Debug mode
  • Assets path for HTML templates
  • Request/write timeout configuration
  • UI enable/disable toggle
  • Cache configuration (enabled, max items, max memory, browser cache max-age)
  • Cache endpoint security (disable routes, API key authentication)
  • Metadata configuration (title, description)
  • Website basemap URL configuration

Operational

  • Graceful shutdown with signal handling
  • Request timeouts with context cancellation
  • Database connection pooling
  • Concurrent HTTP and HTTPS servers
  • Timeout handler for long-running requests (returns 503 on timeout)
  • Abort timeout on shutdown to prevent hanging

Data Types

  • All geometry types via DuckDB Spatial (POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION)
  • Common scalar types: text, int, float, numeric
  • Automatic detection of geometry columns
  • First geometry column used when multiple exist (with warning)
  • Support for tables with and without primary keys

Tables / Views

  • Table column schema discovery
  • Support tables with geometry columns
  • Support views with geometry columns
  • Include/exclude published tables via configuration
  • Automatic SRID detection
  • Multi-SRID table support with transformation

User Interface (HTML)

  • Interactive HTML landing page with map viewer
  • MapLibre GL JS-based map display
  • Automatic loading of all available layers
  • Layer visibility toggles
  • Feature attribute display on click
  • Layer list with geometry type indicators
  • Configurable basemap URL
  • Responsive design
  • Development mode for template reloading

Architecture

┌─────────────────┐
│   HTTP Client   │
│ (Browser/QGIS)  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  HTTP Handlers  │
│  (Gorilla Mux)  │
│  - CORS         │
│  - GZIP         │
│  - Timeout      │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  Cache Layer    │
│  (LRU Cache)    │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  Tile Generator │
│  (ST_AsMVT)     │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│   DuckDB + SQL  │
│  Spatial Ext.   │
└─────────────────┘

Performance Features

  1. Tile Caching: LRU cache with configurable size and memory limits
  2. Spatial Indexing: DuckDB Spatial automatically creates R-Tree indexes
  3. Connection Pooling: Go database/sql package handles connection pooling
  4. Efficient Tile Generation: Uses DuckDB's native ST_AsMVT function
  5. GZIP Compression: Automatic response compression
  6. Request Timeouts: Prevents long-running queries from blocking
  7. Browser Caching: Configurable Cache-Control headers

Technology Stack

  • Language: Go 1.24+
  • Database: DuckDB with Spatial extension v1.4+
  • HTTP Framework: Gorilla Mux
  • Map Viewer: MapLibre GL JS
  • Tile Format: Mapbox Vector Tiles (MVT/PBF)
  • Configuration: Viper (TOML + environment variables)
  • Logging: Logrus