Skip to content
Newer
Older
100644 268 lines (222 sloc) 6.29 KB
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
1 # PJsonCouch
2
3 (PJs-on-Couch) is a [node.js](http://nodejs.org/) client lib for [CouchDB](http://couchdb.apache.org/).
4
5 PJsonCouch it means Pure-Json-on-Couch but it should be read PJs-on-Couch :)
6
7 ## Why.
8 The main idea is to use as most as possible [JSON](http://www.json.org/) for data transport.
9
10 For example the CouchDB URL invocation:
11
12 /developers/_design/basic_info/_view/by_name?reduce=false&key="Jane"
13
14 translates to:
15
16 {db:"developers",design:"basic_info",view:"by_name",args:{reduce:false,key:"Jane"}}
17
18 With this method we can send all data necessary to query views in the same structure:
19
20 {db:"developers",design:"basic_info",view:"by_name",args:{reduce:false},request:{keys:["Jane"]}}
21
22
23 PJsonCouch requires knowing the [CouchDB API](http://techzone.couchbase.com/sites/default/files/uploads/all/documentation/couchbase-api.html) and does not intend to overcome the logic behind the original API.
24
25 ## How is PJsonCouch organized?
26
27 PJsonCouch is inspired on the CouchDB HTTP API structure, so is divide in 4 main blocks
28
29 * Database Methods.
30 * Document Methods / Local (non-replicating) Document Methods
31 * Design Document Methods
32 * Miscellaneous Methods
33
34
35
36 ## Examples
37
38 How to connect to CouchDB without db definition and request a complex query to `_all_docs`
39
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
40 ``` js
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
41 // Constructor without db definition
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
42 var test = PJsonCouch({
43 host : "127.0.0.1",
44 port : 5984
45 });
46
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
47 // set a DB, this does not have callbackfuntion
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
48 test.setDB({
49 db : "thisisatempdb"
50 });
51
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
52 // Login if your DB is protected
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
53 test.login({
54 user : "landeiro",
55 password : "123"
56 }, function(r) {
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
57 // Get all docs from DB, supports all args and request data from original couchdb API
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
58 test.queryDB({
59 action : "_all_docs",
60 args : {
61 descending : true,
62 startkey : "objmyid6",
63 endkey : "objmyid2"
64 }
65 }, function(r) {
66 log("*queryDB start/endkey*", r);
67 });
68 test.queryDB({
69 action : "_all_docs",
70 request : {
71 keys : ["objmyid1", "objmyid7"]
72 }
73 }, function(r) {
74 log("*queryDB keys*", r);
75 });
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
76 });
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
77 ```
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
78
79 How to connect to CouchDB with db definition and execute some docs operations
80
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
81 ``` js
82 var test = PJsonCouch({
83 host : "127.0.0.1",
84 port : 5984,
85 db : "mydatabase"
86 });
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
87
88 // Docs for test
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
89 var docs = [{
90 _id : "objmyid0",
91 a : 0
92 }, {
93 _id : "objmyid1",
94 a : 1
95 }, {
96 _id : "objmyid2",
97 a : 3
98 }];
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
99
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
100 // Save bulk, supports all request data from original couchdb API
101 test.saveBulkDocs({
102 docs : docs
103 }, function(r) {
104 log("insert bulk", r);
105 // Get Doc, supports all arguments from original couchdb API
106 test.getDoc({
107 id : "objmyid0"
108 }, function(gdoc) {
109 log("*get doc*", gdoc)
110 if(!gdoc.error) {
111 // Delete a Doc, supports all arguments from original couchdb API
112 test.deleteDoc({
113 doc : gdoc
114 }, function(r) {
115 log("*deleted " + gdoc._id + "*", r);
116 });
117 }
118 });
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
119 });
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
120 ```
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
121
122
123
124 Some random server operations
125
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
126 ``` js
127 test.server({}, function(r) {
128 log("*welcome msg*", r);
129 });
130
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
131 // Show active tasks
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
132 test.server({
133 action : "_active_tasks"
134 }, function(r) {
135 log("*active tasks*", r);
136 });
137
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
138 // Start continuos replication database. Replication supports all configuration from original couchdb API
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
139 test.server({
140 action : "_replicate",
141 source : "thisisatempdb",
142 target : "http://somedomain.com/land",
143 continuous : true
144 }, function(r) {
145 log("*replicate*", r);
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
146 // Cancel continuos replication database, supports all configuration from original couchdb API
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
147 test.server({
148 action : "_replicate",
149 source : "thisisatempdb",
150 target : "http://somedomain.com/land",
151 continuous : true,
152 cancel : true
153 }, function(r) {
154 log("*cancel replication*", r);
155 })
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
156 });
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
157 ```
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
158
159 Some random design doc operations
160
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
161 ``` js
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
162 // List customers using view by_name from "Jane" to "Pedro"
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
163 test.queryDesign({
164 design : "design_doc",
165 list : "customers",
166 view : "by_name",
167 args : {
168 startkey : "Jane",
169 endkey : "Pedro"
170 }
171 }, function(r) {
172 log("*get list with view with args*", r);
173 });
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
174 // Display a Doc using Show costumer, supports all arguments from original couchdb API
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
175 test.queryDesign({
176 design : "design_doc",
177 show : "customer",
178 id : "3535e007bd9c765de0554c0a4900385b"
179 }, function(r) {
180 log("*get show*", r);
181 });
182 // Getting docs using view by_name with request keys ["Jane"] and argument limit=1
183 test.queryDesign({
184 design : "design_doc",
185 view : "by_name",
186 args : {
187 limit : 1
188 },
189 request : {
190 keys : ["Jane", "joey"]
191 }
192 }, function(r) {
193 log("*get view with request and args*", r);
194 });
195 ```
196
197 GeoCouch Integration
198
199 ``` js
200 // Make a bounding box request
201 test.queryDesign({
202 db : "places",
203 design : "main",
204 spatial : "points",
205 args : {
206 bbox : "0,0,180,90"
207 }
208 }, function(data) {
209 console.log(data);
210 });
211 ```
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
212
213 ### Errors can be configured to return a lot of debug, like request content and headers.
214
215 Cannot connect do CouchDB
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
216
217 ``` js
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
218 { error: 'request_to_couchdb',
219 detail:
220 { stack: 'Error: ECONNREFUSED, Connection refused\n at Socket._onConnect (net.js:576:18)\n at IOWatcher.onWritable [as callback] (net.js:165:12)',
221 message: 'ECONNREFUSED, Connection refused',
222 errno: 61,
223 code: 'ECONNREFUSED',
224 syscall: 'connect' },
225 debug:
226 { content: '""',
227 request:
228 { protocol: 'http',
229 host: '127.0.0.1',
230 port: 5984,
231 path: '/_log?bytes=2000',
232 method: 'GET',
233 headers: [Object],
234 agent: [Object] } } }
235
236 Unauthorized
237
238 { error: 'unauthorized',
239 reason: 'You are not a server admin.',
240 debug:
241 { content: '""',
242 request:
243 { protocol: 'http',
244 host: '127.0.0.1',
245 port: 5984,
246 path: '/_active_tasks',
247 method: 'GET',
248 headers: [Object],
249 agent: [Object],
250 content_type: 'text/plain;charset=utf-8',
251 content_length: '64' },
252 resultHeaders:
253 { server: 'CouchDB/1.1.1 (Erlang OTP/R14B)',
254 location: 'http://127.0.0.1/_utils/session.html?return=%2F_active_tasks&reason=You%20are%20not%20a%20server%20admin.',
255 date: 'Tue, 26 Apr 2011 11:47:53 GMT',
256 'content-type': 'text/plain;charset=utf-8',
257 'content-length': '64',
258 'cache-control': 'must-revalidate' } } }
53ff261 @landeiro Support for GeoCouch and bug fixes
authored Dec 3, 2011
259 ```
bb0f119 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
260
131f738 @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
261 See more examples [here](https://github.com/landeiro/PJsonCouch/wiki/PJsonCouch).
05554ab @landeiro Pure-Json-on-Couch
authored Apr 26, 2011
262
263 ## TODO
264
265 There are yet some CouchDB HTTP API methods to cover, that i'll hope to update as soon as possible.
266
267
Something went wrong with that request. Please try again.