ArchiTools/geoportal/skill-vector-tile-serving.md

Skill: Vector Tile Serving from PostGIS

When to Use

When building a web map that serves vector tiles from PostgreSQL/PostGIS data. Applies to any project using MapLibre GL JS, Mapbox GL JS, or OpenLayers with MVT tiles from a spatial database.

---

Core Architecture Decision

Always use a dedicated tile server over GeoJSON for datasets >20K features.

GeoJSON limits:

• 20K polygons: visible jank on setData(), 200-400ms freezes
• 50K polygons: multi-second freezes, 500MB+ browser memory
• 100K+ polygons: crashes mobile browsers, 1-2GB memory on desktop
• JSON.stringify runs on main thread — blocks UI proportional to data size

Vector tiles (MVT) solve this:

• Only visible tiles loaded (~50-200KB per viewport)
• Incremental pan/zoom (no re-fetch)
• ~100-200MB client memory regardless of total dataset size
• Works on mobile

---

Tile Server Rankings (Rechsteiner Benchmark, April 2025)

Rank	Server	Language	Speed	Notes
1	Martin	Rust	1x	Clear winner, 95-122ms range
2	Tegola	Go	2-3x slower	Only supports SRID 3857/4326
3	BBOX	Rust	~same as Tegola	Unified raster+vector
4	pg_tileserv	Go	~4x slower	Zero-config but limited control
5	TiPg	Python	Slower	Not for production scale
6	ldproxy	Java	4-70x slower	Enterprise/OGC compliance

Source: github.com/FabianRechsteiner/vector-tiles-benchmark

---

Martin: Best Practices

Always use explicit config (not auto-discovery)

Auto-discovery can drop properties, misdetect SRIDs, and behave unpredictably with nested views.

postgres:
  connection_string: ${DATABASE_URL}
  default_srid: 3844       # your source SRID
  auto_publish: false       # explicit sources only
  tables:
    my_layer:
      schema: public
      table: my_view_name
      geometry_column: geom
      srid: 3844
      bounds: [20.2, 43.5, 30.0, 48.3]  # approximate extent
      minzoom: 10
      maxzoom: 18
      properties:
        object_id: text     # explicit column name: pg_type
        name: text
        area: float8

Docker image tags

Martin changed tag format at v1.0:

• Pre-1.0: ghcr.io/maplibre/martin:v0.15.0 (with v prefix)
• Post-1.0: ghcr.io/maplibre/martin:1.4.0 (no v prefix)

Docker deployment

If your orchestrator has access to the full repo (docker-compose CLI, Docker Swarm with repo checkout):

martin:
  image: ghcr.io/maplibre/martin:1.4.0
  command: ["--config", "/config/martin.yaml"]
  environment:
    - DATABASE_URL=postgresql://user:pass@host:5432/db
  volumes:
    - ./martin.yaml:/config/martin.yaml:ro
  ports:
    - "3010:3000"

If using Portainer CE or any system that only sees docker-compose.yml (not full repo): Volume mounts for repo files fail silently — Docker creates an empty directory instead. Bake config into a custom image:

# martin.Dockerfile
FROM ghcr.io/maplibre/martin:1.4.0
COPY martin.yaml /config/martin.yaml

martin:
  build:
    context: .
    dockerfile: martin.Dockerfile
  command: ["--config", "/config/martin.yaml"]
  environment:
    - DATABASE_URL=postgresql://user:pass@host:5432/db
  ports:
    - "3010:3000"

Custom SRID handling

Martin handles non-4326/3857 SRIDs natively. Set default_srid globally or srid per source. Martin reprojects to Web Mercator (3857) internally for tile envelope calculations. Your PostGIS spatial indexes on the source SRID are used correctly.

Zoom-dependent simplification

Create separate views per zoom range with ST_SimplifyPreserveTopology:

-- z0-5: heavy simplification (2000m tolerance)
CREATE VIEW my_layer_z0 AS
SELECT id, name, ST_SimplifyPreserveTopology(geom, 2000) AS geom
FROM my_table;

-- z8-12: moderate (50m)
CREATE VIEW my_layer_z8 AS
SELECT id, name, ST_SimplifyPreserveTopology(geom, 50) AS geom
FROM my_table;

-- z12+: full precision
CREATE VIEW my_layer_z12 AS
SELECT * FROM my_table;

Performance at 1M+ features

• Set minzoom per source to avoid pathological low-zoom tiles
• Buildings: minzoom 14 (skip at overview levels)
• Use zoom-dependent simplified views for boundaries
• Add HTTP cache (nginx proxy_cache) in front of Martin
• Consider PMTiles for static overview layers

---

PMTiles: Pre-generated Tile Archives

Best for: static/rarely-changing layers, overview zoom levels, eliminating DB load.

Pipeline

# 1. Export from PostGIS, reproject to WGS84
ogr2ogr -f FlatGeobuf -s_srs EPSG:3844 -t_srs EPSG:4326 \
  layer.fgb "PG:dbname=mydb" \
  -sql "SELECT id, name, geom FROM my_table"

# 2. Generate PMTiles
tippecanoe -o output.pmtiles \
  --layer="my_layer" layer.fgb \
  --minimum-zoom=0 --maximum-zoom=14 \
  --drop-densest-as-needed \
  --detect-shared-borders \
  --hilbert --force

# 3. Serve from any HTTP server with Range request support (MinIO, nginx, CDN)

MapLibre integration

import { Protocol } from 'pmtiles';
maplibregl.addProtocol('pmtiles', new Protocol().tile);

// Add source
map.addSource('overview', {
  type: 'vector',
  url: 'pmtiles://https://my-server/tiles/overview.pmtiles',
});

Hybrid approach (recommended for large datasets)

• PMTiles for overview (z0-z14): pre-generated, ~5ms serving, zero DB load
• Martin for detail (z14+): live from PostGIS, always-current data
• Rebuild PMTiles on schedule (nightly) or after data sync

---

MLT (MapLibre Tiles) — Next-Gen Format (2026)

• 6x better compression than MVT (column-oriented layout)
• 3.7-4.4x faster client decode (SIMD-friendly)
• Martin v1.3+ supports serving MLT
• MapLibre GL JS 5.x supports decoding MLT
• Spec: github.com/maplibre/maplibre-tile-spec

---

Common Pitfalls

1. Martin auto-discovery drops properties — always use explicit config with auto_publish: false
2. Martin Docker tag format changed at v1.0 — v0.15.0 (with v) but 1.4.0 (without v). Check actual tags at ghcr.io.
3. Portainer CE volume mounts fail silently — Docker creates empty directory instead of file. Bake configs into images via Dockerfile COPY.
4. Martin logs UNKNOWN GEOMETRY TYPE for views — normal for nested views, does not affect tile generation
5. Nested views lose SRID metadata — cast geometry: geom::geometry(Geometry, 3844)
6. GisUat.geometry is huge — always select to exclude in list queries
7. Low-zoom tiles scan entire dataset — use zoom-dependent simplified views
8. No tile cache by default — add nginx/Varnish in front of any tile server
9. tippecanoe requires WGS84 — reproject from custom SRID before generating PMTiles
10. PMTiles not incrementally updatable — full rebuild required on data change
11. Tegola doesn't support custom SRIDs — only 3857/4326, requires ST_Transform everywhere
12. pg_tileserv ST_Estimated_Extent fails on views — use materialized views or function layers
13. Martin caches source schema at startup — restart after view DDL changes