Parse Database URIs

2.1.2 · active · verified Wed Apr 22

parse-db-uri is a utility library designed to parse database connection URIs into a structured JavaScript object. It extends the output of the 'parse-url' package with database-specific fields such as `database`, `user`, `host`, `password`, and `dialect`. The library is currently stable at version 2.1.2, with recent updates including automatic decoding of passwords and usernames in the URI and added support for SQLite URIs. It provides a straightforward, function-based API for extracting components from common database URI formats, making it easier to configure database connections in applications. The release cadence is irregular but has seen active maintenance recently within the 2.x major version.

Common errors

```
TypeError: parseDbUri is not a function
```
cause This error typically occurs when the `parseDbUri` function is not correctly imported or referenced, often due to an incorrect import syntax for a default export (e.g., using named destructuring for a CommonJS default).

fix Ensure the import statement is `import parseDbUri from 'parse-db-uri';` for ESM, or `const parseDbUri = require('parse-db-uri');` for CommonJS.
```
ReferenceError: parseDbUri is not defined
```
cause The variable `parseDbUri` was used before it was declared or properly imported into the current scope, or there's a typo in the variable name.

fix Verify that `import parseDbUri from 'parse-db-uri';` or `const parseDbUri = require('parse-db-uri');` is present at the top of your module and that `parseDbUri` is spelled correctly wherever it's used.

Warnings

breaking Version 2.0.0 introduced a major version bump, implying potential breaking changes. While specific details were not provided in the changelog, users upgrading from 1.x should exercise caution and thoroughly test their implementations, as underlying parsing logic or result object structure may have changed.
Fix: Carefully review the package's behavior and the structure of the returned object if upgrading from a 1.x version. Consult the `parse-url` documentation for any upstream changes.
gotcha The package is primarily a CommonJS module that exports a single function as its default. In modern ESM environments, attempting to use named imports (`import { parseDbUri } from 'parse-db-uri';`) will fail, returning `undefined` for `parseDbUri`.
Fix: For ESM projects, always use `import parseDbUri from 'parse-db-uri';`. For CommonJS, use `const parseDbUri = require('parse-db-uri');`.
gotcha As of version 2.1.2, the library automatically decodes URL-encoded characters within usernames and passwords. While this is generally desired for usability, developers should be aware of this behavior, especially if their application relies on the raw, encoded form of these URI components.
Fix: No specific fix is required, but be mindful that the `user` and `password` fields in the parsed object will contain their decoded values. Adjust any downstream logic that might expect encoded characters.

Install

npm install parse-db-uri npm
yarn add parse-db-uri yarn
pnpm add parse-db-uri pnpm

Imports

parseDbUri
wrong:
```
import { parseDbUri } from 'parse-db-uri';
```
correct:
```
import parseDbUri from 'parse-db-uri';
```
The package primarily uses CommonJS `module.exports = function` pattern, which translates to a default import in ESM. Using named destructuring for ESM imports will result in `undefined`.
parseDbUri
wrong:
```
const { parseDbUri } = require('parse-db-uri');
```
correct:
```
const parseDbUri = require('parse-db-uri');
```
This is the recommended and most robust way to import the function in Node.js CommonJS environments. Attempting to use named destructuring for `require` will result in `undefined`.

Quickstart

Demonstrates parsing MySQL, SQLite, and PostgreSQL database URIs into structured objects, including database-specific fields and environment variable usage for sensitive credentials.

const parseDbUri = require("parse-db-uri");

const mysqlUri = "mysql://root:secretpass@localhost:3306/my_database";
const sqliteUri = "sqlite://data/db.sqlite3";
const postgresUri = `postgres://${process.env.DB_USER ?? 'admin'}:${process.env.DB_PASSWORD ?? 'password'}@db.example.com:5432/my_app_db?sslmode=require`;

console.log("MySQL URI parsed:", parseDbUri(mysqlUri));
// Expected output for mysqlUri:
// { protocols: [ 'mysql' ], protocol: 'mysql', port: 3306, resource: 'localhost', host: 'localhost', user: 'root', password: 'secretpass', pathname: '/my_database', hash: '', search: '', href: 'mysql://root:secretpass@localhost:3306/my_database', query: {}, parse_failed: false, uri: 'mysql://root:secretpass@localhost:3306/my_database', database: 'my_database', dialect: 'mysql' }

console.log("SQLite URI parsed:", parseDbUri(sqliteUri));
// Expected output for sqliteUri:
// { protocols: [ 'sqlite' ], protocol: 'sqlite', port: 0, resource: 'data', host: 'data', user: '', password: '', pathname: 'data/db.sqlite3', hash: '', search: '', href: 'sqlite://data/db.sqlite3', query: {}, parse_failed: false, uri: 'sqlite://data/db.sqlite3', dialect: 'sqlite' }

console.log("PostgreSQL URI parsed:", parseDbUri(postgresUri));

view raw JSON →