Registry / database / mongodb-connection-string-url

mongodb-connection-string-url

library7.0.1jsnpmunverified

This package provides a robust API for parsing and manipulating MongoDB connection strings, aligning with the WhatWG URL API specification while introducing MongoDB-specific extensions. It is currently at version 7.0.1 (as of Jan 2026) and is actively maintained by the MongoDB Node.js team. Releases are typically aligned with the major versions of the `mongodb` driver, with rapid iterations within a major version to address issues. Key differentiators from a standard URL object include case-insensitive URL parameters, a `.hosts` property for extracting all host details, an `.isSRV` property to identify `mongodb+srv` schemes, and the immutability of standard `.host`, `.hostname`, `.port`, and `.href` properties, which cannot be directly set and may not return meaningful results in the MongoDB context.

database

npm install mongodb-connection-string-url

github ↗package ↗

INSTALL

IMPORT

SIG · MONGODB-CONNECTION

mongodb-connection-string-url

databasejavascriptv7.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConnectionString

✓ import ConnectionString from 'mongodb-connection-string-url';

✗ const ConnectionString = require('mongodb-connection-string-url');

The package primarily targets ES modules for modern Node.js and TypeScript environments. While CommonJS `require` might work via a wrapper, `import` is the recommended and best-supported pattern.

Demonstrates parsing various MongoDB connection string formats, modifying URL parameters, and accessing MongoDB-specific properties like `hosts` and `isSRV`.

import ConnectionString from 'mongodb-connection-string-url'; // Example 1: Basic connection string manipulation const cs1 = new ConnectionString('mongodb://user:pass@host1:27017,host2:27018/mydatabase?replicaSet=rs0&authSource=admin'); cs1.searchParams.set('readPreference', 'secondary'); console.log('Modified URL:', cs1.href); // 'mongodb://user:pass@host1:27017,host2:27018/mydatabase?replicaSet=rs0&authSource=admin&readPreference=secondary' console.log('Hosts:', cs1.hosts.map(h => `${h.host}:${h.port}`)); // ['host1:27017', 'host2:27018'] console.log('Is SRV:', cs1.isSRV); // false // Example 2: Using mongodb+srv (DNS Seed List) with environment variables // For a real application, replace placeholders with actual values from process.env const username = process.env.MONGO_USER ?? 'myUser'; const password = process.env.MONGO_PASS ?? 'myComplexPassword123'; const srvHost = process.env.MONGO_SRV_HOST ?? 'cluster0.example.com'; const secureCs = new ConnectionString(`mongodb+srv://${username}:${password}@${srvHost}/testdb?retryWrites=true&w=majority`); console.log('SRV URL (obfuscated pass):', secureCs.href.replace(password, '******')); console.log('Is SRV:', secureCs.isSRV); // true console.log('Database from SRV:', secureCs.pathname.substring(1)); // 'testdb'

Debug

Known issues

breakingVersion 7.0.0 and above drop support for Node.js 16 and 18. The package now requires Node.js >= 20.19.0.

fix

Upgrade your Node.js runtime environment to version 20.19.0 or higher.

affects: >=7.0.0

gotchaStandard WhatWG URL properties like `.host`, `.hostname`, `.port`, and `.href` cannot be directly set and their read values may not be meaningful for MongoDB connection strings, especially with multiple hosts or SRV records.

fix

Access and modify host details exclusively through the MongoDB-specific `.hosts` array property. To modify other URL parts, use methods like `cs.searchParams.set()` or reconstruct the string. The `.href` property is read-only.

affects: >=3.0.0

gotchaMajor versions of `mongodb-connection-string-url` (e.g., v7.x) are explicitly aligned with the major versions of the main `mongodb` driver package to clarify compatibility. This resulted in skipped major versions (4.x to 6.x) for this package.

fix

Refer to the `mongodb` driver's changelog or documentation to ensure you are using a compatible `mongodb-connection-string-url` version.

affects: >=7.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

Attempting to `require()` this package in a CommonJS module when it primarily exposes ES Modules, or your project is configured for ESM.

fix

If using Node.js modules, ensure your project is configured for ES modules (`"type": "module"` in `package.json`) and use `import ConnectionString from 'mongodb-connection-string-url';`. If you must remain in CommonJS, consider dynamic `import()` or review if an older version of the package or a different MongoDB driver setup is more appropriate.

DeprecationWarning: The `punycode` module is deprecated.

This warning typically arises from an older version of the `whatwg-url` dependency, which `mongodb-connection-string-url` uses, pulling in the deprecated `punycode` module.

fix

Ensure `whatwg-url` is resolved to version 14.x or higher in your project's dependency tree. This might require updating `mongodb-connection-string-url` itself, the `mongodb` driver, or using package manager `overrides` or `resolutions` to force the `whatwg-url` version.

Error: Invalid `new ConnectionString()` invocation: The provided database string is invalid.

The input string does not conform to the expected MongoDB connection string URI format, potentially due to missing required components, incorrect characters, or improper percent-encoding of special characters in credentials or options.

fix

Review the MongoDB connection string specification for correct formatting. Ensure all special characters in usernames, passwords, or database names are correctly percent-encoded (e.g., `@` as `%40`, `/` as `%2F`). Verify that the scheme (`mongodb://` or `mongodb+srv://`) and host components are present and correctly formatted.

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

whatwg-urlrequiredInternal dependency for URL parsing, update to version 14.x or higher is recommended to avoid `punycode` deprecation warnings in newer Node.js versions.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/mongodb-js/mongodb-connection-string-url ↗

packagehttps://www.npmjs.com/package/mongodb-connection-string-url ↗