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

cs01 · cs01 · commit 6e01a06c7cea · 2026-04-13T22:15:43.000-07:00
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).
diff --git a/c_bridges/pg-bridge.c b/c_bridges/pg-bridge.c
@@ -43,6 +43,42 @@ void *cs_pg_exec_params(void *conn, const char *sql, double nparams, const char
     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);
diff --git a/docs/stdlib/index.md b/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.
diff --git a/docs/stdlib/postgres.md b/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.
diff --git a/lib/postgres.ts b/lib/postgres.ts
@@ -12,6 +12,9 @@ declare function cs_pg_ncols(res: string): number;
 declare function cs_pg_fname(res: string, col: number): string;
 declare function cs_pg_getvalue(res: string, row: number, col: number): string;
 declare function cs_pg_getisnull(res: string, row: number, col: number): number;
+declare function cs_pg_params_new(): string;
+declare function cs_pg_params_add(params: string, value: string): void;
+declare function cs_pg_exec_params_with(conn: string, sql: string, params: string): string;
 
 const CONNECTION_OK: number = 0;
 
@@ -75,6 +78,40 @@ export class QueryResult {
     }
     return "";
   }
+
+  getInt(row: number, col: string): number {
+    const s = this.getValue(row, col);
+    return parseInt(s, 10);
+  }
+
+  getFloat(row: number, col: string): number {
+    const s = this.getValue(row, col);
+    return parseFloat(s);
+  }
+
+  getBool(row: number, col: string): boolean {
+    const s = this.getValue(row, col);
+    return s === "t" || s === "true" || s === "1";
+  }
+}
+
+export class Pool {
+  private _client: Client;
+
+  constructor(conninfo: string) {
+    this._client = new Client(conninfo);
+  }
+
+  query(sql: string, params: string[] = []): QueryResult {
+    if (!this._client.isConnected()) {
+      this._client.connect();
+    }
+    return this._client.query(sql, params);
+  }
+
+  end(): void {
+    this._client.end();
+  }
 }
 
 export class Client {
@@ -88,6 +125,10 @@ export class Client {
     this._connected = false;
   }
 
+  isConnected(): boolean {
+    return this._connected;
+  }
+
   connect(): void {
     this._conn = cs_pg_connect(this._conninfo);
     const status = cs_pg_status(this._conn);
@@ -100,11 +141,20 @@ export class Client {
     this._connected = true;
   }
 
-  query(sql: string): QueryResult {
+  query(sql: string, params: string[] = []): QueryResult {
     if (!this._connected) {
       throw new Error("postgres query on disconnected client");
     }
-    const res = cs_pg_exec(this._conn, sql);
+    let res: string;
+    if (params.length === 0) {
+      res = cs_pg_exec(this._conn, sql);
+    } else {
+      const p = cs_pg_params_new();
+      for (let i = 0; i < params.length; i++) {
+        cs_pg_params_add(p, params[i]);
+      }
+      res = cs_pg_exec_params_with(this._conn, sql, p);
+    }
     const ok = cs_pg_result_ok(res);
     if (ok === 0) {
       const msg = cs_pg_result_error_message(res);
diff --git a/tests/fixtures/stdlib/postgres-params-types.ts b/tests/fixtures/stdlib/postgres-params-types.ts
@@ -0,0 +1,61 @@
+// @test-skip
+import { Pool } from "chadscript/postgres";
+
+const pool = new Pool("host=127.0.0.1 port=5432 user=postgres password=test dbname=chadtest");
+
+pool.query("DROP TABLE IF EXISTS t_typed");
+pool.query("CREATE TABLE t_typed (id INT, price REAL, active BOOLEAN, name TEXT)");
+
+pool.query("INSERT INTO t_typed VALUES ($1, $2, $3, $4)", ["1", "19.99", "true", "widget"]);
+pool.query("INSERT INTO t_typed VALUES ($1, $2, $3, $4)", ["2", "3.5", "false", "gadget"]);
+
+const sel = pool.query("SELECT id, price, active, name FROM t_typed WHERE id = $1", ["1"]);
+if (sel.rowCount !== 1) {
+  console.log("TEST_FAILED: rowCount " + sel.rowCount);
+  process.exit(1);
+}
+
+const id = sel.getInt(0, "id");
+if (id !== 1) {
+  console.log("TEST_FAILED: id " + id);
+  process.exit(1);
+}
+
+const price = sel.getFloat(0, "price");
+if (price < 19.98 || price > 20.0) {
+  console.log("TEST_FAILED: price " + price);
+  process.exit(1);
+}
+
+const active = sel.getBool(0, "active");
+if (!active) {
+  console.log("TEST_FAILED: active was false");
+  process.exit(1);
+}
+
+const name = sel.getValue(0, "name");
+if (name !== "widget") {
+  console.log("TEST_FAILED: name " + name);
+  process.exit(1);
+}
+
+const all = pool.query("SELECT id, active FROM t_typed ORDER BY id");
+if (all.numRows !== 2) {
+  console.log("TEST_FAILED: all.numRows " + all.numRows);
+  process.exit(1);
+}
+if (all.getBool(1, "active")) {
+  console.log("TEST_FAILED: row 1 active should be false");
+  process.exit(1);
+}
+
+pool.query("INSERT INTO t_typed VALUES ($1, $2, $3, $4)", ["99", "0", "false", "sql-safe ' test"]);
+const safe = pool.query("SELECT name FROM t_typed WHERE id = $1", ["99"]);
+if (safe.getValue(0, "name") !== "sql-safe ' test") {
+  console.log("TEST_FAILED: injection-unsafe name " + safe.getValue(0, "name"));
+  process.exit(1);
+}
+
+pool.query("DROP TABLE t_typed");
+pool.end();
+console.log("TEST_PASSED");
diff --git a/tests/fixtures/stdlib/postgres-pool.ts b/tests/fixtures/stdlib/postgres-pool.ts
@@ -0,0 +1,23 @@
+// @test-skip
+import { Pool } from "chadscript/postgres";
+
+const pool = new Pool("host=127.0.0.1 port=5432 user=postgres password=test dbname=chadtest");
+
+pool.query("DROP TABLE IF EXISTS t_pool");
+pool.query("CREATE TABLE t_pool (id INT, name TEXT)");
+pool.query("INSERT INTO t_pool VALUES (1, 'alice'), (2, 'bob')");
+
+const res = pool.query("SELECT id, name FROM t_pool ORDER BY id");
+if (res.rowCount !== 2) {
+  console.log("TEST_FAILED: rowCount was " + res.rowCount);
+  process.exit(1);
+}
+const name0 = res.getValue(0, "name");
+if (name0 !== "alice") {
+  console.log("TEST_FAILED: name0 was " + name0);
+  process.exit(1);
+}
+
+pool.query("DROP TABLE t_pool");
+pool.end();
+console.log("TEST_PASSED");
