Dev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug report
-about: Create a report to help us improve
+about: Report unexpected or incorrect behavior
 title: ''
 labels: ''
 assignees: ''
@@ -11,28 +11,30 @@ assignees: ''
 A clear and concise description of what the bug is.
 
 **To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+A minimal, self-contained code snippet that reproduces the issue - the
+connection options used (redact any password/host you don't want public)
+and the query or API calls involved.
 
-**Expected behavior**
-A clear and concise description of what you expected to happen.
+```ts
+// e.g.
+const connection = new Connection({ host: 'localhost', database: 'test' });
+await connection.connect();
+const result = await connection.query('select 1');
+```
 
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
+**Expected behavior**
+What you expected to happen.
 
-**Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+**Actual behavior**
+What actually happened - include the full error message and stack trace,
+or the incorrect value returned, if applicable.
 
-**Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+**Environment**
+ - PostgreJS version: [e.g. 3.0.0]
+ - Node.js version: [e.g. 22.1.0]
+ - PostgreSQL version and provider: [e.g. PostgreSQL 16, self-hosted / RDS / Supabase / ...]
+ - OS: [e.g. Ubuntu 22.04]
 
 **Additional context**
-Add any other context about the problem here.
+Anything else relevant - connection pooling, SSL/TLS settings, whether it
+reproduces consistently or intermittently, etc.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -8,13 +8,22 @@ assignees: ''
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. Ex. I'm always
+frustrated when [...]
 
 **Describe the solution you'd like**
-A clear and concise description of what you want to happen.
+A clear and concise description of what you want to happen - what would
+the API look like (a new option, method, or type), and how would it be
+used?
+
+```ts
+// e.g. a sketch of the API you have in mind
+```
 
 **Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
+Other ways to solve the same problem, including workarounds you're using
+today, and why they fall short.
 
 **Additional context**
-Add any other context or screenshots about the feature request here.
+Anything else relevant - links to the PostgreSQL protocol/feature docs
+this depends on, or how other drivers handle it, for instance.

.github/workflows/test.yml

@@ -18,7 +18,7 @@ on:
       - support/**/*.*
       - .mocharc.cjs
       - .c8rc.json
-      - tsconfig*.json
+      - /tsconfig*.json
 
 # Only one run per branch at a time
 concurrency:
@@ -43,8 +43,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: [ '20', '22', '23', '24' ]
-        postgres: [ '12', '14', '16', '17' ]
+        node: [ '20', '22', '24', '26' ]
+        postgres: [ '12', '16', '18' ]
     runs-on: ubuntu-latest
     timeout-minutes: 15
     services:

.gitignore

@@ -2,6 +2,9 @@ node_modules
 /build
 /examples/*/package-lock.json
 *.tsbuildinfo
+.claude
+graphify-out
+/test-*
 
 # environment variables
 .env
@@ -23,6 +26,9 @@ lerna-debug.log*
 /reports
 /.nyc_output
 
+# Benchmarks
+/benchmark/results
+
 # IDEs and editors
 /.idea
 .project

.run/cli.ts.run.xml

@@ -0,0 +1,5 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="cli.ts" type="NodeJSConfigurationType" application-parameters="-s simple-query-execute*" nameIsGenerated="true" node-parameters="--import @swc-node/register/esm-register" path-to-js-file="cli.ts" working-dir="$PROJECT_DIR$/benchmark">
+    <method v="2" />
+  </configuration>
+</component>

CHANGELOG.md

@@ -1,6 +1,157 @@
 ## Changelog
 
-### [v2.23.1](https://github.com/panates/postgrejs/compare/v2.23.0...v2.23.1) - 
+### [v3.0.1](https://github.com/panates/postgrejs/compare/v3.0.0...v3.0.1) - 
+
+- 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
 

CLAUDE.md

@@ -0,0 +1,97 @@
+## Project Orientation
+
+`postgrejs` is a from-scratch PostgreSQL wire-protocol client for Node.js/TypeScript - no `libpq`, no native
+bindings. See README.md's "Why PostgreJS?" section for the pitch and `doc/BENCHMARKS.md` for performance data
+against `pg` and `postgres.js`.
+
+Directory layout:
+
+- `src/protocol/` - the wire protocol itself: `Backend`/`Frontend` message codecs, `PgSocket` (the connected
+  socket plus auth/TLS negotiation), `SmartBuffer`/`BufferReader`.
+- `src/connection/` - the public-facing layer: `Connection`, `Pool`, `IntlConnection` (the shared internals
+  `Connection`/`Pool` both wrap), `Cursor`, `PreparedStatement`, `Portal`, `CopyToStream`/`CopyFromStream`,
+  `LogicalReplication`, `LargeObject`.
+- `src/data-types/` - one file per PostgreSQL type, each exporting a scalar `DataType` and its array counterpart
+  (`encodeBinary`/`decodeBinary`/`encodeText`/`decodeText`/`isType`, registered in `data-type-map.ts`).
+- `src/util/` - parsing/encoding helpers used across the above (array literals, dates, buffers, etc).
+
+Tests mirror this in `test/`:
+
+- `test/A-common/` - pure unit tests, no live connection. Prefer this whenever the code under test doesn't
+  actually need a socket: build the wire bytes/fake dependency by hand rather than reaching for a live server.
+- `test/B-connection/` - integration tests against a real local PostgreSQL (`docker/docker-compose.yml`; see
+  CONTRIBUTING.md for the SCRAM/MD5 setup needed for full coverage locally).
+- `test/C-data-types/` - one file per data type, round-tripping values through a live connection via
+  `_testers.ts`'s `testParse`/`testEncode`.
+
+Every change must come with a test, and the code it touches must be covered - see CONTRIBUTING.md for the full
+contributor workflow (lint/compile/test commands, commit message convention, PR checklist).
+
+## Testing Techniques
+
+- **Coverage tool is `c8`, not istanbul.** Use `/* c8 ignore next */` or `/* c8 ignore start */` ... `/* c8 ignore
+  stop */` - `/* istanbul ignore next */` is silently not honored here. Even correctly-placed `c8 ignore` comments
+  have occasionally been observed not to suppress branch-level reporting on a single line with a ternary/`&&`
+  chain; if the coverage number doesn't move after adding one, don't fight it further - just leave a plain
+  explanatory comment instead of an ignore directive that isn't doing anything.
+- **Classes that wrap a socket/connection** (`CopyToStream`, `CopyFromStream`, `LogicalReplication`, `PgSocket`)
+  are best unit-tested directly against a fake stub object (`pause`/`resume`/`sendCopyData`/`execute`/etc. as
+  plain functions recording calls) rather than racing real server timing to hit backpressure, mid-stream errors,
+  or a dead socket - those are reproducible instantly with a fake and flaky against a real one.
+- **PostgreSQL version-gated behavior** must self-skip in CI's matrix (PostgreSQL 12/16/18 - see
+  `.github/workflows/test.yml`): check `connection.sessionParameters.server_version` and call `this.skip()` from
+  a `function () {}` test callback (not an arrow function - `this` binding is required). Known gates already hit:
+  `numeric` Infinity/-Infinity needs PG 14+, direct TLS negotiation needs PG 17+.
+- **Before assuming a branch is unreachable**, reason through the actual call sites rather than guessing - it's
+  easy to be wrong in both directions (a branch that looks defensive can be reachable through a caller you
+  haven't checked yet, and vice versa).
+- Dead code (an exported method with zero callers anywhere in `src/`) should be confirmed via
+  `grep -rn '\.methodName(' src/` and removed rather than tested, unless it's plausibly part of the public API
+  surface a consumer could rely on.
+
+## Working in this repo
+
+- Run `git status` before staging/committing. The user works concurrently in their own terminal on this same
+  repo sometimes (e.g. local docker setup files) - `git add <specific files>` still commits whatever else is
+  already sitting in the index, so an unrelated in-progress change can end up folded into your commit if you
+  don't check first.
+- Don't run the full benchmark suite (`npm run bench`) unless asked.
+
+## Code style
+
+### Class member order
+
+Declare members in this order, with non-public ones always at the bottom rather than next to the code that uses them:
+
+1. Properties (private, protected, public order)
+2. Constructor
+3. Getters / setters
+4. Public methods
+5. Protected methods
+6. Private methods
+
+Prefer `protected` over `private`. Use `private` only when a member genuinely must not be reachable by a subclass — `Connection`, `Pool` and `IntlConnection` extend and wrap each other, so sealing a member closes off a real extension point.
+
+### Loops
+
+Hoist loop-invariant work out of the loop condition and body — `for (let i = 0; i < obj.length; i++)` re-reads the property on every iteration. V8 can only hoist it when the value is a plain array field and the body calls nothing opaque; anything behind a getter (`BufferReader.length`, `SmartBuffer.length`) or any body that calls a parser/decoder blocks that, which is most of this codebase's hot loops. Read it once into a local first:
+
+```ts
+const l = arr.length;
+let i: number;
+for (i = 0; i < l; i++) { ... }
+```
+
+The same applies to conditions that don't depend on the loop variable (`level < dim.length - 1`) — lift the whole comparison, not just the property read.
+
+Declaring `let x` inside the loop body costs nothing when no closure captures it, so keep it scoped there; hoisting it only matters when a closure does capture it, and then hoisting would change behaviour anyway.
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-colinmcd94@gmail.com or scott@scotttrinh.com.
+info@panates.com.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the