chadscript/postgres: native postgres client via libpq (#512)

* postgres: libpq c bridge (step 1/10)

adds c_bridges/pg-bridge.c with thin wrappers around libpq for connect,
exec, parameterized exec, and result introspection. build-vendor.sh
detects libpq headers (keg-only brew install on darwin, system paths on
linux) and gracefully skips when absent. no codegen or ts wiring yet —
this commit is just the foundation for chadscript/postgres.

* postgres: lib/postgres.ts with Client, extern binding, link wiring (step 2/10)

adds chadscript/postgres module. lib/postgres.ts uses declare function
bindings to cs_pg_* externs — compiler auto-detects the cs_pg_ prefix
in llvm-generator.ts, flips a new usesPostgres flag, and the link step
picks up -lpq plus homebrew keg-only libpq lib path. pg-bridge.o is
included conditionally. Client class exposes connect()/end() — query
comes in step 3.

verified end-to-end: compiled a fixture that connects to a local
podman postgres and cleanly disconnects. the cs_pg_connect extern is
called directly from the TS Client.connect method, no codegen
special-casing required. pattern matches cs_llvm_*/cs_lld_*.

workaround: added trailing return in parser-native transformExpression
for the known checkMissingReturns false-positive
(memory/native-missing-returns-false-positive.md) — the usesPostgres
field addition shifted AST layouts and tripped the bug.

* postgres: .query() returning rowCount + abi fix (step 3/10)

adds Client.query(sql) that returns QueryResult with rowCount for
INSERT/UPDATE/DELETE. test fixture covers single insert, multi-row
insert, update, and delete.

abi fix: c functions called from chadscript as returning 'number' must
return 'double', not 'int' — chadscript maps 'number' to llvm double,
which lives in d0 on arm64 while c int returns come back in w0,
completely different registers. previous step 2 passed by luck because
CONNECTION_OK happens to be 0 and d0 was zero-initialized.

fixed the whole bridge preemptively: all int-returning cs_pg_* now
return double, all int parameters (row, col, nparams) are now double
with internal cast. matches the pattern cs_lld_available uses.

* postgres: SELECT support with Row access (step 4/10)

adds nrows/ncols/fname/getvalue/getisnull extern bindings and SELECT
row access. QueryResult now holds flat { fields, values } plus numRows
/numCols — getValue(row, col) walks the fields[] to resolve a column
name to its offset and returns the string. getRow(idx) constructs a
lightweight Row view for iteration.

flat-storage design avoids chadscript ObjectArray type-loss: storing
Row[] and accessing rows[i].get() inside lib/postgres.ts triggered
compile errors because element access on an object array discards the
concrete type. keeping values as a string[] sidesteps the problem.

test covers 3-row SELECT with column-name lookup, field ordering,
empty result set, and rowCount.

c bridge now gc_strdups all string returns (getvalue, fname, error
messages, cmdtuples) so they survive past cs_pg_clear — previously
those pointers dangled into the freed PGresult.

* postgres: Pool, parameterized queries, typed accessors, docs (steps 5+6/10)

Pool: thin wrapper over Client that lazy-connects on first query. v1
is sequential — real pooling (multiple conns, queuing) needs async and
is a follow-up. matches node-pg's Pool entry point so copy-paste from
tutorials works. Pool is now the documented primary API; Client is
the low-level escape hatch.

Parameterized queries: pool.query(sql, params) uses libpq's PQexecParams
via a stateful param-builder pattern (cs_pg_params_new / _add /
_exec_params_with). avoids marshaling a chadscript string[] across the
ffi boundary — the %StringArray struct layout doesn't match libpq's
const char**. TS passes values one at a time; c side grows its own
dynamic array. placeholders are $1, $2, $3 (postgres native syntax).
libpq handles escaping so user input with quotes or semicolons is safe.

Typed accessors on QueryResult: getInt, getFloat, getBool delegate to
parseInt/parseFloat/string compare — saves users from writing boiler-
plate parsing on every access. no OID-based auto-typing — users know
their schema, they call the right getter. avoids type-coercion surprises.

Docs: new docs/stdlib/postgres.md with Pool-first API, documented
limitations (sync, no null detection, string-only params, no real
pooling). chadscript/postgres added to stdlib module index.

test coverage: postgres-pool (Pool lazy-connect + CRUD),
postgres-params-types (getInt/Float/Bool + parameterized queries +
sql-injection safety with quoted param values).

* postgres: fix stage 2 self-hosting regression via minimal src surface

step 2 added a usesPostgres field to LLVMGenerator plus a cs_pg_ prefix
check in generateExternDeclaration plus a trailing-return workaround in
parser-native/transformer.ts. any of those shifted enough state that the
native stage 1 compiler began miscompiling generateGlobalVariableDeclarations
— storing a pointer into a double slot for isClassInstance. --quick
skipped stage 2 so it passed local verify but failed CI.

fix: do the -lpq/pg-bridge.o detection entirely in compiler.ts and
native-compiler-lib.ts by walking generator.declaredExternFunctions for
anything starting with cs_pg_. no changes to llvm-generator.ts,
generator-context.ts, or parser-native/transformer.ts. feature is
functionally identical end-to-end (verified against local postgres).

npm run verify (full, including stage 2) is green on this commit.

---------

Co-authored-by: cs01 <cs01@users.noreply.github.com>

Author: cs01

c_bridges/pg-bridge.c

@@ -0,0 +1,138 @@
+#include <libpq-fe.h>
+#include <stdlib.h>
+#include <string.h>
+
+extern void *GC_malloc_atomic(size_t);
+
+static const char *gc_strdup(const char *s) {
+    if (!s) return "";
+    size_t n = strlen(s);
+    char *out = (char *)GC_malloc_atomic(n + 1);
+    memcpy(out, s, n + 1);
+    return out;
+}
+
+void *cs_pg_connect(const char *conninfo) {
+    if (!conninfo) return NULL;
+    PGconn *conn = PQconnectdb(conninfo);
+    return (void *)conn;
+}
+
+double cs_pg_status(void *conn) {
+    if (!conn) return (double)CONNECTION_BAD;
+    return (double)PQstatus((PGconn *)conn);
+}
+
+const char *cs_pg_error_message(void *conn) {
+    if (!conn) return "null connection";
+    return gc_strdup(PQerrorMessage((PGconn *)conn));
+}
+
+void cs_pg_finish(void *conn) {
+    if (!conn) return;
+    PQfinish((PGconn *)conn);
+}
+
+void *cs_pg_exec(void *conn, const char *sql) {
+    if (!conn || !sql) return NULL;
+    return (void *)PQexec((PGconn *)conn, sql);
+}
+
+void *cs_pg_exec_params(void *conn, const char *sql, double nparams, const char **values) {
+    if (!conn || !sql) return NULL;
+    return (void *)PQexecParams((PGconn *)conn, sql, (int)nparams, NULL, values, NULL, NULL, 0);
+}
+
+typedef struct {
+    const char **values;
+    int count;
+    int capacity;
+} PgParamList;
+
+void *cs_pg_params_new(void) {
+    PgParamList *p = (PgParamList *)GC_malloc_atomic(sizeof(PgParamList));
+    if (!p) return NULL;
+    p->count = 0;
+    p->capacity = 8;
+    p->values = (const char **)GC_malloc_atomic(sizeof(const char *) * (size_t)p->capacity);
+    return (void *)p;
+}
+
+void cs_pg_params_add(void *params, const char *value) {
+    if (!params) return;
+    PgParamList *p = (PgParamList *)params;
+    if (p->count >= p->capacity) {
+        int newcap = p->capacity * 2;
+        const char **newvals = (const char **)GC_malloc_atomic(sizeof(const char *) * (size_t)newcap);
+        for (int i = 0; i < p->count; i++) newvals[i] = p->values[i];
+        p->values = newvals;
+        p->capacity = newcap;
+    }
+    p->values[p->count++] = value ? gc_strdup(value) : NULL;
+}
+
+void *cs_pg_exec_params_with(void *conn, const char *sql, void *params) {
+    if (!conn || !sql) return NULL;
+    PgParamList *p = (PgParamList *)params;
+    int n = p ? p->count : 0;
+    const char **vals = p ? p->values : NULL;
+    return (void *)PQexecParams((PGconn *)conn, sql, n, NULL, vals, NULL, NULL, 0);
+}
+
+double cs_pg_result_status(void *res) {
+    if (!res) return (double)PGRES_FATAL_ERROR;
+    return (double)PQresultStatus((PGresult *)res);
+}
+
+const char *cs_pg_result_error_message(void *res) {
+    if (!res) return "null result";
+    return gc_strdup(PQresultErrorMessage((PGresult *)res));
+}
+
+double cs_pg_nrows(void *res) {
+    if (!res) return 0.0;
+    return (double)PQntuples((PGresult *)res);
+}
+
+double cs_pg_ncols(void *res) {
+    if (!res) return 0.0;
+    return (double)PQnfields((PGresult *)res);
+}
+
+const char *cs_pg_fname(void *res, double col) {
+    if (!res) return "";
+    const char *n = PQfname((PGresult *)res, (int)col);
+    return gc_strdup(n ? n : "");
+}
+
+double cs_pg_ftype(void *res, double col) {
+    if (!res) return 0.0;
+    return (double)PQftype((PGresult *)res, (int)col);
+}
+
+const char *cs_pg_getvalue(void *res, double row, double col) {
+    if (!res) return "";
+    return gc_strdup(PQgetvalue((PGresult *)res, (int)row, (int)col));
+}
+
+double cs_pg_getisnull(void *res, double row, double col) {
+    if (!res) return 1.0;
+    return (double)PQgetisnull((PGresult *)res, (int)row, (int)col);
+}
+
+const char *cs_pg_cmdtuples(void *res) {
+    if (!res) return "0";
+    const char *c = PQcmdTuples((PGresult *)res);
+    return gc_strdup((c && *c) ? c : "0");
+}
+
+void cs_pg_clear(void *res) {
+    if (!res) return;
+    PQclear((PGresult *)res);
+}
+
+double cs_pg_result_ok(void *res) {
+    if (!res) return 0.0;
+    ExecStatusType s = PQresultStatus((PGresult *)res);
+    return (s == PGRES_COMMAND_OK || s == PGRES_TUPLES_OK) ? 1.0 : 0.0;
+}

docs/stdlib/index.md

@@ -25,11 +25,13 @@ A few APIs live in named modules and need an import:
 ```typescript
 import { httpServe, Router, Context } from "chadscript/http";
 import { ArgumentParser } from "chadscript/argparse";
+import { Pool } from "chadscript/postgres";
 ```
 
 | Module | Contents |
 |--------|----------|
 | `chadscript/http` | `httpServe`, `wsBroadcast`, `wsSend`, `parseMultipart`, `bytesResponse`, `serveFile`, `getHeader`, `parseQueryString`, `parseCookies`, `Router`, `Context`, `RouterRequest` |
 | `chadscript/argparse` | `ArgumentParser` |
+| `chadscript/postgres` | `Pool`, `Client`, `QueryResult`, `Row` — PostgreSQL client via `libpq` |
 
 The `chadscript/` prefix works like Node's `node:` prefix — unambiguous and collision-free.

docs/stdlib/postgres.md

@@ -0,0 +1,147 @@
+# postgres
+
+PostgreSQL client via `libpq`. Connect to a Postgres database, run queries, and read results as native strings. Imported as a module:
+
+```typescript
+import { Pool } from "chadscript/postgres";
+```
+
+`libpq` is required at build time. On macOS: `brew install libpq`. On Debian/Ubuntu: `apt install libpq-dev`.
+
+## `new Pool(conninfo)`
+
+Create a connection pool. The connection string follows [libpq's format](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) — either key/value pairs or a URI.
+
+```typescript
+const pool = new Pool("host=127.0.0.1 port=5432 user=postgres password=secret dbname=mydb");
+// or
+const pool2 = new Pool("postgresql://postgres:secret@127.0.0.1:5432/mydb");
+```
+
+`Pool` is the recommended entry point for application code. It connects lazily on first query — the constructor does not block.
+
+## `pool.query(sql)`
+
+Execute a SQL statement and return a [`QueryResult`](#queryresult). Throws on SQL errors. Parameterized queries are coming in a follow-up; for now, build the SQL string yourself — **escape any user input** or you will ship an SQL injection.
+
+```typescript
+pool.query("CREATE TABLE users (id INT, name TEXT)");
+pool.query("INSERT INTO users VALUES (1, 'alice')");
+
+const res = pool.query("SELECT id, name FROM users ORDER BY id");
+console.log(res.rowCount);            // 1
+console.log(res.getValue(0, "name")); // "alice"
+```
+
+## `pool.end()`
+
+Close the pool's underlying connection. Safe to call multiple times.
+
+```typescript
+pool.end();
+```
+
+## `Client` (low-level)
+
+For cases where you need explicit connection lifecycle, use `Client` directly:
+
+```typescript
+import { Client } from "chadscript/postgres";
+
+const c = new Client("postgresql://postgres:secret@127.0.0.1:5432/mydb");
+c.connect();
+const res = c.query("SELECT 1");
+c.end();
+```
+
+Most application code should prefer `Pool`. `Client` requires you to call `connect()` before any queries — `Pool` handles this automatically.
+
+## `QueryResult`
+
+Returned by `client.query()`. All values are currently strings — type coercion (integer, boolean, date) is a follow-up.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rowCount` | `number` | Affected rows (INSERT/UPDATE/DELETE) or number of rows returned (SELECT) |
+| `numRows` | `number` | Number of rows in the result set (SELECT) |
+| `numCols` | `number` | Number of columns in the result set |
+| `fields` | `string[]` | Column names in order |
+
+### `result.getValue(row, col)`
+
+Return the value at a given row index and column name, as a string.
+
+```typescript
+const res = c.query("SELECT id, name, city FROM users ORDER BY id");
+for (let i = 0; i < res.numRows; i++) {
+  const name = res.getValue(i, "name");
+  const city = res.getValue(i, "city");
+  console.log(name + " in " + city);
+}
+```
+
+Column lookup by name is linear in the number of columns. If you're reading millions of rows in a tight loop, cache the column index:
+
+```typescript
+const nameIdx = res.fields.indexOf("name");
+for (let i = 0; i < res.numRows; i++) {
+  const r = res.getRow(i);
+  console.log(r.getAt(nameIdx));
+}
+```
+
+### `result.getRow(index)`
+
+Return a lightweight `Row` view into the result set. The returned `Row` holds a reference to the parent result's data — it does not copy.
+
+```typescript
+const r = res.getRow(0);
+const name = r.get("name");    // by column name
+const first = r.getAt(0);      // by column index
+```
+
+## Example — CRUD
+
+```typescript
+import { Pool } from "chadscript/postgres";
+
+const pool = new Pool("postgresql://postgres:secret@127.0.0.1:5432/mydb");
+
+pool.query("DROP TABLE IF EXISTS users");
+pool.query("CREATE TABLE users (id INT, name TEXT, city TEXT)");
+
+pool.query("INSERT INTO users VALUES (1, 'alice', 'nyc'), (2, 'bob', 'sf')");
+
+const res = pool.query("SELECT id, name, city FROM users ORDER BY id");
+console.log("rows: " + res.numRows);
+for (let i = 0; i < res.numRows; i++) {
+  console.log(res.getValue(i, "id") + " " + res.getValue(i, "name") + " " + res.getValue(i, "city"));
+}
+
+const upd = pool.query("UPDATE users SET city = 'LA' WHERE id = 1");
+console.log("updated " + upd.rowCount);
+
+pool.end();
+```
+
+## Current Limitations
+
+This module is under active development. Known gaps:
+
+- **No parameterized queries yet** — every query is literal SQL. Build strings carefully and never concatenate user input. Coming soon.
+- **All values are strings** — integers come back as `"42"`, booleans as `"t"`/`"f"`, dates as ISO-ish strings. Type coercion is a follow-up.
+- **`Pool` is a thin wrapper over a single `Client`** — no real connection reuse yet. Calls are sequential. Real pooling (multiple connections, queuing, limits) needs async, which is a follow-up.
+- **Synchronous under the hood** — `libpq` is called synchronously. Calls block the event loop. Real async (libuv integration) is a follow-up.
+- **No `LISTEN`/`NOTIFY`, no `COPY`, no streaming** — the basics only.
+
+## Native Implementation
+
+| API | Maps to |
+|-----|---------|
+| `new Client()` / `connect()` | `PQconnectdb()` + `PQstatus()` |
+| `client.query()` | `PQexec()` + `PQresultStatus()` + `PQgetvalue()` loop |
+| `QueryResult.fields` | `PQfname()` per column |
+| `QueryResult.numRows` / `numCols` | `PQntuples()` / `PQnfields()` |
+| `client.end()` | `PQfinish()` |
+
+All string values returned from `libpq` are copied into GC-managed memory before the underlying `PGresult` is cleared, so values remain valid after the next query.