Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100755 190 lines (142 sloc) 6.708 kb
13dd906 @cliffano Add avatar.
authored
1 <img align="right" src="https://raw.github.com/cliffano/couchpenter/master/avatar.jpg" alt="Avatar"/>
14942ce @cliffano Initial commit.
authored
2
0f28660 @cliffano Update badges.
authored
3 [![Build Status](https://secure.travis-ci.org/cliffano/couchpenter.png?branch=master)](http://travis-ci.org/cliffano/couchpenter)
4 [![Dependencies Status](https://david-dm.org/cliffano/couchpenter.png)](http://david-dm.org/cliffano/couchpenter)
3387274 @cliffano Add coverage status badge.
authored
5 [![Coverage Status](https://coveralls.io/repos/cliffano/couchpenter/badge.png?branch=master)](https://coveralls.io/r/cliffano/couchpenter?branch=master)
0f28660 @cliffano Update badges.
authored
6 [![Published Version](https://badge.fury.io/js/couchpenter.png)](http://badge.fury.io/js/couchpenter)
7 <br/>
8 [![npm Badge](https://nodei.co/npm/couchpenter.png)](http://npmjs.org/package/couchpenter)
9
10 Couchpenter
11 -----------
12
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
13 Couchpenter is a CouchDB database and document setup tool.
14
15 This is handy when you want to create or delete CouchDB databases and documents based on a predefined setup file, either from the command-line or programmatically.
16
17 A common usage scenario is to hook up Couchpenter to application start up code, ensuring CouchDB to have the required databases along with any data, design, and replication documents, before the server starts listening.
18
19 Another usage is for integration testing, either from test libraries (e.g. Mocha's beforeEach/afterEach), or from a Continuous Integration build pipeline (e.g. resetting the databases prior to running the test suites).
14942ce @cliffano Initial commit.
authored
20
21 Installation
22 ------------
23
24 npm install -g couchpenter
25
26 Usage
27 -----
28
0e5d6f0 @cliffano Revert config target back to init target, was renamed accidentally.
authored
29 Create a sample couchpenter.json setup file:
14942ce @cliffano Initial commit.
authored
30
31 couchpenter init
32
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
33 Execute a task against a CouchDB URL using default couchpenter.json setup file:
14942ce @cliffano Initial commit.
authored
34
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
35 couchpenter <task> -u http://user:pass@host:port
36
37 CouchDB URL can also be set via COUCHDB_URL environment variable:
38
39 (*nix)
40
41 export COUCHDB_URL=http://user:pass@host:port
42
43 (Windows)
44
45 set COUCHDB_URL=http://user:pass@host:port
14942ce @cliffano Initial commit.
authored
46
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
47 Execute a task using custom setup file:
48
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
49 couchpenter <task> -u http://user:pass@host:port -f somecouchpenter.json
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
50
51 Tasks:
ef0cc47 @cliffano Add teardown usage example.
authored
52
9505d8f @cliffano Add teardown-db and teardown-doc targets.
authored
53 <table>
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
54 <tr><th>Task</th><th>Description</th></tr>
7b3bbe2 @cliffano Update setup note with latest backward compatibility fix.
authored
55 <tr><td>setup</td><td>Create databases and documents, overwrite if documents exist.</td></tr>
9505d8f @cliffano Add teardown-db and teardown-doc targets.
authored
56 <tr><td>setup-db</td><td>Create databases only.</td></tr>
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
57 <tr><td>setup-doc</td><td> Create documents only, does not overwrite if exist.</td></tr>
58 <tr><td>setup-doc-overwrite</td><td>Create documents only, overwrite if exist.</td></tr>
59 <tr><td>teardown</td><td>Alias for teardown-db.</td></tr>
60 <tr><td>teardown-db</td><td>Delete databases.</td></tr>
61 <tr><td>teardown-doc</td><td>Delete documents.</td></tr>
62 <tr><td>reset</td><td>Alias for reset-doc.</td></tr>
63 <tr><td>reset-db</td><td>Delete then recreate databases and documents.</td></tr>
f69b4f4 @cliffano Add reset, reset-db, and reset-doc targets.
authored
64 <tr><td>reset-doc</td><td>Delete then recreate documents only.</td></tr>
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
65 <tr><td>clean</td><td>Alias for clean-db.</td></tr>
66 <tr><td>clean-db</td><td>Delete unknown databases (not configured in setup file).</td></tr>
9e485bb @cliffano Rename warm-view target and add doco.
authored
67 <tr><td>warm-view</td><td>Warm up views specified in design documents.</td></tr>
9505d8f @cliffano Add teardown-db and teardown-doc targets.
authored
68 </table>
ef0cc47 @cliffano Add teardown usage example.
authored
69
14942ce @cliffano Initial commit.
authored
70 Programmatically:
71
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
72 // use default couchpenter.json setup file
0b39711 @cliffano Fix sample usage documentation based on >= v0.0.8 . #2
authored
73 var couchpenter = new (require('couchpenter'))(
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
74 'http://user:pass@host:port'
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
75 );
76
77 // use custom setup file
0b39711 @cliffano Fix sample usage documentation based on >= v0.0.8 . #2
authored
78 var couchpenter = new (require('couchpenter'))(
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
79 'http://user:pass@host:port',
5a14ee8 @cliffano Change Couchpenter constructor from (url, setupFile, dir) to (url, opts)...
authored
80 { setupFile: 'somecouchpenter.json' }
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
81 );
82
620eb24 @cliffano Add dbSetup to Couchpenter opts to allow passing setup object as an alte...
authored
83 // use setup object (instead of setup file)
84 var couchpenter = new (require('couchpenter'))(
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
85 'http://user:pass@host:port',
620eb24 @cliffano Add dbSetup to Couchpenter opts to allow passing setup object as an alte...
authored
86 { dbSetup: {
87 "db1": [
88 { "_id": "doc1", "foo": "bar" },
89 { "_id": "doc2", "foo": "bar" },
90 "path/to/doc3file.json"
91 ]
92 }
93 }
94 );
95
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
96 // prefix the database names
97 // handy for running multiple tests in parallel without interrupting each other
0b39711 @cliffano Fix sample usage documentation based on >= v0.0.8 . #2
authored
98 var couchpenter = new (require('couchpenter'))(
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
99 'http://user:pass@host:port',
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
100 { prefix: 'testrun123_' }
101 );
102
103 // specify a base directory for the documents specified in setup file
0b39711 @cliffano Fix sample usage documentation based on >= v0.0.8 . #2
authored
104 var couchpenter = new (require('couchpenter'))(
12d76a1 @cliffano Add URL setting via COUCHDB_URL environment variable.
authored
105 'http://user:pass@host:port',
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
106 { dir: '../some/dir/' }
94e72d3 @cliffano Refactor couchpenter calls to be configurable.
authored
107 );
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
108
c0bc339 @cliffano Add Couchpenter#reset method.
authored
109 // set up databases and documents
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
110 couchpenter.setUp(function (err, results) {
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
111 });
112
c0bc339 @cliffano Add Couchpenter#reset method.
authored
113 // delete databases and documents
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
114 couchpenter.tearDown(function (err, results) {
14942ce @cliffano Initial commit.
authored
115 });
116
c0bc339 @cliffano Add Couchpenter#reset method.
authored
117 // delete databases and documents, then set up databases and documents
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
118 couchpenter.reset(function (err, results) {
c0bc339 @cliffano Add Couchpenter#reset method.
authored
119 });
120
5ec0325 @cliffano Add doco on using resetDocuments programatically.
authored
121 // delete documents, then set up documents
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
122 couchpenter.resetDocuments(function (err, results) {
5ec0325 @cliffano Add doco on using resetDocuments programatically.
authored
123 });
124
9e485bb @cliffano Rename warm-view target and add doco.
authored
125 // warm up all views specified in design documents
126 couchpenter.warmViews(function (err, results) {
127 });
128
b7a2995 @cliffano Add cron scheduling support to couchpenter#warmViews.
authored
129 // warm up all views specified in design documents every minute (scheduled)
130 couchpenter.warmViews('* * * * *', function (err, results) {
131 });
132
42328d4 @cliffano Update usage info with v0.2.0 changes.
authored
133 Check out [lib/couchpenter](https://github.com/cliffano/couchpenter/blob/master/lib/couchpenter.js) for other available methods.
134
14942ce @cliffano Initial commit.
authored
135 Configuration
136 -------------
137
b352a91 @cliffano Fix typo.
authored
138 Couchpenter setup file is just a simple JSON file:
14942ce @cliffano Initial commit.
authored
139
140 {
516e8f3 @cliffano Add replicator example.
authored
141 "db1": [
142 { "_id": "doc1", "foo": "bar" },
143 { "_id": "doc2", "foo": "bar" },
144 "path/to/doc3file.json"
145 ],
146 "db2": [
e2d257b @cliffano Simplify config file structure to db-docs mapping.
authored
147 { "_id": "doc4", "foo": "bar" },
148 "path/to/modulename"
516e8f3 @cliffano Add replicator example.
authored
149 ],
150 "db3": [],
151 "_replicator": {
152 {
153 "_id": "db1_pull",
154 "source": "http://user:pass@remotehost:5984/db1",
155 "target": "db1",
156 "user_ctx": {
157 "name": "user",
158 "roles": ["_admin"]
159 },
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
160 "continuous": true
516e8f3 @cliffano Add replicator example.
authored
161 }
162 }
14942ce @cliffano Initial commit.
authored
163 }
164
c76a2fb @cliffano Add more overview info, update samples to match refactored impl.
authored
165 Property keys are the names of the databases, property values are the documents in each database.
e2d257b @cliffano Simplify config file structure to db-docs mapping.
authored
166
167 A document can be represented as:
14942ce @cliffano Initial commit.
authored
168
b6bffc1 @cliffano Allow module path as configurable document property.
authored
169 * an object
170 * a file path string containing a JSON document, file name must end with .json
e2d257b @cliffano Simplify config file structure to db-docs mapping.
authored
171 * a module path string
172
e058725 @cliffano Add dependencies status badge.
authored
173 Paths are relative to current directory if it's used from command-line, or relative to opts.dir if it's used programmatically (defaults to current directory if opts.dir is not specified).
a1922dc @cliffano Add developer's guide link.
authored
174
175 Colophon
176 --------
177
cf0d937 @cliffano Add build reports links.
authored
178 [Developer's Guide](http://cliffano.github.io/developers_guide.html#nodejs)
179
180 Build reports:
181
182 * [Code complexity report](http://cliffano.github.io/couchpenter/bob/complexity/plato/index.html)
183 * [Unit tests report](http://cliffano.github.io/couchpenter/bob/test/buster.out)
184 * [Test coverage report](http://cliffano.github.io/couchpenter/bob/coverage/buster-istanbul/lcov-report/lib/index.html)
185 * [Integration tests report](http://cliffano.github.io/couchpenter/bob/test-integration/cmdt.out)
d86572d @cliffano Add related projects section.
authored
186 * [API Documentation](http://cliffano.github.io/couchpenter/bob/doc/dox-foundation/index.html)
187
188 Related Projects:
189
190 * [couchtato](http://github.com/cliffano/couchtato) - CouchDB documents iterator tool
Something went wrong with that request. Please try again.