CouchDB Database Ensurer

2.1.0 · active · verified Wed Apr 22

The `couchdb-ensure` package provides a focused Node.js utility for managing CouchDB database existence. Its primary function is to check if a CouchDB database at a specified URL already exists and, if not, to create it. This makes it an ideal tool for initial application setup, automated testing environments, or any scenario requiring a guaranteed database presence before operations begin. The current stable version is 2.1.0, released in October 2021, indicating a mature and stable codebase with an infrequent release cadence, typically driven by updates to its core dependencies like the `nano` CouchDB client. Unlike full-featured ORMs or database management tools, `couchdb-ensure` differentiates itself by its single-purpose API and a convenient command-line interface (CLI) for rapid database initialization, providing a lightweight and efficient solution without unnecessary overhead. It primarily utilizes CommonJS for module exports.

Common errors

```
TypeError: ensure is not a function
```
cause Attempting to use ES module `import` syntax with a CommonJS-exported default function without proper interop.

fix Change `import ensure from 'couchdb-ensure'` to `const ensure = require('couchdb-ensure')` for Node.js environments. If you must use ESM syntax, consider `import ensure = require('couchdb-ensure')` in TypeScript, or a bundler configured for CJS interop.
```
Error: connect ECONNREFUSED 127.0.0.1:5984
```
cause The CouchDB server is not running or is unreachable at the specified address and port.

fix Ensure your CouchDB instance is running. Check the URL provided to `couchdb-ensure` (e.g., `http://localhost:5984`) for correctness. Verify no firewall is blocking access if connecting to a remote server.

Warnings

breaking Version 2.0.0 introduced breaking changes due to an upgrade of the underlying `nano` client from `^6.4.3` to `^9.0.3` and `nano-option` from `^1.3.0` to `^2.0.0`. This could impact how `nano` is configured or how certain options are passed, requiring review of the `nano` documentation.
Fix: Review the official `nano` client documentation for version 9.x to understand changes in API, configuration, and options. Adjust any direct `nano` configuration passed to `couchdb-ensure` if it relies on older `nano` patterns.
gotcha `couchdb-ensure` is primarily designed for CommonJS (CJS) environments and uses `require()` for module loading. Attempting to use `import` statements directly in an ESM environment without proper Node.js configuration or transpilation may lead to module resolution errors.
Fix: For CommonJS, use `const ensure = require('couchdb-ensure')`. For ESM, ensure your `package.json` has `"type": "module"` and consider using an explicit `createRequire` from `module` or a bundler that handles CJS-to-ESM conversion, or stick to the CLI for simple use cases.
gotcha The library relies on `nano` for connectivity. If the CouchDB server is not running, is inaccessible, or credentials are incorrect (if required), `couchdb-ensure` will return connection errors, not just database not found errors.
Fix: Verify that your CouchDB server is running and accessible at the specified URL (`http://localhost:5984` is common). Ensure any necessary authentication details are included in the URL or passed via `nano` options if the CouchDB instance requires them. Check network firewalls if running remotely.

Install

npm install couchdb-ensure npm
yarn add couchdb-ensure yarn
pnpm add couchdb-ensure pnpm

Imports

ensure
wrong:
```
import ensure from 'couchdb-ensure'
```
correct:
```
const ensure = require('couchdb-ensure')
```
The library primarily exposes a default CommonJS export. Direct `import` syntax will likely fail without a transpiler or specific Node.js ESM configuration that allows CJS interop.
CLI usage
```
couchdb-ensure http://localhost:5984/mydb
```
The package also provides a command-line interface for quick database creation, making it useful for shell scripts or quick setups.

Quickstart

This example demonstrates how to use `couchdb-ensure` with both a traditional callback and an `async/await` pattern (using `promisify`) to ensure a CouchDB database exists, including basic error handling.

const ensure = require('couchdb-ensure');

// Basic usage with callback
ensure('http://localhost:5984/my_app_db', (error, response) => {
  if (error) {
    console.error('Error ensuring database:', error);
    // Handle specific errors, e.g., connection issues, authentication failures
    if (error.code === 'ECONNREFUSED') {
      console.error('CouchDB server not running or wrong URL.');
    }
    return;
  }
  console.log('Database ensured:', response);
  // response will contain { ok: true } if created or if it already existed
});

// For an async/await pattern (requires promisify or wrapper)
const { promisify } = require('util');
const ensurePromise = promisify(ensure);

async function setupDatabase() {
  try {
    const response = await ensurePromise('http://localhost:5984/another_db');
    console.log('Another database ensured successfully:', response);
  } catch (error) {
    console.error('Failed to ensure another database:', error);
  }
}

// setupDatabase();

view raw JSON →