0
# pg-protocol
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: pg-protocol
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pg-protocol`
10
11
## Core Imports
12
13
```typescript
14
import { parse, serialize, DatabaseError } from "pg-protocol";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { parse, serialize, DatabaseError } = require("pg-protocol");
21
```
22
23
## Basic Usage
24
25
```typescript
26
import { parse, serialize, DatabaseError } from "pg-protocol";
27
import { Readable } from "stream";
28
29
// Parse incoming protocol data from a stream
30
const callback = (message) => {
31
console.log('Received message:', message.name);
32
if (message.name === 'error') {
33
console.error('Database error:', message);
34
}
35
};
36
37
// Example with a readable stream containing protocol data
38
const stream = new Readable();
39
parse(stream, callback);
40
41
// Serialize outbound messages for sending to PostgreSQL server
42
const queryBuffer = serialize.query("SELECT * FROM users WHERE name = 'john'");
43
const parseBuffer = serialize.parse({ text: "SELECT * FROM users WHERE id = $1" });
44
const bindBuffer = serialize.bind({ values: [25] });
45
const executeBuffer = serialize.execute();
46
```
47
48
## Architecture
49
50
pg-protocol is designed around several key components:
51
52
- **Stream Parser**: The `parse` function provides streaming protocol parsing with an internal `Parser` class
53
- **Message Serialization**: The `serialize` object contains functions for creating all protocol message types
54
- **Message Types**: Comprehensive TypeScript types and classes for all PostgreSQL protocol messages
55
- **Error Handling**: Specialized `DatabaseError` class with detailed PostgreSQL error information
56
57
## Capabilities
58
59
### Protocol Parsing
60
61
Stream-based parsing of PostgreSQL wire protocol messages with callback-based message handling. Supports the complete PostgreSQL protocol specification.
62
63
```typescript { .api }
64
function parse(
65
stream: NodeJS.ReadableStream,
66
callback: MessageCallback
67
): Promise<void>;
68
69
type MessageCallback = (msg: BackendMessage) => void;
70
```
71
72
[Protocol Parsing](./parsing.md)
73
74
### Message Serialization
75
76
Complete set of functions for creating PostgreSQL protocol messages. Covers authentication, queries, prepared statements, and administrative operations.
77
78
```typescript { .api }
79
const serialize: {
80
startup(opts: Record<string, string>): Buffer;
81
query(text: string): Buffer;
82
parse(query: ParseOpts): Buffer;
83
bind(config?: BindOpts): Buffer;
84
execute(config?: ExecOpts): Buffer;
85
// ... additional serialization functions
86
};
87
88
interface ParseOpts {
89
name?: string;
90
types?: number[];
91
text: string;
92
}
93
94
interface BindOpts {
95
portal?: string;
96
binary?: boolean;
97
statement?: string;
98
values?: any[];
99
valueMapper?: ValueMapper;
100
}
101
```
102
103
[Message Serialization](./serialization.md)
104
105
### Protocol Messages
106
107
Comprehensive TypeScript types and classes representing all PostgreSQL protocol messages, from authentication to data transfer.
108
109
```typescript { .api }
110
interface BackendMessage {
111
name: MessageName;
112
length: number;
113
}
114
115
type MessageName =
116
| 'parseComplete' | 'bindComplete' | 'closeComplete'
117
| 'dataRow' | 'commandComplete' | 'readyForQuery'
118
| 'error' | 'notice' | 'authenticationOk'
119
// ... additional message types
120
121
class DatabaseError extends Error {
122
severity?: string;
123
code?: string;
124
detail?: string;
125
hint?: string;
126
// ... additional error fields
127
}
128
```
129
130
[Protocol Messages](./messages.md)
131
132
## Types
133
134
### Core Types
135
136
```typescript { .api }
137
type Mode = 'text' | 'binary';
138
139
type ValueMapper = (param: any, index: number) => any;
140
141
interface ExecOpts {
142
portal?: string;
143
rows?: number;
144
}
145
```