pgstacrs

[gadomski]

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

[bitner]

Only thing that I'd modify there is that pgstacrs will expose every public pgstac function. There are a number of functions in pgstac that are purely internal.

[gadomski]

A note ... for the first iteration I'm going to keep things sync, at least on the Python side. If there's a strong need for async Python please yell.