Server

Server([href])

Represents a CouchDB server, and is used for executing actions that are generally administrative.

var couchdb = require("couchdb-api");

// the URL used below is the default
var srv = couchdb("http://localhost:5984");

Server#url([path])

This helper method is for generating a String URL for the server. If path is specified, it will resolve that path relative to the server root. path can also be an Array:String.

var base = srv.url();
// => http://localhost:5984/

var favicon = srv.url("favicon.ico");
// => http://localhost:5984/favicon.ico

var config = srv.url([ "_config", "log", "level" ]);
// => http://localhost:5984/_config/log/level

Server#db(name)

This helper method creates and returns a new Database object based on this Server.

var db = srv.db("_users");

Server#activeTasks(callback)

GET /_active_tasks CouchDB Documentation

Retrieves an Array:Object of information about tasks currently active/running on the server. This could include active replications, compactions or view index generation.

srv.activeTasks(function (err, tasks) {
    // ...
});

Server#allDbs(callback)

GET /_all_dbs CouchDB Documentation

Retrieves an Array:String of all available databases on this server. (will also include "system" databases like _users and _replicator)

srv.allDbs(function (err, dbs) {
    // ...
});

Server#config([section], [key], [value], callback)

GET /_config/{section}/{key} CouchDB Documentation

When value is excluded, it is assumed to be a get operation.

Note: value must be completely left out of the arguments list, not even as undefined or null.

srv.config(function (err, config) {
    // config => all server config
});

srv.config("log", function (err, config) {
    // config => all config listed under "log" section
});

srv.config("log", "level", function (err, config) {
    // config => the config value for log.level
});

PUT /_config/{section}/{key} CouchDB Documentation

When all 4 parameters are supplied, and value is not null, it is assumed to be a write operation.

// set the log.level config value to "info"
srv.config("log", "level", "info", function (err, results) {
    // ...
});

DELETE /_config/{section}/{key} CouchDB Documentation

// delete the log.level config
srv.config("log", "level", null, function (err, results) {
    // ...
});

Server#info(callback)

GET / CouchDB Documentation

Retrieves meta information about the server, which can include version information as well as relevant vendor details.

srv.info(function (err, info) {
    // ...
});

Server#log(query, callback)

GET /_log CouchDB Documentation

Retrieves the CouchDB log as a String. This API also allows you to select a specific range via the query options: bytes and offset.

// the defaults
var query = {
    bytes: 1000,
    offset: 0
};

srv.log(query, function (err, log) {
    // ...
});

Server#login(name, password, callback)

POST /_session CouchDB Documentation

Logs a user in via cookie authentication.

Note: The cookie is persisted for the user as part of the Client object, via superagent's "client" feature. This means that once you call login for a specific user, all subsequent requests from that object (and any objects that share the same client object) will have this user's userCtx applied.

srv.login("dominic", "123456", function (err, results) {
    // this `srv` (and any `db` or `doc` objects it begets) will share this session
});

Server#logout(callback)

DELETE /_session CouchDB Documentation

Ends a cookie-authentication (ie: after calling Server#login()) session.

srv.logout(function (err, results) {
    // ...
});

Server#register(name, info, callback)

PUT /_users/org.couchdb.user:{name} CouchDB Documentation

Creates a user document in the _users database for the specified user.

The info parameter must have at least password, but should also include roles. Beyond that, everything else will become part of the document when being stored.

// additional document info
var info = {
    password: "123456",
    roles: [ "some-role" ]
};

srv.register("dominic", info, function (err, result) {
    // ...
});

Server#restart(callback)

POST /_restart CouchDB Documentation

Restarts the CouchDB server. (must be logged in as an admin)

srv.restart(function (err, result) {
    // ...
});

Server#session(callback)

GET /_session CouchDB Documentation

Retrieves the user context object for this session.

srv.session(function (err, userCtx) {
    // this `srv` (and any `db` or `doc` objects it begets) will share this session
});

Server#stats([type], callback)

GET /_stats/{type} CouchDB Documentation

Retrieves statistical information about the CouchDB server. The type is optional, and can include multiple namespaces separated by /. (for example: "couchdb/request_time")

// return everything
srv.stats(function (err, stats) {
    // ...
});

// return a specific section
srv.stats("couchdb/request_time", function (err, stats) {
    // ...
});

Server#uuids([count], callback)

GET /_uuids CouchDB Documentation

Retrieves an Array:String of UUIDs, that way you don't have to generate them yourself.

Note: This API call strips away the container object from the response body. (ie: it does not return { uuids: [ ... ] }, instead it just gives you [ ... ])

// return 1 uuid
srv.uuids(function (err, uuids) {
    // ...
});

// return 10 uuids
srv.uuids(10, function (err, uuids) {
    // ...
});