@m2k-5f/pgtx 2.6.11 → 2.7.1

package/README.md

@@ -1,528 +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.
+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.
 
-  **Up to 25% faster than `Postgres.js` and 15.6× faster than `pg` in concurrent pipeline workloads.**
+```bash
+npm install @m2k-5f/pgtx
+```
 
-  ---
+## Thirty seconds
 
-  ## 📦 Installation
+```typescript
+import { sql, Pool } from "@m2k-5f/pgtx"
 
-  ```bash
-  npm install @m2k-5f/pgtx
-  # yarn add @m2k-5f/pgtx
-  # pnpm add @m2k-5f/pgtx
-  # bun add @m2k-5f/pgtx
-  ```
+const pool = new Pool({
+  host: 'localhost',
+  user: 'postgres',
+  password: 'postgres',
+  database: 'myapp'
+})
 
-  ---
-  
-  ## 🚀 Quick Start
+const [user] = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
 
-  ```typescript
-  import { sql, Pool } from "@m2k-5f/pgtx";
+await pool.execute`
+  INSERT INTO users ${sql.insert([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }])}
+`
 
-  const pool = new Pool({
-    host: 'localhost',
-    user: 'postgres',
-    password: 'postgres',
-    database: 'myapp'
-  })
+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}`
+})
+```
 
-  // Type-safe query
-  const [user] = await pool.query<User>`SELECT * FROM users WHERE id = ${1}`
+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.
 
-  // Bulk insert
-  await pool.query`
-    INSERT INTO users ${sql.insert([{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }])}
-  `
+## Benchmarks
+ 
+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.
+ 
+**HTTP throughput against `postgres.js` and Bun's own native `Bun.sql` driver, on Bun:**
+ 
+| Connections | Pgtx | Postgres.js | Bun.sql | vs Postgres.js | vs Bun.sql |
+|---:|---:|---:|---:|---:|---:|
+| 50 | **27,885 req/s** | 8,967 req/s | 10,170 req/s | 3.11× | 2.74× |
+| 200 | **31,975 req/s** | 9,861 req/s | 11,725 req/s | 3.24× | 2.73× |
+| 500 | **31,245 req/s** | 8,289 req/s | 11,005 req/s | 3.77× | 2.84× |
+ 
+Bun.sql is Bun's own built-in driver, written in native code and generally treated as the speed baseline in that ecosystem. Pgtx stays 2.7-2.8× ahead of it at every concurrency level tested — the gap doesn't come from JS-vs-native, it comes from the protocol.
+ 
+**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.
 
-  // 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}`
-  })
-  ```
+## The parts worth knowing about
 
-  ---
+### Errors you can pattern-match on
 
-  ## ✨ Features
+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:
 
-  - **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
+```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))
+```
 
-  ---
+### Pipelining is automatic, not opt-in
 
-  ## ⚡ Performance
+`Bind`/`.bind` from fluent-future group independent queries into the same pipeline batch for you:
 
-  All benchmarks are executed on **GitHub Actions** (Ubuntu, 2 vCPUs) and are fully reproducible. Benchmark sources are included in this repository.
+```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>`...`
+})
+```
 
-  ### 1. PostgreSQL Pipeline Stress Test
+Anything you fire off in the same tick without awaiting in between ends up on the wire together.
 
-  **3000 concurrent parameterized `SELECT` queries**
+### Streaming that doesn't buffer
 
-  * Connection pool: **10 connections**
-  * Measured with **mitata**
+`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.
 
-  | 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 |
+```typescript
+for await (const log of pool.stream<Log>`SELECT * FROM application_logs WHERE level = ${'error'}`) {
+  console.log(log.timestamp, log.data)
+}
+```
 
-  ### 2. Real-World HTTP Throughput
+It's a real Web Streams object, so it drops straight into an HTTP response body:
 
-  Simple `node:http` server serving a PostgreSQL-backed endpoint.
-
-  Measured with:
-
-  ```bash
-  wrk -t2 -c<N> -d10s http://localhost:3000/users
-  ```
-
-  | 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 **2× 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.
-
----
-
-  ## 📖 Features
-
-  ### 🎯 Typed Error Handling
-
-  Pgtx queries return `Future<T, PostgresError>` from [fluent-future](https://www.npmjs.com/package/fluent-future) instead of raw `Promise<T>`. This gives you:
-
-  - **Typed errors** — `PostgresError` with `code`, `severity`, `detail`
-  - **Declarative recovery** — `.recover()`, `.recoverIf()` instead of try/catch
-  - **Chain composition** — `.andThen()`, `.orElse()`, `.tap()`, `.tapErr()`
-
-  ```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
-  ```
-
-  ---
-
-  ### 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}`);
+```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" } })
   }
-  ```
-
-  #### 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.
-
-  ```typescript
-  import { Pool } from "@m2k-5f/pgtx";
+}
+```
 
-  const pool = new Pool({ /* ... config ... */ });
+### Transactions and savepoints
 
-  export default {
-    port: 3000,
-    async fetch(request) {
-      const url = new URL(request.url);
+```typescript
+await pool.begin(async tx => {
+  await tx.execute`INSERT INTO orders (user_id) VALUES (${userId})`
 
-      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`;
+  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)
+})
+```
 
-        return new Response(userStream, {
-          headers: {
-            "Content-Type": "application/json",
-            "Transfer-Encoding": "chunked",
-          },
-        });
-      }
+### LISTEN / NOTIFY without babysitting a connection
 
-      return new Response("Not Found", { status: 404 });
-    },
-  };
-  ```
-
-  ---
-
-  ### Transactions & Savepoints
-
-  ```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
-  })
-  ```
-
-  ---
-
-  ### Async Notifications (LISTEN / NOTIFY)
-
-  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.
-
-  #### 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' }))
-  ```
-
-  #### 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. 
-
-  The method returns a lazy, async **unsubscribe function** that cleanly handles `UNLISTEN` and returns the connection to the pool when invoked.
-
-  ```typescript
-  const onEvent = (payload: string) => {
-    console.log(`Received payload: ${payload}`)
-  }
+```typescript
+await pool.notify('user_events', JSON.stringify({ id: 42, action: 'signup' }))
+
+const unlisten = await pool.listen('user_events', payload => {
+  console.log('got:', payload)
+})
+
+// later
+await unlisten() // sends UNLISTEN, hands the connection back
+```
+
+`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
+
+```typescript
+// bulk insert — columns inferred from the object
+await pool.execute`INSERT INTO users ${sql.insert(users)}`
+
+// dynamic SET clause
+await pool.execute`UPDATE users SET ${sql.update({ status: 'active', last_login: new Date() })} WHERE id = ${userId}`
+```
+
+Rule of thumb: `execute` when you don't need rows back, `query` when you do — same rule as the raw driver, `sql.*` doesn't change it.
+
+```typescript
+// 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 })}`
+
+// conditional fragments
+await pool.query`SELECT * FROM posts ${search ? sql.fragment`WHERE title ILIKE ${search}` : sql.empty}`
+```
+
+`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`.
+
+## Not doing this
+
+```typescript
+// don't
+await pool.query(`SELECT * FROM users WHERE name = '${userInput}'`)
+
+// do
+await pool.query`SELECT * FROM users WHERE name = ${userInput}`
+await pool.query`SELECT * FROM ${sql.ident(tableName)}`
+```
+
+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'
+  ssl?: 'disable' | 'prefer' | 'require' // defaut 'prefer' 
+  caPath?: string // forces `ssl` to 'require' if provided
+}
+```
+
+### `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
+}
+```
+
+### `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
+}
+```
+
+### `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
+}
+```
+
+## What this isn't
+
+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.
+
+## License
+
+MIT © [M2K-5F](https://github.com/M2K-5F)
 
-  // Automatically borrows a connection and sets up the listener
-  const unsubscribe = await pool.listen('user_events', onEvent)
-
-  // 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()
-  ```
-
-  #### 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
-  const conn = await pool.acquire()
-
-  const onEvent = (payload: string) => {
-    console.log(`Received payload: ${payload}`)
-  }
-
-  // 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.
-
-  ---
-
-  ### Bulk Inserts
-
-  ```typescript
-  const users = [
-    { name: 'Alice', email: 'alice@test.com' },
-    { name: 'Bob', email: 'bob@test.com' }
-  ]
-
-  await pool.query`
-    INSERT INTO users ${sql.insert(users)}
-  `
-  // INSERT INTO users (name, email) VALUES ($1, $2), ($3, $4)
-  ```
-
-  ---
-
-  ### Dynamic Updates
-
-  ```typescript
-  const data = { status: 'active', last_login: new Date() }
-
-  await pool.query`
-    UPDATE users SET ${sql.update(data)} WHERE id = ${userId}
-  `
-  // UPDATE users SET status = $1, last_login = $2 WHERE id = $3
-  ```
-
-  ---
-
-  ### Recursive Fragments
-
-  ```typescript
-  const filter = sql.fragment`status = ${'active'} AND age > ${21}`
-  const subquery = sql.fragment`(SELECT id FROM roles WHERE name = ${'admin'})`
-
-  await pool.query`
-    SELECT * FROM users 
-    WHERE ${filter} AND role_id = (${subquery})
-  `
-  ```
-
-  ---
-
-  ### Smart Lists
-
-  ```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)
-
-  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: ConnectionPartialParams): Promise<Connection>
-
-      query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
-      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>
-      stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...params: any[]): ReadableStream<T>
-      get isAlive(): boolean
-      close(): void
-  }
-
-  interface ConnectionPartialParams {
-    user: string
-    password?: string
-    host: string
-    port: number
-    database: string
-    logLevel?: LogLevel, // default "error"
-    int8toBigint?: boolean, // default false
-    queryTimeout?: number // default 30000 (30 seconds)
-    syncShedule?: "Tick" | "Immediate" // default "Immediate"
-  }
-  ```
-
-  ### Pool
-
-  ```typescript
-  class Pool {
-      constructor(config: PoolPartialConfig)
-
-      query<T>(strings: TemplateStringsArray, ...values: any[]): Future<T[], PostgresError>
-      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>
-      stream<T extends Record<string, any>>(templates: TemplateStringsArray, ...args: any[]): ReadableStream<T>
-      withAcquire<T>(fn: (conn: Connection) => Promise<T>): Future<T, unknown>
-      acquire(): Future<Connection, PostgresError>
-      release(conn: Connection): void
-      close(): void
-
-      get size(): number
-      get total(): number
-  }
-
-  interface PoolPartialConfig extends ConnectionPartialConfig {
-      max?: number
-  }
-  ```
-
-  ### 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
-  }
-  ```
-
-  ### **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
-  }
-  ```
-
-  ---
-
-
-  Pgtx is a PostgreSQL driver.
-
-  It is not an ORM. It is absolutely Blazing.
-
-  ## 📝 License
-
-  MIT © [M2K-5F](https://github.com/M2K-5F)
+---
 
-  ---
+**Made with ❤️ and a bit of insanity**
 
-  **Made with ❤️ and a bit of insanity**
+*Manufactured under license by the **Blazing Corporation**. Side effects may include throughput.*