Database URL Parser

1.0.3 · active · verified Tue Apr 21

ts-parse-database-url is a lightweight TypeScript-first utility designed to parse database connection URLs into their distinct components, such as driver, user, host, port, and database name. It provides a structured object output, simplifying the extraction and utilization of individual connection parameters. As of version 1.0.3, the package is stable and maintains a focused scope, primarily supporting common database URL formats. Due to its specific utility nature, major releases are infrequent, with updates generally consisting of bug fixes or enhancements to driver support. Its key differentiator is its native TypeScript support, which ensures type safety for the parsed output, making it highly suitable for modern TypeScript applications that retrieve database configurations from environment variables or other dynamic sources. The library draws inspiration from `node-parse-database-url` but is rebuilt with an emphasis on modern TypeScript practices and explicit type definitions.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'driver')
```
cause The input database URL was malformed or `null`/`undefined`, causing the `parseDatabaseUrl` function to return an unexpected value (e.g., `null`) which then had properties accessed.

fix Ensure the input to `parseDatabaseUrl` is a valid string. Add a check for the parser's return value before accessing its properties, e.g., `const parsed = parseDatabaseUrl(url); if (!parsed) { throw new Error('Invalid URL'); } console.log(parsed.driver);`
```
Property 'password' does not exist on type 'ParseResult'.
```
cause This TypeScript error typically occurs when the database URL did not include a password component, and you're trying to access `parsed.password` without checking for its existence, or if the `ParseResult` type doesn't fully account for optional properties.

fix Access optional properties with caution using optional chaining (`parsed?.password`) or by explicitly checking for their presence ( `if (parsed.password) { ... }`). The `ParseResult` type should correctly mark `password` as optional.

Warnings

gotcha The package supports a limited set of common database drivers (e.g., MySQL, PostgreSQL). Attempting to parse URLs for unsupported or highly specialized drivers may lead to incorrect or incomplete parsing results.
Fix: Always verify that your database URL format and driver type are supported. Consult the package's test suite or source code for the most accurate list of currently supported drivers and their expected URL structures.
gotcha Malformed or non-standard database URLs can result in partial parsing, missing properties (e.g., `null` or `undefined`), or unexpected values in the parsed output object. The parser relies on standard URI components.
Fix: Ensure that all database URLs strictly adhere to standard URI syntax (e.g., `driver://user:pass@host:port/db`) and include all expected components. Validate input strings before passing them to the parser.
gotcha When a port is not explicitly specified in the database URL, the parser will *not* automatically infer a default port based on the driver. The `port` property will be `undefined` or `null`.
Fix: If default ports are required, implement a fallback mechanism in your application code, e.g., `parsed.port ?? getDefaultPort(parsed.driver)`.

Install

npm install ts-parse-database-url npm
yarn add ts-parse-database-url yarn
pnpm add ts-parse-database-url pnpm

Imports

parseDatabaseUrl
wrong:
```
const parseDatabaseUrl = require('ts-parse-database-url');
```
correct:
```
import parseDatabaseUrl from 'ts-parse-database-url';
```
The package is primarily designed for ESM consumption, though CommonJS usage is supported by most bundlers and Node.js versions.
ParseResult
```
import type { ParseResult } from 'ts-parse-database-url';
```
Import the `ParseResult` type for explicit type annotation of the object returned by `parseDatabaseUrl`.

Quickstart

Demonstrates parsing both MySQL and PostgreSQL database URLs, showing how to extract individual connection parameters into a structured object.

import parseDatabaseUrl from 'ts-parse-database-url';

// Example with a common MySQL URL
const mysqlUrl = 'mysql://someuser:password@server.heroku.com:1337/herokudb';
const parsedMysql = parseDatabaseUrl(mysqlUrl);

console.log('Parsed MySQL URL:', parsedMysql);
/* Expected output:
{
  driver: 'mysql',
  user: 'someuser',
  password: 'password',
  host: 'server.heroku.com',
  port: '1337',
  database: 'herokudb'
}*/

// Example with a PostgreSQL URL (often from process.env)
const postgresUrl = process.env.DATABASE_URL ?? 'postgresql://admin:secret@localhost:5432/my_app_db';
const parsedPostgres = parseDatabaseUrl(postgresUrl);

console.log('Parsed PostgreSQL URL:', parsedPostgres);
/* Expected output (example):
{
  driver: 'postgresql',
  user: 'admin',
  password: 'secret',
  host: 'localhost',
  port: '5432',
  database: 'my_app_db'
}*/

view raw JSON →