DSN Parser

1.0.3 · maintenance · verified Wed Apr 22

The `dsn-parser` package (currently at version 1.0.3) provides a fluent API for parsing and constructing database connection strings (DSNs). It supports common DSN formats, extracting components such as driver, user, password, host, port, database name, and query parameters. A primary use case demonstrated is parsing Heroku-style PostgreSQL environment variables (`pgsql://user:pass@host:port/database`) into an object format compatible with popular database drivers like `node-postgres`. The library can also be used to programmatically build DSNs from individual components, offering a concise way to manage database connection configurations. It is a focused utility library solely for DSN manipulation.

Common errors

```
TypeError: DSNParser is not a constructor
```
cause Attempting to use `import { DSNParser } from 'dsn-parser';` or incorrectly accessing the default export of a CommonJS module in an ES module context.

fix If in a CommonJS file, use `const DSNParser = require('dsn-parser');`. If in an ES module file, use `import DSNParser from 'dsn-parser';` and verify your build setup correctly handles CommonJS interop.
```
ReferenceError: require is not defined
```
cause Trying to use `require('dsn-parser')` directly within an ES module (`.mjs` file or `type: 'module'` in `package.json`).

fix Change the import statement to `import DSNParser from 'dsn-parser';` to use ES module syntax. Ensure your environment or bundler is configured to correctly handle CommonJS modules within an ESM project.

Warnings

gotcha The `dsn-parser` package is implemented as a CommonJS module. Attempting to use `import` syntax without proper tooling (like a bundler or specific Node.js configuration) can lead to import errors in ES module contexts.
Fix: Ensure you use `const DSNParser = require('dsn-parser');` when working in a CommonJS environment. In an ESM environment, you might need `import DSNParser from 'dsn-parser';` which relies on Node.js's CJS interop, but direct named imports will fail.
gotcha The package has not been updated in over six years (last commit as of late 2023). While functional for its intended purpose, it may lack support for newer DSN formats, advanced parsing requirements, or security patches for potential vulnerabilities in its parsing logic.
Fix: Evaluate if the existing functionality meets your current and future needs. For actively evolving database ecosystems or stricter security requirements, consider a more actively maintained alternative if available.

Install

npm install dsn-parser npm
yarn add dsn-parser yarn
pnpm add dsn-parser pnpm

Imports

DSNParser
wrong:
```
import DSNParser from 'dsn-parser';
```
correct:
```
const DSNParser = require('dsn-parser');
```
This package is a CommonJS module. Direct ES module imports are not supported.
DSNParser Class Instance
wrong:
```
const dsn = DSNParser.parse('driver://...');
```
correct:
```
const dsn = new DSNParser('driver://user:pass@host:port/db?key=value');
```
The library exports a class. Instantiation with `new` is required to parse or build a DSN.
Module Import (ESM context)
wrong:
```
import { DSNParser } from 'dsn-parser';
```
correct:
```
import DSNParser from 'dsn-parser'; // Requires a CommonJS interop wrapper or bundler
```
While technically possible in an ESM file with `import DSNParser from 'dsn-parser';` due to Node.js's CJS interop, it is still a CJS module. Named imports like `{ DSNParser }` will fail.

Quickstart

Demonstrates parsing a database connection string from an environment variable and extracting its components for use with a client like `node-postgres`, then building a new DSN programmatically.

const DSNParser = require('dsn-parser');
const pg = require('pg'); // Example consumer, install 'pg' separately

// Simulate Heroku environment variable
process.env.HEROKU_POSTGRESQL_COPPER_URL = 'pgsql://user:pass@127.0.0.1:5432/my_db?sslmode=verify-full&application_name=myapp';

console.log('--- Parsing DSN ---');
// Parse the DSN string
const dsn = new DSNParser(process.env.HEROKU_POSTGRESQL_COPPER_URL);
const config = dsn.getParts();

console.log('Parsed DSN configuration:', config);
/*
Example output:
{
  driver: 'pgsql',
  user: 'user',
  password: 'pass',
  host: '127.0.0.1',
  port: 5432,
  database: 'my_db',
  params: { sslmode: 'verify-full', application_name: 'myapp' }
}
*/

// This config object can then be used with database clients, e.g., node-postgres
// try {
//   const pool = new pg.Pool(config);
//   console.log('PG Pool config prepared. First client connect:', await pool.connect());
//   await pool.end();
// } catch (error) {
//   console.error('Failed to connect with pg:', error.message);
// }

console.log('\n--- Building DSN ---');
// Modify and rebuild a DSN
const newDsn = new DSNParser();
newDsn.set('driver', 'mysql')
    .set('user', 'root')
    .set('password', 'mysecurepass')
    .set('host', 'localhost')
    .set('port', 3306)
    .set('database', 'my_application_db')
    .set('params', {
        charset: 'utf8mb4',
        timezone: 'Z'
    });

console.log('Built DSN string:', newDsn.getDSN());
// Expected output: mysql://root:mysecurepass@localhost:3306/my_application_db?charset=utf8mb4&timezone=Z

view raw JSON →