{"id":16251,"library":"ts-parse-database-url","title":"Database URL Parser","description":"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.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/herlon214/ts-parse-database-url","tags":["javascript","typescript"],"install":[{"cmd":"npm install ts-parse-database-url","lang":"bash","label":"npm"},{"cmd":"yarn add ts-parse-database-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-parse-database-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is primarily designed for ESM consumption, though CommonJS usage is supported by most bundlers and Node.js versions.","wrong":"const parseDatabaseUrl = require('ts-parse-database-url');","symbol":"parseDatabaseUrl","correct":"import parseDatabaseUrl from 'ts-parse-database-url';"},{"note":"Import the `ParseResult` type for explicit type annotation of the object returned by `parseDatabaseUrl`.","symbol":"ParseResult","correct":"import type { ParseResult } from 'ts-parse-database-url';"}],"quickstart":{"code":"import parseDatabaseUrl from 'ts-parse-database-url';\n\n// Example with a common MySQL URL\nconst mysqlUrl = 'mysql://someuser:password@server.heroku.com:1337/herokudb';\nconst parsedMysql = parseDatabaseUrl(mysqlUrl);\n\nconsole.log('Parsed MySQL URL:', parsedMysql);\n/* Expected output:\n{\n  driver: 'mysql',\n  user: 'someuser',\n  password: 'password',\n  host: 'server.heroku.com',\n  port: '1337',\n  database: 'herokudb'\n}*/\n\n// Example with a PostgreSQL URL (often from process.env)\nconst postgresUrl = process.env.DATABASE_URL ?? 'postgresql://admin:secret@localhost:5432/my_app_db';\nconst parsedPostgres = parseDatabaseUrl(postgresUrl);\n\nconsole.log('Parsed PostgreSQL URL:', parsedPostgres);\n/* Expected output (example):\n{\n  driver: 'postgresql',\n  user: 'admin',\n  password: 'secret',\n  host: 'localhost',\n  port: '5432',\n  database: 'my_app_db'\n}*/\n","lang":"typescript","description":"Demonstrates parsing both MySQL and PostgreSQL database URLs, showing how to extract individual connection parameters into a structured object."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If default ports are required, implement a fallback mechanism in your application code, e.g., `parsed.port ?? getDefaultPort(parsed.driver)`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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);`","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.","error":"TypeError: Cannot read properties of undefined (reading 'driver')"},{"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.","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.","error":"Property 'password' does not exist on type 'ParseResult'."}],"ecosystem":"npm"}