tessl/npm-pg

PostgreSQL client library for Node.js with both pure JavaScript and optional native libpq bindings

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Connection String Parsing

Name: tessl/npm-pg
Author: tessl

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

Capabilities

Parse Connection String

Parse PostgreSQL connection strings into configuration objects.

/**
 * Parse a PostgreSQL connection string into configuration options
 * @param connectionString - PostgreSQL connection URL
 * @param options - Optional parsing configuration
 * @returns Connection configuration object
 */
function parse(connectionString: string, options?: ParseOptions): ConnectionOptions;

interface ParseOptions {
  /** Use libpq-compatible semantics for SSL parameters */
  useLibpqCompat?: boolean;
}

interface ConnectionOptions {
  host: string | null;
  password?: string;
  user?: string;
  port?: string | null;
  database: string | null | undefined;
  client_encoding?: string;
  ssl?: boolean | string | SSLConfig;
  application_name?: string;
  fallback_application_name?: string;
  options?: string;
  keepalives?: number;
  [key: string]: unknown;
}

Usage Examples:

const { parse } = require('pg-connection-string');

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

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

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

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

Convert to Client Configuration

Convert connection options to pg.Client-compatible configuration.

/**
 * Convert connection options to pg.Client-compatible configuration
 * @param config - Connection options from parse()
 * @returns Client configuration object
 */
function toClientConfig(config: ConnectionOptions): ClientConfig;

interface ClientConfig {
  host?: string;
  port?: number;
  database?: string;
  user?: string;
  password?: string;
  ssl?: boolean | SSLConfig;
  application_name?: string;
  fallback_application_name?: string;
  client_encoding?: string;
  options?: string;
  keepalives?: number;
  [key: string]: unknown;
}

Usage Examples:

const { parse, toClientConfig } = require('pg-connection-string');
const { Client } = require('pg');

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

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

// Use with pg.Client
const client = new Client(clientConfig);

Direct Client Configuration

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

/**
 * Parse connection string directly into pg.Client configuration
 * @param connectionString - PostgreSQL connection URL
 * @returns Client configuration object
 */
function parseIntoClientConfig(connectionString: string): ClientConfig;

Usage Examples:

const { parseIntoClientConfig } = require('pg-connection-string');
const { Client } = require('pg');

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

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

Supported Connection String Formats

TCP Connections

// Standard PostgreSQL URLs
'postgres://user:password@host:port/database'
'pg://user:password@host:port/database'

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

// Minimal format (database name only)
'mydb'

Unix Domain Sockets

// Socket URL format
'socket://user:password@/path/to/socket?db=database&encoding=utf8'
'socket:/path/to/socket?db=database&encoding=utf8'

// Simple path format
'/var/run/postgresql database_name'

SSL Configuration

// SSL modes
'postgres://localhost/mydb?ssl=true'
'postgres://localhost/mydb?sslmode=require'
'postgres://localhost/mydb?sslmode=verify-full'

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

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

SSL Configuration

interface SSLConfig {
  ca?: string;
  cert?: string | null;
  key?: string;
  rejectUnauthorized?: boolean;
  checkServerIdentity?: () => void;
}

Usage Examples:

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

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

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

Query Parameters

Standard PostgreSQL Parameters

// Connection parameters
'?host=alternative-host&port=5433'
'?encoding=utf8&application_name=MyApp'
'?fallback_application_name=Fallback&options=-c statement_timeout=30s'

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

// Connection tuning
'?keepalives=1&keepalives_idle=30'

Custom Parameters

// Custom application parameters are preserved
const config = parse('postgres://localhost/mydb?custom_param=value&app_setting=true');
console.log(config.custom_param); // 'value'
console.log(config.app_setting); // 'true'

Import Patterns

CommonJS

// Default import (parse function)
const parse = require('pg-connection-string');
const config = parse('postgres://localhost/mydb');

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

ES Modules

// Default import
import parse from 'pg-connection-string';

// Named imports
import { parse, toClientConfig, parseIntoClientConfig } from 'pg-connection-string';

TypeScript

import { parse, toClientConfig, parseIntoClientConfig, ConnectionOptions, ClientConfig } from 'pg-connection-string';

const options: ConnectionOptions = parse('postgres://localhost/mydb');
const clientConfig: ClientConfig = toClientConfig(options);

Error Handling

try {
  const config = parse('invalid://connection/string');
} catch (error) {
  console.error('Invalid connection string:', error.message);
}

// SSL file errors
try {
  const config = parse('postgres://localhost/mydb?sslcert=/nonexistent/cert.pem');
} catch (error) {
  console.error('SSL certificate error:', error.message);
}

Integration with pg

const { parseIntoClientConfig } = require('pg-connection-string');
const { Client, Pool } = require('pg');

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

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

// Environment variable support
const config = parseIntoClientConfig(
  process.env.DATABASE_URL || 'postgres://localhost:5432/development'
);

Install with Tessl CLI