@m2k-5f/pgtx 2.6.0 → 2.6.2

package/README.md

@@ -1,544 +1,278 @@
-  ## 🚀 Pgtx
+# Pgtx
 
-  [![Tests](https://github.com/M2K-5F/pgtx/actions/workflows/tests.yaml/badge.svg)](https://github.com/M2K-5F/pgtx/actions/workflows/tests.yaml)
-  [![npm version](https://img.shields.io/npm/v/@m2k-5f/pgtx.svg)](https://www.npmjs.com/package/@m2k-5f/pgtx)
+[![Tests](https://github.com/M2K-5F/pgtx/actions/workflows/tests.yaml/badge.svg)](https://github.com/M2K-5F/pgtx/actions/workflows/tests.yaml)
+[![npm version](https://img.shields.io/npm/v/@m2k-5f/pgtx.svg)](https://www.npmjs.com/package/@m2k-5f/pgtx)
 
-  **Blazing-fast PostgreSQL driver for Node.js.**
+A PostgreSQL driver for Node.js that pipelines everything by default, caches prepared statements without asking, and doesn't ship a single dependency.
 
-  Pipeline execution, automatic prepared statements, typed SQL, transactions, and zero dependencies.
-
-  **Up to 25% faster than `Postgres.js` and 15.6× faster than `pg` in concurrent pipeline workloads.**
-
-  ---
-
-  ## 📦 Installation
-
-  ```bash
-  npm install @m2k-5f/pgtx
-  # yarn add @m2k-5f/pgtx
-  # pnpm add @m2k-5f/pgtx
-  # bun add @m2k-5f/pgtx
-  ```
-
-  ---
-  
-  ## 🚀 Quick Start
-
-  ```typescript
-  import { sql, Pool } from "@m2k-5f/pgtx";
-
-  const pool = new Pool({
-    host: 'localhost',
-    user: 'postgres',
-    password: 'postgres',
-    database: 'myapp'
-  })
-
-  // Type-safe query
-  const [user] = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
-
-  // Bulk insert
-  await pool.query`
-    INSERT INTO users ${sql.insert([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }])}
-  `
-
-  // Transaction
-  await pool.begin(async (tx) => {
-    await tx.query`UPDATE accounts SET balance = balance - 100 WHERE id = ${1}`
-    await tx.query`UPDATE accounts SET balance = balance + 100 WHERE id = ${2}`
-  })
-  ```
-
-  ---
-
-  ## ✨ Features
-
-  - **Pipeline queries** — Automatic query multiplexing over PostgreSQL pipeline protocol
-  - **Tagged templates** — Natural SQL with type safety
-  - **Native Web Streams API** — Memory-efficient data streaming via `pool.stream()`
-  - **Transactions & Savepoints** — Nested transactions with rollback
-  - **Bulk inserts** — Auto-extract columns from objects
-  - **Dynamic updates** — Generate SET clauses from objects
-  - **Recursive fragments** — Compose SQL like Lego
-  - **Prepared statements** — Automatic prepared statement caching
-  - **Connection pool** — Auto-management connections with support for pipeline queries via the pool itself.
-  - **Zero dependencies** — Lightweight and blazing
-
----
-
-## ⚡ Performance
-
-All benchmarks are executed on **GitHub Actions** (Ubuntu, 2 vCPUs) and are fully reproducible. Benchmark sources are included in this repository.
-
-### 1. PostgreSQL Pipeline Stress Test
-
-**3000 concurrent parameterized `SELECT` queries**
-
-* Connection pool: **10 connections**
-* Measured with **mitata**
-
-| Driver                 |     Avg Time |       Relative Speed | Memory (p75) |
-| :--------------------- | -----------: | -------------------: | -----------: |
-| **Pgtx (Pipeline)**    | **24.18 ms** | **Baseline (1.00×)** |  **≈2.5 MB** |
-| Postgres.js (Pipeline) |     83.36 ms |     **3.45× slower** |      ≈7.6 MB |
-| node-postgres (`pg`)   |    377.95 ms |    **15.63× slower** |     ≈11.4 MB |
-
-### 2. Real-World HTTP Throughput
-
-Simple `node:http` server serving a PostgreSQL-backed endpoint.
-
-Measured with:
+It exists because `pg` leaves throughput on the table and `postgres.js`, while fast, still isn't fast enough once you actually saturate a connection pool. Pgtx is built around one idea: batch what can be batched, write to the socket once, and get out of the way.
 
 ```bash
-wrk -t2 -c<N> -d10s http://localhost:3000/users
+npm install @m2k-5f/pgtx
 ```
 
-| Concurrent Connections |             Pgtx |  Postgres.js |   Speedup |
-| ---------------------: | ---------------: | -----------: | --------: |
-|                     50 |      5,272 req/s |  5,691 req/s |     0.93× |
-|                    200 | **12,918 req/s** |  6,724 req/s | **1.92×** |
-|                   1000 | **21,429 req/s** |  8,423 req/s | **2.54×** |
-|                  10000 | **22,486 req/s** | 12,764 req/s | **1.76×** |
-
-### Why is Pgtx fast?
-
-Pgtx is engineered for **throughput**, not for minimizing the latency of individual queries.
-
-Instead of optimizing a single request in isolation, Pgtx minimizes per-query overhead under sustained concurrent load by combining:
-
-* Pipeline query multiplexing
-* Synchronous PostgreSQL wire protocol encoding
-* Batched socket writes
-* Automatic prepared statement caching
-* Prepared statement deduplication
-* Row description caching
-* Binary protocol support
-* Zero-dependency implementation
-
-As concurrency increases, these optimizations significantly reduce protocol overhead, allowing Pgtx to scale more efficiently than traditional PostgreSQL drivers.
-
-In the `mitata` benchmark, Pgtx also demonstrated approximately **3× lower memory usage** than Postgres.js while processing the same workload, reducing allocation pressure and improving sustained throughput under heavy load.
-
-> **Blazing** isn't just a tagline — it's backed by reproducible benchmarks.
-
----
-
-  ## 🔥 Why Pgtx?
-
-  | Capability                          | **Pgtx** | **Postgres.js** | **pg** |
-  | -------------------------------- | :------: | :-------------: | :----: |
-  | Pipeline queries                 |     ✅    |        ✅        |    ❌   |
-  | Pipeline multiplexing in pool    |     ✅    |        ❌        |    ❌   |
-  | Tagged template SQL              |     ✅    |        ✅        |    ❌   |
-  | Automatic prepared statements    |     ✅    |        ✅        |    ✅   |
-  | Prepared statement deduplication |     ✅    |        ❌        |    ❌   |
-  | Transactions                     |     ✅    |        ✅        |    ✅   |
-  | Savepoints                       |     ✅    |        ✅        |    ❌   |
-  | LISTEN / NOTIFY                  |     ✅    |        ✅        |    ✅   |
-  | Connection pool                  |     ✅    |        ✅        |    ✅   |
-  | Zero dependencies                |     ✅    |        ✅        |    ❌   |
-
-  ---
-
-
-  ## 📖 Features
-
-  ### 🎯 Typed Error Handling
+## Thirty seconds
 
-  Pgtx queries return `Future<T, PostgresError>` from [fluent-future](https://www.npmjs.com/package/fluent-future) instead of raw `Promise<T>`. This gives you:
+```typescript
+import { sql, Pool } from "@m2k-5f/pgtx"
 
-  - **Typed errors** — `PostgresError` with `code`, `severity`, `detail`
-  - **Declarative recovery** — `.recover()`, `.recoverIf()` instead of try/catch
-  - **Chain composition** — `.andThen()`, `.orElse()`, `.tap()`, `.tapErr()`
+const pool = new Pool({
+  host: 'localhost',
+  user: 'postgres',
+  password: 'postgres',
+  database: 'myapp'
+})
 
-  ```typescript
-  const users = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
-    .recoverIf(err => err.code === '42P01', [])  // undefined_table → []
-    .recoverIf(err => err.code === '23505', [])  // unique_violation → []
-    .tapErr(err => logger.error(err))            // log remaining errors
-  ```
+const [user] = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
 
-  ---
+// returns rows → query, doesn't → execute
+await pool.execute`
+  INSERT INTO users ${sql.insert([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }])}
+`
 
-  ### Pipeline by Default
-
-  `Bind` and `.bind` from [fluent-future](https://www.npmjs.com/package/fluent-future) automatically multiplex independent queries over PostgreSQL pipeline protocol — no manual batching required:
-
-  ```typescript
-  // 5 queries, only 2 network round-trips
-  const {user, posts, ...data} = await Bind({
-    user: () => pool.query<User>`...`,
-    config: () => pool.query<Config>`...`,
-    announcements: () => pool.query<Announcement>`...`
-  })
-  .bind({
-    posts: ({ user }) => pool.query<Post>`...`,
-    notifications: ({ user }) => pool.query<Notif>`...`
-  })
-  ```
-  > 🚀 Pgtx automatically groups concurrent queries into pipeline batches, reducing network overhead by up to 5x compared to sequential queries.
-
-
-  ---
-
-
-  ### High-Performance Data Streaming (`pool.stream`)
-
-  For heavy database lookups (exporting millions of rows, bulk reports, or large analytical dumps), memory accumulation is the ultimate killer of backend stability. Storing rows in a standard JavaScript array causes massive heap pollution and triggers blocking Garbage Collection spikes.
-
-  Pgtx solves this at the protocol level by introducing `pool.stream()`, which bypasses row aggregation entirely and pipes rows transitively directly into a native Web **`ReadableStream`**.
-
-  #### 1. Ultra-Low Memory Row Iteration
-  You can consume database rows sequentially using standard `for await...of` syntax. Rows are processed and evicted from memory the moment they arrive from the network socket buffer.
-
-  ```typescript
-  interface HeavyLog { id: number; data: string; timestamp: Date; }
-
-  const logStream = pool.stream<HeavyLog>`
-    SELECT id, data, timestamp FROM application_logs WHERE level = ${'error'}
-  `;
-
-  for await (const log of logStream) {
-    // Each log object is parsed on-the-fly and processed instantly.
-    // Zero rows are accumulated in the internal driver state!
-    console.log(`[${log.timestamp.toISOString()}] ${log.data}`);
-  }
-  ```
+await pool.begin(async tx => {
+  await tx.execute`UPDATE accounts SET balance = balance - 100 WHERE id = ${1}`
+  await tx.execute`UPDATE accounts SET balance = balance + 100 WHERE id = ${2}`
+})
+```
 
-  #### 2. Streaming Directly to HTTP Responses (`Bun.serve`)
-  Since Pgtx implements the standardized Web Streams API, you can bridge your database query directly into an HTTP response body with absolutely zero intermediate buffers.
+That's most of what you need to know to use it. The rest of this document is for when you want to know *why* it's fast, or you need one of the sharper tools.
 
-  ```typescript
-  import { Pool } from "@m2k-5f/pgtx";
+## Numbers, since it's the first thing everyone asks
 
-  const pool = new Pool({ /* ... config ... */ });
+Benchmarks run on GitHub Actions (Ubuntu, 2 vCPUs), reproducible, sources in this repo. Take CI numbers with the usual grain of salt — noisy neighbors and all that — but the gap is wide enough that it holds.
 
-  export default {
-    port: 3000,
-    async fetch(request) {
-      const url = new URL(request.url);
+**3000 concurrent parameterized SELECTs, pool of 10, measured with mitata:**
 
-      if (url.pathname === "/export/users") {
-        // Synchronously returns a stream handle even if pool sockets are currently busy
-        const userStream = pool.stream`SELECT id, email, profile_metadata FROM giant_user_table`;
+| Driver | Avg time | Relative | Memory (p75) |
+|---|---:|---:|---:|
+| Pgtx | **24.18 ms** | 1.00× | ≈4.5 MB |
+| Postgres.js | 83.36 ms | 3.45× slower | ≈7.6 MB |
+| node-postgres (`pg`) | 377.95 ms | 15.63× slower | ≈11.4 MB |
 
-        return new Response(userStream, {
-          headers: {
-            "Content-Type": "application/json",
-            "Transfer-Encoding": "chunked",
-          },
-        });
-      }
+**Real HTTP throughput, `node:http` serving a PG-backed route, `wrk`:**
 
-      return new Response("Not Found", { status: 404 });
-    },
-  };
-  ```
+| Concurrency | Pgtx | Postgres.js | Speedup |
+|---:|---:|---:|---:|
+| 50 | 5,272 req/s | 5,691 req/s | 0.93× |
+| 200 | **12,918 req/s** | 6,724 req/s | 1.92× |
+| 1000 | **21,429 req/s** | 8,423 req/s | 2.54× |
+| 10000 | **22,486 req/s** | 12,764 req/s | 1.76× |
 
-  ---
+At low concurrency Pgtx is roughly a wash with Postgres.js — pipelining has nothing to multiplex yet. The gap opens up as soon as there's real contention, which is the only regime that matters in production.
 
-  ### Transactions & Savepoints
+**How:** everything you fire concurrently against the same connection gets folded into one pipelined write — Parse/Bind/Execute for every query in the batch goes out in a single `socket.write()`, and results get demuxed as they come back, in order, without buffering rows you haven't asked for yet. Prepared statements are cached and deduplicated automatically, row descriptions are cached alongside them, and the binary protocol skips text (de)serialization where it can. None of this requires you to change how you write queries.
 
-  ```typescript
-  await pool.begin(async (tx) => {
-    await tx.query`INSERT INTO orders (user_id) VALUES (${userId})`
-    
-    await tx.savepoint('update_stock', async (stx) => {
-      await stx.query`UPDATE stock SET count = count - 1 WHERE product_id = ${productId}`
-      if (outOfStock) throw new Error('out of stock') // Only savepoint rolls back
-    })
-    .tapErr(console.log) // Error: out of stock
-  })
-  ```
+## The parts worth knowing about
 
-  ---
+### Errors you can pattern-match on
 
-  ### Async Notifications (LISTEN / NOTIFY)
+Every call returns a `Future<T[], PostgresError>` from [fluent-future](https://www.npmjs.com/package/fluent-future) instead of a bare `Promise`. `await` still works exactly like you'd expect — but you also get typed errors and a way to handle them without a `try/catch` pyramid:
 
-  Pgtx natively handles PostgreSQL `LISTEN/NOTIFY` protocol messages asynchronously without interrupting the multiplexed query pipeline. It offers two distinct ways to subscribe: high-level pool-driven subscriptions and low-level connection pinning.
+```typescript
+const users = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
+  .recoverIf(err => err.code === '42P01', [])  // undefined_table → []
+  .recoverIf(err => err.code === '23505', [])  // unique_violation → []
+  .tapErr(err => logger.error(err))
+```
 
-  #### 1. Sending a Notification
-  Notifications are atomic and can be triggered directly from the `Pool` utilizing any available socket:
-  ```typescript
-  await pool.notify('user_events', JSON.stringify({ id: 42, action: 'signup' }))
-  ```
+### Pipelining is automatic, not opt-in
 
-  #### 2. High-Level Pool Subscription (Recommended)
-  You can subscribe directly via the `Pool` instance. Pgtx will automatically borrow a dedicated connection from the pool, issue the `LISTEN` command, and seamlessly manage its lifecycle. 
+`Bind`/`.bind` from fluent-future group independent queries into the same pipeline batch for you:
 
-  The method returns a lazy, async **unsubscribe function** that cleanly handles `UNLISTEN` and returns the connection to the pool when invoked.
+```typescript
+// 5 queries, 2 round-trips
+const { user, posts, ...data } = await Bind({
+  user: pool.query<User>`...`,
+  config: pool.query<Config>`...`,
+  announcements: pool.query<Announcement>`...`
+}).bind({
+  posts: ({ user }) => pool.query<Post>`...`,
+  notifications: ({ user }) => pool.query<Notif>`...`
+})
+```
 
-  ```typescript
-  const onEvent = (payload: string) => {
-    console.log(`Received payload: ${payload}`)
-  }
+Anything you fire off in the same tick without awaiting in between ends up on the wire together.
 
-  // Automatically borrows a connection and sets up the listener
-  const unsubscribe = await pool.listen('user_events', onEvent)
+### Streaming that doesn't buffer
 
-  // When the subscription is no longer needed (e.g., server shutdown):
-  // It automatically sends UNLISTEN and releases the connection back to the pool!
-  await unsubscribe()
-  ```
+`pool.stream()` pipes rows straight from the socket into a `ReadableStream`, no intermediate array, no GC spike from holding a million-row export in memory.
 
-  #### 3. Low-Level Connection Subscription (Stateful)
-  If you need complete control over a specific PostgreSQL backend process, you can acquire an explicit `Connection` instance. This allows you to multiplex multiple callbacks onto a single channel seamlessly.
+```typescript
+for await (const log of pool.stream<Log>`SELECT * FROM application_logs WHERE level = ${'error'}`) {
+  console.log(log.timestamp, log.data)
+}
+```
 
-  ```typescript
-  const conn = await pool.acquire()
+It's a real Web Streams object, so it drops straight into an HTTP response body:
 
-  const onEvent = (payload: string) => {
-    console.log(`Received payload: ${payload}`)
+```typescript
+export default {
+  async fetch(req) {
+    const stream = pool.stream`SELECT id, email FROM giant_user_table`
+    return new Response(stream, { headers: { "Content-Type": "application/json" } })
   }
+}
+```
 
-  // Multiplexes multiple callbacks onto a single LISTEN command seamlessly
-  await conn.listen('user_events', onEvent)
-  await conn.listen('user_events', (data) => logToFile(data))
-
-  // Cleans up callbacks (Sends UNLISTEN only when the channel has zero callbacks left)
-  await conn.unlisten('user_events', onEvent)
-
-  // ⚠️ Manual lifecycle management is strictly required for this pattern!
-  // Do NOT release it back to the pool until you are completely done listening.
-  this.release(conn)
-  ```
-
-  > ⚠️ **Architecture Note:** While `pool.notify` is a fire-and-forget atomic command, subscription states (`LISTEN`/`UNLISTEN`) are strictly tied to specific PostgreSQL backend processes. Using the high-level `pool.listen()` is strongly recommended for application code, as it encapsulates socket management into an elegant, leak-proof callback boundary.
-
-  ---
+### Transactions and savepoints
 
-  ### Bulk Inserts
+```typescript
+await pool.begin(async tx => {
+  await tx.execute`INSERT INTO orders (user_id) VALUES (${userId})`
 
-  ```typescript
-  const users = [
-    { name: 'Alice', email: 'alice@test.com' },
-    { name: 'Bob', email: 'bob@test.com' }
-  ]
+  await tx.savepoint('reserve_stock', async stx => {
+    await stx.execute`UPDATE stock SET count = count - 1 WHERE product_id = ${productId}`
+    if (outOfStock) throw new Error('out of stock') // only the savepoint rolls back
+  }).tapErr(console.log)
+})
+```
 
-  await pool.query`
-    INSERT INTO users ${sql.insert(users)}
-  `
-  // INSERT INTO users (name, email) VALUES ($1, $2), ($3, $4)
-  ```
+### LISTEN / NOTIFY without babysitting a connection
 
-  ---
+```typescript
+await pool.notify('user_events', JSON.stringify({ id: 42, action: 'signup' }))
 
-  ### Dynamic Updates
+const unlisten = await pool.listen('user_events', payload => {
+  console.log('got:', payload)
+})
 
-  ```typescript
-  const data = { status: 'active', last_login: new Date() }
+// later
+await unlisten() // sends UNLISTEN, hands the connection back
+```
 
-  await pool.query`
-    UPDATE users SET ${sql.update(data)} WHERE id = ${userId}
-  `
-  // UPDATE users SET status = $1, last_login = $2 WHERE id = $3
-  ```
+`pool.listen` borrows a dedicated connection and manages its lifecycle for you. If you need to multiplex several callbacks onto one channel on a connection you're pinning yourself, drop down to `conn.listen`/`conn.unlisten` directly — just don't release that connection back to the pool while you're still using it for that.
 
-  ---
+### Building queries without string-gluing
 
-  ### Recursive Fragments
+```typescript
+// bulk insert — columns inferred from the object
+await pool.execute`INSERT INTO users ${sql.insert(users)}`
 
-  ```typescript
-  const filter = sql.fragment`status = ${'active'} AND age > ${21}`
-  const subquery = sql.fragment`(SELECT id FROM roles WHERE name = ${'admin'})`
+// dynamic SET clause
+await pool.execute`UPDATE users SET ${sql.update({ status: 'active', last_login: new Date() })} WHERE id = ${userId}`
 
-  await pool.query`
-    SELECT * FROM users 
-    WHERE ${filter} AND role_id = (${subquery})
-  `
-  ```
+// composable fragments
+const filter = sql.fragment`status = ${'active'} AND age > ${21}`
+await pool.query`SELECT * FROM users WHERE ${filter}`
 
-  ---
+// clean WHERE from an object, undefined keys just drop out
+await pool.query`SELECT * FROM users WHERE ${sql.where({ role: 'admin', age: undefined, active: true })}`
 
-  ### Smart Lists
+// conditional fragments
+await pool.query`SELECT * FROM posts ${search ? sql.fragment`WHERE title ILIKE ${search}` : sql.empty}`
+```
 
-  ```typescript
-  const ids = [10, 20, 30]
-  await pool.query`
-    SELECT * FROM users WHERE id IN (${sql.array(ids)})
-  `
-  // SELECT * FROM users WHERE id IN ($1, $2, $3)
+`undefined` means `DEFAULT` in an insert, means "skip this field" in an update, and throws if you try to hand it to `VALUES` or an array — it's meant to be a decision point, not a silent `NULL`.
 
-  const conditions = [
-    sql.fragment`status = ${'active'}`,
-    sql.fragment`age > ${18}`
-  ]
-  await pool.query`
-    SELECT * FROM users WHERE ${sql.array(conditions, ' AND ')}
-  `
-  ```
-
-  ---
-
-  ### Clean WHERE Clauses
-
-  ```typescript
-  const filters = { role: 'admin', age: undefined, active: true }
-  await pool.query`
-    SELECT * FROM users WHERE ${sql.where(filters)}
-  `
-  // SELECT * FROM users WHERE role = $1 AND active = $2
-  ```
-
-  ---
-
-  ### Conditional Logic
-
-  ```typescript
-  const search = ""
-  await pool.query`
-    SELECT * FROM posts 
-    ${search ? sql.fragment`WHERE title ILIKE ${search}` : sql.empty}
-  `
-  ```
-
-  ---
-
-  ## 🛡️ Security
-
-  | Pattern | Protection |
-  |---------|------------|
-  | `sql.ident(name)` | Escapes identifiers: `user` → `"user"` |
-  | `sql.literal(value)` | Escapes string literals |
-  | Parameter binding | Uses native `$1, $2` placeholders |
-  | Template tags | Cannot be injected via user input |
-
-  ```typescript
-  // ✅ Safe - parameterized
-  await pool.query`SELECT * FROM users WHERE name = ${userInput}`
-
-  // ⚠️ Unsafe - raw interpolation (DON'T DO THIS)
-  await pool.query(`SELECT * FROM users WHERE name = '${userInput}'`)
-
-  // ✅ Safe - identifiers
-  await pool.query`SELECT * FROM ${sql.ident(tableName)}`
-  ```
-
-  ---
-
-  ## 📊 Null & Undefined Handling
-
-  | Value | In INSERT | In UPDATE | In VALUES | In Arrays |
-  |-------|-----------|-----------|-----------|-----------|
-  | `null` | `NULL` | `NULL` | `NULL` | `NULL` |
-  | `undefined` | `DEFAULT` | Skipped | `Error` | `Error` |
-
-
-  ```typescript
-  // undefined becomes DEFAULT
-  await pool.query`
-    INSERT INTO users ${sql.insert({ 
-      name: 'Alice', 
-      age: undefined,  // → DEFAULT
-      email: null      // → NULL
-    })}
-  `
-  // INSERT INTO users (name, age, email) VALUES ($1, DEFAULT, $2)
-
-  // undefined fields are skipped in UPDATE
-  await pool.query`
-    UPDATE users SET ${sql.update({ 
-      name: 'Bob',
-      age: undefined   // Skipped - age remains unchanged
-    })} WHERE id = 1
-  `
-  // UPDATE users SET name = $1 WHERE id = 1
-  ```
-
-  ---
-
-  ## 🔧 API Reference
-
-  ###  Connection 
-  ```typescript
-  class Connection {
-      static new(params: ConnectionParams): Promise<Connection>
-
-      query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
-      begin<T>(callback: (tx: Transaction) => Promise<T>): Future<T, Error>
-      notify(channelName: string, payload?: string): Future<[], PostgresError>
-      listen(channelName: string, callback: (payload: string) => void): Future<[], PostgresError>
-      unlisten(channelName: string, callback: (payload: string) => void): Future<[], PostgresError>
-      stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>
-      get isAlive(): boolean
-      close(): void
-  }
+## Not doing this
 
-  interface ConnectionParams {
-      user: string
-      password?: string
-      host: string
-      port: number
-      database: string
-      queryTimeout?: number // default: 30 srconds
-      logLevel?: 'none' | 'error' | 'notice' | 'query' // default: "error"
-  }
-  ```
-
-  ### Pool
-
-  ```typescript
-  class Pool {
-      constructor(config: PoolConfig)
-
-      query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
-      begin<T>(callback: (tx: Transaction) => Promise<T>): Future<T, Error>
-      notify(channelName: string, payload?: string): Future<[], PostgresError>
-      listen(channel: string, callback: (payload: string) => void): Future<() => Promise<void>, PostgresError>
-      stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): ReadableStream<T>
-      withAcquire<T>(fn: (conn: Connection) => Promise<T>): Future<T, Error>
-      acquire(): Future<Connection, PostgresError>
-      release(conn: Connection): void
-      close(): void
-
-      get size(): number
-      get total(): number
-  }
+```typescript
+// don't
+await pool.query(`SELECT * FROM users WHERE name = '${userInput}'`)
 
-  interface PoolConfig extends ConnectionParams {
-      max?: number
-  }
-  ```
+// do
+await pool.query`SELECT * FROM users WHERE name = ${userInput}`
+await pool.query`SELECT * FROM ${sql.ident(tableName)}`
+```
 
-  ### Transaction
+Everything that goes through a tagged template is bound as `$1, $2, ...`. There's no code path where a template value becomes raw SQL text — if you need a dynamic identifier or literal, `sql.ident`/`sql.literal` exist precisely so you're never tempted to interpolate by hand.
+
+## API
+
+### `Connection`
+
+```typescript
+class Connection {
+  static new(config: ConnectionPartialConfig): Future<Connection, PostgresError>
+
+  query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
+  execute(strings: TemplateStringsArray, ...values: any[]): Future<void, PostgresError>
+  stream<T>(strings: TemplateStringsArray, ...values: any[]): ReadableStream<T>
+  begin<T>(callback: (tx: Transaction) => Promise<T>): Future<T, unknown>
+  notify(channelName: string, payload?: string): Future<void, PostgresError>
+  listen(channelName: string, callback: (payload: string) => void): Future<void, PostgresError>
+  unlisten(channelName: string, callback: (payload: string) => void): Future<void, PostgresError>
+  close(): Future<void, PostgresError>
+
+  get isOpened(): boolean
+  get isClosed(): boolean
+}
+
+interface ConnectionPartialConfig {
+  user: string
+  password?: string
+  host: string
+  port: number
+  database: string
+  logLevel?: 'error' | 'notice' | 'query'   // default 'error'
+  int8toBigint?: boolean                     // default false
+  queryTimeout?: number                      // default 30000
+  syncShedule?: 'beforeMicrotask' | 'afterMicrotask' | 'Immediate'  // default 'afterMicrotask'
+}
+```
 
-  ```typescript
-  class Transaction {
-    query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
-    commit(): Future<[], PostgresError>
-    rollback(): Future<[], PostgresError>
-    savepoint<T>(name: string, callback: (tx: Transaction) => Promise<T>): Future<T, Error>
+### `Pool`
+
+```typescript
+class Pool {
+  constructor(config: PoolPartialConfig)
+
+  query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
+  execute(strings: TemplateStringsArray, ...values: any[]): Future<void, PostgresError>
+  stream<T>(strings: TemplateStringsArray, ...values: any[]): ReadableStream<T>
+  begin<T>(callback: (tx: Transaction) => Promise<T>): Future<T, unknown>
+  notify(channelName: string, payload?: string): Future<void, PostgresError>
+  listen(channel: string, callback: (payload: string) => void): Future<() => Future<void, PostgresError>, PostgresError>
+  withAcquire<T>(fn: (conn: Connection) => Promise<T>): Future<T, unknown>
+  acquire(): Future<Connection, PostgresError>
+  release(conn: Connection): void
+  close(): Future<void, PostgresError>
+
+  get size(): number
+  get total(): number
+}
+
+interface PoolPartialConfig extends ConnectionPartialConfig {
+  max?: number  // default 20
+}
+```
 
-    get isActive(): boolean
-  }
-  ```
-
-  ### **sql** helper
-  ```typescript
-  const sql: {
-    ident<T extends string>(identificator: T): IdentifierClause<T>
-    literal<T extends string>(value: T): LiteralClause<T>
-    fragment(strings: TemplateStringsArray, ...values: any[]): FragmentClause
-    insert<T extends Record<string, any>>(...objects: NoInfer<T>[]): InsertClause<T>
-    update<T extends Record<string, any>>(object: T): UpdateClause<T>
-    where<T extends Record<string, any>>(whereMap: T): WhereClause<T>
-    excluded(fields: string[]): ExcludeUpdateClause
-    array(array: any[], separator?: string): ArrayClause
-    empty: EmptyClause
-  }
-  ```
+### `Transaction`
 
-  ---
+```typescript
+class Transaction {
+  query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
+  commit(): Future<void, PostgresError>
+  rollback(): Future<void, PostgresError>
+  savepoint<T>(name: string, callback: (tx: Transaction) => Promise<T>): Future<T, unknown>
 
+  get isActive(): boolean
+}
+```
 
-  Pgtx is a PostgreSQL driver.
+### `sql`
+
+```typescript
+const sql: {
+  ident<T extends string>(name: T): IdentifierClause<T>
+  literal<T extends string>(value: T): LiteralClause<T>
+  fragment(strings: TemplateStringsArray, ...values: any[]): FragmentClause
+  insert<T extends Record<string, any>>(...objects: T[]): InsertClause<T>
+  update<T extends Record<string, any>>(object: T): UpdateClause<T>
+  where<T extends Record<string, any>>(map: T): WhereClause<T>
+  excluded(fields: string[]): ExcludeUpdateClause
+  array(values: any[], separator?: string): ArrayClause
+  empty: EmptyClause
+}
+```
 
-  It is not an ORM. It is absolutely Blazing.
+## What this isn't
 
-  ## 📝 License
+Not an ORM. No migrations, no model layer, no query builder that hides SQL from you. You write SQL, Pgtx gets it to Postgres as fast as it can and gets the rows back to you with as little overhead as possible. If you want an ORM on top, Pgtx is a fine thing to put underneath one.
 
-  MIT © [M2K-5F](https://github.com/M2K-5F)
+## License
 
-  ---
+MIT © [M2K-5F](https://github.com/M2K-5F)
 
-  **Made with ❤️ and a bit of insanity**
+**Made with ❤️ and a bit of insanity**