chore(pg): remove native pg binding, compile real package from source

[proggeramlug]

Summary

Deletes the native pg binding (crates/perry-ext-pg, sqlx::postgres + tokio bridge) and the duplicate pre-#466 in-tree pg implementation living inside crates/perry-stdlib/src/pg/ (the bundled-pg Cargo feature), plus every registry entry that pointed at either one. import ... from "pg" no longer resolves as a native module at all — it now compiles the real npm pg package from source, same as any other TypeScript/JavaScript dependency.

Must not merge before #10674 (fix/10437-cjs-conditional-require) — pg does not run without that fix: a literal require('pg-native') inside a conditional guard in pg/lib/native/client.js was hoisted to an eager static import and threw at program start. This branch is based on #10674's head (b1ba0caf5), not main.

Why two implementations

crates/perry-ext-pg (the registered [bindings.pg] binding, sqlx::postgres + perry-ffi) was the one actually wired up. But crates/perry-stdlib/src/pg/ turned out to be a second, older, full native reimplementation of pg (its own module doc: "pg compatible native implementation... drop-in replacement for the pg npm package using sqlx"), kept around behind a bundled-pg feature since before the #466 migration to a separate ext crate. It defined the exact same extern "C" symbol names (js_pg_client_new, js_pg_client_query, …) as perry-ext-pg, so in any build that linked both, the linker's link-order (perry-ext wins) silently discarded the stdlib copy — but it still compiled into every build that also used mysql2 (its #[cfg] was any(bundled-pg, bundled-mysql2)). Verified zero cross-references from mysql2's module before deleting it, so this is a clean removal, not a partial one.

What was deleted

• crates/perry-ext-pg/ (Cargo.toml + 750-line lib.rs)
• crates/perry-stdlib/src/pg/ (929 lines: connection.rs, pool.rs, result.rs, types.rs, mod.rs) and the bundled-pg / database-postgres Cargo features that gated it
• the now-unused "postgres" sqlx feature on perry-stdlib's shared sqlx dependency (verified nothing outside the deleted pg/ module referenced sqlx::postgres/PgPool/etc. — mysql2's own sqlx dependency never requested it)
• registry entries: crates/perry/well_known_bindings.toml ([bindings.pg] + upstream pin), NATIVE_MODULES in crates/perry-api-manifest/src/entries.rs, the manifest method/class rows in entries/part_1.rs and part_3.rs, the pg row in crates/perry-codegen/src/lower_call/native_table/databases.rs (7 NativeModSig rows — caught by every_dispatch_entry_has_manifest_counterpart, which fails on drift between this table and the manifest), crates/perry/src/commands/stdlib_features.rs, the bundled-pg/pg entries in optimized_libs/driver.rs and optimized_libs/freshness.rs, the workspace Cargo.toml member + path-dependency entries, and the perry-ext-pg entry in workspace-architecture.json

What was deliberately left alone

A grep sweep turned up roughly a dozen more "pg"-literal matches deep in perry-hir (local_natives.rs, native_new.rs, native_fetch.rs, module_decl.rs, stmt.rs, expr_call/static_and_instance.rs, expr_assign.rs) and perry-codegen (lower_call/builtin.rs's lower_builtin_new disambiguation, codegen/opts.rs's doc comment) — all ("pg", "connect") => Some("Client")-shaped type-narrowing heuristics for the removed native binding. Checked each one: every arm is reached only through ctx.lookup_native_module() / ctx.imported_class_sources lookups that require the module to have actually been classified native at import time. Since pg can no longer classify as native, these arms are unreachable dead code, not live landmines — confirmed both by reading the gating code and empirically, since the original compilability probe (which forced real-source pg via compilePackages while pg was still registered native) already exercised this exact "real pg source, non-native path" combination successfully. perry-codegen-js/src/emit/native.rs's browser-target "pg" => throw(...) arm is similarly dead (only reached for calls already lowered as native). Left as-is per the brief's "keep the diff tight" scope — noting them here for anyone doing a future dead-code sweep.

The real post-removal experience (no compilePackages entry for pg)

Tested with a from-scratch node_modules (npm install under Node 26.5.1) and a package.json containing only:

{
  "dependencies": { "pg": "^8" }
}

No perry.compilePackages key at all. perry compile pg_test.ts printed Compile package wildcard: expanded to 14 installed package(s) — when perry.compilePackages is entirely absent, Perry's default behavior sweeps every installed node_modules package as a compile-from-source candidate, which covered pg and all 13 of its transitive deps (pg-cloudflare, pg-connection-string, pg-pool, pg-protocol, pg-types, pgpass, pg-int8, postgres-array, postgres-date, postgres-interval, postgres-bytea, split2, xtend) automatically. It compiled all 43 modules, linked, and produced a 24.7 MB binary.

So: for a project where pg is the only (or main) native-ish dependency, no perry.compilePackages configuration is needed at all — just the ordinary npm "pg": "^8" entry. For a project with a larger, more heterogeneous node_modules (where blindly wildcard-compiling everything installed isn't desirable — some packages may not be TypeScript-subset-compatible), the recommended path is still an explicit perry.compilePackages list naming pg and the same 13 transitive packages above, scoping compilation precisely instead of relying on the wildcard.

Running the compiled binary against a Client({ host: "127.0.0.1", port: 5432, ... }) / client.connect() (no Postgres listening on this host): RESULT: ERROR Connection refused (os error 111) — a genuine OS-level net.connect() failure from the real npm pg source, reached with zero native-pg code anywhere in the tree. This is the same milestone the original compilability probe hit (which needed compilePackages forcing while the native binding still existed); this PR reaches it as the default, unforced behavior. No live Postgres was available to test a real query round-trip — that remains unverified, stated plainly rather than implied.

Validation (host: perrymaster, Node 26.5.1 at /opt/node-v26.5.1-linux-x64; box default is 26.8.1)

• Build: cargo build --profile perry-dev -p perry -p perry-runtime-static -p perry-stdlib-static — clean, single invocation, confirmed the .a/binary mtimes moved after the final edit (an earlier E2E attempt caught a real coherence bug from building perry before the last source edit landed — a stale/current source-fingerprint mismatch between the compiler and a freshly auto-optimize-built runtime archive; rebuilding both together in one invocation fixed it, consistent with the Archives from separate cargo invocations can bundle different tokio builds off one Cargo.lock; the link guard catches it but two agents hit it today in unrelated work #10671 archive-coherence warning in the brief).
• cargo test, all perry-dev:
  • perry-api-manifest: 39/39
  • perry-hir (lib + every integration test file, including unimplemented_api_check.rs): 459 lib tests + all integration suites, 0 failures
  • perry-codegen: all 36 integration test targets green (including manifest_consistency's every_dispatch_entry_has_manifest_counterpart, which initially caught the dispatch-table drift this PR now fixes). perry-codegen's own lib unit tests could not be compiled — pre-existing on the fix(cjs): defer conditional CommonJS require() init instead of hoisting (#10437) #10674 base commit itself (b1ba0caf5), unrelated to this change: instanceof_imported_rhs_tests.rs / new_builtin_shadow_tests.rs construct an ImportedClass literal missing the constructor_has_synthetic_arguments field, confirmed present at b1ba0caf5 before my first commit. Not mine to fix; named explicitly here as something I did not get a pass/fail count for.
  • perry-stdlib: 139/139
  • perry --bin perry (stdlib_features + optimized_libs filtered): 52/52 (matches chore: remove Tier A native bindings (fetch alias, tursodb, iroh) #10618's precedent number). Full unfiltered suite: 1129/1130 on the first run, with one commands::compile::geisterhand::…warm_archives_are_rebuilt_as_one_runtime_graph failure that re-ran green in isolation — a transient resource-contention artifact from a heavily shared host (multiple concurrent agents running their own cargo build --release, disk at 96-99% used throughout), not a pg regression; that test doesn't touch pg/mysql2/well_known_bindings at all.
  • perry-runtime (RUST_TEST_THREADS=1, untouched by this diff): 4039 passed, 2 failed, 4 ignored. Both failures are the two known pre-existing debug_assert!-gated cases named in the campaign brief (gc::tests::copy_slot_decode::…, gc::tests::heap_generation::…), which fail under perry-dev/release by construction (both profiles compile out debug_assert!). Confirmed unrelated to this change — perry-runtime is untouched by this diff.
• Lint (SKIP_COMPILE_GATES=1 ./scripts/run_lint_gates.sh): 76 of 77 passed (compile tier skipped per host convention, 2 CI-only skipped). The one red, "Public benchmark evidence freshness", is the pre-existing, repo-wide red named in the brief — not chased. Along the way this also caught and fixed two gates this removal touches that PR chore: remove Tier A native bindings (fetch alias, tursodb, iroh) #10618's tier-A removal never exercised: workspace_architecture.py --check (the recorded baseline object in workspace-architecture.json needed workspace_members/decision_counts refreshed — no script flag does this automatically, recomputed via the module's own helpers) and string_payload_access_inventory.py (a per-file ratchet baseline with a stale perry-ext-pg entry).
• Governance/registry gates (the ones this removal is actually about): binding_governance.py --check OK, binding_pins.mjs --check OK, unrooted_local_shape.py --check OK (baseline refreshed), check_file_size.sh OK.

package.json a user now needs

{
  "dependencies": { "pg": "^8" }
}

No perry.compilePackages entry required when pg is the project's only real dependency (Perry's no-config wildcard covers it and its transitive deps). For a project with other, unrelated npm packages installed, list pg plus its transitive deps explicitly in perry.compilePackages instead of relying on the wildcard sweeping everything: pg, pg-cloudflare, pg-connection-string, pg-pool, pg-protocol, pg-types, pgpass, pg-int8, postgres-array, postgres-date, postgres-interval, postgres-bytea, split2, xtend.

Scope

Removal only — no other binding touched. A sibling agent is concurrently removing the axios binding on its own branch against the same shared registry files (well_known_bindings.toml, entries.rs, stdlib_features.rs, workspace Cargo.toml, workspace-architecture.json); expect a merge conflict there, resolved by the merge train, not by either PR individually.

---

Rebase note (2026-09-20)

Rebased onto main @ b9ba951ff861c61afb845bfbdfa574cb0fa4080e (train 239) as part of a
4-PR sequential rebase campaign together with #10795, #10680, #10704 — all four
independently rebased onto this same main SHA and pushed together. This PR's base is now
main, not fix/10437-cjs-conditional-require: that branch squash-merged into main
some time ago (its content lives on main as e52aae9947/077140b8eb), so this needed the
two-step unstack — git rebase --onto origin/main <fix/10437 tip> pr-10677 followed by
gh pr edit --base main — not a plain rebase, which would have reported CONFLICTING
against a stale, no-longer-reachable base.

Conflicts: Cargo.lock (resynced via cargo metadata --offline), crates/perry-api-manifest/ src/entries.rs and workspace-architecture.json (both the ordinary "two unrelated
deletions landed at the same list position" shape — main had already dropped uuid/qs
entries adjacent to pg's; resolved by removing only pg's own lines, keeping everything
else exactly as it stands on current main), then a second round on docs/api/perry.d.ts,
docs/src/api/reference.md, docs/src/native-libraries/governance.md,
scripts/string_payload_access_baseline.txt, scripts/unrooted_local_shape_baseline.json
and workspace-architecture.json again — all fully regenerated from the resolved tree
via their own tools rather than hand-merged.

Found and fixed a gap in the original PR while rebasing: .github/workflows/test.yml
still named -p perry-ext-pg in two cargo build --release steps (the compile-smoke job and
the per-UI-backend build job, ~lines 3029/3881 on current main) — the original PR never
touched test.yml. Left alone, both jobs would fail to resolve a crate this PR deletes.
Removed -p perry-ext-pg from both lines; left -p perry-ext-mysql2 on those same lines
untouched (that's #10680's job, landing independently).

Recomputed triple: workspace_members=69 (decision_counts: externalize=20, keep=44,
merge=1, remove=1, review=3) — the committed baseline was stale (recorded from an earlier
main) and needed a full recompute, plus a stray "perry-ext-pg" entry survived the
auto-merge in the per-crate map itself (baseline alone would have looked consistent while
still naming a deleted crate — --check catches this, which is why it's not enough to trust
a clean auto-merge); native_result_ledger: 349 rows / 300 providers (main's real ledger
minus pg's 7 rows / 7 providers); unrooted-local-shape total: 520 (main's real total minus
pg's 7-line perry-ext-pg/src/lib.rs entry; one unrelated file, tls.rs, also drifted +1
between this branch's fork point and current main — real tree drift, not something this PR
touched).

These numbers assume main is still at the stated SHA — #10795/#10680/#10704 remove
different crates from the same starting point; whichever of the four lands first moves the
ground under the other three's counts.

Gates: cargo fmt --all -- --check OK (after one cargo fmt --all pass to fix a
comment-alignment mismatch left by the merge resolution); cargo check --workspace --all-targets under -D warnings on the default dev profile (excl. perry-ui-gtk4) —
clean; run_lint_gates.sh SKIP_COMPILE_GATES=1 — 78 of 79 passed (1 pre-existing, #10707,
not chased); binding_governance.py --check OK; binding_pins.mjs --check under Node
26.5.1 OK; check_file_size.sh OK. Compile tier not run. No gap sweep run. No acceptance
re-run — pg's behavior is unchanged by this rebase.

Summary by CodeRabbit

• Breaking Changes

  • Removed Perry’s bundled native PostgreSQL (pg) binding.
  • import ... from "pg" now uses the npm pg package compiled from source instead of native support.
  • PostgreSQL-specific native APIs, including Client, Pool, connect, query, and related methods, are no longer provided.

• Documentation

  • Updated API references and native-binding documentation to reflect the removal and new package-compilation behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 7981b337-c652-46d3-8eca-73d06e11e746

📥 Commits

Reviewing files that changed from the base of the PR and between b9ba951 and 624b9d6.

⛔ Files ignored due to path filters (2)

• Cargo.lock is excluded by !**/*.lock
• scripts/native_result_ledger.tsv is excluded by !**/*.tsv

📒 Files selected for processing (28)

• .github/workflows/test.yml
• Cargo.toml
• changelog.d/10677-remove-pg-native-binding.md
• crates/perry-api-manifest/src/entries.rs
• crates/perry-api-manifest/src/entries/part_1.rs
• crates/perry-api-manifest/src/entries/part_3.rs
• crates/perry-codegen/src/lower_call/native_table/databases.rs
• crates/perry-ext-pg/Cargo.toml
• crates/perry-ext-pg/src/lib.rs
• crates/perry-stdlib/Cargo.toml
• crates/perry-stdlib/src/lib.rs
• crates/perry-stdlib/src/pg/connection.rs
• crates/perry-stdlib/src/pg/mod.rs
• crates/perry-stdlib/src/pg/pool.rs
• crates/perry-stdlib/src/pg/result.rs
• crates/perry-stdlib/src/pg/types.rs
• crates/perry/src/commands/compile/optimized_libs/driver.rs
• crates/perry/src/commands/compile/optimized_libs/freshness.rs
• crates/perry/src/commands/stdlib_features.rs
• crates/perry/well_known_bindings.toml
• docs/api/perry.d.ts
• docs/src/api/reference.md
• docs/src/native-libraries/governance.md
• docs/src/native-libraries/overview.md
• scripts/native_result_ledger.py
• scripts/string_payload_access_baseline.txt
• scripts/unrooted_local_shape_baseline.json
• workspace-architecture.json

💤 Files with no reviewable changes (17)

• crates/perry-api-manifest/src/entries.rs
• crates/perry-stdlib/src/pg/mod.rs
• crates/perry/src/commands/compile/optimized_libs/freshness.rs
• crates/perry-api-manifest/src/entries/part_1.rs
• Cargo.toml
• crates/perry-stdlib/src/pg/result.rs
• crates/perry-ext-pg/Cargo.toml
• docs/src/native-libraries/governance.md
• crates/perry-stdlib/src/pg/connection.rs
• crates/perry-api-manifest/src/entries/part_3.rs
• crates/perry/src/commands/compile/optimized_libs/driver.rs
• crates/perry/well_known_bindings.toml
• crates/perry/src/commands/stdlib_features.rs
• crates/perry-codegen/src/lower_call/native_table/databases.rs
• crates/perry-stdlib/src/pg/pool.rs
• crates/perry-ext-pg/src/lib.rs
• crates/perry-stdlib/src/pg/types.rs

Included review availability: Your plan provides up to 8 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR removes Perry’s native PostgreSQL binding, including its extension crate, bundled standard-library implementation, manifest entries, dispatch rows, feature gates, workspace records, and generated documentation. pg imports now compile the npm package from source.

Changes

Native PostgreSQL binding removal

Layer / File(s)	Summary
Remove PostgreSQL implementations Cargo.toml, crates/perry-ext-pg/*, crates/perry-stdlib/Cargo.toml, crates/perry-stdlib/src/lib.rs, crates/perry-stdlib/src/pg/*, crates/perry/well_known_bindings.toml	Removes the native extension crate, bundled PostgreSQL modules, PostgreSQL Cargo features, SQLx PostgreSQL support, and workspace registration.
Remove PostgreSQL resolution and dispatch paths crates/perry-api-manifest/*, crates/perry-codegen/.../databases.rs, crates/perry/src/commands/compile/*, workspace-architecture.json	Removes pg from native-module classification, API manifests, dispatch tables, automatic feature selection, Tokio coordination, and architecture metadata.
Update documentation and validation metadata .github/workflows/test.yml, changelog.d/*, docs/api/*, docs/src/api/*, scripts/*	Updates build package lists, documents source compilation of npm pg, regenerates API and native-library documentation, and adjusts ledger and baseline counts.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: removing the native pg binding and compiling the real package from source.
Description check	✅ Passed	The description is detailed and relevant. It explains the removal scope, affected registry and documentation updates, migration behavior, dependency on #10674, rebase status, validation results, and k…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 2

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch wip/pg-native-binding-removal

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[proggeramlug]

Heads-up before this is queued: this PR's recorded workspace baseline is stale and will fail workspace_architecture.py --check on rebase.

It records workspace_members 82 / externalize 32 / keep 45. Main (023dc0b653) is at 80 / 31 / 44, so a removal landing on it must produce 79 / 30 / 44 — not 82. Five sibling removal PRs carry the identical 82/32/45, which is also mutually impossible: six different crates cannot all produce the same transition.

Full table and reasoning in #10739. The short version, for whoever rebases this:

• Recompute from the resolved tree and let workspace_architecture.py --check --print-summary reproduce the number independently. Do not derive it from 83 by arithmetic, and do not copy a sibling's figure or one quoted in a comment — they all go stale as the queue advances.
• The same hazard applies to scripts/native_result_ledger.tsv, scripts/string_payload_access_baseline.txt and the governance/pins tables. Regenerate with their own scripts rather than resolving by hand.
• MERGEABLE will not catch this. The counts sit on different JSON lines from the deleted crate entry, so git auto-merges both sides without a conflict — chore(bindings): remove axios native binding, compile real axios from source #10679 rebased onto current main today, came out MERGEABLE, and still carried 82/32/45.

Also relevant to the acceptance run whenever it happens: #10735 is live on main — require.main === module is true in every compiled CommonJS module, so any dependency with a CLI entry guard runs its CLI branch when merely imported. A fix is in flight. If acceptance fails in a way that looks like the package misbehaving at import time, test a dependency-free fixture that never mentions the package before attributing it to this removal.

[proggeramlug]

This PR reports MERGEABLE, but its recorded counts are stale by twelve crates and will fail workspace_architecture.py --check on rebase.

It records workspace_members: 82 / externalize: 32 / keep: 45, derived when main was at a base of 83. Main is now at 70 / 21 / 44 — fourteen bindings have been removed since. A one-crate removal landing on today's main must produce 69 / 20 / 44, not 82/32/45.

Nothing about this is visible in the diff: the counts sit on different JSON lines from the deleted crate entry, so git auto-merges cleanly and GitHub reports the PR mergeable. See #10739 for the general mechanism.

A distinction worth drawing, because it caught me out

This PR's file is internally consistent: sum(decision_counts) == workspace_members == len(crates) = 82 in all three. It passes the three-way identity check that has caught two defects elsewhere in this campaign.

So the three-way check is necessary but not sufficient. It validates the file against itself, not against the tree the PR will land on. A file can be perfectly self-consistent and still describe a workspace that no longer exists. Both checks are needed:

1. internal: sum == workspace_members == len(crates) — catches a merge that updated one field and not another;
2. external: the values equal what the resolved tree actually contains after rebasing onto current main — catches staleness.

This PR passes (1) and fails (2). #10691 earlier failed (1) while looking plausible on (2). They are independent failure modes and neither check subsumes the other.

What this needs

A rebase onto current origin/main, with every absolute re-derived from the resolved tree rather than adjusted:

• workspace-architecture.json — recompute, verify both checks above.
• scripts/native_result_ledger.py — EXPECTED_ROWS/EXPECTED_PROVIDERS. Recount, do not subtract: the value is not obtainable by applying this PR's old delta to main's new base, because the tree shape differs.
• scripts/unrooted_local_shape_baseline.json — re-derive even if --check passes; a technically-passing stale number is how native_result_ledger.py is red on pristine main (expected 371, found 376), and its path filter means it can only fail on an unrelated PR #10738's masked defect survived.
• docs/api/perry.d.ts and docs/src/api/reference.md — regenerate from a fresh binary, header and body. These merge clean and stay stale, and nothing gates them; a stale declare module "..." block survived a clean merge on a previous removal.
• Cargo.lock — after any git checkout --ours, re-sync immediately with cargo metadata --offline rather than trusting the next build to catch a stale perry-ext-* entry.

[proggeramlug]

Landed via merge train 245 (#10845), released as v0.5.1624 — merge commit b3bffd778c.

Carried together with its sibling removal, deliberately: #10678's duplicate-symbol hazard is only closed by removing both bindings, because each existed twice (the perry-ext-* crate and the pre-#466 in-tree perry-stdlib/src/<pkg> behind a bundled-* feature), defining the same extern "C" symbols with link order silently deciding the winner. Removing one leaves the other's pair intact.

Two things were redone rather than carried through the rebase onto v0.5.1623:

• Cargo.lock was regenerated, not hand-merged. A hand-merge for a change that deletes two crates and their transitive trees is a guess; this took main's lock and let cargo reconcile it, then asserted the result (cargo metadata --offline --locked rc=0, no markers, no perry-ext-{pg,mysql2} / postgres / mysql_* entries).
• Every absolute count was re-derived against the new base. Removal counts are chained, so a baseline computed against an older main is wrong against the current one. All eight ratchets green, and binding_governance --check was checked for discrimination rather than assumed live: rc=0 on the train, rc=1 naming both crates on main's file.

Validation on the union: lint 6-of-6 with no unexpected failures, 6 unit suites with an empty failing set, both compiler-output suites at failed_workloads=[] with no transient excused, repsel_census rc=0, and a 140-fixture gap sweep across seven areas with zero unexplained regressions and every area asserted live.

Closing here rather than merging — a train lands the commits directly, so the source PR has nothing left to merge.