pgstacrs #523
Description
Overview
pgstacrs will be a "full access" Python API for pgstac backed by the pgstac crate.
Prior art
- pypgstac is a Python package that interacts with a pgstac database. It's mostly used via it's command-line interface (CLI). It's primary issue is that it is currently tightly-coupled to the pgstac version, meaning that its "impossible" to release new Python package features without releasing a new database schema version 😢. There is (in my opinion) a good argument for keeping Rust code out of the pgstac repo, because that repo does enough stuff already.
- stac-fastapi-pgstac does a lot of custom SQL queries to pgstac PostgreSQL functions that could be refactored out to their own API. The goal here would be for stac-fastapi-pgstac to contain zero SQL 🤯
Integration and goals
The plan is that pgstacrs will live "above" pypgstac and stac-fastapi-pgstac in the dependency chain:
graph LR
pgstacrs --> pypgstac
pgstacrs --> stac-fastapi-pgstac
To do this, pgstacrs will:
- Expose every public pgstac PostgreSQL function via a Python function/method
- Provide a pooled client that can be used directly from stac-fastapi-pgstac for efficient server-side queries
- Provide "smart loading" that can be used via the pypgstac CLI or via a Python API to load collections and items into the database The Right Way™
- Provide backward compatibility, meaning that (from some point) it will continue to support older pgstac versions
- Integrate with pystac objects
Examples
Here's some rough sketches of what pgstacrs might look like:
from pgstacrs import Client
from pystac import Collection
client = Client.open("postgresql://username:password@localhost:5432/pgstac")
print("pgstac version:", client.version())
collection = Collection.from_file(
"https://raw.githubusercontent.com/radiantearth/stac-spec/refs/heads/master/examples/collection.json"
)
items = list(collection.get_items())
client.add_collection(collection)
client.add_items(items)
client = Client.open("postgresql://username:password@localhost:5432/pgstac", pool=True)
items = client.search(collections=["collection-id"], filter={}, intersects={}) # etc