0
# Message Serialization
1

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

4
## Capabilities
5

6
### Connection Management
7

8
Functions for establishing and managing PostgreSQL connections.
9

10
```typescript { .api }
11
/**
12
 * Create connection startup message
13
 * @param opts - Connection parameters (user, database, etc.)
14
 * @returns Buffer containing startup message
15
 */
16
function startup(opts: Record<string, string>): Buffer;
17

18
/**
19
 * Create SSL connection request
20
 * @returns Buffer containing SSL request
21
 */
22
function requestSsl(): Buffer;
23

24
/**
25
 * Create connection termination message
26
 * @returns Buffer containing termination message
27
 */
28
function end(): Buffer;
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import { serialize } from "pg-protocol";
35

36
// Connection startup
37
const startupBuffer = serialize.startup({
38
  user: 'postgres',
39
  database: 'mydb'
40
});
41

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

45
// Connection termination
46
const endBuffer = serialize.end();
47
```
48

49
### Authentication
50

51
Functions for handling various PostgreSQL authentication methods.
52

53
```typescript { .api }
54
/**
55
 * Create password authentication response
56
 * @param password - Password string
57
 * @returns Buffer containing password message
58
 */
59
function password(password: string): Buffer;
60

61
/**
62
 * Create SASL initial response message
63
 * @param mechanism - SASL mechanism name
64
 * @param initialResponse - Initial response data
65
 * @returns Buffer containing SASL response
66
 */
67
function sendSASLInitialResponseMessage(
68
  mechanism: string, 
69
  initialResponse: string
70
): Buffer;
71

72
/**
73
 * Create SCRAM client final message
74
 * @param additionalData - Additional SCRAM data
75
 * @returns Buffer containing SCRAM final message
76
 */
77
function sendSCRAMClientFinalMessage(additionalData: string): Buffer;
78
```
79

80
### Query Execution
81

82
Functions for executing queries and managing query results.
83

84
```typescript { .api }
85
/**
86
 * Create simple query message
87
 * @param text - SQL query text
88
 * @returns Buffer containing query message
89
 */
90
function query(text: string): Buffer;
91

92
/**
93
 * Create flush message to force server response
94
 * @returns Buffer containing flush message
95
 */
96
function flush(): Buffer;
97

98
/**
99
 * Create sync message to complete transaction
100
 * @returns Buffer containing sync message
101
 */
102
function sync(): Buffer;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
// Simple query
109
const queryBuffer = serialize.query("SELECT * FROM users WHERE id = $1");
110

111
// Force flush
112
const flushBuffer = serialize.flush();
113

114
// Transaction sync
115
const syncBuffer = serialize.sync();
116
```
117

118
### Prepared Statements
119

120
Functions for managing prepared statements with parameters.
121

122
```typescript { .api }
123
/**
124
 * Create parse message for prepared statements
125
 * @param query - Query options including text and types
126
 * @returns Buffer containing parse message
127
 */
128
function parse(query: ParseOpts): Buffer;
129

130
interface ParseOpts {
131
  /** Optional statement name */
132
  name?: string;
133
  /** Optional parameter type OIDs */
134
  types?: number[];
135
  /** SQL query text */
136
  text: string;
137
}
138

139
/**
140
 * Create bind message for parameter binding
141
 * @param config - Binding configuration
142
 * @returns Buffer containing bind message
143
 */
144
function bind(config?: BindOpts): Buffer;
145

146
interface BindOpts {
147
  /** Portal name (default: '') */
148
  portal?: string;
149
  /** Use binary format (default: false) */
150
  binary?: boolean;
151
  /** Statement name (default: '') */
152
  statement?: string;
153
  /** Parameter values */
154
  values?: any[];
155
  /** Optional value transformation function */
156
  valueMapper?: ValueMapper;
157
}
158

159
/**
160
 * Create execute message for portal execution
161
 * @param config - Execution configuration
162
 * @returns Buffer containing execute message
163
 */
164
function execute(config?: ExecOpts): Buffer;
165

166
interface ExecOpts {
167
  /** Portal name (default: '') */
168
  portal?: string;
169
  /** Maximum rows to return (default: 0 = all) */
170
  rows?: number;
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
// Parse a prepared statement
178
const parseBuffer = serialize.parse({
179
  name: 'get_user',
180
  text: 'SELECT * FROM users WHERE id = $1',
181
  types: [23] // INT4 type
182
});
183

184
// Bind parameters
185
const bindBuffer = serialize.bind({
186
  statement: 'get_user',
187
  values: [123]
188
});
189

190
// Execute the statement
191
const executeBuffer = serialize.execute({
192
  portal: '',
193
  rows: 10
194
});
195
```
196

197
### Portal and Statement Management
198

199
Functions for managing portals and prepared statements.
200

201
```typescript { .api }
202
/**
203
 * Create describe message for portals or statements
204
 * @param msg - Portal options
205
 * @returns Buffer containing describe message
206
 */
207
function describe(msg: PortalOpts): Buffer;
208

209
/**
210
 * Create close message for portals or statements
211
 * @param msg - Portal options
212
 * @returns Buffer containing close message
213
 */
214
function close(msg: PortalOpts): Buffer;
215

216
interface PortalOpts {
217
  /** Type: 'S' for statement, 'P' for portal */
218
  type: 'S' | 'P';
219
  /** Optional name */
220
  name?: string;
221
}
222
```
223

224
### Copy Protocol
225

226
Functions for handling PostgreSQL COPY operations.
227

228
```typescript { .api }
229
/**
230
 * Create copy data message
231
 * @param chunk - Data chunk to copy
232
 * @returns Buffer containing copy data message
233
 */
234
function copyData(chunk: Buffer): Buffer;
235

236
/**
237
 * Create copy done message
238
 * @returns Buffer containing copy done message
239
 */
240
function copyDone(): Buffer;
241

242
/**
243
 * Create copy fail message
244
 * @param message - Error message
245
 * @returns Buffer containing copy fail message
246
 */
247
function copyFail(message: string): Buffer;
248
```
249

250
### Administrative Operations
251

252
Functions for administrative and control operations.
253

254
```typescript { .api }
255
/**
256
 * Create query cancellation message
257
 * @param processID - Backend process ID
258
 * @param secretKey - Secret key from BackendKeyData
259
 * @returns Buffer containing cancel message
260
 */
261
function cancel(processID: number, secretKey: number): Buffer;
262
```
263

264
## Value Mapping
265

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

268
```typescript { .api }
269
type ValueMapper = (param: any, index: number) => any;
270
```
271

272
**Usage Example:**
273

274
```typescript
275
const bindBuffer = serialize.bind({
276
  values: [new Date(), 'text', null],
277
  valueMapper: (value, index) => {
278
    if (value instanceof Date) {
279
      return value.toISOString();
280
    }
281
    return value;
282
  }
283
});
284
```
285

286
## Buffer Management
287

288
All serialization functions use internal buffer management for optimal performance:
289

290
- Automatic buffer growth during message construction
291
- Efficient binary encoding following PostgreSQL protocol specification
292
- Proper message length calculation and byte order handling