postgrejs 2.23.1 → 3.0.2

package/CHANGELOG.md

@@ -1,6 +1,176 @@
 ## Changelog
 
-### [v2.23.1](https://github.com/panates/postgrejs/compare/v2.23.0...v2.23.1) - 
+### [v3.0.2](https://github.com/panates/postgrejs/compare/v3.0.1...v3.0.2) - 
+
+#### 🚀 New Features
+
+- feat: add Docker setup for PostgreSQL with SSL support @Eray Hanoğlu 
+- feat: support nested startTransaction()/commit() and savepoint()/releaseSavepoint() @Eray Hanoğlu 
+- feat: make execute()/query() timing an opt-in, default-off option @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: raise warmup for Simple Query benchmark, regenerate BENCHMARKS.md @Eray Hanoğlu 
+- fix: enlarge benchmark charts so GitHub's Mermaid overlay doesn't swallow them @Eray Hanoğlu 
+- fix: replace deprecated substr() with substring() @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: remove needless async wrapping and coercion from execute()/query() hot path @Eray Hanoğlu 
+- perf: hoist loop-invariant reads in Frontend/numeric encoders @Eray Hanoğlu 
+
+### [v3.0.1](https://github.com/panates/postgrejs/compare/v3.0.0...v3.0.1) -  7 September 2026 
+
+- Dev
+- Dev
+- Dev
+- Dev
+- dev: Removed path filter
+- Dev
+- Dev
+- fix missing quotes in exception
+- Don't fail if husky is not present
+- Dev
+- Dev
+
+#### 🚀 New Features
+
+- feat: make async caller-stack capture an opt-out, per-call overridable option @Eray Hanoğlu 
+- feat: exact-match --scenario/--lib by default, glob with a leading/trailing * @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: LISTEN dropped for extra channels, lost after Pool reconnect, double 'close' emit @Eray Hanoğlu 
+- fix: cancel() ignored multi-host failover and direct TLS negotiation @Eray Hanoğlu 
+- fix: default omitted day-of-month to 1, not 0, when parsing dates @Eray Hanoğlu 
+- fix: numeric encodeBinary() silently corrupts magnitudes >= 1e21 @Eray Hanoğlu 
+- fix: benchmark console summary leaked every scenario ever run @Eray Hanoğlu 
+- fix: LogicalReplication.close() never actually drops a permanent slot it created @Eray Hanoğlu 
+- fix: JsonType.encodeText() throws on a bigint value @Eray Hanoğlu 
+- fix: restore execute()'s timing, and switch it to performance.now() @Eray Hanoğlu 
+- fix: skip numeric Infinity/-Infinity tests on PostgreSQL < 14 @Eray Hanoğlu 
+- fix: skip direct-negotiation SSL test on PostgreSQL < 17 @Eray Hanoğlu 
+- fix: avoid a rare race in the cancel() test's own cleanup @Eray Hanoğlu 
+- fix: correct stale contact and copyright holder in project docs @Eray Hanoğlu 
+- fix: header link/image attributes in README @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: rewrite benchmark scenario descriptions as readable paragraphs @Eray Hanoğlu 
+- docs: capitalize PostgreJS consistently, rebuild BENCHMARKS.md for 3.0.0 @Eray Hanoğlu 
+- docs: add a v2-to-v3 migration guide @Eray Hanoğlu 
+- docs: expand CONTRIBUTING.md with a full contributor workflow @Eray Hanoğlu 
+- docs: rewrite README intro to lead with speed, memory, and features @Eray Hanoğlu 
+- docs: expand CLAUDE.md with project orientation and testing techniques @Eray Hanoğlu 
+- docs: tailor issue templates to a PostgreSQL driver @Eray Hanoğlu 
+- docs: document local SCRAM/MD5 test setup in CONTRIBUTING.md @Eray Hanoğlu 
+
+#### 🛠 Refactoring and Updates
+
+- refactor: remove dead Portal/PgSocket message-send methods @Eray Hanoğlu 
+- refactor: remove dead SmartBuffer.fill(), add full coverage @Eray Hanoğlu 
+- refactor: remove dead BufferReader.moveBy()/moveTo(), add full coverage @Eray Hanoğlu 
+
+#### 🧪 Changes to Test Assests
+
+- test: cover pure utility functions, wire-protocol messages, and SASL/cert parsing @Eray Hanoğlu 
+- test: add full coverage for copy-stream.ts @Eray Hanoğlu 
+- test: add full coverage for the pgoutput logical-replication decoder @Eray Hanoğlu 
+- test: add direct unit coverage for LogicalReplication's pure logic @Eray Hanoğlu 
+- test: add full coverage for the remaining small scalar data types @Eray Hanoğlu 
+- test: add full coverage for frontend.ts wire-message builders @Eray Hanoğlu 
+- test: add full coverage for parse-row.ts @Eray Hanoğlu 
+- test: add full coverage for get-parsers.ts @Eray Hanoğlu 
+- test: add full coverage for LsegType @Eray Hanoğlu 
+- test: add full coverage for CircleType @Eray Hanoğlu 
+- test: raise connection-config.ts branch coverage @Eray Hanoğlu 
+- test: raise sql-tag.ts branch coverage, mark one path unreachable @Eray Hanoğlu 
+- test: raise cursor.ts coverage @Eray Hanoğlu 
+- test: add full coverage for OidVectorType @Eray Hanoğlu 
+- test: add full coverage for Int2VectorType @Eray Hanoğlu 
+- test: add coverage for the encodeText() pass-throughs on temporal types @Eray Hanoğlu 
+- test: raise large-object.ts coverage @Eray Hanoğlu 
+- test: raise prepared-statement.ts coverage @Eray Hanoğlu 
+- test: add full coverage for SafeEventEmitter @Eray Hanoğlu 
+- test: add full coverage for CharType @Eray Hanoğlu 
+- test: add full coverage for BoolType.encodeText() @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: skip the instanceof check on plain string SQL in execute() @Eray Hanoğlu 
+
+## [v3.0.0](https://github.com/panates/postgrejs/compare/v2.23.1...v3.0.0) -  6 September 2026 
+
+#### Breaking Changes :warning:
+
+- refactor: name data type methods decode* to pair with encode* @Eray Hanoğlu  
+
+#### 🚀 New Features
+
+- feat: bulk import and export with COPY TO STDOUT / COPY FROM STDIN @Eray Hanoğlu 
+- feat: stream row changes with LogicalReplication @Eray Hanoğlu 
+- feat: build statements with the sql tag @Eray Hanoğlu 
+- feat: opt-in query pipelining for Pool.query() and Pool.execute() @Eray Hanoğlu 
+- feat: cancel queries and time them out with an AbortSignal @Eray Hanoğlu 
+- feat: large object API @Eray Hanoğlu 
+- feat: try several hosts and pick one by role @Eray Hanoğlu 
+- feat: SCRAM channel binding, and report what the server says when auth fails @Eray Hanoğlu 
+- feat: direct TLS negotiation, and only negotiate TLS when asked @Eray Hanoğlu 
+- feat: two-phase commit with prepareTransaction and commitPrepared @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: jsonb text encoder wrote the binary version header, and add the last binary encoders @Eray Hanoğlu 
+- fix: oidvector was registered as a second array type of oid @Eray Hanoğlu 
+- fix: prototype pollution via a query result column named "__proto__" @Eray Hanoğlu 
+- fix: float4 precision loss and sslmode=prefer incorrectly requiring SSL @Eray Hanoğlu 
+- fix: numeric NaN/Infinity/-Infinity decode as 0 in binary format @Eray Hanoğlu 
+- fix: int4 OID auto-detection accepts values outside the 32-bit range @Eray Hanoğlu 
+- fix: preserve caller stack traces in async error handling @Eray Hanoğlu 
+- fix: PreparedStatement.close() not idempotent, re-sends CLOSE+SYNC @Eray Hanoğlu 
+- fix: midnight timestamps mis-detected as date instead of timestamp @Eray Hanoğlu 
+- fix: array literal parser treats apostrophe as a quote character @Eray Hanoğlu 
+- fix: TLS downgrade, credential decoding, and data-corruption bugs found in audit @Eray Hanoğlu 
+- fix: ParameterDescription parameter count read as Int32 instead of Int16 @Eray Hanoğlu 
+- fix: hang instead of an error when the server asks for GSSAPI or SSPI @Eray Hanoğlu 
+- fix: escapeLiteral silently passes through embedded NUL bytes @Eray Hanoğlu 
+- fix: char OID auto-detection matches multi-byte characters, crashing bind @Eray Hanoğlu 
+- fix: CopyInResponse message code is 'g' rather than 'G' @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: record multi-host connections in the comparison @Eray Hanoğlu 
+- docs: count encoder and decoder coverage per wire format @Eray Hanoğlu 
+- docs: add a feature comparison table and correct stale claims @Eray Hanoğlu 
+- docs: record direct TLS negotiation, and drop the example section @Eray Hanoğlu 
+- docs: record class member order and loop-hoisting conventions @Eray Hanoğlu 
+- docs: native bindings are partial, not a plain yes @Eray Hanoğlu 
+- docs: correct two names in the comparison table @Eray Hanoğlu 
+- docs: record two-phase commit and drop the callback API row @Eray Hanoğlu 
+
+#### 🌸 Tidying of Code eg Whitespace
+
+- style: sort imports and align a comment left over from the decode* rename @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: rewrite the request/response pipeline and decode rows without per-column slices @Eray Hanoğlu 
+- perf: reassemble backend messages in one allocation instead of concatenating every chunk @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- doc: Rebuild BENCHMARKS.md @Eray Hanoğlu 
+- doc: Updated README.md @Eray Hanoğlu 
+- dev: Removed unused `init-pg.ts`, adjusted imports, and updated path in tsconfig @Eray Hanoğlu 
+- doc: Remove outdated and unused badges from README.md @Eray Hanoğlu 
+- doc: correct grammar in connection.ts method comments @Eray Hanoğlu 
+- dev: Added CLAUDE.md with graphify usage rules @Eray Hanoğlu 
+- dev: Updated test matrix to include Node 26 and Postgres 18 @Eray Hanoğlu 
+- dev: Changed import extension for `env.js` in init-pg.ts @Eray Hanoğlu 
+- dev: Updated gitignore to include claude and graphify @Eray Hanoğlu 
+- dev: Broadened eslint disable rule in bigint-methods.ts @Eray Hanoğlu 
+
+### [v2.23.1](https://github.com/panates/postgrejs/compare/v2.23.0...v2.23.1) -  7 July 2026 
 
 #### 💬 General Changes
 

package/LICENSE

@@ -1,21 +1,30 @@
-MIT License
+BSD 3-Clause License
 
-Copyright (c) 2020 Panates, Eray Hanoglu
+Copyright (c) 2020 Panates
+All rights reserved.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,53 +1,49 @@
 <!--suppress HtmlDeprecatedAttribute -->
-<p align="center">¨
-  <a href="https://postgrejs.panates.com/" target="blank">
-    <img src="https://postgrejs.panates.com/img/postgrejs-header-block.png" width="800" alt="PostgreJS Logo" />
+<p align="center">
+  <a href="https://postgrejs.panates.com/" target="_blank" rel="noopener noreferrer">
+    <img src="https://postgrejs.panates.com/img/postgrejs-header-block.png" width="800" height="446" alt="PostgreJS Logo" />
   </a>
 </p>
-  
+
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
 [![CI Tests][ci-test-image]][ci-test-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
 
+## Why PostgreJS?
 
-PostgreJS is an enterprise-level PostgreSQL client for Node.js.
-It is designed to provide a robust and efficient interface to PostgreSQL databases,
-ensuring high performance and reliability for enterprise applications.
-Written entirely in TypeScript, it leverages modern JavaScript features to deliver a seamless development experience.
-
+**PostgreJS** is a PostgreSQL driver for Node.js built from the wire protocol up - no `libpq`, no native bindings,
+just TypeScript talking directly to PostgreSQL. That from-scratch design is also what makes it fast and light: every
+byte on the wire is handled by code written for exactly that purpose, with a binary-first protocol, shared buffers,
+and row/column decoding pipelines built to avoid unnecessary allocation, instead of generic string plumbing bolted
+onto a client meant for text.
 
-## Library Overview
+### ⚡ Blazing Fast
 
-PostgreJS is a pure JavaScript library, meticulously crafted with TypeScript to offer a strictly typed, well-structured,
-and highly maintainable codebase.
-Key highlights include:
+The numbers back it up. In PostgreJS's own benchmark suite - run head-to-head against
+[`pg`](https://github.com/brianc/node-postgres) (node-postgres) and [`postgres`](https://github.com/porsager/postgres)
+(postgres.js) on identical workloads - PostgreJS opens a connection up to **3x faster** than postgres.js and
+**2x faster** than pg, pushes pooled queries through up to **6.6x faster** than postgres.js, and fetches large
+result sets nearly **5x faster** than pg. It's also the only one of the three with a complete binary wire protocol
+across every data type, rather than falling back to text for most of them. See
+[`doc/BENCHMARKS.md`](doc/BENCHMARKS.md) for the full methodology and every scenario.
 
-- **Language:** Pure modern JavaScript library.
-- **Strictly Typed:** Completely written in TypeScript, offering strong typing and enhanced development experience.
-- **Compatibility:** Works seamlessly with both CommonJS and ESM module systems, ensuring flexibility in various project setups.
-- **Comprehensive Testing:** Rigorously tested to ensure stability and reliability in production environments.
-- **Promise-Based API:** Asynchronous operations are handled with a Promise-based API, promoting clean and efficient asynchronous code.
-
-## Features
+### 🪶 Small Footprint
 
-- **Connection Management:** Supports both single connection and advanced pooling, providing scalability and efficient resource management.
-- **Binary Wire Protocol:** Implements the full binary wire protocol for all PostgreSQL data types, ensuring robust and efficient data handling.
-- **Prepared Statements:** Named prepared statements for optimized query execution.
-- **Cursors:** Features fast double-link cache cursors for efficient data retrieval.
-- **Notifications:**  High-level implementation for PostgreSQL notifications (LISTEN/NOTIFY), enabling real-time data updates.
-- **Extensibility:** Extensible data-types and type mapping to accommodate custom requirements.
-- **Parameter Binding:**  Bind parameters with OID mappings for precise and efficient query execution.
-- **Array Handling:** Supports multidimensional arrays with fast binary encoding/decoding.
-- **Performance Optimization:**  Low memory utilization and boosted performance through the use of shared buffers.
-- **Authorization:** SSupports various password algorithms including Clear text, MD5, and SASL, ensuring secure authentication.
-- **Flexible Data Retrieval:**  Can return both array and object rows to suit different data processing needs.
-- **Resource Management:** Auto disposal of resources with the "using" syntax ([TC30 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)), ensuring efficient resource cleanup.
+The same benchmarks show it using a fraction of the memory: peak heap usage typically runs **3-7x lower** than both
+pg and postgres.js - as much as **7x lower** when streaming cursors or fetching large arrays - and it spends a
+fraction of the time either of them does in garbage collection. Shared buffers and decode paths that read values
+straight out of the wire buffer leave far less garbage behind per row, so there's less for the GC to clean up in
+the first place.
 
-Whether you're building a simple application or a complex enterprise system,
-PostgreJS provides the features and performance you need to succeed.
-Explore the capabilities of the library and elevate your PostgreSQL integration to the next level.
+### 🔋 Batteries Included
 
+Speed and memory aside, PostgreJS is also the most complete driver of the three: a dynamic `sql` tag for
+composable, parameterized SQL, per-query type mapping, and TC39 Explicit Resource Management (`using`) support are
+unique to it, alongside a feature set most drivers spread across several add-on packages - connection pooling,
+prepared statements, server-side cursors, LISTEN/NOTIFY, bulk `COPY` streams, logical replication, large objects,
+two-phase commit, multi-host failover, and SCRAM channel binding - all in the one package, written in
+strictly-typed TypeScript from the ground up.
 
 ## Installation
 
@@ -56,161 +52,185 @@ $ npm install postgrejs --save
 ```
 
 ## Documentation
-Please read :small_orange_diamond: [DOCUMENTATION](https://postgrejs.panates.com/) :small_orange_diamond: for detailed usage.
-
-## Example usage
-
-### Establish a single connection, execute a simple query
 
-```ts
-import { Connection } from 'postgrejs';
-// Create connection
-const connection = new Connection('postgres://localhost');
-// Connect to database server
-await connection.connect();
+Please read :small_orange_diamond: [DOCUMENTATION](https://postgrejs.panates.com/) :small_orange_diamond: for detailed
+usage.
 
-// Execute query and fetch rows
-const result = await connection.query(
-    'select * from cities where name like $1',
-    {params: ['%york%']});
-const rows: any[] = result.rows;
-// Do what ever you want with rows
-
-// Disconnect from server
-await connection.close(); 
-```
+## Library Overview
 
-### Establish a pooled connection, create a cursor
-```ts
-import { Pool } from 'postgrejs';
-
-// Create connection pool
-const db = new Pool({
-    host: 'postgres://localhost',
-    pool: {
-       min: 1,
-       max: 10,
-       idleTimeoutMillis: 5000
-    }
-});
-
-// Execute query and fetch cursor
-const result = await db.query(
-    'select * from cities where name like $1',
-    {params: ['%york%'], cursor: true});
-
-// Walk through the cursor, and do whatever you want with fetched rows
-const cursor = result.cursor;
-let row;
-while ((row = await cursor.next())) {
-  console.log(row);
-}
-// Close cursor, (Send connection back to the pool)
-await cursor.close();
-
-// Disconnect all connections and shutdown pool
-await db.close(); 
-```
+- **Language:** Pure JavaScript, with no native/binary dependencies to compile or ship.
+- **Strictly typed:** Written entirely in TypeScript, with types shipped alongside the package.
+- **Modern module format:** Ships as ESM; Node 20.19+/22.12+ can `require()` it from CommonJS code as well.
+- **Promise-based API:** Every asynchronous operation returns a promise - no callbacks to wrangle.
+- **Rigorously tested:** A test suite covering the wire protocol, every data type, and connection-handling edge case,
+  run on every push against PostgreSQL 12 through 18.
 
-### Using prepared statements
-```ts
-import { DataTypeOIDs } from 'postgrejs'; 
+## Features
 
-// .....
-const statement = await connection.prepare( 
-    'insert into my_table(id, name) values ($1, $2)', {
-        paramTypes: [DataTypeOIDs.Int4, DataTypeOIDs.Varchar]
-    });
+- **Connection Management:** Supports both single connection and advanced pooling, providing scalability and efficient
+  resource management.
+- **Binary Wire Protocol:** Implements the full binary wire protocol for all PostgreSQL data types, ensuring robust and
+  efficient data handling.
+- **Prepared Statements:** Named prepared statements for optimized query execution.
+- **Cursors:** Features fast double-link cache cursors for efficient data retrieval.
+- **Notifications:**  High-level implementation for PostgreSQL notifications (LISTEN/NOTIFY), enabling real-time data
+  updates.
+- **Extensibility:** Extensible data-types and type mapping to accommodate custom requirements.
+- **Parameter Binding:**  Bind parameters with OID mappings for precise and efficient query execution.
+- **Array Handling:** Supports multidimensional arrays with fast binary encoding/decoding.
+- **Performance Optimization:**  Low memory utilization and boosted performance through the use of shared buffers.
+- **Authorization:** Supports various password algorithms including Clear text, MD5, and SASL, ensuring secure
+  authentication.
+- **Bulk Import/Export:** `COPY TO STDOUT` and `COPY FROM STDIN` as Node streams, with backpressure in both directions.
+- **Query Pipelining:** Pooled queries can share connections so a burst is not capped by pool size - opt-in per call.
+- **Dynamic SQL:** A `sql` tag builds statements from composable fragments - values become parameters, names are quoted,
+  and `sql.values()`/`sql.set()` write INSERT and UPDATE clauses from objects.
+- **Multiple Hosts:** A connection can list several servers and pick one by role
+  (`target_session_attrs`), so a cluster that has failed over is found on the next connect.
+- **Large Objects:** File-like access to binary data stored outside the row - seek, partial reads, streams - for
+  values past what a `bytea` column can hold.
+- **Logical Replication:** `LogicalReplication` streams committed row changes as an async iterable, decoding
+  `pgoutput` itself, with client-side filtering and positions confirmed as you consume.
+- **Channel Binding:** SCRAM authentication binds itself to the TLS channel when the server offers it, the way libpq
+  does by default, so a relayed login is detected even where the certificate is not verified.
+- **Two-phase commit:** `prepareTransaction()` leaves a transaction waiting under a name for `commitPrepared()`/
+  `rollbackPrepared()`, from any connection.
+- **Cancellation:** Any call takes an `AbortSignal`, which also gives per-query timeouts via `AbortSignal.timeout()`.
+- **Flexible Data Retrieval:**  Can return both array and object rows to suit different data processing needs.
+- **Resource Management:** Auto disposal of resources with the "using" syntax
+  ([TC39 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)), ensuring
+  efficient resource cleanup.
+
+## Feature Comparison
+
+How PostgreJS compares to [`pg`](https://github.com/brianc/node-postgres) (node-postgres) and
+[`postgres`](https://github.com/porsager/postgres) (postgres.js). Every row was checked against the libraries' own
+source rather than their documentation — versions compared: **PostgreJS 2.23.1, pg 8.23.0, postgres.js 3.4.9**. ✅ built
+in · 🟡 partial or needs a separate package · ❌ not supported.
+
+| Feature                           |       PostgreJS        |          pg           |   postgres.js    |
+|:---------------------------------|:----------------------:|:-------------------:|:----------------:|
+| ***Packaging***                   |                        |                       |                  |
+| Packages to install               |           1            |    4 <sup>1</sup>     |        1         |
+| Module system                     |          ESM           |        ESM/CJS        |     ESM/CJS      |
+| Language                          |           TS           |    JS <sup>2</sup>    | JS <sup>3</sup>  |
+| ***Wire protocol***               |                        |                       |                  |
+| Simple Query protocol             |           ✅           |          ✅           |        ✅        |
+| Extended Query protocol           |           ✅           |          ✅           |        ✅        |
+| Text wire format                  |           ✅           |          ✅           |        ✅        |
+| Binary wire format                |           ✅           |    🟡 <sup>4</sup>    | ❌ <sup>5</sup>  |
+| Per-column format selection       |           ✅           |          ❌           |        ❌        |
+| ***High-level API***              |                        |                       |                  |
+| Object and array row modes        |           ✅           |          ✅           |        ✅        |
+| Dynamic SQL helpers               |      ✅ `sql` tag      |          ❌           |        ✅        |
+| Per-query type mapping            |           ✅           |    ❌ <sup>6</sup>    | ❌ <sup>6</sup>  |
+| Query cancellation                |     ✅ AbortSignal     |          ✅           |        ✅        |
+| Per-query timeout                 |     ✅ AbortSignal     |          ✅           | ❌ <sup>7</sup>  |
+| Reference counters                | Connection / Statement |          ❌           |        ❌        |
+| Caller kept in async error stacks |           ✅           |    🟡 <sup>8</sup>    | 🟡 <sup>9</sup>  |
+| Error located in the SQL text     |    ✅ line and mark    |       🟡 offset       |    🟡 offset     |
+| TC39 Explicit Resource Management |           ✅           |          ❌           |        ❌        |
+| ***Querying***                    |                        |                       |                  |
+| Query parameters                  |           ✅           |          ✅           |        ✅        |
+| Parameter type casting            |           ✅           |   🟡 <sup>10</sup>    |        ✅        |
+| Prepared statements               |      ✅ explicit       |          ✅           |   ✅ automatic   |
+| Multi-statement scripts           |           ✅           |          ✅           |        ✅        |
+| Server-side cursors               |           ✅           |   🟡 <sup>11</sup>    |        ✅        |
+| `COPY TO` / `COPY FROM`           |           ✅           |   🟡 <sup>12</sup>    |        ✅        |
+| Row count after a COPY            |           ✅           |          ✅           |        ❌        |
+| ***Transaction management***      |                        |                       |                  |
+| Transaction API                   |           ✅           |          ❌           |        ✅        |
+| Savepoints                        |           ✅           |          ❌           |        ✅        |
+| Two-phase commit API              |           ✅           |          ❌           | 🟡 <sup>13</sup> |
+| ***Session management***          |                        |                       |                  |
+| Built-in connection pool          |           ✅           |          ✅           |   ✅ implicit    |
+| Pipelining on one connection      |     ✅ opt-in/call     |   ✅ opt-in/client    |   ✅ automatic   |
+| Graceful shutdown                 |           ✅           |   ❌ <sup>14</sup>    |        ✅        |
+| Multiple hosts                    |           ✅           |          ❌           |        ✅        |
+| LISTEN/NOTIFY                     |           ✅           |   🟡 <sup>15</sup>    |        ✅        |
+| ***Data types***                  |                        |                       |                  |
+| Text encoders                     |           56           | generic <sup>16</sup> |        14        |
+| Text decoders                     |           56           |          44           | 12 <sup>17</sup> |
+| Binary encoders                   |           56           |          ❌           |        ❌        |
+| Binary decoders                   |           56           |          16           |        ❌        |
+| Multidimensional arrays           |       ✅ binary        | 🟡 text <sup>18</sup> |     🟡 text      |
+| ***Security***                    |                        |                       |                  |
+| SSL/TLS                           |           ✅           |          ✅           |        ✅        |
+| Direct TLS negotiation (PG17)     |           ✅           |          ✅           |        ✅        |
+| Cleartext, MD5, SCRAM-SHA-256     |           ✅           |          ✅           |        ✅        |
+| SCRAM channel binding (`-PLUS`)   |       ✅ default       |       ✅ opt-in       |        ❌        |
+| ***Beyond querying***             |                        |                       |                  |
+| Logical replication               |           ✅           |   🟡 <sup>19</sup>    |        ✅        |
+| Large object API                  |           ✅           |          ❌           |        ✅        |
+| Native libpq bindings             |           ❌           |   🟡 <sup>20</sup>    |        ❌        |
+
+- <sup>1</sup> What it takes to reach the feature set above. PostgreJS and postgres.js ship everything in the one
+  package you import; `pg` needs `pg-cursor` for cursors, `pg-query-stream`
+  for row streams and `pg-copy-streams` for COPY, each installed and versioned separately.
+- <sup>2</sup> Types come from the separate `@types/pg`; only the `pg-protocol` and
+  `pg-connection-string` sub-packages are written in TypeScript.
+- <sup>3</sup> Ships a hand-maintained `.d.ts`.
+- <sup>4</sup> Results only - parameters are always stringified. Opt-in per query or per client, and all columns at
+  once. No binary parser is registered for `bytea`, and binary arrays decode only `int4`, `int8` and `text` elements.
+- <sup>5</sup> Both format-code counts are hardcoded to zero and parameters are stringified, so everything on the wire
+  is text.
+- <sup>6</sup> Global or per-client (pg) and per-instance (postgres.js), but not per query.
+- <sup>7</sup> Connection-level timeouts only.
+- <sup>8</sup> Restored by calling `Error.captureStackTrace` from the promise's own rejection handler, where the
+  synchronous stack is already gone - the caller's frames come from Node's async stack traces, so they survive an
+  awaited chain but not a `.then()`/`.catch()` one, and the callback API gets none at all.
+- <sup>9</sup> Captured at the tagged template, four frames deep; `sql.unsafe()` gets none.
+- <sup>10</sup> A `types` array on the query config does reach the Parse message, but the same field doubles as the
+  result parser override, so any row-returning query throws inside pg's own handler. Verified usable only for statements
+  that return no rows (pg 8.23.0).
+- <sup>11</sup> Core has the row-limit primitive; the cursor and stream APIs are separate packages.
+- <sup>12</sup> The core `Query` refuses COPY IN; `pg-copy-streams` is required.
+- <sup>13</sup> `sql.prepare(name)` runs `PREPARE TRANSACTION` inside `begin`, but there is no helper for the other
+  half - `COMMIT PREPARED` / `ROLLBACK PREPARED` have to be written as raw SQL.
+- <sup>14</sup> `end()` destroys the socket when a query is still in flight, so the query is aborted rather than
+  awaited; only a client in pipeline mode waits for drain first.
+- <sup>15</sup> On the client only - the pool does not forward notifications.
+- <sup>16</sup> pg has no per-OID text encoders: a parameter is converted by its
+  JavaScript type rather than by the type it is going into, so there is no
+  count to give.
+- <sup>17</sup> Plus every array type, whose OIDs are read from the catalog when a
+  connection opens rather than registered ahead of time.
+- <sup>18</sup> Its binary array decoder covers only `int4`, `int8` and `text` elements, so everything else falls back to
+  text anyway.
+- <sup>19</sup> A connection flag exists, but nothing decodes the stream.
+- <sup>20</sup> `pg-native` swaps the pure JavaScript protocol for libpq, and its own
+  documentation lists what stops working with it: `pg-cursor`, `pg-query-stream` and
+  `pg-copy-streams` all "operate directly on the binary stream and therefore are
+  incompatible" - so server-side cursors, row streaming and COPY are what it costs.
+
+
+## Benchmarks
+
+PostgreJS implements the full PostgreSQL wire protocol from scratch, with no dependency on `pg`/libpq.
+[`doc/BENCHMARKS.md`](doc/BENCHMARKS.md) compares it against `pg` (node-postgres) and `postgres` (postgres.js)
+across connection setup, simple/prepared queries, mixed-type decoding, bulk fetches, cursor streaming and pool
+concurrency, each library run through its own idiomatic fast path. The numbers there are reproducible on your own
+machine via `npm run bench` against the repo's own
+`docker/docker-compose.yml` Postgres instance; see [`benchmark/README.md`](./benchmark/README.md) for details.
 
-for (let i = 0; i < 100; i++) {
-    await statement.execute({params: [i, ('name' + i)]});
-}
-await statement.close(); // When you done, close the statement to relase resources
-```
+## Support
 
-#### Check [DOCUMENTATION](https://postgrejs.panates.com/) for other examples.
-
-
-
-## Type mappings
-The table below lists builtin data type mappings.
-
-| PosgtreSQL type | JS type     | Receive     | Send   | 
-|-----------------|:------------|-------------|--------|
-| bool            | boolean     | text,binary | binary | 
-| int2            | number      | text,binary | binary | 
-| int4            | number      | text,binary | binary | 
-| int8            | BigInt      | text,binary | binary | 
-| float4          | number      | text,binary | binary | 
-| float8          | number      | text,binary | binary | 
-| char            | string      | text,binary | binary | 
-| bpchar          | string      | text,binary | binary | 
-| varchar         | string      | text,binary | binary | 
-| date            | Date        | text,binary | binary | 
-| time            | Date        | text,binary | binary | 
-| timestamp       | Date        | text,binary | binary | 
-| timestamptz     | Date        | text,binary | binary | 
-| oid             | number      | text,binary | binary | 
-| bytea           | Buffer      | text,binary | binary | 
-| uuid            | string      | text,binary | binary | 
-| json            | object      | text,binary | binary | 
-| jsonb           | object      | text,binary | binary | 
-| xml             | string      | text,binary | binary | 
-| point           | Point       | text,binary | binary | 
-| circle          | Circle      | text,binary | binary | 
-| lseg            | Rectangle   | text,binary | binary | 
-| box             | Rectangle   | text,binary | binary | 
-| int2Vector      | number[]    | text,binary | binary | 
-| _bool           | boolean[]   | text,binary | binary | 
-| _int2           | number[]    | text,binary | binary | 
-| _int4           | number[]    | text,binary | binary | 
-| _int8           | BigInt[]    | text,binary | binary | 
-| _float4         | number[]    | text,binary | binary | 
-| _float8         | number[]    | text,binary | binary | 
-| _char           | string[]    | text,binary | binary | 
-| _bpchar         | string[]    | text,binary | binary | 
-| _varchar        | string[]    | text,binary | binary | 
-| _date           | Date[]      | text,binary | binary | 
-| _time           | Date[]      | text,binary | binary | 
-| _timestamp      | Date[]      | text,binary | binary | 
-| _timestamptz    | Date[]      | text,binary | binary | 
-| _uuid           | string[]    | text,binary | binary | 
-| _oid            | number[]    | text,binary | binary | 
-| _bytea          | Buffer[]    | text,binary | binary | 
-| _json           | object[]    | text,binary | binary | 
-| _jsonb          | object[]    | text,binary | binary | 
-| _xml            | string[]    | text,binary | binary | 
-| _point          | Point[]     | text,binary | binary | 
-| _circle         | Circle[]    | text,binary | binary | 
-| _lseg           | Rectangle[] | text,binary | binary | 
-| _box            | Rectangle[] | text,binary | binary | 
-| _int2Vector     | number[][]  | text,binary | binary | 
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/postgrejs/issues) page When
+you open an issue please provide version of NodeJS and PostgreSQL server.
 
+## Node Compatibility
 
-## Support
-You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/postgrejs/issues) page
-When you open an issue please provide version of NodeJS and PostgreSQL server.
+- node >= 20.x
 
-## Node Compatibility
-- node >= 16.x
- 
-  
 ## License
-PostgreJS is available under [MIT](LICENSE) license.
+
+PostgreJS is available under the [BSD 3-Clause](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/postgrejs
 [npm-url]: https://npmjs.org/package/postgrejs
+[downloads-image]: https://img.shields.io/npm/dm/postgrejs.svg
+[downloads-url]: https://npmjs.org/package/postgrejs
 [ci-test-image]: https://github.com/panates/postgrejs/actions/workflows/test.yml/badge.svg
 [ci-test-url]: https://github.com/panates/postgrejs/actions/workflows/test.yml
 [coveralls-image]: https://img.shields.io/coveralls/panates/postgrejs/master.svg
 [coveralls-url]: https://coveralls.io/r/panates/postgrejs
-[downloads-image]: https://img.shields.io/npm/dm/postgrejs.svg
-[downloads-url]: https://npmjs.org/package/postgrejs
-[gitter-image]: https://badges.gitter.im/panates/postgrejs.svg
-[gitter-url]: https://gitter.im/panates/postgrejs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-[dependencies-image]: https://david-dm.org/panates/postgrejs/status.svg
-[dependencies-url]:https://david-dm.org/panates/postgrejs
-[devdependencies-image]: https://david-dm.org/panates/postgrejs/dev-status.svg
-[devdependencies-url]:https://david-dm.org/panates/postgrejs?type=dev
-[quality-image]: http://npm.packagequality.com/shield/postgrejs.png
-[quality-url]: http://packagequality.com/#?package=postgrejs