pgrx unfortunately has essentially zero documentation or samples on use outside of extensions.
For instance, say you want to write a new Table Access Method handler. There are bindings to TableAM stuff in the core pg-sys SDK but no docs or examples on using it in Rust.
I don’t think we even expose the TableAM APIs? They are incredibly hard to generate bindings for from the C headers — lots of inline functions and complex #define macros.
We have an ambitious goal with pgrx and it’s going to take many years and countless hours of developer effort to get there.
It can, however, serve as a way for newcomers to gain experience with Postgres internals.
Regarding the TableAM specifically, when we are able to create a safe Rust wrapper around it, that wrapper will be documented.
Those are the internals we currently expose as unsafe “sys” bindings.
As we/contributors identify more that are desired we add them.
pgrx’ focus is on providing safe wrappers and general interfaces to the Postgres internals, which is the bulk of our work and is what will take many years.
As unsafe bindings go, we could just expose everything, and likely eventually will. There’s just some practical management concerns around doing that without a better namespace organization —- something we’ve been working.
The Postgres sources are not small. They are very complex, inconsistent in places, and often follow patterns that are specific to Postgres and not easy to generalize.
If you’ve never built an extension with pgrx, give it a shot one afternoon. It’s very exciting to see your own code running in your database.
For instance, say you want to write a new Table Access Method handler. There are bindings to TableAM stuff in the core pg-sys SDK but no docs or examples on using it in Rust.