Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Parser
✓ import { Parser } from 'pg-protocol';
✗ const Parser = require('pg-protocol').Parser;
Primarily used for processing incoming PostgreSQL wire protocol buffers from the server. CommonJS `require` syntax is generally discouraged in modern TypeScript/ESM projects.
Serializer
✓ import { Serializer } from 'pg-protocol';
✗ const { Serializer } = require('pg-protocol');
Used for constructing outgoing PostgreSQL wire protocol messages to the server. Prefer ESM named imports.
Message
✓ import type { Message } from 'pg-protocol';
Importing types like `Message` should use `import type` for clarity and to ensure they are stripped from the JavaScript output, avoiding accidental runtime imports.
Query
✓ import { Query } from 'pg-protocol/dist/messages';
Specific message classes like `Query` might be nested within submodules or the `dist/messages` path, depending on the exact package structure. Refer to type definitions for precise paths.
Demonstrates how to initialize the Parser to consume an incoming PostgreSQL `ReadyForQuery` message and how to use the Serializer to create an outgoing SQL `Query` message buffer. This highlights the low-level parsing and serialization capabilities.
import { Parser, Serializer } from 'pg-protocol';
import { Query, ReadyForQueryMessage, BackendMessageCode } from 'pg-protocol/dist/messages';
// 1. Simulate an incoming 'ReadyForQuery' message from the server
// (Type 'Z' for ReadyForQuery, length, transaction status 'I' for idle)
const readyForQueryBuffer = Buffer.from([BackendMessageCode.ReadyForQuery, 0, 0, 0, 5, 'I'.charCodeAt(0)]);
const parser = new Parser();
parser.parse(readyForQueryBuffer);
// In a real scenario, you'd listen to 'message' events
// For this example, we'll manually check the parsed queue
let parsedMessage: ReadyForQueryMessage | undefined;
while (true) {
const msg = parser.shift();
if (msg) {
if (msg.name === 'ReadyForQuery') {
parsedMessage = msg as ReadyForQueryMessage;
console.log(`Parsed ReadyForQuery: Transaction Status = ${parsedMessage.transactionStatus}`);
break;
}
} else {
break;
}
}
if (!parsedMessage) {
console.error('Failed to parse ReadyForQuery message.');
}
// 2. Serialize an outgoing 'Query' message to the server
const query = 'SELECT 1 + 1 AS solution;';
const serializer = new Serializer();
// The Query message expects a string and can be serialized directly
const queryMessage = new Query(query);
const serializedBuffer = serializer.query(query);
console.log(`
Original Query: ${query}`);
console.log('Serialized Query Buffer (first 20 bytes):', serializedBuffer.toString('hex').substring(0, 40), '...');
console.log(`Buffer length: ${serializedBuffer.length} bytes`);
// Example: Basic structure of a 'Query' message buffer
// Message type 'Q', then length including length itself, then query string + null terminator
const expectedHeader = Buffer.from([0x51, 0x00, 0x00, 0x00, (query.length + 5) >> 8, 0x00, 0x00, 0x00, (query.length + 5) & 0xFF]);
// Note: Actual serialization includes the string and null terminator.
// This is a simplified check.
Debug
Known issues
gotchapg-protocol is primarily an internal module of the `node-postgres` ecosystem. Its API is low-level and not designed for direct public consumption. Using it directly may expose you to internal changes that are not considered breaking within `node-postgres`'s public API, but could break your direct usage.fixUnless building a custom PostgreSQL client or proxy, prefer using the higher-level `pg` package which wraps `pg-protocol` and provides a stable, documented API.
affects: >=1.0.0
breakingWith `node-postgres` v8.x (which utilizes `pg-protocol` internally), the default behavior for SSL connections changed. Previously, `rejectUnauthorized` defaulted to `false`, allowing self-signed certificates without explicit configuration. It now defaults to `true` for improved security.fixIf connecting to a PostgreSQL server with a self-signed certificate, explicitly set `{ ssl: { rejectUnauthorized: false } }` in your `pg.Client` or `pg.Pool` configuration. Alternatively, provide a valid CA certificate. affects: pg@>=8.0.0 (internal impact on pg-protocol consumers)
gotchaPostgreSQL 18 introduces Wire Protocol 3.2, which includes enhanced security features like 256-bit cancel request keys. While `pg-protocol` aims to support new protocol features, adopting them requires updates to both the client (e.g., `node-postgres`) and the server. Older clients or `pg-protocol` versions might not fully utilize newer protocol features.fixMonitor `node-postgres` releases for explicit support of new PostgreSQL wire protocol versions. Ensure your `pg-protocol` version (via `node-postgres`) is updated to match new server capabilities if you need to leverage them.
affects: >=1.0.0 (impacted by server updates)
Errors
Common errors & fixes
Cannot find module 'pg-protocol' or its corresponding type declarations.
The `pg-protocol` package is not installed, or the import path is incorrect, especially if trying to import specific nested modules.
fixEnsure `pg-protocol` is installed via `npm install pg-protocol` or `yarn add pg-protocol`. If importing specific sub-paths (e.g., for messages), verify the exact path from the package's type definitions or source.
TypeError: Serializer.query is not a function
Attempting to call a method that doesn't exist or using an outdated API, potentially due to `pg-protocol`'s internal nature and API instability for direct consumers.
fixConsult the `pg-protocol` source code or TypeScript declarations for the exact methods and their signatures available in your installed version. The internal API might change more frequently than `node-postgres`'s public API. Ensure you are importing the correct class (e.g., `Serializer`) and using its methods as defined in the current version.
Audit
Dependencies
No dependency data recorded yet.