MBTiles and PMTiles File Sources

Martin can serve any type of tiles from PMTile and MBTile files. To serve a file from CLI, simply put the path to the file or the directory with *.mbtiles or *.pmtiles files. A path to PMTiles file may be a URL. For example:

martin  /path/to/mbtiles/file.mbtiles  /path/to/directory   https://example.org/path/tiles.pmtiles

You may also want to generate a config file using the --save-config my-config.yaml, and later edit it and use it with --config my-config.yaml option.

Autodiscovery

For mbtiles or local pmtiles files, we support auto discovering at startup. This means that the following will discover all mbtiles and pmtiles files in the directory:

martin  /path/to/directory

MBTiles Hot Reload

Martin watches directories configured under mbtiles for changes at runtime. When .mbtiles files are added, modified, or removed from a watched directory, Martin automatically updates the tile catalog — no restart required.

# Martin will watch this directory and reflect any *.mbtiles changes live
martin  /path/to/mbtiles/directory

Or via config file:

mbtiles:
  paths:
    - /path/to/mbtiles/directory

The following events are handled automatically:

• File added - the new source appears in the catalog.
• File modified - the source is reloaded and its tile cache is invalidated. Not avaliable on windows due to OS-limtations (SQLite not allowing FILE_SHARE_DELETE).
• File removed - the source is removed from the catalog.

MBTiles vs PMTiles

MBTiles and PMTiles are both formats for storing tiled geospatial data, but they differ in architecture, deployment, and operational characteristics.

Key Differences

• Deployment model MBTiles archives must be stored locally on the same machine as the tile server. PMTiles archives can be accessed either locally or remotely via HTTP range requests, e.g. from an object storage like S3. PMTiles allows simpler production deployment with Kubernetes, as it allows the large data file to reside in S3 and shared by multiple pods, but restricted from direct user access.
• Performance MBTiles typically provide slightly lower latency due to local access and SQLite indexing. PMTiles may introduce additional latency when accessed remotely, but this is usually mitigated by HTTP caching and CDN usage.
• Storage efficiency PMTiles archives are generally more space-efficient, typically ~10–15% smaller than equivalent MBTiles archives.
• Memory usage MBTiles relies on SQLite, which maintains an internal page cache and may increase memory usage under load. PMTiles can, in some cases, operate with lower memory overhead, depending on access patterns and caching configuration.

Serving PMTiles without a Tile Server

PMTiles archives can be served directly from HTTP range–capable storage without a dedicated tile server. This approach has several limitations:

• Unrestricted access risk Without proper access controls, clients may download large portions (or all) of an archive, leading to significant egress costs. A tile server restricts access to tile requests, but bulk extraction remains possible via many requests, which are generally easier to detect and block.
• Over-fetching PMTiles may fetch more data than strictly required per tile request to minimize the number of HTTP requests.
• Lack of source composition Direct serving does not support combining PMTiles with dynamic data sources (e.g., PostGIS) into a unified tile service. A tile server (e.g, Martin) is required for this.
• Caching behavior Cache efficiency may be reduced compared to setups with a dedicated tile server that can optimize request patterns.

The choice between MBTiles and PMTiles depends on system requirements:

• Use MBTiles for local, self-contained deployments with minimal external dependencies.
• Use PMTiles for cloud-native or distributed setups where remote access, CDN integration, or object storage is preferred.

Serving PMTiles from local file systems, http or Object Storage

The settings available for a PMTiles source depend on the backend:

martin  path/to/tiles.pmtiles

pmtiles:
  sources:
    tiles: file:///path/to/my/file.pmtiles

martin  https://example.com/tiles.pmtiles

pmtiles:
  allow_http: true
  sources:
    tiles: s3://bucket/path/to/tiles.pmtiles

martin  s3://my-bucket/tiles.pmtiles

pmtiles:
  allow_http: true
  sources:
    tiles: s3://bucket/path/to/tiles.pmtiles

martin  gs://my-bucket/tiles.pmtiles

pmtiles:
  allow_http: true
  sources:
    tiles: gs://bucket/path/to/tiles.pmtiles

martin  az://my-container/tiles.pmtiles

pmtiles:
  allow_http: true
  sources:
    tiles: az://my-container/tiles.pmtiles