PostgreSQL Connection URL Builder

0.1.0 · abandoned · verified Wed Apr 22

pg-database-url is a minimalist utility that constructs a PostgreSQL connection string (URI) from a structured JavaScript configuration object. Released as version 0.1.0, this package targets older Node.js environments (specifically `>=4.2.0`) and exclusively uses CommonJS modules. As of the last observed activity, the project appears to be abandoned, with no significant updates or maintenance in recent years (last commit over 11 years ago). Its primary function is to simplify the creation of connection strings for use with PostgreSQL client libraries like `node-postgres`, converting host, port, database, username, and password into a standard `postgres://` URI format. It does not offer advanced features like connection pooling, query building, or extensive validation, focusing solely on the URI generation aspect. There are no clear release cadences or stated differentiators, as it is a very specific, single-purpose library.

Common errors

```
Error: Invalid connection string
```
cause The generated connection string is missing critical components (e.g., database name, username) or has improperly formatted values due to incomplete input `dbConfig`.

fix Ensure that the `dbConfig` object passed to `pgUrl` includes at least `database` and `username`. Verify that `host` and `port` are correctly specified if not using defaults.
```
TypeError: pgUrl is not a function
```
cause Attempting to use ES module `import` syntax or destructuring assignment with this CommonJS-only package, which exports a single default function.

fix Use the CommonJS `require` syntax: `const pgUrl = require('pg-database-url')`.
```
Error: password authentication failed for user "user"
```
cause The generated connection string contains an incorrect password (or username) which is then used by the PostgreSQL client to attempt authentication.

fix Double-check the `password` and `username` properties in your `dbConfig` object to ensure they match the credentials configured for your PostgreSQL database. Ensure no accidental URL encoding issues are present if the password contains special characters, though this library doesn't explicitly mention handling it, modern drivers typically do.

Warnings

breaking The package `pg-database-url` is version 0.1.0 and has not been updated in over 11 years. It is effectively abandoned, meaning no new features, bug fixes, or security updates will be provided. Using unmaintained software can pose significant security risks and compatibility issues with newer Node.js versions or PostgreSQL features.
Fix: Consider migrating to actively maintained alternatives like `pg-connection-string` (from the `node-postgres` ecosystem) or manually constructing connection URIs, ensuring proper URL encoding of credentials.
gotcha The library performs minimal validation on the input `dbConfig` object. Supplying incomplete or malformed parameters (e.g., missing `database` or `username`, or `port` as a non-numeric string) will result in a syntactically malformed connection string, which will then cause connection errors when used by a PostgreSQL client.
Fix: Always ensure the `dbConfig` object contains all necessary and correctly typed properties (`host`, `port`, `database`, `username`, `password`) before passing it to `pgUrl`. Implement your own input validation if needed.
gotcha Sensitive information like passwords provided in the `dbConfig` object are directly embedded into the connection string. Without proper handling (e.g., environment variables, secret management), this could expose credentials if the connection string is logged or exposed.
Fix: Always use secure practices for handling database credentials. Retrieve sensitive data from environment variables (as shown in quickstart), a dedicated secret management service, or a secure configuration system. Avoid hardcoding credentials.

Install

npm install pg-database-url npm
yarn add pg-database-url yarn
pnpm add pg-database-url pnpm

Imports

pgUrl
wrong:
```
import pgUrl from 'pg-database-url'
```
correct:
```
const pgUrl = require('pg-database-url')
```
The package is CommonJS-only, as indicated by its `require` usage in the README and its age. ESM `import` statements will fail.
pgUrl
wrong:
```
const { pgUrl } = require('pg-database-url')
```
correct:
```
const pgUrl = require('pg-database-url')
```
The package exports a single default function, not named exports. Destructuring `pgUrl` will result in `undefined`.

Quickstart

This quickstart demonstrates how to generate a PostgreSQL connection string from a configuration object, suitable for use with client libraries like `node-postgres`. It includes placeholder environment variables for security and best practices.

const pgUrl = require('pg-database-url');

// Basic configuration from environment variables or a config file
const dbConfig = {
  host: process.env.DB_HOST ?? 'localhost',
  port: parseInt(process.env.DB_PORT ?? '5432', 10),
  database: process.env.DB_NAME ?? 'mydb',
  username: process.env.DB_USER ?? 'user',
  password: process.env.DB_PASSWORD ?? 'pass'
};

const connectionString = pgUrl(dbConfig);
console.log('Generated Connection String:', connectionString);

// Example with `node-postgres` (install separately: npm install pg)
// const { Client } = require('pg');
// const client = new Client({ connectionString });
//
// async function testConnection() {
//   try {
//     await client.connect();
//     const res = await client.query('SELECT NOW() as current_time');
//     console.log('Database time:', res.rows[0].current_time);
//   } catch (err) {
//     console.error('Database connection error:', err);
//   } finally {
//     await client.end();
//   }
// }
//
// testConnection();

view raw JSON →