couchinator

couchinator

Fixtures for CouchDB and IBM Cloudant.

Setup and teardown CouchDB and IBM Cloudant databases with ease. couchinator is a great tool for unit testing and more. couchinator is both a library and a command line utility.

See it in action

Represent your database(s) as a set of folders and files and couchinator takes care of the rest.

See the Data Layout section for information on how to represent your database with couchinator.

Install

npm install couchinator

Global installation is convenient when using the CLI

npm install couchinator -g

If you're a Java user, try this

Use the CLI

couchinator create --url http://127.0.0.1:5984 --path ./fixtures

Create

couchinator create --url <COUCHDB-OR-CLOUDANT-URL> --path <RESOURCE_PATH>

Destroy

couchinator destroy --url <COUCHDB-OR-CLOUDANT-URL> --path <RESOURCE_PATH><br>

Recreate

couchinator recreate --url <COUCHDB-OR-CLOUDANT-URL> --path <RESOURCE_PATH>

Note: RESOURCE_PATH may be absolute path or a path relative to the current working directy

Use the Library

Basic Usage

const Couchinator = require('couchinator');

const couchinator = new Couchinator('http://127.0.0.1:5984').resources(
  './fixtures'
);

// The following methods return promises
couchinator.create();
couchinator.recreate();
couchinator.destroy();

see Advanced Usage for more library customization options

Data Layout

The following sections describe how to create a data layout.

To skip directly to a working example, go here

Getting Started

Couchinator enables you to represent CouchDB and Cloudant database(s) using a simple filesystem structure that mimics the actual database structure.

A couchinator filesystem data layout might look as such:

users
    _design
        students.json
	 teachers.json
    students-docs.json
    teachers-docs.json
classrooms
    _design
        classrooms.json
        classrooms-docs.json

Create a data layout representing 2 databases

Let's create a data layout to describe two databases users and classrooms

1. Create two folders, one for users and another for classrooms.

   users/
   classrooms/
   

   Note: Couchinator will use the folder name as the database name

2. Within each folder optionally create a _design folder to store any design documents

   users/
       _design/
   classrooms/
       _design/
   

3. Create design document(s) and store them in the appropriate _design folder

   In the example below, we create two design documents in the schools database and one in the users database.

   	```shell
   	users/
   	    _design/
   	        students.json
   	        teachers.json
   	classrooms/
   	    _design/
   	        classrooms.json
   	```
   
   	The contents of each design document `.json` must be a valid CouchDB [design document]([design document](http://docs.couchdb.org/en/2.0.0/json-structure.html#design-document)).
   
   	For example, `students.json`:
   

   {
     "_id": "_design/students",
     "views": {
       "byId": {
         "map": "function (doc) {  if (doc.type === 'student') emit(doc._id, doc);}"
       }
     },
     "language": "javascript"
   }
   

4. Create the data to store in each database

   • Data must be stored using CouchDB's bulk document format
   • The data may be stored in a single JSON file or spread across multiple JSON files (useful for organizing data)

   users/
       _design/
           students.json
           teachers.json
       students-docs.json   # contains student data
       teachers-docs.json   # contains teacher data
   
   classrooms/
       _design/
           classrooms.json
       users-docs.json
   

For example, student-docs.json contains students

{
  "docs": [
    {
      "_id": "sam895454857",
      "name": "Sam C.",
      "type": "student"
    },
    {
      "_id": "josie895454856",
      "name": "Josie D.",
      "type": "student"
    }
  ]
}

1. Run couchinator to create each database

   Assuming the data layout is stored in the folder ./fixtures, run the following command(s):

   couchinator create --url http://127.0.0.1:5984 --path ./fixtures
   

Data Layout Example

To view a complete data layout example, see examples/db-resources.

To run the the example:

• clone this repo
• cd examples
• edit examples.js and set <CLOUDANT-URL> to your cloudant url
• Run node example
• Your database should now contain documents

Library Initialization

var cloudant = Cloudant({account:me, password:password}); If you would prefer, you can also initialize Cloudant with a URL:

Cloudant Url

const url = 'https://MYUSERNAME:[e-mail]';
new Couchinator(url);

Account

const url = 'https://MYUSERNAME:[e-mail]';
new Couchinator({ account: me, password: password });

Advanced Usage

The couchinator library enables a variety of customizations, including the ability to provide a custom visitor to configure exactly what log information is output.

const Generator = require('couchinator');
const path = require('path');

// Define the directory that contains our db resources
const resourcePath = path.join(process.cwd(), 'db-resources');

const c = new Couchinator('<YOUR-DB-URL>')
  .resources(resourcePath)
  .visitor(e => {
  		if (e.level >= 30) console.log(e.msg);
	})
  .configure();

Apis

• couchinator create

  Creates all databases, design documents, and executes any bulk documents represented in the data layout. If a design document exists, the design document is updated to reflect the version currently represented in the data layout.

  Using the --ddocsonly flag skips any bulk documents. This flag is particulary useful when you simply want to add/update design documents.

• couchinator destroy

  destroys all databases represented in the data layout.

• couchinator rcreate Calls destroy followed by create.

See CLI Usage section for additional arguments.

CLI Usage

Currently, the CLI only support a Cloudant URL.

> couchinator
  Usage: couchinator [options] [command]


  Commands:

    create
    recreate
    destroy

  Options:

    -h, --help        output usage information
    -V, --version     output the version number
    -u --url <url>    couchdb url
    -p --path <path>  resource path. Default ./cloudant-database
    -b --verbose      verbose logs
    -d --ddocsonly    import design docs only. Do no import other docs

TODO / Errata

• if design doc name doesnt match its file name, we get a null crash

License

Apache 2.0