# Golem Add Postgres TS

> Using golem:rdbms/postgres from a TypeScript Golem agent. Use when the user asks to connect to PostgreSQL, run SQL, or use PostgreSQL from TypeScript agent code.

- Skill: `golemcloud/golem-add-postgres-ts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add golemcloud/golem-add-postgres-ts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/golemcloud/golem-add-postgres-ts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: golemcloud (https://skillmd.com/u/golemcloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/golemcloud/golem-add-postgres-ts

---


# 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

```ts
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

```ts
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.

```ts
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:

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

## Execute Statements

`execute` returns the number of affected rows.

```ts
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:

```ts
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()`:

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