{"id":16477,"library":"parse-db-url","title":"parse-db-url","description":"The `parse-db-url` library is a specialized utility designed to accurately parse database connection URLs into structured configuration objects. Unlike Node.js's built-in `url.parse`, this package understands common conventions associated with various database drivers, such as 'postgres' or 'mysql', and intelligently extracts components like the adapter, host, port, database name, username, and password. A key feature is its ability to handle query-string parameters that can override earlier parts of the URL, offering flexible configuration options. The current stable version is 2.3.0. As a domain-specific parsing tool, its release cadence is slow, with the last publish being over five years ago, indicating a stable, feature-complete state primarily in maintenance mode, rather than active development. It provides a consistent interface for abstracting database connection details, simplifying multi-database application setups.","status":"maintenance","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/grncdr/parse-db-url","tags":["javascript","any-db","db","url"],"install":[{"cmd":"npm install parse-db-url","lang":"bash","label":"npm"},{"cmd":"yarn add parse-db-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add parse-db-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exports as a CommonJS module. While `import parseDbUrl from 'parse-db-url'` works in ESM, Node.js internally wraps the CJS module. For strict CJS contexts, `require` is the idiomatic approach.","wrong":"import parseDbUrl from 'parse-db-url';","symbol":"parseDbUrl","correct":"const parseDbUrl = require('parse-db-url');"},{"note":"The package does not ship with explicit TypeScript types. Users should define types manually or use JSDoc for type inference based on the runtime output.","symbol":"DBConfig","correct":"/** @typedef {ReturnType<typeof import('parse-db-url')>} DBConfig */"}],"quickstart":{"code":"import parseDbUrl from 'parse-db-url';\n\nconst databaseUrl = process.env.DATABASE_URL ?? 'postgres://user:password@host:5432/mydb?ssl=true';\n\ntry {\n  const dbConfig = parseDbUrl(databaseUrl);\n  console.log('Parsed database configuration:');\n  console.log(`  Adapter: ${dbConfig.adapter}`);\n  console.log(`  Host: ${dbConfig.host}`);\n  console.log(`  Port: ${dbConfig.port}`);\n  console.log(`  Database: ${dbConfig.database}`);\n  console.log(`  User: ${dbConfig.user}`);\n  // console.log(`  Password: ${dbConfig.password ? '****' : 'N/A'}`); // Be cautious with logging credentials\n\n  // Example usage with a different URL format\n  const sqliteUrl = 'sqlite:///path/to/my.db';\n  const sqliteConfig = parseDbUrl(sqliteUrl);\n  console.log('\\nParsed SQLite configuration:');\n  console.log(`  Adapter: ${sqliteConfig.adapter}`);\n  console.log(`  Database: ${sqliteConfig.database}`);\n\n} catch (error) {\n  console.error('Error parsing database URL:', error.message);\n  process.exit(1);\n}","lang":"javascript","description":"Demonstrates how to parse a database URL from an environment variable and a direct string, then access the structured configuration properties like adapter, host, and database."},"warnings":[{"fix":"URL-encode special characters in the password segment of your database URL, for example, using `encodeURIComponent()` if constructing the URL programmatically.","message":"Database passwords containing special characters (e.g., '/', '#', '?', '@') may not be parsed correctly, leading to inconsistent or incorrect configuration objects. Always URL-encode special characters in passwords within the URL string if issues arise.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement custom validation logic in your application to check if the `adapter` property returned by `parseDbUrl` is one of your supported database drivers.","message":"The library does not validate if the specified database 'driver' or 'adapter' in the URL corresponds to an existing or supported database type. It extracts the string as provided, leaving validation to the consuming application.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Sanitize and validate all user-supplied URL inputs before passing them to `parseDbUrl`. Avoid concatenating user input directly into database connection strings without proper encoding and validation.","message":"The `parse-db-url` package is built on Node.js's internal `url` module. While it adds database-specific logic, it may inherit parsing quirks or security considerations from the underlying URL parser. Always treat URLs from untrusted sources with caution to prevent potential SSRF, injection, or misinterpretation issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the project's GitHub repository for any unlisted `CHANGELOG` or release notes if encountering unexpected behavior between minor versions.","message":"No explicit major breaking changes have been documented for versions within the 2.x range, nor are there readily available details for breaking changes between a hypothetical v1 and the current v2.3.0 in public resources. The package's stable state suggests minimal API evolution.","severity":"breaking","affected_versions":"n/a"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use the ESM import syntax: `import parseDbUrl from 'parse-db-url';`. If you need to stay in CommonJS, ensure your file is `.js` and `\"type\": \"module\"` is not set, or it's within a CJS-specific directory.","cause":"Attempting to use `require()` syntax in a JavaScript file that is being treated as an ES Module (e.g., via `\"type\": \"module\"` in `package.json` or `.mjs` extension).","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Ensure that any special characters in the username or password are correctly URL-encoded. For example, a password like `p@ss/word` should be `p%40ss%2Fword` in the URL. Use `encodeURIComponent()` for programmatic URL construction.","cause":"Special characters (like `@`, `:`, `/`, `?`, `#`) in the username or password portion of the database URL are not properly URL-encoded, causing the URL parser to misinterpret the segments.","error":"Parsed database configuration is incorrect or inconsistent (e.g., password missing, host is part of the password)"},{"fix":"For CommonJS, use `const parseDbUrl = require('parse-db-url');`. For ESM, use `import parseDbUrl from 'parse-db-url';`. Double-check the package name is exactly `parse-db-url`.","cause":"The module was imported incorrectly, perhaps attempting a named import for a default CommonJS export, or `require()` was used on a non-existent module.","error":"TypeError: parseDbUrl is not a function"}],"ecosystem":"npm"}