nano

To perform operations on a specific database (like inserting documents or fetching data), use nano.use(name). This returns a database object that provides access to Document Functions.

Note: nano.db.use(name), nano.db.scope(name), and nano.scope(name) are all aliases for nano.use(name).

const alice = nano.use('alice');
await alice.insert({ happy: true }, 'rabbit')

Nano supports CouchDB's cookie authentication. If you initialize Nano to be cookie-aware, you can call nano.auth(username, userpass) to establish a session. Nano will automatically manage and refresh the AuthSession cookie for subsequent requests, behaving like a web browser.

You can check your current permissions/session by calling nano.session().

const nano = require('nano')({
  url: 'http://127.0.0.1:5984'
})
const username = 'user'
const userpass = 'pass'
const db = nano.db.use('mydb')

// Authenticate and establish session cookie
await nano.auth(username, userpass)

// Subsequent requests are automatically authenticated
const doc = await db.get('mydoc')

// Check session info
const session = await nano.session()

Nano 11 uses the native Node.js fetch API as its HTTP client, which requires Node.js 20 or newer.

• Use Nano 11 if you are running Node.js 20+.
• Use Nano 10 if you must support Node.js 18 or older.

Install the nano library using npm. Note that the minimum required Node.js version is 10.

Important Compatibility Note: Nano version 11.0.0 and later is a breaking change for Node.js versions 16 and older. Nano 11 uses the built-in fetch HTTP client, which requires Node.js 18 or later. If you are using Node 16 or older, you must continue using Nano 10.

npm install nano
# or
npm install --save nano

Nano 11 has removed support for callbacks. All asynchronous operations now return Promises. If your existing codebase relies on passing a callback as the last argument to Nano functions, you must refactor your code to use .then() or the await pattern to avoid breakage.

// Using .then()
db.list().then((data) => { console.log('response', data )})

// Using await
const data = await db.list()
console.log('response', data)

Nano includes built-in TypeScript definitions. You can import the Nano namespace to type your own classes and handle API responses (like DocumentInsertResponse) with full type safety.

import * as Nano from 'nano';

let n = Nano('http://127.0.0.1:5984');
let db = n.db.use('people');

interface iPerson extends Nano.MaybeDocument {
  name: string;
  dob: string;
}

class Person implements iPerson {
  _id: string;
  _rev: string;
  name: string;
  dob: string;

  constructor(name: string, dob: string) {
    this._id = undefined;
    this._rev = undefined;
    this.name = name;
    this.dob = dob;
  }

  processAPIResponse(response: Nano.DocumentInsertResponse) {
    if (response.ok === true) {
      this._id = response.id;
      this._rev = response.rev;
    }
  }
}

To use nano, connect it to your CouchDB instance by passing the server URL to the require('nano') function.

Note: Supplying authentication credentials directly in the URL (e.g., http://admin:password@localhost:5984) is deprecated. Use nano.auth instead.

Most operations are asynchronous and return native Promises. You can use .then().catch() or the async/await pattern.

const nano = require('nano')('http://127.0.0.1:5984');

// Create a new database
await nano.db.create('alice');

// Use an existing database
const alice = nano.db.use('alice');

// Insert a document
const response = await alice.insert({ happy: true }, 'rabbit');

When instantiating Nano, you can provide a log function to capture requests and responses. You can pass console.log directly or provide a custom function to format the data.

// Simple logging
const nano = Nano({ url: process.env.COUCH_URL, log: console.log });

// Custom formatted logging
const logger = (data) => {
  // data contains err, uri, method, qs, headers, body, etc.
  if (typeof data.err === 'undefined') {
    console.log(data.method, data.uri);
  } else {
    console.log('ERR', data.err.statusCode);
  }
};
const nano = Nano({ url: process.env.COUCH_URL, log: logger });