tessl/npm-pg-protocol
The postgres client/server binary protocol, implemented in TypeScript
—
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
index.mddocs/
pg-protocol
pg-protocol is a low-level TypeScript library that implements the PostgreSQL client/server binary protocol. It provides streaming parsing capabilities and message serialization utilities that serve as the foundation for higher-level PostgreSQL client libraries in the node-postgres ecosystem.
Package Information
- Package Name: pg-protocol
- Package Type: npm
- Language: TypeScript
- Installation:
npm install pg-protocol
Core Imports
import { parse, serialize, DatabaseError } from "pg-protocol";For CommonJS:
const { parse, serialize, DatabaseError } = require("pg-protocol");Basic Usage
import { parse, serialize, DatabaseError } from "pg-protocol";
import { Readable } from "stream";
// Parse incoming protocol data from a stream
const callback = (message) => {
console.log('Received message:', message.name);
if (message.name === 'error') {
console.error('Database error:', message);
}
};
// Example with a readable stream containing protocol data
const stream = new Readable();
parse(stream, callback);
// Serialize outbound messages for sending to PostgreSQL server
const queryBuffer = serialize.query("SELECT * FROM users WHERE name = 'john'");
const parseBuffer = serialize.parse({ text: "SELECT * FROM users WHERE id = $1" });
const bindBuffer = serialize.bind({ values: [25] });
const executeBuffer = serialize.execute();Architecture
pg-protocol is designed around several key components:
- Stream Parser: The
parsefunction provides streaming protocol parsing with an internalParserclass - Message Serialization: The
serializeobject contains functions for creating all protocol message types - Message Types: Comprehensive TypeScript types and classes for all PostgreSQL protocol messages
- Error Handling: Specialized
DatabaseErrorclass with detailed PostgreSQL error information
Capabilities
Protocol Parsing
Stream-based parsing of PostgreSQL wire protocol messages with callback-based message handling. Supports the complete PostgreSQL protocol specification.
function parse(
stream: NodeJS.ReadableStream,
callback: MessageCallback
): Promise<void>;
type MessageCallback = (msg: BackendMessage) => void;Message Serialization
Complete set of functions for creating PostgreSQL protocol messages. Covers authentication, queries, prepared statements, and administrative operations.
const serialize: {
startup(opts: Record<string, string>): Buffer;
query(text: string): Buffer;
parse(query: ParseOpts): Buffer;
bind(config?: BindOpts): Buffer;
execute(config?: ExecOpts): Buffer;
// ... additional serialization functions
};
interface ParseOpts {
name?: string;
types?: number[];
text: string;
}
interface BindOpts {
portal?: string;
binary?: boolean;
statement?: string;
values?: any[];
valueMapper?: ValueMapper;
}Protocol Messages
Comprehensive TypeScript types and classes representing all PostgreSQL protocol messages, from authentication to data transfer.
interface BackendMessage {
name: MessageName;
length: number;
}
type MessageName =
| 'parseComplete' | 'bindComplete' | 'closeComplete'
| 'dataRow' | 'commandComplete' | 'readyForQuery'
| 'error' | 'notice' | 'authenticationOk'
// ... additional message types
class DatabaseError extends Error {
severity?: string;
code?: string;
detail?: string;
hint?: string;
// ... additional error fields
}Types
Core Types
type Mode = 'text' | 'binary';
type ValueMapper = (param: any, index: number) => any;
interface ExecOpts {
portal?: string;
rows?: number;
}