0
# Connection String Parsing
1

2
Connection string parsing utilities for PostgreSQL connection URLs with comprehensive support for SSL, Unix sockets, and configuration parameters.
3

4
## Capabilities
5

6
### Parse Connection String
7

8
Parse PostgreSQL connection strings into configuration objects.
9

10
```javascript { .api }
11
/**
12
 * Parse a PostgreSQL connection string into configuration options
13
 * @param connectionString - PostgreSQL connection URL
14
 * @param options - Optional parsing configuration
15
 * @returns Connection configuration object
16
 */
17
function parse(connectionString: string, options?: ParseOptions): ConnectionOptions;
18

19
interface ParseOptions {
20
  /** Use libpq-compatible semantics for SSL parameters */
21
  useLibpqCompat?: boolean;
22
}
23

24
interface ConnectionOptions {
25
  host: string | null;
26
  password?: string;
27
  user?: string;
28
  port?: string | null;
29
  database: string | null | undefined;
30
  client_encoding?: string;
31
  ssl?: boolean | string | SSLConfig;
32
  application_name?: string;
33
  fallback_application_name?: string;
34
  options?: string;
35
  keepalives?: number;
36
  [key: string]: unknown;
37
}
38
```
39

40
**Usage Examples:**
41

42
```javascript
43
const { parse } = require('pg-connection-string');
44

45
// Basic connection string
46
const config = parse('postgres://user:pass@localhost:5432/mydb');
47
console.log(config);
48
// { user: 'user', password: 'pass', host: 'localhost', port: '5432', database: 'mydb' }
49

50
// Connection string with query parameters
51
const sslConfig = parse('postgres://localhost/mydb?ssl=true&application_name=MyApp');
52
console.log(sslConfig);
53
// { host: 'localhost', database: 'mydb', ssl: true, application_name: 'MyApp' }
54

55
// Unix socket connection
56
const socketConfig = parse('socket:///var/run/postgresql?db=mydb&user=postgres');
57
console.log(socketConfig);
58
// { host: '/var/run/postgresql', database: 'mydb', user: 'postgres' }
59

60
// With libpq compatibility
61
const libpqConfig = parse('postgres://localhost/mydb?sslmode=require', { useLibpqCompat: true });
62
```
63

64
### Convert to Client Configuration
65

66
Convert connection options to pg.Client-compatible configuration.
67

68
```javascript { .api }
69
/**
70
 * Convert connection options to pg.Client-compatible configuration
71
 * @param config - Connection options from parse()
72
 * @returns Client configuration object
73
 */
74
function toClientConfig(config: ConnectionOptions): ClientConfig;
75

76
interface ClientConfig {
77
  host?: string;
78
  port?: number;
79
  database?: string;
80
  user?: string;
81
  password?: string;
82
  ssl?: boolean | SSLConfig;
83
  application_name?: string;
84
  fallback_application_name?: string;
85
  client_encoding?: string;
86
  options?: string;
87
  keepalives?: number;
88
  [key: string]: unknown;
89
}
90
```
91

92
**Usage Examples:**
93

94
```javascript
95
const { parse, toClientConfig } = require('pg-connection-string');
96
const { Client } = require('pg');
97

98
// Parse and convert to client config
99
const options = parse('postgres://user:pass@localhost:5432/mydb');
100
const clientConfig = toClientConfig(options);
101

102
// Port is converted from string to number for pg.Client
103
console.log(typeof clientConfig.port); // 'number'
104

105
// Use with pg.Client
106
const client = new Client(clientConfig);
107
```
108

109
### Direct Client Configuration
110

111
Parse connection string directly into pg.Client-compatible configuration.
112

113
```javascript { .api }
114
/**
115
 * Parse connection string directly into pg.Client configuration
116
 * @param connectionString - PostgreSQL connection URL
117
 * @returns Client configuration object
118
 */
119
function parseIntoClientConfig(connectionString: string): ClientConfig;
120
```
121

122
**Usage Examples:**
123

124
```javascript
125
const { parseIntoClientConfig } = require('pg-connection-string');
126
const { Client } = require('pg');
127

128
// One-step parsing to client config
129
const config = parseIntoClientConfig('postgres://user:pass@localhost:5432/mydb');
130
const client = new Client(config);
131
await client.connect();
132

133
// Works with complex connection strings
134
const prodConfig = parseIntoClientConfig(
135
  'postgres://user:pass@db.example.com:5432/prod?ssl=true&application_name=MyApp&options=-c statement_timeout=30s'
136
);
137
```
138

139
## Supported Connection String Formats
140

141
### TCP Connections
142

143
```javascript
144
// Standard PostgreSQL URLs
145
'postgres://user:password@host:port/database'
146
'pg://user:password@host:port/database'
147

148
// With query parameters
149
'postgres://user:pass@localhost:5432/mydb?ssl=true&application_name=MyApp'
150

151
// Minimal format (database name only)
152
'mydb'
153
```
154

155
### Unix Domain Sockets
156

157
```javascript
158
// Socket URL format
159
'socket://user:password@/path/to/socket?db=database&encoding=utf8'
160
'socket:/path/to/socket?db=database&encoding=utf8'
161

162
// Simple path format
163
'/var/run/postgresql database_name'
164
```
165

166
### SSL Configuration
167

168
```javascript
169
// SSL modes
170
'postgres://localhost/mydb?ssl=true'
171
'postgres://localhost/mydb?sslmode=require'
172
'postgres://localhost/mydb?sslmode=verify-full'
173

174
// SSL certificates
175
'postgres://localhost/mydb?sslcert=/path/to/cert.pem&sslkey=/path/to/key.pem&sslrootcert=/path/to/ca.pem'
176

177
// libpq-compatible SSL
178
const config = parse('postgres://localhost/mydb?sslmode=verify-ca', { useLibpqCompat: true });
179
```
180

181
## SSL Configuration
182

183
```javascript { .api }
184
interface SSLConfig {
185
  ca?: string;
186
  cert?: string | null;
187
  key?: string;
188
  rejectUnauthorized?: boolean;
189
  checkServerIdentity?: () => void;
190
}
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
// File-based SSL certificates
197
const sslConnection = parse('postgres://localhost/mydb?sslrootcert=/etc/ssl/ca.pem&sslcert=/etc/ssl/client.pem&sslkey=/etc/ssl/client.key');
198

199
// SSL with verification
200
const secureConnection = parse('postgres://localhost/mydb?sslmode=verify-full');
201

202
// Custom SSL configuration
203
const customSSL = parse('postgres://localhost/mydb?ssl=true&sslmode=require');
204
console.log(customSSL.ssl); // SSL configuration object
205
```
206

207
## Query Parameters
208

209
### Standard PostgreSQL Parameters
210

211
```javascript
212
// Connection parameters
213
'?host=alternative-host&port=5433'
214
'?encoding=utf8&application_name=MyApp'
215
'?fallback_application_name=Fallback&options=-c statement_timeout=30s'
216

217
// SSL parameters  
218
'?ssl=true&sslmode=require'
219
'?sslcert=/path/cert.pem&sslkey=/path/key.pem'
220

221
// Connection tuning
222
'?keepalives=1&keepalives_idle=30'
223
```
224

225
### Custom Parameters
226

227
```javascript
228
// Custom application parameters are preserved
229
const config = parse('postgres://localhost/mydb?custom_param=value&app_setting=true');
230
console.log(config.custom_param); // 'value'
231
console.log(config.app_setting); // 'true'
232
```
233

234
## Import Patterns
235

236
### CommonJS
237

238
```javascript
239
// Default import (parse function)
240
const parse = require('pg-connection-string');
241
const config = parse('postgres://localhost/mydb');
242

243
// Named imports
244
const { parse, toClientConfig, parseIntoClientConfig } = require('pg-connection-string');
245
```
246

247
### ES Modules
248

249
```javascript
250
// Default import
251
import parse from 'pg-connection-string';
252

253
// Named imports
254
import { parse, toClientConfig, parseIntoClientConfig } from 'pg-connection-string';
255
```
256

257
### TypeScript
258

259
```typescript
260
import { parse, toClientConfig, parseIntoClientConfig, ConnectionOptions, ClientConfig } from 'pg-connection-string';
261

262
const options: ConnectionOptions = parse('postgres://localhost/mydb');
263
const clientConfig: ClientConfig = toClientConfig(options);
264
```
265

266
## Error Handling
267

268
```javascript
269
try {
270
  const config = parse('invalid://connection/string');
271
} catch (error) {
272
  console.error('Invalid connection string:', error.message);
273
}
274

275
// SSL file errors
276
try {
277
  const config = parse('postgres://localhost/mydb?sslcert=/nonexistent/cert.pem');
278
} catch (error) {
279
  console.error('SSL certificate error:', error.message);
280
}
281
```
282

283
## Integration with pg
284

285
```javascript
286
const { parseIntoClientConfig } = require('pg-connection-string');
287
const { Client, Pool } = require('pg');
288

289
// Client connection
290
const clientConfig = parseIntoClientConfig(process.env.DATABASE_URL);
291
const client = new Client(clientConfig);
292

293
// Pool connection
294
const poolConfig = parseIntoClientConfig(process.env.DATABASE_URL);
295
const pool = new Pool(poolConfig);
296

297
// Environment variable support
298
const config = parseIntoClientConfig(
299
  process.env.DATABASE_URL || 'postgres://localhost:5432/development'
300
);
301
```