---
url: /unthrown/api/drizzle/node-postgres.md
---
[**@unthrown/drizzle**](index.md)

***

[@unthrown/drizzle](index.md) / node-postgres

# node-postgres

## Database

### NodePgUnthrownDatabase

Defined in: [packages/drizzle/src/node-postgres/driver.ts:66](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L66)

A node-postgres database whose every query resolves to an `AsyncResult`.

#### Remarks

The unthrown sibling of drizzle's `NodePgDatabase`. Build one with
[drizzle](#drizzle) rather than by hand — the factory is what pairs a dialect, a
session and a client.

#### Extends

* [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase)<`NodePgQueryResultHKT`, `TRelations`>

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
|  `TRelations` *extends* `AnyRelations` | `EmptyRelations` | the relational schema backing `db.query`. |

#### Constructors

##### Constructor

```ts
new NodePgUnthrownDatabase<TRelations>(
   dialect, 
   session, 
   relations
): NodePgUnthrownDatabase<TRelations>;
```

Defined in: [packages/drizzle/src/node-postgres/driver.ts:83](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L83)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `dialect` | `PgDialect` |
| `session` | [`NodePgUnthrownSession`](#nodepgunthrownsession)<`TRelations`> |
| `relations` | `TRelations` |

###### Returns

[`NodePgUnthrownDatabase`](#nodepgunthrowndatabase)<`TRelations`>

###### Overrides

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`constructor`](index-1.md#constructor-5)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides | Inherited from | Defined in |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
|  `_` | `readonly` | `object` | `undefined` | - | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`_`](index-1.md#_-1) | [packages/drizzle/src/pg-core/db.ts:142](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L142) |
| `_.relations` | `readonly` | `TRelations` | `undefined` | - | - | - | [packages/drizzle/src/pg-core/db.ts:143](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L143) |
| `_.session` | `readonly` | [`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession)<`unknown`> | `undefined` | - | - | - | [packages/drizzle/src/pg-core/db.ts:144](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L144) |
|  `$with` | `readonly` | `PgUnthrownWithBuilder` | `...` | Creates a subquery that defines a temporary named result set as a CTE. It is useful for breaking down complex queries into simpler parts and for reusing the result set in subsequent parts of the query. See docs: <https://orm.drizzle.team/docs/select#with-clause> **Param** **alias** The alias for the subquery. Failure to provide an alias will result in a DrizzleTypeError, preventing the subquery from being referenced in other queries. **Example** `// Create a subquery with alias 'sq' and use it in the select query const sq = db.$with("sq").as(db.select().from(users).where(eq(users.id, 42))); const rows = (await db.with(sq).select().from(sq)).get();` To select arbitrary SQL values as fields in a CTE and reference them in other CTEs or in the main query, you need to add aliases to them: `// Select an arbitrary SQL value as a field in a CTE and reference it in the main query const sq = db.$with("sq").as( db .select({ name: sql<string>`upper(${users.name})`.as("name"), }) .from(users), ); const rows = (await db.with(sq).select({ name: sq.name }).from(sq)).get();` | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`$with`](index-1.md#with) | [packages/drizzle/src/pg-core/db.ts:254](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L254) |
|  `query` | `readonly` | { \[K in string | number | symbol]: RelationalQueryBuilder\<TRelations, TRelations\[K], PgUnthrownRelationalQueryHKT> } | `undefined` | The relational query API — `db.query.users.findMany(…)`, one entry per table in the relational schema. | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`query`](index-1.md#query) | [packages/drizzle/src/pg-core/db.ts:151](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L151) |
|  `session` | `readonly` | [`NodePgUnthrownSession`](#nodepgunthrownsession)<`TRelations`> | `undefined` | The node-postgres session this database runs on. **Remarks** Narrows the base's `PgUnthrownSession<unknown>` — whose transaction handle is deliberately unresolved, because the base facade is built *underneath* the transaction class that extends it — to the one this driver actually holds. `declare` because the base already assigns it; this only restates its type, which is what gives [transaction](#transaction) a typed handle. | `PgUnthrownDatabase.session` | - | [packages/drizzle/src/node-postgres/driver.ts:81](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L81) |
|  `tagged` | `readonly` | `boolean` | `false` | - | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`tagged`](index-1.md#tagged) | [packages/drizzle/src/pg-core/db.ts:166](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L166) |
|  `[entityKind]` | `static readonly` | `string` | `"NodePgUnthrownDatabase"` | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`[entityKind]`](index-1.md#entitykind-1) | - | [packages/drizzle/src/node-postgres/driver.ts:69](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L69) |

#### Methods

##### $count()

```ts
$count(source, filters?): PgUnthrownCountBuilder;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:308](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L308)

Count the rows a table, view or subquery yields, optionally filtered.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `source` | | `PgTable`<`TableConfig`> | `PgViewBase`<`ViewConfig`<`ColumnsSelection`>> | `SQL`<`unknown`> | `SQLWrapper`<`unknown`> |
| `filters?` | `SQL`<`unknown`> |

###### Returns

[`PgUnthrownCountBuilder`](index-1.md#pgunthrowncountbuilder)

###### Example

```ts
const total = (await db.$count(users, eq(users.active, true))).get();
//    ^? number — a count is a read, so its error channel is `never`.
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`$count`](index-1.md#count)

##### delete()

```ts
delete<TTable>(table): PgUnthrownDeleteBase<TTable, NodePgQueryResultHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:715](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L715)

Creates a delete query.

Calling this method without `.where()` clause will delete all rows in a
table. The `.where()` clause specifies which rows should be deleted.

See docs: <https://orm.drizzle.team/docs/delete>

A write carries the full `PgQueryError` union — a delete can still raise
`23505` through an `ON DELETE SET DEFAULT` — so awaiting the builder
resolves to a `Result` you fold with `mapErrCases` or `match`.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TTable` *extends* `PgTable`<`TableConfig`> |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `table` | `TTable` | The table to delete from. |

###### Returns

[`PgUnthrownDeleteBase`](index-1.md#pgunthrowndeletebase)<`TTable`, `NodePgQueryResultHKT`>

###### Example

```ts
// Delete all rows in the 'cars' table
const all = await db.delete(cars);
//    ^? Result<DeleteResult<…>, PgQueryError>

// Delete rows with filters and conditions
await db.delete(cars).where(eq(cars.color, "green"));

// Delete with returning clause
const deleted = await db.delete(cars).where(eq(cars.id, 1)).returning();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`delete`](index-1.md#delete)

##### execute()

```ts
execute<TRow>(query): PgUnthrownRaw<QueryResult<Assume<TRow, QueryResultRow>>>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:752](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L752)

Run a statement drizzle does not model — a raw `SQL` fragment or a string.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
|  `TRow` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `string` | `SQLWrapper`<`unknown`> |

###### Returns

[`PgUnthrownRaw`](index-1.md#pgunthrownraw)<`QueryResult`<`Assume`<`TRow`, `QueryResultRow`>>>

###### Remarks

Unlike every other entry point, this one compiles its argument **eagerly**,
because `PgUnthrownRaw` is defined as holding an already-prepared query
(that is what makes its `getSQL`, `getQuery` and `_prepare` synchronous
accessors, exactly as in drizzle). Compilation therefore happens here rather
than at `await`, and a `SQLWrapper` that cannot compile **throws at this call
site** instead of yielding a defect.

That is a deliberate line, not an oversight: the contract this package makes
is about *running* a query — awaiting a builder, or calling its `execute()` —
and `db.execute(…)` is the factory that produces one, not the run itself. The
builder it returns is fully guarded. Reaching the throw takes handing in a
query builder that is already broken (`db.execute(db.select({ t:
other.col }).from(users))`); a string or a `sql` template — the documented
use — cannot. Closing the gap would mean deferring compilation, which would
cost `PgRaw`'s shape and its synchronous accessors for a case where the
argument, not the statement, is the bug.

###### Example

```ts
const result = await db.execute(sql`select now()`);
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`execute`](index-1.md#execute-1)

##### insert()

```ts
insert<TTable>(table): PgInsertBuilder<TTable, NodePgQueryResultHKT, "all", false, PgUnthrownInsertHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:673](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L673)

Creates an insert query.

Calling this method will create new rows in a table. Use `.values()` method
to specify which values to insert.

See docs: <https://orm.drizzle.team/docs/insert>

A write carries the full `PgQueryError` union, so awaiting the builder
resolves to a `Result` you fold with `mapErrCases` or `match` — never a
rejection.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TTable` *extends* `PgTable`<`TableConfig`> |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `table` | `TTable` | The table to insert into. |

###### Returns

`PgInsertBuilder`<`TTable`, `NodePgQueryResultHKT`, `"all"`, `false`, [`PgUnthrownInsertHKT`](index-1.md#pgunthrowninserthkt)>

###### Example

```ts
// Insert one row
const one = await db.insert(cars).values({ brand: "BMW" });
//    ^? Result<InsertResult<…>, PgQueryError>

// Insert multiple rows
await db.insert(cars).values([{ brand: "BMW" }, { brand: "Porsche" }]);

// Insert with returning clause
const inserted = await db.insert(cars).values({ brand: "BMW" }).returning();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`insert`](index-1.md#insert)

##### refreshMaterializedView()

```ts
refreshMaterializedView<TView>(view): PgUnthrownRefreshMaterializedView<NodePgQueryResultHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:720](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L720)

Rebuild a materialized view's stored rows.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TView` *extends* `PgMaterializedView`<`ViewConfig`<`ColumnsSelection`>> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `view` | `TView` |

###### Returns

[`PgUnthrownRefreshMaterializedView`](index-1.md#pgunthrownrefreshmaterializedview)<`NodePgQueryResultHKT`>

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`refreshMaterializedView`](index-1.md#refreshmaterializedview)

##### select()

###### Call Signature

```ts
select(): PgUnthrownSelectBuilder<undefined>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:497](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L497)

Creates a select query.

Calling this method with no arguments will select all columns from the
table. Pass a selection object to specify the columns you want to select.

Use `.from()` method to specify which table to select from.

See docs: <https://orm.drizzle.team/docs/select>

Awaiting the builder resolves to a `Result`, never rows directly — a read
has no modeled failure, so the error channel is `never` and `.get()`
compiles.

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`>

###### Example

```ts
// Select all columns and all rows from the 'cars' table
const allCars = (await db.select().from(cars)).get();

// Select specific columns and all rows from the 'cars' table
const carsIdsAndBrands = (
  await db
    .select({
      id: cars.id,
      brand: cars.brand,
    })
    .from(cars)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`select`](index-1.md#select)

###### Call Signature

```ts
select<TSelection>(fields): PgUnthrownSelectBuilder<TSelection>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:498](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L498)

Creates a select query.

Calling this method with no arguments will select all columns from the
table. Pass a selection object to specify the columns you want to select.

Use `.from()` method to specify which table to select from.

See docs: <https://orm.drizzle.team/docs/select>

Awaiting the builder resolves to a `Result`, never rows directly — a read
has no modeled failure, so the error channel is `never` and `.get()`
compiles.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TSelection` *extends* `SelectedFields` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fields` | `TSelection` |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`>

###### Example

```ts
// Select all columns and all rows from the 'cars' table
const allCars = (await db.select().from(cars)).get();

// Select specific columns and all rows from the 'cars' table
const carsIdsAndBrands = (
  await db
    .select({
      id: cars.id,
      brand: cars.brand,
    })
    .from(cars)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`select`](index-1.md#select)

##### selectDistinct()

###### Call Signature

```ts
selectDistinct(): PgUnthrownSelectBuilder<undefined>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:538](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L538)

Adds `distinct` expression to the select query.

Calling this method will return only unique values. When multiple columns
are selected, it returns rows with unique combinations of values in these
columns.

Use `.from()` method to specify which table to select from. Pass a
selection object to specify the columns you want to select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`>

###### Example

```ts
// Select all unique rows from the 'cars' table
const unique = (
  await db.selectDistinct().from(cars).orderBy(cars.id, cars.brand, cars.color)
).get();

// Select all unique brands from the 'cars' table
const brands = (
  await db.selectDistinct({ brand: cars.brand }).from(cars).orderBy(cars.brand)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinct`](index-1.md#selectdistinct)

###### Call Signature

```ts
selectDistinct<TSelection>(fields): PgUnthrownSelectBuilder<TSelection>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:539](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L539)

Adds `distinct` expression to the select query.

Calling this method will return only unique values. When multiple columns
are selected, it returns rows with unique combinations of values in these
columns.

Use `.from()` method to specify which table to select from. Pass a
selection object to specify the columns you want to select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Type Parameters

| Type Parameter |
| ------ |
|  `TSelection` *extends* `SelectedFields` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fields` | `TSelection` |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`>

###### Example

```ts
// Select all unique rows from the 'cars' table
const unique = (
  await db.selectDistinct().from(cars).orderBy(cars.id, cars.brand, cars.color)
).get();

// Select all unique brands from the 'cars' table
const brands = (
  await db.selectDistinct({ brand: cars.brand }).from(cars).orderBy(cars.brand)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinct`](index-1.md#selectdistinct)

##### selectDistinctOn()

###### Call Signature

```ts
selectDistinctOn(on): PgUnthrownSelectBuilder<undefined>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:584](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L584)

Adds `distinct on` expression to the select query.

Calling this method will specify how the unique rows are determined.

Use `.from()` method to specify which table to select from. Pass a
selection object as the second argument to specify the columns you want to
select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `on` | ( | `SQLWrapper`<`unknown`> | `PgColumn`<`any`, `PgColumnBaseConfig`<`any`>, { }>)\[] | The expression defining uniqueness. |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`>

###### Example

```ts
// Select the first row for each unique brand from the 'cars' table
const firstPerBrand = (
  await db.selectDistinctOn([cars.brand]).from(cars).orderBy(cars.brand)
).get();

// The first occurrence of each unique brand, with its color
const brandColors = (
  await db
    .selectDistinctOn([cars.brand], { brand: cars.brand, color: cars.color })
    .from(cars)
    .orderBy(cars.brand, cars.color)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinctOn`](index-1.md#selectdistincton)

###### Call Signature

```ts
selectDistinctOn<TSelection>(on, fields): PgUnthrownSelectBuilder<TSelection>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:585](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L585)

Adds `distinct on` expression to the select query.

Calling this method will specify how the unique rows are determined.

Use `.from()` method to specify which table to select from. Pass a
selection object as the second argument to specify the columns you want to
select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Type Parameters

| Type Parameter |
| ------ |
|  `TSelection` *extends* `SelectedFields` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `on` | ( | `SQLWrapper`<`unknown`> | `PgColumn`<`any`, `PgColumnBaseConfig`<`any`>, { }>)\[] | The expression defining uniqueness. |
| `fields` | `TSelection` | - |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`>

###### Example

```ts
// Select the first row for each unique brand from the 'cars' table
const firstPerBrand = (
  await db.selectDistinctOn([cars.brand]).from(cars).orderBy(cars.brand)
).get();

// The first occurrence of each unique brand, with its color
const brandColors = (
  await db
    .selectDistinctOn([cars.brand], { brand: cars.brand, color: cars.color })
    .from(cars)
    .orderBy(cars.brand, cars.color)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinctOn`](index-1.md#selectdistincton)

##### transaction()

```ts
transaction<A, E>(fn, config?): AsyncResult<A, PgQueryError | E>;
```

Defined in: [packages/drizzle/src/node-postgres/driver.ts:134](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L134)

Run `fn` inside a database transaction.

###### Type Parameters

| Type Parameter |
| ------ |
|  `A` |
|  `E` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fn` | (`tx`) => `AsyncResult`<`A`, `E`> | the work to run inside the transaction. |
| `config?` | `PgTransactionConfig` | isolation level, access mode and deferrability, rendered into the `BEGIN`. |

###### Returns

`AsyncResult`<`A`, [`PgQueryError`](index-1.md#pgqueryerror) | `E`>

###### Remarks

**`Ok` commits; `Err` and `Defect` both roll back.** An `Err` re-surfaces
typed in the error channel, so rolling back costs no information — and
because rollback *is* returning an `Err`, there is no `tx.rollback()`.

[PgQueryError](index-1.md#pgqueryerror) joins the callback's own error channel because the
transaction's control statements can fail on their own account: a
`DEFERRABLE` constraint is checked at `COMMIT`, so a unique violation can be
raised by the commit rather than by any statement the callback ran.

The callback owes an `AsyncResult`, so each step ends in `.execute()` — a
builder is a thenable that resolves to a `Result`, not an `AsyncResult`
itself — and the steps compose with `flatMap` or `DoAsync().bind(…)`.

A one-line delegate to [NodePgUnthrownSession.transaction](#transaction-1), exactly as
drizzle's own database delegates to its session: the session owns the
connection, and a transaction is a property of one connection.

###### Example

```ts
const moved = await db.transaction((tx) =>
  tx
    .update(accounts)
    .set({ balance: sql`${accounts.balance} - 100` })
    .where(eq(accounts.id, from))
    .execute()
    .flatMap(() =>
      tx
        .update(accounts)
        .set({ balance: sql`${accounts.balance} + 100` })
        .where(eq(accounts.id, to))
        .execute(),
    ),
);
```

##### update()

```ts
update<TTable>(table): PgUpdateBuilder<TTable, NodePgQueryResultHKT, PgUnthrownUpdateHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:639](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L639)

Creates an update query.

Calling this method without `.where()` clause will update all rows in a
table. The `.where()` clause specifies which rows should be updated.

Use `.set()` method to specify which values to update.

See docs: <https://orm.drizzle.team/docs/update>

A write carries the full `PgQueryError` union, so awaiting the builder
resolves to a `Result` you fold with `mapErrCases` or `match` — never a
rejection.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TTable` *extends* `PgTable`<`TableConfig`> |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `table` | `TTable` | The table to update. |

###### Returns

`PgUpdateBuilder`<`TTable`, `NodePgQueryResultHKT`, [`PgUnthrownUpdateHKT`](index-1.md#pgunthrownupdatehkt)>

###### Example

```ts
// Update all rows in the 'cars' table
const all = await db.update(cars).set({ color: "red" });
//    ^? Result<UpdateResult<…>, PgQueryError>

// Update rows with filters and conditions
await db.update(cars).set({ color: "red" }).where(eq(cars.brand, "BMW"));

// Update with returning clause
const updated = await db
  .update(cars)
  .set({ color: "red" })
  .where(eq(cars.id, 1))
  .returning();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`update`](index-1.md#update)

##### with()

```ts
with<Q>(...queries): object;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:341](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L341)

Incorporates a previously defined CTE (using `$with`) into the main query.

This method allows the main query to reference a temporary named result set.

See docs: <https://orm.drizzle.team/docs/select#with-clause>

###### Type Parameters

| Type Parameter |
| ------ |
|  `Q` *extends* `WithSubquery`<`string`, `Record`<`string`, `unknown`>>\[] |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`queries` | `Q` | The CTEs to incorporate into the main query. |

###### Returns

`object`

| Name | Type | Defined in |
| ------ | ------ | ------ |
| `delete()` | <`TTable`>(`table`) => [`PgUnthrownDeleteBase`](index-1.md#pgunthrowndeletebase)<`TTable`, `NodePgQueryResultHKT`> | [packages/drizzle/src/pg-core/db.ts:369](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L369) |
| `insert()` | <`TTable`>(`table`) => `PgInsertBuilder`<`TTable`, `NodePgQueryResultHKT`, `"all"`, `false`, [`PgUnthrownInsertHKT`](index-1.md#pgunthrowninserthkt)> | [packages/drizzle/src/pg-core/db.ts:366](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L366) |
| `select()` | { (): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; <`TSelection`>(`fields`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; } | [packages/drizzle/src/pg-core/db.ts:344](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L344) |
| `selectDistinct()` | { (): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; <`TSelection`>(`fields`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; } | [packages/drizzle/src/pg-core/db.ts:350](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L350) |
| `selectDistinctOn()` | { (`on`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; <`TSelection`>(`on`, `fields`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; } | [packages/drizzle/src/pg-core/db.ts:356](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L356) |
| `update()` | <`TTable`>(`table`) => `PgUpdateBuilder`<`TTable`, `NodePgQueryResultHKT`, [`PgUnthrownUpdateHKT`](index-1.md#pgunthrownupdatehkt)> | [packages/drizzle/src/pg-core/db.ts:363](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L363) |

###### Example

```ts
// Define a subquery 'sq' as a CTE using $with
const sq = db.$with("sq").as(db.select().from(users).where(eq(users.id, 42)));

// Incorporate the CTE 'sq' into the main query and select from it
const rows = (await db.with(sq).select().from(sq)).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`with`](index-1.md#with-1)

***

### NodePgUnthrownTransaction

Defined in: [packages/drizzle/src/node-postgres/session.ts:437](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L437)

A Postgres database whose every query resolves to an `AsyncResult`.

#### Remarks

The unthrown sibling of drizzle's own `PgAsyncDatabase` (promises) and
`PgEffectDatabase` (Effects). The entry points below only *build* queries —
every one of them hands back a builder from this package's tree, and nothing
touches the database until that builder is awaited or `execute`d. That is why
their bodies are drizzle's, unchanged but for the builder classes.

#### Extends

* [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase)<`NodePgQueryResultHKT`, `TRelations`>

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
|  `TRelations` *extends* `AnyRelations` | `EmptyRelations` | the driver's result kind, which decides what a write without `.returning()` resolves to. |

#### Constructors

##### Constructor

```ts
new NodePgUnthrownTransaction<TRelations>(
   dialect, 
   session, 
   relations, 
   savepoints?, 
   parseRqbJson?
): NodePgUnthrownTransaction<TRelations>;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:447](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L447)

###### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `dialect` | `PgDialect` | `undefined` | - |
| `session` | [`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession)<`unknown`> | `undefined` | - |
| `relations` | `TRelations` | `undefined` | - |
| `savepoints?` | { `count`: `number`; } | `...` | the savepoint-name counter, **shared by every handle descended from one transaction** (see [transaction](#transaction-2)). Defaults to a fresh one, which is what a root transaction wants. |
| `savepoints.count` | `number` | `undefined` | - |
| `parseRqbJson?` | `boolean` | `false` | - |

###### Returns

[`NodePgUnthrownTransaction`](#nodepgunthrowntransaction)<`TRelations`>

###### Overrides

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`constructor`](index-1.md#constructor-5)

#### Properties

| Property | Modifier | Type | Default value | Description | Overrides | Inherited from | Defined in |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |
|  `_` | `readonly` | `object` | `undefined` | - | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`_`](index-1.md#_-1) | [packages/drizzle/src/pg-core/db.ts:142](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L142) |
| `_.relations` | `readonly` | `TRelations` | `undefined` | - | - | - | [packages/drizzle/src/pg-core/db.ts:143](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L143) |
| `_.session` | `readonly` | [`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession)<`unknown`> | `undefined` | - | - | - | [packages/drizzle/src/pg-core/db.ts:144](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L144) |
|  `$with` | `readonly` | `PgUnthrownWithBuilder` | `...` | Creates a subquery that defines a temporary named result set as a CTE. It is useful for breaking down complex queries into simpler parts and for reusing the result set in subsequent parts of the query. See docs: <https://orm.drizzle.team/docs/select#with-clause> **Param** **alias** The alias for the subquery. Failure to provide an alias will result in a DrizzleTypeError, preventing the subquery from being referenced in other queries. **Example** `// Create a subquery with alias 'sq' and use it in the select query const sq = db.$with("sq").as(db.select().from(users).where(eq(users.id, 42))); const rows = (await db.with(sq).select().from(sq)).get();` To select arbitrary SQL values as fields in a CTE and reference them in other CTEs or in the main query, you need to add aliases to them: `// Select an arbitrary SQL value as a field in a CTE and reference it in the main query const sq = db.$with("sq").as( db .select({ name: sql<string>`upper(${users.name})`.as("name"), }) .from(users), ); const rows = (await db.with(sq).select({ name: sq.name }).from(sq)).get();` | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`$with`](index-1.md#with) | [packages/drizzle/src/pg-core/db.ts:254](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L254) |
|  `query` | `readonly` | { \[K in string | number | symbol]: RelationalQueryBuilder\<TRelations, TRelations\[K], PgUnthrownRelationalQueryHKT> } | `undefined` | The relational query API — `db.query.users.findMany(…)`, one entry per table in the relational schema. | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`query`](index-1.md#query) | [packages/drizzle/src/pg-core/db.ts:151](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L151) |
|  `tagged` | `readonly` | `boolean` | `false` | - | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`tagged`](index-1.md#tagged) | [packages/drizzle/src/pg-core/db.ts:166](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L166) |
|  `[entityKind]` | `static readonly` | `string` | `"NodePgUnthrownTransaction"` | - | [`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`[entityKind]`](index-1.md#entitykind-1) | - | [packages/drizzle/src/node-postgres/session.ts:440](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L440) |

#### Methods

##### $count()

```ts
$count(source, filters?): PgUnthrownCountBuilder;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:308](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L308)

Count the rows a table, view or subquery yields, optionally filtered.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `source` | | `PgTable`<`TableConfig`> | `PgViewBase`<`ViewConfig`<`ColumnsSelection`>> | `SQL`<`unknown`> | `SQLWrapper`<`unknown`> |
| `filters?` | `SQL`<`unknown`> |

###### Returns

[`PgUnthrownCountBuilder`](index-1.md#pgunthrowncountbuilder)

###### Example

```ts
const total = (await db.$count(users, eq(users.active, true))).get();
//    ^? number — a count is a read, so its error channel is `never`.
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`$count`](index-1.md#count)

##### delete()

```ts
delete<TTable>(table): PgUnthrownDeleteBase<TTable, NodePgQueryResultHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:715](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L715)

Creates a delete query.

Calling this method without `.where()` clause will delete all rows in a
table. The `.where()` clause specifies which rows should be deleted.

See docs: <https://orm.drizzle.team/docs/delete>

A write carries the full `PgQueryError` union — a delete can still raise
`23505` through an `ON DELETE SET DEFAULT` — so awaiting the builder
resolves to a `Result` you fold with `mapErrCases` or `match`.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TTable` *extends* `PgTable`<`TableConfig`> |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `table` | `TTable` | The table to delete from. |

###### Returns

[`PgUnthrownDeleteBase`](index-1.md#pgunthrowndeletebase)<`TTable`, `NodePgQueryResultHKT`>

###### Example

```ts
// Delete all rows in the 'cars' table
const all = await db.delete(cars);
//    ^? Result<DeleteResult<…>, PgQueryError>

// Delete rows with filters and conditions
await db.delete(cars).where(eq(cars.color, "green"));

// Delete with returning clause
const deleted = await db.delete(cars).where(eq(cars.id, 1)).returning();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`delete`](index-1.md#delete)

##### execute()

```ts
execute<TRow>(query): PgUnthrownRaw<QueryResult<Assume<TRow, QueryResultRow>>>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:752](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L752)

Run a statement drizzle does not model — a raw `SQL` fragment or a string.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
|  `TRow` *extends* `Record`<`string`, `unknown`> | `Record`<`string`, `unknown`> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `string` | `SQLWrapper`<`unknown`> |

###### Returns

[`PgUnthrownRaw`](index-1.md#pgunthrownraw)<`QueryResult`<`Assume`<`TRow`, `QueryResultRow`>>>

###### Remarks

Unlike every other entry point, this one compiles its argument **eagerly**,
because `PgUnthrownRaw` is defined as holding an already-prepared query
(that is what makes its `getSQL`, `getQuery` and `_prepare` synchronous
accessors, exactly as in drizzle). Compilation therefore happens here rather
than at `await`, and a `SQLWrapper` that cannot compile **throws at this call
site** instead of yielding a defect.

That is a deliberate line, not an oversight: the contract this package makes
is about *running* a query — awaiting a builder, or calling its `execute()` —
and `db.execute(…)` is the factory that produces one, not the run itself. The
builder it returns is fully guarded. Reaching the throw takes handing in a
query builder that is already broken (`db.execute(db.select({ t:
other.col }).from(users))`); a string or a `sql` template — the documented
use — cannot. Closing the gap would mean deferring compilation, which would
cost `PgRaw`'s shape and its synchronous accessors for a case where the
argument, not the statement, is the bug.

###### Example

```ts
const result = await db.execute(sql`select now()`);
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`execute`](index-1.md#execute-1)

##### insert()

```ts
insert<TTable>(table): PgInsertBuilder<TTable, NodePgQueryResultHKT, "all", false, PgUnthrownInsertHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:673](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L673)

Creates an insert query.

Calling this method will create new rows in a table. Use `.values()` method
to specify which values to insert.

See docs: <https://orm.drizzle.team/docs/insert>

A write carries the full `PgQueryError` union, so awaiting the builder
resolves to a `Result` you fold with `mapErrCases` or `match` — never a
rejection.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TTable` *extends* `PgTable`<`TableConfig`> |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `table` | `TTable` | The table to insert into. |

###### Returns

`PgInsertBuilder`<`TTable`, `NodePgQueryResultHKT`, `"all"`, `false`, [`PgUnthrownInsertHKT`](index-1.md#pgunthrowninserthkt)>

###### Example

```ts
// Insert one row
const one = await db.insert(cars).values({ brand: "BMW" });
//    ^? Result<InsertResult<…>, PgQueryError>

// Insert multiple rows
await db.insert(cars).values([{ brand: "BMW" }, { brand: "Porsche" }]);

// Insert with returning clause
const inserted = await db.insert(cars).values({ brand: "BMW" }).returning();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`insert`](index-1.md#insert)

##### refreshMaterializedView()

```ts
refreshMaterializedView<TView>(view): PgUnthrownRefreshMaterializedView<NodePgQueryResultHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:720](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L720)

Rebuild a materialized view's stored rows.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TView` *extends* `PgMaterializedView`<`ViewConfig`<`ColumnsSelection`>> |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `view` | `TView` |

###### Returns

[`PgUnthrownRefreshMaterializedView`](index-1.md#pgunthrownrefreshmaterializedview)<`NodePgQueryResultHKT`>

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`refreshMaterializedView`](index-1.md#refreshmaterializedview)

##### select()

###### Call Signature

```ts
select(): PgUnthrownSelectBuilder<undefined>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:497](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L497)

Creates a select query.

Calling this method with no arguments will select all columns from the
table. Pass a selection object to specify the columns you want to select.

Use `.from()` method to specify which table to select from.

See docs: <https://orm.drizzle.team/docs/select>

Awaiting the builder resolves to a `Result`, never rows directly — a read
has no modeled failure, so the error channel is `never` and `.get()`
compiles.

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`>

###### Example

```ts
// Select all columns and all rows from the 'cars' table
const allCars = (await db.select().from(cars)).get();

// Select specific columns and all rows from the 'cars' table
const carsIdsAndBrands = (
  await db
    .select({
      id: cars.id,
      brand: cars.brand,
    })
    .from(cars)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`select`](index-1.md#select)

###### Call Signature

```ts
select<TSelection>(fields): PgUnthrownSelectBuilder<TSelection>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:498](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L498)

Creates a select query.

Calling this method with no arguments will select all columns from the
table. Pass a selection object to specify the columns you want to select.

Use `.from()` method to specify which table to select from.

See docs: <https://orm.drizzle.team/docs/select>

Awaiting the builder resolves to a `Result`, never rows directly — a read
has no modeled failure, so the error channel is `never` and `.get()`
compiles.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TSelection` *extends* `SelectedFields` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fields` | `TSelection` |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`>

###### Example

```ts
// Select all columns and all rows from the 'cars' table
const allCars = (await db.select().from(cars)).get();

// Select specific columns and all rows from the 'cars' table
const carsIdsAndBrands = (
  await db
    .select({
      id: cars.id,
      brand: cars.brand,
    })
    .from(cars)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`select`](index-1.md#select)

##### selectDistinct()

###### Call Signature

```ts
selectDistinct(): PgUnthrownSelectBuilder<undefined>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:538](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L538)

Adds `distinct` expression to the select query.

Calling this method will return only unique values. When multiple columns
are selected, it returns rows with unique combinations of values in these
columns.

Use `.from()` method to specify which table to select from. Pass a
selection object to specify the columns you want to select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`>

###### Example

```ts
// Select all unique rows from the 'cars' table
const unique = (
  await db.selectDistinct().from(cars).orderBy(cars.id, cars.brand, cars.color)
).get();

// Select all unique brands from the 'cars' table
const brands = (
  await db.selectDistinct({ brand: cars.brand }).from(cars).orderBy(cars.brand)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinct`](index-1.md#selectdistinct)

###### Call Signature

```ts
selectDistinct<TSelection>(fields): PgUnthrownSelectBuilder<TSelection>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:539](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L539)

Adds `distinct` expression to the select query.

Calling this method will return only unique values. When multiple columns
are selected, it returns rows with unique combinations of values in these
columns.

Use `.from()` method to specify which table to select from. Pass a
selection object to specify the columns you want to select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Type Parameters

| Type Parameter |
| ------ |
|  `TSelection` *extends* `SelectedFields` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fields` | `TSelection` |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`>

###### Example

```ts
// Select all unique rows from the 'cars' table
const unique = (
  await db.selectDistinct().from(cars).orderBy(cars.id, cars.brand, cars.color)
).get();

// Select all unique brands from the 'cars' table
const brands = (
  await db.selectDistinct({ brand: cars.brand }).from(cars).orderBy(cars.brand)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinct`](index-1.md#selectdistinct)

##### selectDistinctOn()

###### Call Signature

```ts
selectDistinctOn(on): PgUnthrownSelectBuilder<undefined>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:584](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L584)

Adds `distinct on` expression to the select query.

Calling this method will specify how the unique rows are determined.

Use `.from()` method to specify which table to select from. Pass a
selection object as the second argument to specify the columns you want to
select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `on` | ( | `SQLWrapper`<`unknown`> | `PgColumn`<`any`, `PgColumnBaseConfig`<`any`>, { }>)\[] | The expression defining uniqueness. |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`>

###### Example

```ts
// Select the first row for each unique brand from the 'cars' table
const firstPerBrand = (
  await db.selectDistinctOn([cars.brand]).from(cars).orderBy(cars.brand)
).get();

// The first occurrence of each unique brand, with its color
const brandColors = (
  await db
    .selectDistinctOn([cars.brand], { brand: cars.brand, color: cars.color })
    .from(cars)
    .orderBy(cars.brand, cars.color)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinctOn`](index-1.md#selectdistincton)

###### Call Signature

```ts
selectDistinctOn<TSelection>(on, fields): PgUnthrownSelectBuilder<TSelection>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:585](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L585)

Adds `distinct on` expression to the select query.

Calling this method will specify how the unique rows are determined.

Use `.from()` method to specify which table to select from. Pass a
selection object as the second argument to specify the columns you want to
select.

See docs: <https://orm.drizzle.team/docs/select#distinct>

###### Type Parameters

| Type Parameter |
| ------ |
|  `TSelection` *extends* `SelectedFields` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `on` | ( | `SQLWrapper`<`unknown`> | `PgColumn`<`any`, `PgColumnBaseConfig`<`any`>, { }>)\[] | The expression defining uniqueness. |
| `fields` | `TSelection` | - |

###### Returns

[`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`>

###### Example

```ts
// Select the first row for each unique brand from the 'cars' table
const firstPerBrand = (
  await db.selectDistinctOn([cars.brand]).from(cars).orderBy(cars.brand)
).get();

// The first occurrence of each unique brand, with its color
const brandColors = (
  await db
    .selectDistinctOn([cars.brand], { brand: cars.brand, color: cars.color })
    .from(cars)
    .orderBy(cars.brand, cars.color)
).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`selectDistinctOn`](index-1.md#selectdistincton)

##### setTransaction()

```ts
setTransaction(config): AsyncResult<unknown, PgQueryError>;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:470](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L470)

Set the characteristics of the transaction already in progress.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `config` | `PgTransactionConfig` |

###### Returns

`AsyncResult`<`unknown`, [`PgQueryError`](index-1.md#pgqueryerror)>

###### Remarks

A config that asks for nothing (`{}`) issues no statement: Postgres requires
at least one mode after `set transaction`, so the alternative is a syntax
error reported as a defect for a call that requested no change.

###### Example

```ts
await tx.setTransaction({ isolationLevel: "serializable" });
```

##### transaction()

```ts
transaction<A, E>(fn): AsyncResult<A, PgQueryError | E>;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:524](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L524)

Run `fn` inside a nested transaction — a savepoint of the enclosing one.

###### Type Parameters

| Type Parameter |
| ------ |
|  `A` |
|  `E` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fn` | (`tx`) => `AsyncResult`<`A`, `E`> |

###### Returns

`AsyncResult`<`A`, [`PgQueryError`](index-1.md#pgqueryerror) | `E`>

###### Remarks

The same rule one level down: `Ok` releases the savepoint, `Err` and
`Defect` roll back to it. Only the nested scope is undone, so the enclosing
transaction stays open and decides for itself — recover the inner `Err` and
the outer scope still commits.

Savepoint names come from a counter **shared by every handle descended from
one transaction**, so no two live savepoints on that connection can share a
name. Naming them by nesting depth (drizzle's scheme) is safe only while
nested transactions are started one after another; two started concurrently
— which `allAsync` makes an easy thing to write — would both be `sp1` on the
one connection, and the first `rollback to savepoint sp1` would unwind the
other's work.

Distinct names are not enough on their own, because savepoints are a
*stack*: rolling back to `sp1` also discards an `sp2` opened after it. So
nested transactions started on one handle **run one after another**, in the
order they were started — `allAsync([tx.transaction(a), tx.transaction(b)])`
is safe, and each keeps its own outcome. Start a nested transaction from
inside a nested callback through the handle that callback receives: the
enclosing handle is busy until that callback finishes, so a transaction
started on it from inside could only wait for itself — it is a `Defect`
(a `TypeError` naming the mistake) instead.

###### Example

```ts
const result = await db.transaction((tx) =>
  tx
    .transaction((nested) => nested.insert(logs).values({ message: "optional" }).execute())
    // The savepoint rolled back; the outer transaction carries on. Every
    // case is named, so the grouped arm lists the whole PgQueryError union.
    .recoverErrCases((m) =>
      m.with(
        P.tag("UniqueConstraintViolation"),
        P.tag("ForeignKeyViolation"),
        P.tag("CheckViolation"),
        P.tag("ExclusionViolation"),
        P.tag("NotNullViolation"),
        () => undefined,
      ),
    )
    .flatMap(() => tx.insert(users).values({ id: 1, name: "ada" }).execute()),
);
```

##### update()

```ts
update<TTable>(table): PgUpdateBuilder<TTable, NodePgQueryResultHKT, PgUnthrownUpdateHKT>;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:639](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L639)

Creates an update query.

Calling this method without `.where()` clause will update all rows in a
table. The `.where()` clause specifies which rows should be updated.

Use `.set()` method to specify which values to update.

See docs: <https://orm.drizzle.team/docs/update>

A write carries the full `PgQueryError` union, so awaiting the builder
resolves to a `Result` you fold with `mapErrCases` or `match` — never a
rejection.

###### Type Parameters

| Type Parameter |
| ------ |
|  `TTable` *extends* `PgTable`<`TableConfig`> |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `table` | `TTable` | The table to update. |

###### Returns

`PgUpdateBuilder`<`TTable`, `NodePgQueryResultHKT`, [`PgUnthrownUpdateHKT`](index-1.md#pgunthrownupdatehkt)>

###### Example

```ts
// Update all rows in the 'cars' table
const all = await db.update(cars).set({ color: "red" });
//    ^? Result<UpdateResult<…>, PgQueryError>

// Update rows with filters and conditions
await db.update(cars).set({ color: "red" }).where(eq(cars.brand, "BMW"));

// Update with returning clause
const updated = await db
  .update(cars)
  .set({ color: "red" })
  .where(eq(cars.id, 1))
  .returning();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`update`](index-1.md#update)

##### with()

```ts
with<Q>(...queries): object;
```

Defined in: [packages/drizzle/src/pg-core/db.ts:341](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L341)

Incorporates a previously defined CTE (using `$with`) into the main query.

This method allows the main query to reference a temporary named result set.

See docs: <https://orm.drizzle.team/docs/select#with-clause>

###### Type Parameters

| Type Parameter |
| ------ |
|  `Q` *extends* `WithSubquery`<`string`, `Record`<`string`, `unknown`>>\[] |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`queries` | `Q` | The CTEs to incorporate into the main query. |

###### Returns

`object`

| Name | Type | Defined in |
| ------ | ------ | ------ |
| `delete()` | <`TTable`>(`table`) => [`PgUnthrownDeleteBase`](index-1.md#pgunthrowndeletebase)<`TTable`, `NodePgQueryResultHKT`> | [packages/drizzle/src/pg-core/db.ts:369](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L369) |
| `insert()` | <`TTable`>(`table`) => `PgInsertBuilder`<`TTable`, `NodePgQueryResultHKT`, `"all"`, `false`, [`PgUnthrownInsertHKT`](index-1.md#pgunthrowninserthkt)> | [packages/drizzle/src/pg-core/db.ts:366](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L366) |
| `select()` | { (): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; <`TSelection`>(`fields`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; } | [packages/drizzle/src/pg-core/db.ts:344](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L344) |
| `selectDistinct()` | { (): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; <`TSelection`>(`fields`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; } | [packages/drizzle/src/pg-core/db.ts:350](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L350) |
| `selectDistinctOn()` | { (`on`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`undefined`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; <`TSelection`>(`on`, `fields`): [`PgUnthrownSelectBuilder`](index-1.md#pgunthrownselectbuilder)<`TSelection`, [`WithListError`](index-1.md#withlisterror)<`Q`\[`number`]>>; } | [packages/drizzle/src/pg-core/db.ts:356](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L356) |
| `update()` | <`TTable`>(`table`) => `PgUpdateBuilder`<`TTable`, `NodePgQueryResultHKT`, [`PgUnthrownUpdateHKT`](index-1.md#pgunthrownupdatehkt)> | [packages/drizzle/src/pg-core/db.ts:363](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/db.ts#L363) |

###### Example

```ts
// Define a subquery 'sq' as a CTE using $with
const sq = db.$with("sq").as(db.select().from(users).where(eq(users.id, 42)));

// Incorporate the CTE 'sq' into the main query and select from it
const rows = (await db.with(sq).select().from(sq)).get();
```

###### Inherited from

[`PgUnthrownDatabase`](index-1.md#pgunthrowndatabase).[`with`](index-1.md#with-1)

***

### UnthrownDrizzleConfig

```ts
type UnthrownDrizzleConfig<TRelations> = object;
```

Defined in: [packages/drizzle/src/node-postgres/driver.ts:36](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L36)

The options [drizzle](#drizzle) accepts.

#### Remarks

Drizzle's `DrizzlePgConfig` minus the members this package does not carry:

* `schema` — drizzle removed it from the Postgres config in v1; `relations`
  is the successor.
* `cache` — the query cache hangs off `db.$cache` and invalidates on mutation,
  neither of which this database facade models yet.
* `jit` — drizzle's JIT row mappers are gated behind an `@internal`
  compatibility probe that is stripped from its published `.d.ts`, so it
  cannot be forwarded without reimplementing the probe. Leaving it out gives
  drizzle's own default (the premade mappers), so nothing silently changes.

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
|  `TRelations` *extends* `AnyRelations` | `EmptyRelations` | the relational schema backing `db.query`. |

#### Properties

| Property | Modifier | Type | Description | Defined in |
| ------ | ------ | ------ | ------ | ------ |
|  `codecs?` | `readonly` | `PgCodecs` | Column codecs, overriding node-postgres' own. | [packages/drizzle/src/node-postgres/driver.ts:45](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L45) |
|  `logger?` | `readonly` | `boolean` | `Logger` | `true` for drizzle's `DefaultLogger` (every statement to the console), a `Logger` of your own, or `false`/absent for none. | [packages/drizzle/src/node-postgres/driver.ts:43](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L43) |
|  `relations?` | `readonly` | `TRelations` | The relational schema, as built by drizzle's `defineRelations`. | [packages/drizzle/src/node-postgres/driver.ts:38](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L38) |

***

### drizzle()

#### Call Signature

```ts
function drizzle<TRelations>(connectionString, config?): NodePgUnthrownDatabase<TRelations> & object;
```

Defined in: [packages/drizzle/src/node-postgres/driver.ts:218](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L218)

Build a Postgres database whose every query resolves to an `AsyncResult`.

##### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
|  `TRelations` *extends* `TablesRelationalConfig` | `EmptyRelations` |

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `connectionString` | `string` |
| `config?` | [`UnthrownDrizzleConfig`](#unthrowndrizzleconfig)<`TRelations`> |

##### Returns

[`NodePgUnthrownDatabase`](#nodepgunthrowndatabase)<`TRelations`> & `object`

##### Remarks

This **replaces** `drizzle-orm/node-postgres`'s own `drizzle()` rather than
wrapping its result: migrating a call site is an import change. Every method
on the database already speaks `AsyncResult`, so there is no `try*` naming
scheme to learn — a query's modeled failures are the [PgQueryError](index-1.md#pgqueryerror)
union, and every infrastructure failure (a dropped connection, a deadlock, a
statement that will not compile) is a defect rather than a value you branch
on.

The escape hatch is `db.$client`: it is the very client you passed (or the
pool the factory built), so a stock `drizzle-orm/node-postgres` database over
the same pool — for a migration runner, or a batch API this package does not
model — is one line away.

The call forms are **exactly** drizzle's own — a connection string (with an
optional [UnthrownDrizzleConfig](#unthrowndrizzleconfig) second argument), or a configuration
object carrying a client under `client` or connection details under
`connection`. There is deliberately no positional-client form: drizzle has
none, and a second spelling of `{ client: pool }` would mean a call site no
longer ports back by changing the import. (`@param` is left unspelled
deliberately: one doc comment fronts three overloads whose parameters are
named differently.)

##### Example

```ts
const db = drizzle({ client: pool, relations });

const created = await db
  .insert(users)
  .values({ id: 1, email: "ada@example.com" })
  .returning()
  .execute()
  .mapErrCases((m) =>
    m.with(P.tag("UniqueConstraintViolation"), () => "email already taken" as const)
     .with(
       P.tag("ForeignKeyViolation"),
       P.tag("CheckViolation"),
       P.tag("ExclusionViolation"),
       P.tag("NotNullViolation"),
       (e) => e._tag,
     ),
  );
```

#### Call Signature

```ts
function drizzle<TClient, TRelations>(config): NodePgUnthrownDatabase<TRelations> & object;
```

Defined in: [packages/drizzle/src/node-postgres/driver.ts:222](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L222)

Build a Postgres database whose every query resolves to an `AsyncResult`.

##### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
|  `TClient` *extends* [`NodePgClient`](#nodepgclient) | - |
|  `TRelations` *extends* `TablesRelationalConfig` | `EmptyRelations` |

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `config` | [`UnthrownDrizzleConfig`](#unthrowndrizzleconfig)<`TRelations`> & `object` |

##### Returns

[`NodePgUnthrownDatabase`](#nodepgunthrowndatabase)<`TRelations`> & `object`

##### Remarks

This **replaces** `drizzle-orm/node-postgres`'s own `drizzle()` rather than
wrapping its result: migrating a call site is an import change. Every method
on the database already speaks `AsyncResult`, so there is no `try*` naming
scheme to learn — a query's modeled failures are the [PgQueryError](index-1.md#pgqueryerror)
union, and every infrastructure failure (a dropped connection, a deadlock, a
statement that will not compile) is a defect rather than a value you branch
on.

The escape hatch is `db.$client`: it is the very client you passed (or the
pool the factory built), so a stock `drizzle-orm/node-postgres` database over
the same pool — for a migration runner, or a batch API this package does not
model — is one line away.

The call forms are **exactly** drizzle's own — a connection string (with an
optional [UnthrownDrizzleConfig](#unthrowndrizzleconfig) second argument), or a configuration
object carrying a client under `client` or connection details under
`connection`. There is deliberately no positional-client form: drizzle has
none, and a second spelling of `{ client: pool }` would mean a call site no
longer ports back by changing the import. (`@param` is left unspelled
deliberately: one doc comment fronts three overloads whose parameters are
named differently.)

##### Example

```ts
const db = drizzle({ client: pool, relations });

const created = await db
  .insert(users)
  .values({ id: 1, email: "ada@example.com" })
  .returning()
  .execute()
  .mapErrCases((m) =>
    m.with(P.tag("UniqueConstraintViolation"), () => "email already taken" as const)
     .with(
       P.tag("ForeignKeyViolation"),
       P.tag("CheckViolation"),
       P.tag("ExclusionViolation"),
       P.tag("NotNullViolation"),
       (e) => e._tag,
     ),
  );
```

#### Call Signature

```ts
function drizzle<TRelations>(config): NodePgUnthrownDatabase<TRelations> & object;
```

Defined in: [packages/drizzle/src/node-postgres/driver.ts:228](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/driver.ts#L228)

Build a Postgres database whose every query resolves to an `AsyncResult`.

##### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
|  `TRelations` *extends* `TablesRelationalConfig` | `EmptyRelations` |

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `config` | [`UnthrownDrizzleConfig`](#unthrowndrizzleconfig)<`TRelations`> & `object` |

##### Returns

[`NodePgUnthrownDatabase`](#nodepgunthrowndatabase)<`TRelations`> & `object`

##### Remarks

This **replaces** `drizzle-orm/node-postgres`'s own `drizzle()` rather than
wrapping its result: migrating a call site is an import change. Every method
on the database already speaks `AsyncResult`, so there is no `try*` naming
scheme to learn — a query's modeled failures are the [PgQueryError](index-1.md#pgqueryerror)
union, and every infrastructure failure (a dropped connection, a deadlock, a
statement that will not compile) is a defect rather than a value you branch
on.

The escape hatch is `db.$client`: it is the very client you passed (or the
pool the factory built), so a stock `drizzle-orm/node-postgres` database over
the same pool — for a migration runner, or a batch API this package does not
model — is one line away.

The call forms are **exactly** drizzle's own — a connection string (with an
optional [UnthrownDrizzleConfig](#unthrowndrizzleconfig) second argument), or a configuration
object carrying a client under `client` or connection details under
`connection`. There is deliberately no positional-client form: drizzle has
none, and a second spelling of `{ client: pool }` would mean a call site no
longer ports back by changing the import. (`@param` is left unspelled
deliberately: one doc comment fronts three overloads whose parameters are
named differently.)

##### Example

```ts
const db = drizzle({ client: pool, relations });

const created = await db
  .insert(users)
  .values({ id: 1, email: "ada@example.com" })
  .returning()
  .execute()
  .mapErrCases((m) =>
    m.with(P.tag("UniqueConstraintViolation"), () => "email already taken" as const)
     .with(
       P.tag("ForeignKeyViolation"),
       P.tag("CheckViolation"),
       P.tag("ExclusionViolation"),
       P.tag("NotNullViolation"),
       (e) => e._tag,
     ),
  );
```

## Session

### NodePgUnthrownSession

Defined in: [packages/drizzle/src/node-postgres/session.ts:246](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L246)

A node-postgres session whose every query resolves to an `AsyncResult`.

#### Remarks

The unthrown sibling of drizzle's `NodePgSession`. Everything above it is type
plumbing; this is where a real driver is spoken to.

#### Extends

* [`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession)<[`NodePgUnthrownTransaction`](#nodepgunthrowntransaction)<`TRelations`>>

#### Type Parameters

| Type Parameter | Default type | Description |
| ------ | ------ | ------ |
|  `TRelations` *extends* `AnyRelations` | `EmptyRelations` | the relational schema backing `db.query`. |

#### Constructors

##### Constructor

```ts
new NodePgUnthrownSession<TRelations>(
   client, 
   dialect, 
   relations, 
   logger?
): NodePgUnthrownSession<TRelations>;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:259](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L259)

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `client` | [`NodePgClient`](#nodepgclient) | the pool or client to run statements against. A pool has a connection checked out for the duration of a [transaction](#transaction-1) and released afterwards; a plain client is used as-is. |
| `dialect` | `PgDialect` | drizzle's Postgres dialect, which compiles the SQL. |
| `relations` | `TRelations` | the relational schema, forwarded to every transaction. |
| `logger?` | `Logger` | drizzle's query logger. |

###### Returns

[`NodePgUnthrownSession`](#nodepgunthrownsession)<`TRelations`>

###### Overrides

[`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`constructor`](index-1.md#constructor-14)

#### Properties

| Property | Modifier | Type | Default value | Overrides | Defined in |
| ------ | ------ | ------ | ------ | ------ | ------ |
|  `[entityKind]` | `static readonly` | `string` | `"NodePgUnthrownSession"` | [`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`[entityKind]`](index-1.md#entitykind-10) | [packages/drizzle/src/node-postgres/session.ts:249](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L249) |

#### Methods

##### arrays()

```ts
arrays(query): AsyncResult<unknown, PgQueryError>;
```

Defined in: [packages/drizzle/src/pg-core/session.ts:276](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/session.ts#L276)

Run a raw `SQL` fragment, returning each row as an array of column values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `SQL` |

###### Returns

`AsyncResult`<`unknown`, [`PgQueryError`](index-1.md#pgqueryerror)>

###### Inherited from

[`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`arrays`](index-1.md#arrays)

##### execute()

```ts
execute(query): AsyncResult<unknown, PgQueryError>;
```

Defined in: [packages/drizzle/src/pg-core/session.ts:271](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/session.ts#L271)

Run a raw `SQL` fragment, returning the driver's own result object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `SQL` |

###### Returns

`AsyncResult`<`unknown`, [`PgQueryError`](index-1.md#pgqueryerror)>

###### Remarks

Compilation runs **inside** the failure boundary — see `runQuery`.
`dialect.sqlToQuery` throws for mistakes that are type-legal and reachable,
and a throw escaping here would land on a caller who has no `try`/`catch`,
because this method's contract is a `Result`.

###### Inherited from

[`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`execute`](index-1.md#execute-10)

##### objects()

```ts
objects(query): AsyncResult<unknown, PgQueryError>;
```

Defined in: [packages/drizzle/src/pg-core/session.ts:281](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/pg-core/session.ts#L281)

Run a raw `SQL` fragment, returning each row as a column-keyed object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `SQL` |

###### Returns

`AsyncResult`<`unknown`, [`PgQueryError`](index-1.md#pgqueryerror)>

###### Inherited from

[`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`objects`](index-1.md#objects)

##### prepareQuery()

```ts
prepareQuery<T>(
   query, 
   mode, 
   name, 
   mapper?
): PgUnthrownPreparedQuery<T>;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:268](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L268)

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
|  `T` *extends* `PreparedQueryConfig` | `PreparedQueryConfig` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `Query` |
| `mode` | [`PgQueryMode`](index-1.md#pgquerymode) |
| `name` | `string` | `boolean` |
| `mapper?` | [`PgRowMapper`](index-1.md#pgrowmapper) |

###### Returns

[`PgUnthrownPreparedQuery`](index-1.md#pgunthrownpreparedquery)<`T`>

###### Overrides

[`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`prepareQuery`](index-1.md#preparequery)

##### transaction()

```ts
transaction<A, E>(fn, config?): AsyncResult<A, PgQueryError | E>;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:342](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L342)

Run `fn` inside a database transaction.

###### Type Parameters

| Type Parameter |
| ------ |
|  `A` |
|  `E` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `fn` | (`tx`) => `AsyncResult`<`A`, `E`> |
| `config?` | `PgTransactionConfig` |

###### Returns

`AsyncResult`<`A`, [`PgQueryError`](index-1.md#pgqueryerror) | `E`>

###### Remarks

**`Ok` commits; `Err` and `Defect` both roll back.** An `Err` re-surfaces
typed in the error channel, so rolling back costs no information — and
because rollback *is* returning an `Err`, there is no `tx.rollback()`.

[PgQueryError](index-1.md#pgqueryerror) joins the callback's own error channel because the
transaction's control statements can fail on their own account: a
`DEFERRABLE` constraint is checked at `COMMIT`, so a unique violation can
be raised by the commit rather than by any statement the callback ran.

The whole sequence is qualified **once**, here, and nothing inside it is
left to a channel that could swallow it: the control statements run on the
raw rejecting path (see `PgUnthrownPreparedQuery.runUnqualified`), so
a failed `COMMIT` can never be mistaken for a successful one.

The callback owes an `AsyncResult`, so each step ends in `.execute()` — a
builder is a thenable that resolves to a `Result`, not an `AsyncResult`
itself — and the steps compose with `flatMap`.

###### Example

```ts
const moved = await db.transaction((tx) =>
  tx
    .update(accounts)
    .set({ balance: sql`${accounts.balance} - 100` })
    .where(eq(accounts.id, from))
    .execute()
    .flatMap(() =>
      tx
        .update(accounts)
        .set({ balance: sql`${accounts.balance} + 100` })
        .where(eq(accounts.id, to))
        .execute(),
    ),
);
```

###### Overrides

[`PgUnthrownSession`](index-1.md#abstract-pgunthrownsession).[`transaction`](index-1.md#transaction)

***

### NodePgClient

```ts
type NodePgClient = pg.Pool | pg.PoolClient | pg.Client;
```

Defined in: [packages/drizzle/src/node-postgres/session.ts:36](https://github.com/btravstack/unthrown/blob/62d016501fb81e91d4b8a2090643a21cfdab956d/packages/drizzle/src/node-postgres/session.ts#L36)

A node-postgres client this package can drive: a pool, a client checked out of
one, or a standalone client.