Tegola Mapbox Vector Tile Server for PostGIS and GeoPackage

Tegola's Spatial Data Pipeline

Tegola addresses the gap between spatial databases and clients that consume Mapbox Vector Tiles. A database table or geodata file may contain geometry and attributes, while a web map commonly requests tiles by zoom and tile coordinates. Tegola sits between those layers. It reads configured provider layers, transforms the geometry for the requested tile and projection, applies the configured layer visibility, and encodes the result as a Mapbox Vector Tile.

The documented configuration model connects a provider layer to a map layer through `provider_layer`. Each map layer has a `min_zoom` and `max_zoom`, so the same source can be exposed only at appropriate zoom levels. For the PostGIS provider, the SQL query commonly includes `ST_AsMVTGeom`, the `!BBOX!` token, and an optional `!PARAM!` token. Tegola replaces the bounding box token according to the requested tile and can pass URL parameters into the query through a configured SQL fragment.

The server also supports Web Mercator, using EPSG:3857, and WGS84, using EPSG:4326. Geometry processing includes simplification, clipping, make valid, intersection, contains, scaling, and translation. Those operations matter because a database query can return geometries that overlap a tile, extend beyond its bounds, or need simplification at lower resolutions. Tegola documents parallelized tile serving and geometry processing, but it does not state a fixed throughput or latency figure.

Configuring PostGIS Through TOML

Tegola uses TOML for configuration. The README's example registers an `mvt_postgis` provider, connects to a PostgreSQL database, defines a provider layer, and attaches that layer to a map named `zoning`. The provider uses PostGIS's `ST_AsMVT()` path rather than treating it as a generic provider.

The example connection string includes a placeholder password, so it is configuration structure rather than a ready-to-use credential. The SQL statement must use `ST_AsMVTGeom` and should constrain geometry with `!BBOX!`. If a map parameter is intended to influence the query, the SQL must also contain the configured token. This is an explicit contract between the map configuration and the database query. Omitting `!PARAM!` can make the parameter appear configured but have no effect on the SQL.

A map can contain only one MVT provider according to the README example. That restriction prevents mixing an `mvt_postgis` provider with another MVT provider in the same map. It is a design boundary, not a general inability to use multiple data sources: a map can still associate layers from the supported provider types when those layers are configured consistently.

The capabilities endpoints provide a JSON list of configured maps and layers, while the map-specific capabilities endpoint returns TileJSON details. This makes the configuration inspectable through HTTP rather than requiring an operator to infer all map names and layer settings from the TOML file.

Installing Tegola and Starting the Server

The README directs users to download the appropriate Tegola binary for their platform from the GitHub release page. It does not provide a package-manager installation command or document installation from a language package registry, so this article does not add one.

After placing the binary, Tegola looks for `config.toml` in the same directory as the binary by default. The following command starts the server with an explicit configuration path. The reader should see the configured server start and serve the root viewer and tile endpoints on the server's configured address.

./tegola serve --config=/path/to/config.toml

The command interface also exposes `cache`, `serve`, `version`, and `help`. The default configuration path is shown in the usage output as `config.toml`.

./tegola version

The README's endpoint list provides a first check after startup. Opening `/` should display the built-in viewer. Requesting `/capabilities` returns the configured maps and layers as JSON. A tile request uses `/maps/:map_name/:z/:x/:y`, and a layer-specific request inserts `:layer_name` before the coordinates. For the example configuration, the map name is `zoning`, so its map route would be `/maps/zoning/10/0/0`. The README does not document a default HTTP port in the shown configuration example.

Tile Requests, Layers, and Cache Controls

The map-level route returns the configured map as a vector tile. The layer-level route returns one named layer, which is useful when a client needs to control visibility or request a specific source. Tile coordinates are supplied as `:z`, `:x`, and `:y`, and the README defines `:x` as the row and `:y` as the column at that zoom level.

Tegola supports file, S3, Redis, and Azure Blob Store cache backends. The cache can be manipulated through the `cache` command, and the feature list states that seeding and invalidation can target an individual `ZXY` tile, latitude and longitude bounds, or a list of `ZXY` tiles. This gives operators a way to populate predictable areas after a database change and to remove stale tiles without rebuilding every map.

The `/maps/:map_name/style.json` endpoint returns an automatically generated Mapbox GL Style for the configured map. That generated style is primarily useful for quick inspection. The repository does not document a workflow for editing the generated style and having those edits persist as server configuration, so teams should not assume that the style endpoint is a complete production cartography system.

Cache choice affects operational dependencies. A file cache is local to the server or volume. S3 and Azure Blob Store require cloud object storage configuration, while Redis requires a reachable Redis service. The README names these backends but does not give a complete configuration example for each one.

PostGIS, GeoPackage, and Deployment Choices

Tegola supports PostGIS, GeoPackage, and SAP HANA Spatial providers. The repository also has provider and mvtprovider directories, with a PostGIS `ST_AsMVT` implementation documented separately. GeoPackage support is relevant when source data is distributed as a file rather than hosted in PostgreSQL, while PostGIS suits installations where filtering, joins, and parameterized SQL are already part of the data workflow.

The architecture is extensible for additional providers, but that statement should not be read as proof that every data source can be added without writing provider code. The existing `provider` and `mvtprovider` structure separates data access from tile serving, which gives a custom provider a defined integration area. The README does not document the exact interface or compatibility obligations for such a provider.

Deployment options include a conventional server and AWS Lambda through `cmd/tegola_lambda`. The Dockerfile documents building an image and mounting local configuration and GeoPackage files at `/opt/tegola_config/`. The Docker example uses host port mapping with `-p 8080`, but the visible Dockerfile excerpt does not show a complete application port mapping or final `CMD`, so operators should verify the image's actual behavior before relying on that example.

git clone https://github.com/go-spatial/tegola.git
cd tegola
docker build -t tegola .

These commands come from the Dockerfile comments and are intended for building the image from the repository root. They do not by themselves start a production server or create a working spatial database.

Operational Boundaries, Maintenance, and License

Tegola is not archived, and its last push was on 2026-10-11. The listed releases are v0.21.0 on 2024-12-19, v0.21.1 on 2025-01-06, and v0.21.2 on 2025-01-08. Operators should check the changelog and release notes for changes between the binary they use and the current source. The repository includes a `CHANGELOG.md`, but the README does not summarize its upgrade notes.

The license is MIT. That provides a permissive licensing basis for examining and using the code, subject to the terms in `LICENSE.md`. It does not remove operational obligations from database credentials, cloud cache credentials, third-party client licenses, or the licensing of data placed in PostGIS or GeoPackage. Those matters require review of the relevant files and services rather than inference from Tegola's repository license.

A concrete limitation is that the built-in viewer and generated style focus on inspection, as the README describes them as a quick visualization and inspection aid. Tegola is also not a general-purpose GIS analysis application. It accepts spatial sources and serves tiles, but it does not claim to replace a desktop GIS or a full spatial database.

Prometheus observability is supported, with details in `observability/prometheus/README.md`. HTTPS serving is also listed as a feature. The README does not document authentication, authorization, rate limiting, or a complete production deployment guide. Those omissions matter if a tile service exposes expensive database queries or administrative cache operations.

Editorial conclusion

Tegola fits teams that need a configurable Mapbox Vector Tile service backed by PostGIS, GeoPackage, or SAP HANA Spatial. It is less suitable for users who only need a static tile file or cannot operate a Go server and spatial database. Verify provider SQL, projection choices, cache behavior, and the available release artifact before adoption.

Frequently asked questions

Official sources

1. go-spatial/tegola on GitHub
2. License: MIT
3. Project website
4. README
5. Releases