fix(pgdog-plugin): api version check

[meskill]

pgdog-plugin compatibility check

fixes #600

Adds a compatibility version check for plugins based on the pgdog-plugin crate version. The implementation extracts and validates only the version of pgdog-plugin since it contains the definitions of the bridge layer between PgDog and plugins. Checking only pgdog-plugin avoids tight coupling with the main pgdog version while still enabling a meaningful compatibility check.

Highlights

Compatibility check

Added a new function pgdog_plugin_api_version to the Plugin trait and a corresponding verification step in the initialization code.

For now, this check is not enforced to avoid breaking existing plugins. It can be enabled later to prevent loading older, incompatible plugins.

Integration tests

I added a couple of integration tests to verify the plugins behave as expected. The tests exercise different pgdog-plugin versions (the local repo version, the crates.io version, and a main-branch/dev version) to exercise the compatibility checks and surface potential issues.

Removed pg_query version check

Note: the pg_query version was referenced in docs but not actually enforced.

There were no real checks for the pg_query version despite documentation references, so I removed the separate crate and the export from pgdog-plugin. The pg_query version is important, but the previous check was unused and ineffective.

The current approach is to control the pg_query version via the pgdog-plugin crate and rely on its versioning. We currently use a fork of pg_query pinned by git revision rather than a crates.io version, so this central control makes the most sense.

Cleanup and documentation

I updated documentation and cleaned up some plugin-related dependencies. I also added an LLM-generated doc section for the plugin which should help developers get started.

Future design

I explored the current approach and the challenges around enforcing Rust/Rustc compatibility. While most FFI types use #[repr(C)], there are places that rely on Rust's ABI layout (for example, Vec and some pg_query structures passed as raw pointers). Because of that, using the same Rust toolchain and dependency versions between host and plugin is sensible but it still does not fully guarantee ABI compatibility, especially when compilation flags differ.

For a more robust future solution, consider using a crate like stabby to help enforce ABI compatibility between host and plugins. That approach could add stricter validations and reduce subtle runtime errors, but would likely require reworking parts of the plugin interface and some data representations (notably the pg_query-related types).

TODO

If merged, update the PgDog site documentation to reflect these changes.

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pgdog/src/plugin/mod.rs	0.00%	16 Missing ⚠️
pgdog-plugin/src/plugin.rs	0.00%	9 Missing ⚠️
pgdog-plugin/src/comp.rs	0.00%	3 Missing ⚠️
pgdog/src/util.rs	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[levkk]

Really cool!