0
# Protocol Messages
1

2
Comprehensive TypeScript types and classes representing all PostgreSQL protocol messages, from authentication to data transfer.
3

4
## Capabilities
5

6
### Base Message Types
7

8
Core interfaces and types used throughout the protocol message system.
9

10
```typescript { .api }
11
/**
12
 * Base interface for all backend protocol messages
13
 */
14
interface BackendMessage {
15
  /** Message type identifier */
16
  name: MessageName;
17
  /** Message length in bytes */
18
  length: number;
19
}
20

21
/**
22
 * Union type of all possible PostgreSQL protocol message names
23
 */
24
type MessageName =
25
  | 'parseComplete' | 'bindComplete' | 'closeComplete'
26
  | 'noData' | 'portalSuspended' | 'replicationStart'
27
  | 'emptyQuery' | 'copyDone' | 'copyData'
28
  | 'rowDescription' | 'parameterDescription'
29
  | 'parameterStatus' | 'backendKeyData' | 'notification'
30
  | 'readyForQuery' | 'commandComplete' | 'dataRow'
31
  | 'copyInResponse' | 'copyOutResponse'
32
  | 'authenticationOk' | 'authenticationMD5Password'
33
  | 'authenticationCleartextPassword' | 'authenticationSASL'
34
  | 'authenticationSASLContinue' | 'authenticationSASLFinal'
35
  | 'error' | 'notice';
36

37
/**
38
 * Data format mode for protocol fields
39
 */
40
type Mode = 'text' | 'binary';
41
```
42

43
### Simple Message Constants
44

45
Pre-built message objects for common protocol responses.
46

47
```typescript { .api }
48
/** Parse operation completed successfully */
49
const parseComplete: BackendMessage;
50

51
/** Bind operation completed successfully */
52
const bindComplete: BackendMessage;
53

54
/** Close operation completed successfully */
55
const closeComplete: BackendMessage;
56

57
/** No data available for portal */
58
const noData: BackendMessage;
59

60
/** Portal execution suspended */
61
const portalSuspended: BackendMessage;
62

63
/** Replication stream started */
64
const replicationStart: BackendMessage;
65

66
/** Empty query executed */
67
const emptyQuery: BackendMessage;
68

69
/** Copy operation completed */
70
const copyDone: BackendMessage;
71
```
72

73
### Error and Notice Handling
74

75
Classes for handling PostgreSQL errors and notices with detailed field information.
76

77
```typescript { .api }
78
/**
79
 * PostgreSQL database error with detailed diagnostic information
80
 */
81
class DatabaseError extends Error {
82
  /** Error severity level */
83
  severity?: string;
84
  /** PostgreSQL error code */
85
  code?: string;
86
  /** Detailed error description */
87
  detail?: string;
88
  /** Suggestion for resolving the error */
89
  hint?: string;
90
  /** Character position of error in query */
91
  position?: string;
92
  /** Internal query position (for internally generated queries) */
93
  internalPosition?: string;
94
  /** Internal query text that caused the error */
95
  internalQuery?: string;
96
  /** Location context where error occurred */
97
  where?: string;
98
  /** Schema name related to error */
99
  schema?: string;
100
  /** Table name related to error */
101
  table?: string;
102
  /** Column name related to error */
103
  column?: string;
104
  /** Data type name related to error */
105
  dataType?: string;
106
  /** Constraint name related to error */
107
  constraint?: string;
108
  /** Source file where error was generated */
109
  file?: string;
110
  /** Line number where error was generated */
111
  line?: string;
112
  /** Function name where error was generated */
113
  routine?: string;
114

115
  constructor(
116
    message: string,
117
    length: number,
118
    name: MessageName
119
  );
120
}
121

122
/**
123
 * PostgreSQL notice message with diagnostic information
124
 */
125
class NoticeMessage implements BackendMessage {
126
  readonly name = 'notice';
127
  severity?: string;
128
  code?: string;
129
  detail?: string;
130
  hint?: string;
131
  position?: string;
132
  internalPosition?: string;
133
  internalQuery?: string;
134
  where?: string;
135
  schema?: string;
136
  table?: string;
137
  column?: string;
138
  dataType?: string;
139
  constraint?: string;
140
  file?: string;
141
  line?: string;
142
  routine?: string;
143

144
  constructor(
145
    length: number,
146
    message?: string
147
  );
148
}
149
```
150

151
### Query Result Messages
152

153
Classes representing query execution results and data.
154

155
```typescript { .api }
156
/**
157
 * Command execution completion message
158
 */
159
class CommandCompleteMessage {
160
  readonly name: MessageName = 'commandComplete';
161
  
162
  constructor(
163
    /** Message length */
164
    public readonly length: number,
165
    /** Command tag text (e.g., "SELECT 5", "INSERT 0 1") */
166
    public readonly text: string
167
  );
168
}
169

170
/**
171
 * Single row of query result data
172
 */
173
class DataRowMessage {
174
  readonly name: MessageName = 'dataRow';
175
  /** Number of fields in the row */
176
  readonly fieldCount: number;
177
  
178
  constructor(
179
    /** Message length */
180
    public length: number,
181
    /** Array of field values (strings or null) */
182
    public fields: any[]
183
  );
184
}
185

186
/**
187
 * Description of query result structure
188
 */
189
class RowDescriptionMessage {
190
  readonly name: MessageName = 'rowDescription';
191
  /** Array of field descriptors */
192
  readonly fields: Field[];
193
  
194
  constructor(
195
    /** Message length */
196
    public readonly length: number,
197
    /** Number of fields in result */
198
    public readonly fieldCount: number
199
  );
200
}
201

202
/**
203
 * Individual field descriptor within a row description
204
 */
205
class Field {
206
  constructor(
207
    /** Field name */
208
    public readonly name: string,
209
    /** Table OID (0 if not from a table column) */
210
    public readonly tableID: number,
211
    /** Column attribute number (0 if not from a table column) */
212
    public readonly columnID: number,
213
    /** Data type OID */
214
    public readonly dataTypeID: number,
215
    /** Data type size (-1 for variable length) */
216
    public readonly dataTypeSize: number,
217
    /** Type modifier */
218
    public readonly dataTypeModifier: number,
219
    /** Format code (text or binary) */
220
    public readonly format: Mode
221
  );
222
}
223
```
224

225
### Parameter and Status Messages
226

227
Classes for prepared statement parameters and server status information.
228

229
```typescript { .api }
230
/**
231
 * Description of prepared statement parameters
232
 */
233
class ParameterDescriptionMessage {
234
  readonly name: MessageName = 'parameterDescription';
235
  /** Array of parameter data type OIDs */
236
  readonly dataTypeIDs: number[];
237
  
238
  constructor(
239
    /** Message length */
240
    public readonly length: number,
241
    /** Number of parameters */
242
    public readonly parameterCount: number
243
  );
244
}
245

246
/**
247
 * Server parameter status notification
248
 */
249
class ParameterStatusMessage {
250
  readonly name: MessageName = 'parameterStatus';
251
  
252
  constructor(
253
    /** Message length */
254
    public readonly length: number,
255
    /** Parameter name */
256
    public readonly parameterName: string,
257
    /** Parameter value */
258
    public readonly parameterValue: string
259
  );
260
}
261

262
/**
263
 * Server ready state indicator
264
 */
265
class ReadyForQueryMessage {
266
  readonly name: MessageName = 'readyForQuery';
267
  
268
  constructor(
269
    /** Message length */
270
    public readonly length: number,
271
    /** Transaction status: 'I' (idle), 'T' (in transaction), 'E' (error) */
272
    public readonly status: string
273
  );
274
}
275
```
276

277
### Authentication Messages
278

279
Classes for handling various authentication methods.
280

281
```typescript { .api }
282
/**
283
 * MD5 password authentication challenge
284
 */
285
class AuthenticationMD5Password implements BackendMessage {
286
  readonly name: MessageName = 'authenticationMD5Password';
287
  
288
  constructor(
289
    /** Message length */
290
    public readonly length: number,
291
    /** 4-byte salt for MD5 hashing */
292
    public readonly salt: Buffer
293
  );
294
}
295
```
296

297
### Administrative Messages
298

299
Classes for administrative and connection management information.
300

301
```typescript { .api }
302
/**
303
 * Backend process identification for query cancellation
304
 */
305
class BackendKeyDataMessage {
306
  readonly name: MessageName = 'backendKeyData';
307
  
308
  constructor(
309
    /** Message length */
310
    public readonly length: number,
311
    /** Backend process ID */
312
    public readonly processID: number,
313
    /** Secret key for cancellation requests */
314
    public readonly secretKey: number
315
  );
316
}
317

318
/**
319
 * Asynchronous notification message
320
 */
321
class NotificationResponseMessage {
322
  readonly name: MessageName = 'notification';
323
  
324
  constructor(
325
    /** Message length */
326
    public readonly length: number,
327
    /** Process ID of notifying backend */
328
    public readonly processId: number,
329
    /** Notification channel name */
330
    public readonly channel: string,
331
    /** Optional payload data */
332
    public readonly payload: string
333
  );
334
}
335
```
336

337
### Copy Protocol Messages
338

339
Classes for handling PostgreSQL COPY operations.
340

341
```typescript { .api }
342
/**
343
 * Copy operation data chunk
344
 */
345
class CopyDataMessage {
346
  readonly name = 'copyData';
347
  
348
  constructor(
349
    /** Message length */
350
    public readonly length: number,
351
    /** Data chunk */
352
    public readonly chunk: Buffer
353
  );
354
}
355

356
/**
357
 * Copy operation response (CopyIn or CopyOut)
358
 */
359
class CopyResponse {
360
  /** Array of column format codes */
361
  readonly columnTypes: number[];
362
  
363
  constructor(
364
    /** Message length */
365
    public readonly length: number,
366
    /** Message name ('copyInResponse' or 'copyOutResponse') */
367
    public readonly name: MessageName,
368
    /** Whether data is in binary format */
369
    public readonly binary: boolean,
370
    /** Number of columns */
371
    columnCount: number
372
  );
373
}
374
```
375

376
## Usage Patterns
377

378
These message classes are typically created by the parser and passed to message callback functions:
379

380
```typescript
381
import { DatabaseError } from "pg-protocol";
382

383
const callback = (message) => {
384
  switch (message.name) {
385
    case 'dataRow':
386
      console.log('Row data:', message.fields);
387
      break;
388
      
389
    case 'commandComplete':
390
      console.log('Command completed:', message.text);
391
      break;
392
      
393
    case 'error':
394
      const error = message;
395
      console.error(`Database error [${error.code}]: ${error.message}`);
396
      if (error.hint) console.log('Hint:', error.hint);
397
      break;
398
  }
399
};
400
```