pg_ripple / pg_ripple_http Compatibility Matrix

pg_ripple (the PostgreSQL extension) and pg_ripple_http (the standalone HTTP companion service) are versioned independently. This page documents which extension versions are compatible with which HTTP companion versions and what guarantees apply to the combination.

Versioning policy

• pg_ripple follows semantic versioning tied to extension features and PostgreSQL catalog changes.
• pg_ripple_http follows its own version series (currently 0.x.y) since it is a standalone binary with its own release cadence. The HTTP companion version number tracks the minimum pg_ripple extension version it was tested against.

A given pg_ripple_http release is compatible with the extension version range [tested_with, next_major). The HTTP companion logs a warning at startup if the installed extension version is outside its known-compatible range.

Compatibility table

Startup version check

Starting with pg_ripple_http 0.16.0, the HTTP companion performs a compatibility check at startup. It queries the installed extension version and compares it against its known-compatible range. If the extension is older than the minimum supported version:

• Warning is logged: the companion starts but logs a prominent warning.
• The GET /ready endpoint returns HTTP 503 with {"compatible": false, ...} if the extension is below the hard minimum.

The check can be disabled with PG_RIPPLE_HTTP_SKIP_COMPAT_CHECK=1 for testing scenarios where an older extension is intentionally paired with a newer companion.

⚠ Production warning (COMPAT-DOC-01 / MF-R): PG_RIPPLE_HTTP_SKIP_COMPAT_CHECK=1 is intended only for testing and development where you deliberately need to run a mismatched pair (e.g., integration tests against an older extension). Do not set this in production environments. Skipping the check allows the HTTP companion to serve requests to an incompatible extension, which can result in silent data corruption, unexpected errors, or security vulnerabilities when new SQL functions are called against an older extension schema. If you need to silence the compatibility warning in production, upgrade the extension or the companion to a compatible version pair instead.

Independent versioning rationale

The HTTP companion is distributed as a pre-built binary. Extension upgrades (ALTER EXTENSION pg_ripple UPDATE) are applied in-database and do not require rebuilding or redeploying the companion. This means:

1. A single pg_ripple_http binary can serve multiple extension versions within its compatible range.
2. Extension-only changes (new SQL functions, GUCs, performance improvements) do not require a companion update.
3. Breaking API changes (new required request fields, removed endpoints) do require a companion update.

Upgrade procedure

1. Upgrade the extension first: ALTER EXTENSION pg_ripple UPDATE TO 'X.Y.Z';
2. Restart or redeploy pg_ripple_http if a companion upgrade is also required.
3. Verify compatibility via GET /ready — returns {"compatible": true} when correctly paired.

See also: Arrow Flight Reference, HTTP API.

pg_tide / pg_trickle Extension Compatibility

pg_ripple integrates with two companion PostgreSQL extensions:

Architecture change (pg_ripple v0.93.0 / pg_trickle v0.46.0): pg_trickle v0.46.0 extracted the relay, outbox, and inbox subsystem (~6,150 Rust LOC + ~2,500 SQL LOC) into the new standalone pg_tide extension (trickle-labs/pg-tide). Starting with v0.93.0, pg_ripple recognises pg_tide as the recommended relay transport layer.

pg_ripple + pg_trickle compatibility

pg_ripple + pg_tide compatibility

Recommended stack (pg_ripple ≥ 0.127.0)

CREATE EXTENSION pg_tide;      -- relay, outbox, inbox (trickle-labs/pg-tide ≥ 0.33.0)
CREATE EXTENSION pg_trickle;   -- IVM (trickle-labs/pg-trickle ≥ 0.46.0)
CREATE EXTENSION pg_ripple;    -- RDF triple store (≥ 0.127.0)

Call pg_ripple.pg_tide_available() to verify pg_tide is installed at runtime. Call pg_ripple.pg_trickle_available() to verify pg_trickle is installed at runtime.