Skip to main content

Crate samkhya_postgres

Crate samkhya_postgres 

Source
Expand description

samkhya-postgres — PostgreSQL adapter for samkhya.

§Build modes

  • Default (no features): empty rlib. Compiles without PostgreSQL development headers; suitable for cargo check --workspace in CI environments that do not have libpq-dev / postgresql-server-dev-* installed.

  • pg_extension feature plus samkhya_pgrx_enabled rustc cfg flag: pulls in pgrx and exposes the functions defined below as a loadable PostgreSQL extension targeting PostgreSQL 17 (the only major supported in v1.0). Build with cargo pgrx — see this crate’s README. The recommended invocation is:

    RUSTFLAGS="--cfg=samkhya_pgrx_enabled" \
  cargo pgrx run pg17 --features pg_extension --package samkhya-postgres

§v1.0 double-gating + single-version pin (pg17)

pgrx 0.12.9’s pgrx-pg-sys build script panics at bindgen-time when more than one pg$VERSION feature is simultaneously active:

Error: Multiple `pg$VERSION` features found.
`--no-default-features` may be required.
Found: pg13, pg14, pg15, pg16, pg17

Cargo’s --all-features (used by cargo check --workspace --all-features and similar workspace-wide gates) activates every feature in a crate’s [features] table simultaneously. With the canonical pgrx feature-flag pattern (pg13..pg17 as parallel features that each forward pgrx/pgNN), workspace gates therefore cannot pass — pgrx-pg-sys’s build script panics before any manifest-level compile_error! we add ever fires.

For v1.0 the design is:

  1. Single-version pin (pg17). The pg_extension Cargo feature forwards pgrx/pg17. No pg13..pg16 features are declared.
  2. Target-cfg dep isolation. The pgrx dependency lives under [target.'cfg(samkhya_pgrx_enabled)'.dependencies] in Cargo.toml. Under cargo check --workspace --all-features (where samkhya_pgrx_enabled is unset), pgrx is excluded from the dep graph and pg_extension is a harmless no-op. Under RUSTFLAGS="--cfg=samkhya_pgrx_enabled" cargo pgrx run pg17 --features pg_extension, pgrx enters the dep graph and the extension module below compiles.

v1.1 will restore pg13..pg16 when one of:

  • pgrx 0.13+ removes the feature-multiplexing constraint, or
  • the pgrx-using code is moved to a non-workspace sub-crate that does not participate in --workspace --all-features gates.

See feedback-pgrx-feature-isolation memory for the full design-decision record and retire conditions.

§Provided SQL functions (when built as an extension)

  • samkhya_hll_count(input anyarray) -> bigint — build a samkhya HllSketch from the input array and return its estimated distinct-element count. Useful as a quick sanity check that the in-engine sketch agrees with the portable sketch produced by samkhya-core.
  • samkhya_puffin_inspect(path text) -> jsonb — open a Puffin sidecar file on the server filesystem and return per-blob metadata (kind, offset, length, fields, compression-codec).

§Scope

This is the v1.0 scaffold. A v1.1 target is the operator-side cardinality hook (replacing get_relation_info_hook and friends) so the planner picks up samkhya’s portable, feedback-driven, self-correcting row estimates without per-query SQL changes. The get_relation_info_hook integration is intentionally deferred because it requires deeper pgrx hook plumbing than belongs in a scaffold.

Functions§

version
Returns the samkhya-postgres crate version string.