Connect PgSTAC and TiTiler.
Documentation: https://stac-utils.github.io/titiler-pgstac/
Source Code: https://github.com/stac-utils/titiler-pgstac
TiTiler-PgSTAC is a TiTiler extension that connects to a PgSTAC database to create dynamic mosaics based on search queries.
Installation
To install from PyPI and run:
# Make sure to have pip up to date
python -m pip install -U pip
# Install `psycopg` or `psycopg["binary"]` or `psycopg["c"]`
python -m pip install psycopg["binary"]
python -m pip install titiler.pgstac
To install from sources and run for development:
We recommand using uv as project manager for development.
See https://docs.astral.sh/uv/getting-started/installation/ for installation
git clone https://github.com/stac-utils/titiler-pgstac.git
cd titiler-pgstac
uv sync --extra psycopg
PgSTAC version
titiler.pgstac depends on pgstac >=0.3.4 (https://github.com/stac-utils/pgstac/blob/main/CHANGELOG.md#v034).
In theory, pgstac version >=0.3.4 should be supported by titiler-pgstac but old version might fail or require old Postgres version (see https://github.com/stac-utils/titiler-pgstac/issues/252).
Here are the versions officially (tested) supported:
| titiler-pgstac Version | pgstac |
|---|---|
| <1.0 | >=0.7,<0.8 |
| >=1.0,<2.1 | >=0.8,<0.10 |
| >=2.1 | >=0.9,<0.10 |
psycopg requirement
titiler.pgstac depends on the psycopg library. Because there are three ways of installing this package (psycopg or , psycopg["c"], psycopg["binary"]), the user must install this separately from titiler.pgstac.
psycopg: no wheel, pure python implementation. It requires thelibpqinstalled in the system.psycopg["binary"]: binary wheel distribution (shipped with libpq) of thepsycopgpackage and is simpler for development. It requires development packages installed on the client machine.psycopg["c"]: a C (faster) implementation of the libpq wrapper. It requires thelibpqinstalled in the system.
psycopg[c] or psycopg are generally recommended for production use.
In titiler.pgstac setup.py, we have added three options to let users choose which psycopg install to use:
python -m pip install titiler.pgstac["psycopg"]: pure pythonpython -m pip install titiler.pgstac["psycopg-c"]: use the C wrapper (requires development packages installed on the client machine)python -m pip install titiler.pgstac["psycopg-binary"]: binary wheels
Prometheus metrics
Install the optional metrics extra and enable it:
python -m pip install titiler-pgstac[metrics]
export TITILER_PGSTAC_API_METRICS_ENABLED=TRUE
Once enabled, /metrics is available on startup and records:
titiler_pgstac_http_requests_total{operation,method,status}titiler_pgstac_http_request_duration_seconds{operation,method}
operation values are low-cardinality labels such as landing, conformance,
tiles, point, search, search_info, collection, item, register_search,
list_searches, external, tms, algorithms, colormaps, other, and
unknown. status is grouped (2xx, 3xx, 4xx, 5xx). /healthz and the
scrape endpoint are excluded from request counters. Untemplated paths (for example
bare 404s) are also ignored.
With TITILER_PGSTAC_API_METRICS_ENABLED left at its default (FALSE), /metrics
is not registered even if the extra is installed.
Multi-worker deployments
For multi-worker deployments (for example uvicorn --workers N or Gunicorn), set
PROMETHEUS_MULTIPROC_DIR to an existing writable directory before the
application is imported, and clear that directory before each server start.
export PROMETHEUS_MULTIPROC_DIR=/tmp/titiler-pgstac-prometheus
mkdir -p "$PROMETHEUS_MULTIPROC_DIR"
rm -rf "$PROMETHEUS_MULTIPROC_DIR"/*
With Gunicorn, also mark workers dead on exit so stale metric files are cleaned up:
from prometheus_client import multiprocess
def child_exit(server, worker):
multiprocess.mark_process_dead(worker.pid)
Custom apps
Custom apps can enable the same instrumentation:
from titiler.pgstac.metrics import instrument_app
instrument_app(app)
Launch
You'll need to have PGUSER, PGPASSWORD, PGDATABASE, PGHOST, PGPORT variables set in your environment pointing to your Postgres database where pgstac has been installed.
export PGUSER=username
export PGPASSWORD=password
export PGDATABASE=postgis
export PGHOST=database
export PGPORT=5432
$ python -m pip install uvicorn
$ uvicorn titiler.pgstac.main:app --reload
Using Docker
$ git clone https://github.com/stac-utils/titiler-pgstac.git
$ cd titiler-pgstac
$ docker compose up --build app
# or
$ docker compose up --build app-gunicorn
Contribution & Development
See CONTRIBUTING.md
License
See LICENSE
Authors
See contributors for a listing of individual contributors.
Changes
See CHANGES.md.
1 maintainer
Release files for titiler-pgstac 3.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| titiler_pgstac-3.2.0.tar.gz | 38.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| titiler_pgstac-3.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 83.8 kB
Release files / titiler_pgstac-3.2.0.tar.gz
| Download URL | titiler_pgstac-3.2.0.tar.gz |
|---|---|
| Size | 38.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6b4105e3fac1702d6f39a6ab44b773b78aeba110c101f4745465f0cf5aead582
|
|
BLAKE2b-256 checksum How to use checksums |
0ac7153d96d13276f24ed639913576bbafad2a739311068ac6c48af17a515aa1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / titiler_pgstac-3.2.0-py3-none-any.whl
| Download URL | titiler_pgstac-3.2.0-py3-none-any.whl |
|---|---|
| Size | 45.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
abe173539100f9699fcc8d9b6dd874d924a1a61fb1c34d305259a0570a7c4564
|
|
BLAKE2b-256 checksum How to use checksums |
772158d5339f9be77f29e4c07bf541f3d2f88e53c627a9b2136a196b7cd5fa66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
