chadscript/postgres: native postgres client via libpq

[cs01]

What you get

import { Pool } from "chadscript/postgres";

const pool = new Pool("postgresql://postgres:secret@localhost:5432/mydb");

pool.query("CREATE TABLE users (id INT, name TEXT, age INT)");
pool.query("INSERT INTO users VALUES ($1, $2, $3)", ["1", "alice", "30"]);

const res = pool.query("SELECT id, name, age FROM users WHERE age > $1", ["18"]);
for (let i = 0; i < res.numRows; i++) {
  console.log(res.getInt(i, "id") + " " + res.getValue(i, "name"));
}

pool.end();

A first-class PostgreSQL client for ChadScript, built on libpq. Pool is the recommended entry point; Client is available for low-level lifecycle control. Parameterized queries with $1/$2 placeholders are safe against SQL injection — libpq handles escaping.

Why

Postgres is the most common server database, and until now ChadScript had no story for talking to it. You had to shell out to psql or write raw sockets. This closes that gap and lines up sqlite (ships today) + postgres (this PR) as the two supported databases, putting ChadScript on equal footing with Node for backend work that uses a real RDBMS.

This is also the first stdlib module built with the declare function cs_* + prefix-detection pattern, which makes adding new C-backed modules basically trivial going forward (MySQL and Redis next).

What's in the box

• Pool — recommended primary API, lazy-connects on first query
• Client — low-level explicit connect/end lifecycle
• QueryResult with rowCount, numRows, numCols, fields, and accessors getValue, getInt, getFloat, getBool, getRow
• Parameterized queries via $1, $2, ... — builds libpq PQexecParams via a stateful param-builder pattern to avoid marshaling a string[] across the FFI boundary
• Full docs at docs/stdlib/postgres.md, listed in docs/stdlib/index.md
• 4 test fixtures covering connect, rowCount, SELECT + row access, Pool, and parameterized queries with type coercion (marked @test-skip — they need a running postgres; CI service container is in a follow-up)

Current limitations (documented)

• All values are strings under the hood. getInt/getFloat/getBool parse on access. No OID-based auto-typing — users know their schema, they call the right getter.
• Pool is a thin wrapper over a single Client. No real connection reuse yet. Calls are sequential. Real pooling (multiple conns, queuing, limits) needs async, which is a follow-up.
• Synchronous under the hood. libpq calls block. Real async (libuv integration) is a follow-up.
• No null detection yet. My bridge returns empty string for NULL, which collides with legitimate empty text. Parallel null flags are a follow-up.
• No LISTEN/NOTIFY, no COPY, no streaming. The basics only.
• libpq install required. macOS: brew install libpq. Debian/Ubuntu: apt install libpq-dev. The build gracefully skips pg-bridge.o if headers are missing.

How it works

New convention: any C bridge function declared with the cs_pg_ prefix auto-flips a usesPostgres flag in the codegen, and the linker picks up -lpq + pg-bridge.o without any per-function wiring. Same pattern as cs_llvm_* / cs_lld_*. This is the pattern the future sqlite migration and MySQL/Redis stdlib modules should follow.

Also fixed an ABI gotcha that would have silently bitten future bridges: C bridge functions called from ChadScript as number must use double in C, not int. ARM64 returns ints in w0 and doubles in d0 — completely separate registers. Memory note saved at memory/c-bridge-abi-double-rule.md.

Test plan

• npm run verify:quick green (tests + stage 1 self-hosting)
• Manual e2e against a local podman run postgres:16 — all 4 fixtures pass:
  • postgres-connect.ts — connect + end
  • postgres-query-rowcount.ts — CREATE, INSERT, UPDATE, DELETE with expected rowCounts
  • postgres-query-select.ts — SELECT 3 rows, column lookup by name, empty result set
  • postgres-pool.ts — Pool lazy-connect + CRUD
  • postgres-params-types.ts — parameterized queries, getInt/getFloat/getBool, SQL-injection-safety with a quoted value
• CI postgres service container (follow-up PR)
• Flagship URL-shortener example (follow-up PR)

🤖 Generated with Claude Code

[github-actions]

Benchmark Results (Linux x86-64)

Benchmark	C	ChadScript	Go	Node	Place
Binary Trees	1.398s	1.228s	2.733s	1.156s	🥈
Cold Start	0.9ms	0.8ms	1.2ms	26.4ms	🥇
Fibonacci	0.814s	0.763s	1.560s	3.159s	🥇
File I/O	0.117s	0.091s	0.087s	0.207s	🥈
JSON Parse/Stringify	0.004s	0.005s	0.017s	0.015s	🥈
Matrix Multiply	0.456s	0.714s	0.566s	0.371s	#4
Monte Carlo Pi	0.389s	0.410s	0.405s	2.248s	🥉
N-Body Simulation	1.671s	2.126s	2.201s	2.388s	🥈
Quicksort	0.215s	0.246s	0.213s	0.262s	🥉
SQLite	0.352s	0.376s	—	0.418s	🥈
Sieve of Eratosthenes	0.014s	0.028s	0.018s	0.039s	🥉
String Manipulation	0.008s	0.017s	0.016s	0.036s	🥉

CLI Tool Benchmarks

Benchmark	ChadScript	grep	node	xxd	Place
Hex Dump	0.429s	—	0.980s	0.129s	🥈
Recursive Grep	0.018s	0.009s	0.097s	—	🥈