couchinator
Fixtures for CouchDB and IBM Cloudant.
Setup and teardown CouchDB and IBM Cloudant databases with ease. couchinator is a great tool for unit/integration 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 = ; const couchinator = 'http://127.0.0.1:5984'; // Each of the following methods return a promisecouchinator;couchinator;couchinator;
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.jsonclassrooms _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
-
Create two folders, one for
users
and another forclassrooms
.users/classrooms/Note: Couchinator will use the folder name as the database name
-
Within each folder optionally create a
_design
folder to store any design documentsusers/_design/classrooms/_design/ -
Create design document(s) and store them in the appropriate
_design
folderIn the example below, we create two design documents in the
schools
database and one in theusers
database.users/_design/students.jsonteachers.jsonclassrooms/_design/classrooms.jsonThe contents of each design document
.json
must be a valid CouchDB design document.For example,
students.json
: -
Create the data to store in each database
- Data must be represented using CouchDB's bulk document format
- The data may be represented in a single JSON file or spread across multiple JSON files (useful for organizing data)
users/_design/students.jsonteachers.jsonstudents-docs.json # contains student datateachers-docs.json # contains teacher dataclassrooms/_design/classrooms.jsonusers-docs.jsonFor example,
student-docs.json
contains students -
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:MYPASSWORD@MYACCOUNT.cloudant.com';url;
Account
const url = 'https://MYUSERNAME:MYPASSWORD@MYACCOUNT.cloudant.com'; 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 = ;const path = ; // Define the directory that contains our db resourcesconst resourcePath = path; const c = '<YOUR-DB-URL>' ;
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 ./fixtures -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