or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmessages.mdparsing.mdserialization.md
tile.json

tessl/npm-pg-protocol

The postgres client/server binary protocol, implemented in TypeScript

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pg-protocol@1.10.x

To install, run

npx @tessl/cli install tessl/npm-pg-protocol@1.10.0

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 parse function provides streaming protocol parsing with an internal Parser class
  • Message Serialization: The serialize object contains functions for creating all protocol message types
  • Message Types: Comprehensive TypeScript types and classes for all PostgreSQL protocol messages
  • Error Handling: Specialized DatabaseError class 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;

Protocol Parsing

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;
}

Message Serialization

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
}

Protocol Messages

Types

Core Types

type Mode = 'text' | 'binary';

type ValueMapper = (param: any, index: number) => any;

interface ExecOpts {
  portal?: string;
  rows?: number;
}