// STRYKE-POSTGRES — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

stryke-postgres is one of the opt-in connector packages in the stryke ecosystem. PostgreSQL client for stryke. Opt-in package, kept out of the stryke core binary so the daily-driver install stays slim.

Sync postgres crate. Designed for shell pipelines + scripts, not as an ORM layer.

~ARCHITECTURE

In-process cdylib design: the stryke side is a thin .stk wrapper that calls FFI symbols on the dlopen'd library. No subprocess, no pipe — calls return on the same thread that made them.

$WHY OPT-IN (NOT BUILTIN)

Sync postgres crate. Designed for shell pipelines + scripts, not as an ORM layer.

The trade-off is intentional. The core stryke binary stays under ~40 MB precisely because each connector ships separately. Daily-driver work (one-liners, awk replacement, data scripting) doesn't need MongoDB drivers, AWS SDKs, or Spark Connect bindings linked in.

&FFI ENVELOPE

JSON in / JSON out across the FFI boundary. Each Postgres::* wrapper serializes its args to a JSON dict and calls the matching pg__* symbol resolved out of libstryke_postgres.{dylib,so}; the cdylib returns a JSON CString the wrapper parses. JSON binds map to wire values via the cdylib's json_to_param (null → NULL, bool → bool, int → i64, float → f64, string → text, array/object → jsonb). The returned CString is freed via the cdylib-exported stryke_free_cstring, wired automatically by rust_ffi::load_cdylib.

# request shape (built by the .stk wrapper)
{"verb": "<op>", "...": ...}

# response shape
{"result": ...}            # success — per-fn shape
{"error": "<msg>"}        # failure — wrapper die()s with the message

@CONNECTION RESOLUTION

Every connecting wrapper threads its %opts through one builder (Postgres::_req in lib/Postgres.stk), which collects the connection keys and falls back to the environment. Resolution order:

Statements sharing the same resolved connection key reuse the same cached postgres::Client (connection affinity), which is what lets begin/commit, savepoints, and LISTEN/NOTIFY stay on one backend with no extra socket setup.

/PUBLIC SURFACE

The package is intentionally narrower than the underlying postgres driver — the goal is "useful from a shell pipeline", not "complete API coverage". The surface groups into the categories below; the authoritative per-function reference is the README "API reference" and the rendered Docs page.

Injection-safety invariants hold across the surface: table, column, conflict, returning, savepoint, and maintenance-target names are identifier-validated/quoted; values are bound as positional parameters. Where a clause is interpolated rather than bound (update/delete $where, analyze/vacuum/reindex targets), the README documents it explicitly so the caller passes trusted input.

%TYPE ENCODING

Result columns are encoded Postgres → JSON before crossing the FFI boundary:

#PROJECT METADATA