https://github.com/stac-utils/titiler-pgstac
TiTiler + PgSTAC
https://github.com/stac-utils/titiler-pgstac
Last synced: about 1 month ago
JSON representation
TiTiler + PgSTAC
- Host: GitHub
- URL: https://github.com/stac-utils/titiler-pgstac
- Owner: stac-utils
- License: mit
- Created: 2021-07-20T15:19:21.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2026-06-01T15:12:42.000Z (about 1 month ago)
- Last Synced: 2026-06-01T16:27:40.379Z (about 1 month ago)
- Language: Python
- Homepage: https://stac-utils.github.io/titiler-pgstac/
- Size: 24.9 MB
- Stars: 120
- Watchers: 8
- Forks: 36
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-earthobservation-code - titiler-pgstac - TiTiler + PgSTAC (`Python` processing of optical imagery (non deep learning) / Cloud Native Geospatial)
README
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](https://github.com/developmentseed/titiler) extension that connects to a [PgSTAC](https://github.com/stac-utils/pgstac) database to create dynamic **mosaics** based on [search queries](https://github.com/radiantearth/stac-api-spec/tree/master/item-search).
## Installation
To install from PyPI and run:
```bash
# 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`](https://docs.astral.sh/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 the `libpq` installed in the system.
- `psycopg["binary"]`: binary wheel distribution (shipped with libpq) of the `psycopg` package 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 the `libpq` installed 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 python
- `python -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
## 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 tiler
# or
$ docker compose up --build tiler-uvicorn
```
## Contribution & Development
See [CONTRIBUTING.md](https://github.com//stac-utils/titiler-pgstac/blob/main/CONTRIBUTING.md)
## License
See [LICENSE](https://github.com//stac-utils/titiler-pgstac/blob/main/LICENSE)
## Authors
See [contributors](https://github.com/stac-utils/titiler-pgstac/graphs/contributors) for a listing of individual contributors.
## Changes
See [CHANGES.md](https://github.com/stac-utils/titiler-pgstac/blob/main/CHANGES.md).