decision-labs/geobase-skills/geobase-worker-archive-to-pmtiles

Worker: Archive to PMTiles

When to use this skill

• Export one PostGIS table to a PMTiles archive in project Storage via archiveToPmtiles
• Create a durable vector-tile snapshot of a table (offline maps, sharing, or serving outside live tileserver)
• Studio path: Tile Server → Tables → Archive to PMTiles
• Not for live vector tiles from PostGIS (@geobase-tileserver), local file import (@geobase-project-db-data-import), or AOI imports (@geobase-worker-osm-import, @geobase-worker-overture-import)

Public guide: https://docs.geobase.app/guides/gis-analyst/archive-to-pmtiles OpenAPI: {origin}/worker/doc and {origin}/worker/ui.

Secrets (human in the loop)

Worker HTTP needs `GEOBASE_SERVICE_ROLE_KEY`. Agents cannot obtain it. Ask the user to put it in a gitignored `.env.secrets`. Do not paste keys in chat. See @geobase → Secrets (human in the loop).

Shared worker pool callers also need an org Services API key plus a projectTarget object (Studio injects this).

Required inputs

• @geobase → private-beta / Studio path if CLI unavailable
• project_ref
• GEOBASE_SERVICE_ROLE_KEY in local secrets (or org Services key for shared pool)
• Storage bucket `pmtiles` must already exist (v1 does not auto-create)
• Payload JSON:
• table (required) — ^[A-Za-z_][A-Za-z0-9_]*$
• schema (optional; default public)
• minZoom / maxZoom (optional; default 1 / 15)

Storage layout

On success, snapshot fields are mirrored on job metadata.snapshot.

Size guards (fail fast)

Errors start with [pmtiles size guard]. Env 0 disables that check.

Confirm table row count and relation size before submit. Prefer smaller tables or lower maxZoom on first run.

Procedure

1. Session / project: geobase-cli whoami, geobase-cli projects refs (or Studio project_ref).
2. Env: geobase-cli projects env <ref> --persona web --format dotenv for non-secrets; user sources .env.secrets for service role.
3. Human checkpoint: confirm Storage bucket pmtiles exists and table is within size guards.
4. Validate identifiers: table and optional schema match ^[A-Za-z_][A-Za-z0-9_]*$.
5. Verify table exists and has geometry suitable for vector tiles.
6. Submit:

• POST https://${GEOBASE_PROJECT_REF}.geobase.app/worker/jobs/archiveToPmtiles
• headers: apikey + Authorization: Bearer = service role; Content-Type: application/json
• Studio proxy (when available): POST /api/projects/{ref}/jobs/archiveToPmtiles
• shared pool: POST https://services.geobase.app/worker/jobs/archiveToPmtiles with org Services key + projectTarget

1. Poll: GET .../worker/jobs/archiveToPmtiles/<job_id> — 5s then backoff (10s / 20s / 30s).
2. On success: verify metadata.snapshot (path, url, bytes, rows, sha256) and Storage objects under pmtiles/.

Multi-table Studio selection runs one job per table (client loop).

Example payload

{ "table": "buildings" }

With optional zoom bounds:

{
  "table": "buildings",
  "schema": "public",
  "minZoom": 1,
  "maxZoom": 14
}

Submit rule (mandatory)

Only submit when bucket pmtiles exists, identifiers are valid, and the table is within fleet size guards (or user approved limit changes). Re-runs overwrite {table}.pmtiles and {table}.snapshot.json.

Failure handling

• Auth → refresh service role or org Services key in .env.secrets
• Missing bucket → create Storage bucket pmtiles before retry
• [pmtiles size guard] → fewer rows, lower maxZoom, or raise env limits with user approval
• Unable to find driver 'PMTiles' → worker image needs GDAL ≥ 3.8 with PMTiles driver (fleet ops; not fixable from payload)
• Preserve failed job_id and truncated result for debugging

Related skills

• @geobase-tileserver — live vector MVT from PostGIS tables
• @geobase-project-db-data-import — load local files into Postgres first
• @geobase-worker-osm-import / @geobase-worker-overture-import — populate tables before archiving
• @geobase — secrets, project ref, routing