{"id":16317,"library":"couchdb-ensure","title":"CouchDB Database Ensurer","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/jo/couchdb-ensure","tags":["javascript","couchdb","bootstrap"],"install":[{"cmd":"npm install couchdb-ensure","lang":"bash","label":"npm"},{"cmd":"yarn add couchdb-ensure","lang":"bash","label":"yarn"},{"cmd":"pnpm add couchdb-ensure","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core CouchDB client library used for all database interactions.","package":"nano","optional":false},{"reason":"Provides options and configuration utilities for the `nano` client.","package":"nano-option","optional":false}],"imports":[{"note":"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.","wrong":"import ensure from 'couchdb-ensure'","symbol":"ensure","correct":"const ensure = require('couchdb-ensure')"},{"note":"The package also provides a command-line interface for quick database creation, making it useful for shell scripts or quick setups.","symbol":"CLI usage","correct":"couchdb-ensure http://localhost:5984/mydb"}],"quickstart":{"code":"const ensure = require('couchdb-ensure');\n\n// Basic usage with callback\nensure('http://localhost:5984/my_app_db', (error, response) => {\n  if (error) {\n    console.error('Error ensuring database:', error);\n    // Handle specific errors, e.g., connection issues, authentication failures\n    if (error.code === 'ECONNREFUSED') {\n      console.error('CouchDB server not running or wrong URL.');\n    }\n    return;\n  }\n  console.log('Database ensured:', response);\n  // response will contain { ok: true } if created or if it already existed\n});\n\n// For an async/await pattern (requires promisify or wrapper)\nconst { promisify } = require('util');\nconst ensurePromise = promisify(ensure);\n\nasync function setupDatabase() {\n  try {\n    const response = await ensurePromise('http://localhost:5984/another_db');\n    console.log('Another database ensured successfully:', response);\n  } catch (error) {\n    console.error('Failed to ensure another database:', error);\n  }\n}\n\n// setupDatabase();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use ES module `import` syntax with a CommonJS-exported default function without proper interop.","error":"TypeError: ensure is not a function"},{"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.","cause":"The CouchDB server is not running or is unreachable at the specified address and port.","error":"Error: connect ECONNREFUSED 127.0.0.1:5984"}],"ecosystem":"npm"}