Using PostgreSQL from a TypeScript Agent

The TypeScript SDK ships a typed PostgreSQL helper built on the golem:rdbms/postgres@1.5.0 host interface. Every operation returns a Promise and throws a typed PostgresError on failure, so use normal try / catch handling when needed.

Imports

import { Postgres, Pg } from "@golemcloud/golem-ts-sdk";

• Postgres.open(url, options?) — open a connection.
• Pg.* — explicit rich-type parameter wrappers (Pg.uuid, Pg.jsonb, Pg.int4, …).

Open a Connection

const conn = await Postgres.open("postgres://user:password@localhost:5432/app");

Query Data

PostgreSQL placeholders use $1, $2, … Plain JS values are encoded automatically (string → text, integer → int4/int8, etc.); wrap a value in a Pg.* helper to pin an exact type. Rows come back as decoded { columnName: value } records.

const result = await conn.query("SELECT $1::text AS message", ["hello"]);
const message = result.rows[0]?.message as string;

Use Pg.* when the default mapping isn’t what you want:

await conn.query("SELECT * FROM users WHERE id = $1", [Pg.uuid(userId)]);

Execute Statements

execute returns the number of affected rows.

const affected = await conn.execute(
  "INSERT INTO notes (id, body) VALUES ($1, $2)",
  [1, "hello"],
);

Transactions

Run a block inside a transaction — it commits on success and rolls back if the callback throws:

await conn.transaction(async (tx) => {
  tx.execute("UPDATE notes SET body = $1 WHERE id = $2", ["updated", 1]);
  tx.execute("INSERT INTO audit (note_id) VALUES ($1)", [1]);
});

Or drive it manually with begin() / commit() / rollback():

const tx = await conn.begin();
tx.execute("UPDATE notes SET body = $1 WHERE id = $2", ["updated", 1]);
await tx.commit();