tessl/npm-pg-protocol

The postgres client/server binary protocol, implemented in TypeScript

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Message Serialization

Name: tessl/npm-pg-protocol
Author: tessl

Complete set of functions for creating PostgreSQL protocol messages. All serialization functions return Buffer objects ready for transmission over the wire.

Capabilities

Connection Management

Functions for establishing and managing PostgreSQL connections.

/**
 * Create connection startup message
 * @param opts - Connection parameters (user, database, etc.)
 * @returns Buffer containing startup message
 */
function startup(opts: Record<string, string>): Buffer;

/**
 * Create SSL connection request
 * @returns Buffer containing SSL request
 */
function requestSsl(): Buffer;

/**
 * Create connection termination message
 * @returns Buffer containing termination message
 */
function end(): Buffer;

Usage Examples:

import { serialize } from "pg-protocol";

// Connection startup
const startupBuffer = serialize.startup({
  user: 'postgres',
  database: 'mydb'
});

// SSL request
const sslBuffer = serialize.requestSsl();

// Connection termination
const endBuffer = serialize.end();

Authentication

Functions for handling various PostgreSQL authentication methods.

/**
 * Create password authentication response
 * @param password - Password string
 * @returns Buffer containing password message
 */
function password(password: string): Buffer;

/**
 * Create SASL initial response message
 * @param mechanism - SASL mechanism name
 * @param initialResponse - Initial response data
 * @returns Buffer containing SASL response
 */
function sendSASLInitialResponseMessage(
  mechanism: string, 
  initialResponse: string
): Buffer;

/**
 * Create SCRAM client final message
 * @param additionalData - Additional SCRAM data
 * @returns Buffer containing SCRAM final message
 */
function sendSCRAMClientFinalMessage(additionalData: string): Buffer;

Query Execution

Functions for executing queries and managing query results.

/**
 * Create simple query message
 * @param text - SQL query text
 * @returns Buffer containing query message
 */
function query(text: string): Buffer;

/**
 * Create flush message to force server response
 * @returns Buffer containing flush message
 */
function flush(): Buffer;

/**
 * Create sync message to complete transaction
 * @returns Buffer containing sync message
 */
function sync(): Buffer;

Usage Examples:

// Simple query
const queryBuffer = serialize.query("SELECT * FROM users WHERE id = $1");

// Force flush
const flushBuffer = serialize.flush();

// Transaction sync
const syncBuffer = serialize.sync();

Prepared Statements

Functions for managing prepared statements with parameters.

/**
 * Create parse message for prepared statements
 * @param query - Query options including text and types
 * @returns Buffer containing parse message
 */
function parse(query: ParseOpts): Buffer;

interface ParseOpts {
  /** Optional statement name */
  name?: string;
  /** Optional parameter type OIDs */
  types?: number[];
  /** SQL query text */
  text: string;
}

/**
 * Create bind message for parameter binding
 * @param config - Binding configuration
 * @returns Buffer containing bind message
 */
function bind(config?: BindOpts): Buffer;

interface BindOpts {
  /** Portal name (default: '') */
  portal?: string;
  /** Use binary format (default: false) */
  binary?: boolean;
  /** Statement name (default: '') */
  statement?: string;
  /** Parameter values */
  values?: any[];
  /** Optional value transformation function */
  valueMapper?: ValueMapper;
}

/**
 * Create execute message for portal execution
 * @param config - Execution configuration
 * @returns Buffer containing execute message
 */
function execute(config?: ExecOpts): Buffer;

interface ExecOpts {
  /** Portal name (default: '') */
  portal?: string;
  /** Maximum rows to return (default: 0 = all) */
  rows?: number;
}

Usage Examples:

// Parse a prepared statement
const parseBuffer = serialize.parse({
  name: 'get_user',
  text: 'SELECT * FROM users WHERE id = $1',
  types: [23] // INT4 type
});

// Bind parameters
const bindBuffer = serialize.bind({
  statement: 'get_user',
  values: [123]
});

// Execute the statement
const executeBuffer = serialize.execute({
  portal: '',
  rows: 10
});

Portal and Statement Management

Functions for managing portals and prepared statements.

/**
 * Create describe message for portals or statements
 * @param msg - Portal options
 * @returns Buffer containing describe message
 */
function describe(msg: PortalOpts): Buffer;

/**
 * Create close message for portals or statements
 * @param msg - Portal options
 * @returns Buffer containing close message
 */
function close(msg: PortalOpts): Buffer;

interface PortalOpts {
  /** Type: 'S' for statement, 'P' for portal */
  type: 'S' | 'P';
  /** Optional name */
  name?: string;
}

Copy Protocol

Functions for handling PostgreSQL COPY operations.

/**
 * Create copy data message
 * @param chunk - Data chunk to copy
 * @returns Buffer containing copy data message
 */
function copyData(chunk: Buffer): Buffer;

/**
 * Create copy done message
 * @returns Buffer containing copy done message
 */
function copyDone(): Buffer;

/**
 * Create copy fail message
 * @param message - Error message
 * @returns Buffer containing copy fail message
 */
function copyFail(message: string): Buffer;

Administrative Operations

Functions for administrative and control operations.

/**
 * Create query cancellation message
 * @param processID - Backend process ID
 * @param secretKey - Secret key from BackendKeyData
 * @returns Buffer containing cancel message
 */
function cancel(processID: number, secretKey: number): Buffer;

Value Mapping

The bind function supports custom value transformation via the valueMapper parameter:

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

Usage Example:

const bindBuffer = serialize.bind({
  values: [new Date(), 'text', null],
  valueMapper: (value, index) => {
    if (value instanceof Date) {
      return value.toISOString();
    }
    return value;
  }
});