README for lscouchdb commands

Usage of commands

Some of commands have the following common options.

Common Option: -d

This option turns on the debug message output.

Common Option: -u (default: 15)

If a request is sent to the /_all_docs or /_bulk_docs interface, the whole request is split by the number of the "unit."

/dbname/_all_docs?limit=15&skip=0
/dbname/_all_docs?limit=15&skip=15
/dbname/_all_docs?limit=15&skip=30
...

Common Option: -f (default: -)

If the command inputs something from the stream, you can toggle stdin and file by this option.

The '-' value means the standard input, others are used as a filename.

Common Option: -o (default: -)

If the command outputs something to the stream, you can toggle stdout and file by this option.

The '-' value means the standard output, others are used as a filename which will be overwritten.

Common Option: -x

If the command uses the YAML configuration file, you can specify the label name by this option.

If non-existence label is specified, then the following message will be shown.

{"error":"bad label","reason":"not found yaml_label"}

Common Option: -y

If the command uses the YAML configuration file, you can set the path of the YAML file by this option.

The path should be the absolute path or relative path from the current directory.

sbin/mkdb

"mkdb" creates the new database.

./mkdb dbname

Successful message;

{"ok":true}

Error message when the existing dbname is set;

{"error":"undefined","reason":"unknown"}

sbin/rmdb

"rmdb" deletes the existing database.

./rmdb dbname

Successful message;

{"ok":true}

Error message when the non-existing dbname is set;

{"error":"not exist","reason":"database, xxx, not found"}

sbin/lsdbs

"lsdbs" shows the list of the existing databases.

./lsdbs

Successful message;

{"database":[
  "_users",
]}

sbin/senduri

"senduri" shows the result of the request using the YAML configuration file.

./senduri /test01/_all_docs

sbin/sendurl

"sendurl" shows the result of the request by the URL. It does not use the YAML configuration file.

./sendurl http://localhost:5984/_all_dbs

It is almost same as the curl or wget command, but this command uses URI#escape method. You do not need to escape the request string by hand.

sbin/encpassword

"encpassword" generates encrypted password string which can be used for the YAML configuration file.

It also generates the common key file to the default path.

./encpassword -i

If there is a common key file at the path already, following message is shown.

[error] first remove the password file, filename}.

To encrypt your password, xxxx, then type as the following.

./encpassword -p xxxx

You can also use the standard input in the following way.

echo xxxx | ./encpassword -p

"encpassword -p" command will display the salt and encrypted-text string.

salt: 4750509c5e957ceb
encrypted-text: 9c6b1269d20c76500baa273ac6b42444

The '-m' option changes the common key file path.

./encpassword -m a.json -i

or

echo '{"sec_text":"xxxx"}' > a.json
./encpassword -m a.json -p xxxx

sbin/decpassword

"decpassword" is a special tool to check the output of the encpassword command.

./decpassword -s 4750509c5e957ceb -t 9c6b1269d20c76500baa273ac6b42444

The -m option change the a.json file.

./encpassword -m a.json -s 380bcfe610c89f13 -t 782d84e665aa83c3fc6d0da924ae28d0

bin/lsdoc

lsdoc uri [-y yaml_conf] [-x yaml_label] [-d] [-h]

"lsdoc" is almost same as the "sbin/senduri" command.

bin/lsdocs

lsdocs dbname [-p page] [-u unit] [-i] [-d] [-y] [-x] [-h]

"lsdocs" shows all documents of the database by the /dbname/_all_docs interface.

To optimize performance, "lsdocs" uses skip and limit parameters in the internal processing.

-i option

"lsdocs -i" shows the following line instead of the entire document.

{"id":"0000d2ffaec59775230e9cd8bca446dfb3a52f7b","key":"0000d2ffaec59775230e9cd8bca446dfb3a52f7b","value":{"rev":"4-e22f4a5f94b81837161db5ed1e19ce61"}}

-p option (default: 1)

"lsodcs -p" sets the beginning page number.

"lsdocs test01 -p 2 -u 15" sends requests like the following.

/test01/_all_docs?limit=15&skip=15
/test01/_all_docs?limit=15&skip=30
....

-m option

"lsdocs -m" shows only the total number of documents.

"./lsdocs test01 -m" shows the following output.

{"max_numrows":11}

bin/grepjson

grepjson '["key1","value1"]' '["key2","value2"]' ... [-r] [-i] [-v] [-f file] [-d] [-h]

"grepjson" searches the inputs for lines containing specified condition.

The condition is JSON arrays and specified by the multiple keys and one value pair, such as ["key1","key2",.."value"].

$ echo '{"a":"1","b":{"c":30}}' | ./grepjson '["a","1"]'
> {"a":"1","b":{"c":30}}

$ echo '{"a":"1","b":{"c":30}}' | ./grepjson '["a","b"]'
>

$ echo '{"a":"1","b":{"c":30}}' | ./grepjson '["b","c",30]'
> {"a":"1","b":{"c":30}}

If multiple conditions are used, all condition must be match for the output.

$ echo '{"a":"1","b":{"c":30}}' | ./grepjson '["b","c",30]' '["a","1"]'
> {"a":"1","b":{"c":30}}

$ echo '{"a":"1","b":{"c":30}}' | ./grepjson '["b","c",30]' '["a","2"]'
>

-r option - regular expression

"grepjson -r" evaluates the value as the regular expression.

The following command line will output only design documents.

$ echo '{"a":"1","b":{"c":30}}' | ./grepjson '["b","c","^[123]0$"]' -r
> {"a":"1","b":{"c":30}}

-i option - ignore case

"grepjson -i" ignores the case in the value string and implies the -r option is true.

$ echo '{"a":"1","b":{"c":"d"}}' | ./grepjson '["b","c","D"]' -i
> {"a":"1","b":{"c":"d"}}

-v option - invert mode

"grepjson -v" outputs the exclude results like the grep command.

The following command line excludes the design documents and shows all documents without design documents.

$ echo '{"a":"1","b":{"c":"d"}}' | ./grepjson '["b","c","D"]' -v
> {"a":"1","b":{"c":"d"}}

bin/chjson

chjson '[key1,key2,..,value]' ... [-f file] [-o outfile] [-d]

"chjson" adds or overwrites the given key-value pair into each line.

The following command line will add the delete flag for /_bulk_docs api.

$ echo '{"a":"1","b":{"c":"d"}}' | ./chjson '["_deleted",true]'
> {"a":"1","b":{"c":"d"},"_deleted":true}

$ echo '{"a":"1","b":{"c":"d"}}' | ./chjson '["b","c",[1,2,3]]'
> {"a":"1","b":{"c":[1,2,3]}}

bin/reducejson

"reducejson" pulls out some key-value pairs to construct new json line.

$ echo '{"_id":"xxx","_rev":"yyy","name":"zzz"}' | ./reducejson '["_id","name"]'
> {"_id":"xxx","name":"zzz"}

-e option - exclude mode

"reducejson -e" removes key-value pairs from the given list.

$ echo '{"_id":"xxx","_rev":"yyy","name":"zzz"}' | ./reducejson '["_rev"]' -e
> {"_id":"xxx","name":"zzz"}

bin/putdesign

putdesign dbname docname [-f file] [-o outfile] [-d] [-y] [-x]

"putdesign" puts a single reading data into the given path, /dbname/docname.

$ echo '{"views":{"all":{"map":"function(doc) { emit(doc._id,null); }"}}}' | ./putdesign test all
> {"views"=>{"all"=>{"map"=>"function(doc) { emit(doc._id,null); }"}}}

echo '{"validate_doc_update":"function(newDoc, oldDoc, userCtx) { if(newDoc.name === undefined) { throw ({forbidden:\"document must have an name.\"});} }"}' | ./putdesign test auth
> {"validate_doc_update"=>"function(newDoc, oldDoc, userCtx) { if(newDoc.name === undefined) { throw ({forbidden:\"document must have an name.\"});} }"}

bin/putdoc

putdoc uri [-f file] [-y yaml_conf] [-x yaml_label] [-d] [-h]

"putdoc" puts a single reading data to the couchdb server.

$ echo '{"admins":{"names":[],"roles":["dbwriter"]},"readers":{"names":[],"roles":["dbreader"]}}' | ./putdoc /test/_security
> {"ok":true}

bin/putdocs

putdocs dbname [-f file] [-o outfile] [-u num_of_unit] [-y yaml_file] [-x yaml_label] [-d] [-h]"

"putdocs" puts the input json stream to /_bulk_docs.

$ echo -e '{"name":"foo"}\n{"name":"bar"}' | ./putdocs test
$ ./lsdocs test
> {"_id":"bd670757cacde00b29fe777490012d3a","_rev":"1-bc98e8ae0f9c89fbc8c237dfc9bfe478","name":"foo"}
> {"_id":"bd670757cacde00b29fe777490013b00","_rev":"1-62bc3c4d01e43ee9d0cead8cd7c76041","name":"bar"}

The following commands delete some documents from the "test" database.

$ ./lsdocs test| ./chjson '["_deleted",true]' | ./putdocs test
$ ./lsdocs test
>

The failed documents will be outputted to the standard output.

All internal errors will be outputted to the standard error.

bin/lsviews

lsviews dbname designname viewname [[-k key] | [-s startkey] [[-e endkey]]] [-r] [-g] [-u unit] [-p page] [-m] [-i] [-d] [-y yaml_conf] [-x yaml_label] [-h]

"lsviews" shows all documents of the specified view.

$ ./lsviews test all all 
> {"_id"=>"bd670757cacde00b29fe77749001488e", "_rev"=>"1-bc98e8ae0f9c89fbc8c237dfc9bfe478", "name"=>"foo"}
> {"_id"=>"bd670757cacde00b29fe7774900153bc", "_rev"=>"1-62bc3c4d01e43ee9d0cead8cd7c76041", "name"=>"bar"}

-k -s, -e option

Query options, key, startkey and endkey, are used respectively.

-r option

The reverse=true query option will be enabled.

If using startkey and/or endkey, the value will be inverted.

-g option

The group=true query option will be enabled.

-m option

"lsviews -m" shows only the total number of documents.

"./lsviews test all all -i -m" shows the following output.

{"max_numrows":2}

bin/csv2json

csv2json filename [-s sep] [-d] [-h]

For supporting the data input, "csv2json" converts the given csv file into the JSON format.

• The first line is treated as the key list of the JSON.
• The end of each line must not be terminated by the null value, such as ,,.
• The number of columns of each line must be same.

-s option (default: ",")

Set the row delimiter character.

Example 1

| key1 | key2 | 
|=============|  => {key1:val1,key2:val2}
| val1 | val2 |
+-------------|

$ echo -e "key1,key2\nval1,val2" | ./csv2json
> {"key1":"val1","key2":"val2"}

Example 2

| key1 | key2 | 
|=============|   => key1:{key2:val1}
|      | val1 |
+-------------+

$ echo -e "key1,key2\n,val2" | ./csv2json
> {"key1":{"key2":"val2"}}

Example 3

| key1 | 
|======|
| val1 |   => key1:[val1,val2]
|------|
| val2 |
+------+

$ echo -e "key1\nval1\nval2" | ./csv2json
> {"key1":["val1","val2"]}

For the bulk update, the '-n' option process by each line.

$ echo -e "key1\nval1\nval2" | ./csv2json -n
> {"key1":"val1"}
> {"key1":"val2"}

Example 4 - Setting up security roles

admin,names,admin,roles,reader,names,reader,roles
,"",,fwadmin,,"",,fwreader
,"",,fwwriter,,"",,fwreader

$ echo -e 'admin,names,admin,roles,reader,names,reader,roles\n,"",,fwadmin,,"",,fwreader\n,"",,fwwriter,,"",,fwreader' | ./csv2json | ./putdoc /test/_security
$ ./lsdoc /test/_security
> {"admin":{"names":[""],"roles":["fwadmin","fwwriter"]},"reader":{"names":[""],"roles":["fwreader"]}}

Example 5 - Setting up map and reduce methods

$ cat a.csv
"_id","language","views","all","map","views","all","reduce"
"_design/all","javascript",,,"function(doc) {
  if (doc.type && doc.type == ""log"") {
    emit(doc,null);
  }
}",,,"_count"

$ ./csv2json a.csv | ./putdesign test all

bin/jsonfmt

The "jsonfmt" format each input json string to human readable json format.

The output of the "jsonfmt" cannot be used for an input of other command, such as putdocs.

$ ./lsdocs test
{"_id":"bd670757cacde00b29fe77749001488e","_rev":"1-bc98e8ae0f9c89fbc8c237dfc9bfe478","name":"foo"}
{"_id":"bd670757cacde00b29fe7774900153bc","_rev":"1-62bc3c4d01e43ee9d0cead8cd7c76041","name":"bar"}
{"_id":"bd670757cacde00b29fe77749001583c","_rev":"1-49ce25e3db701c8cb613c1fd18d99619","name":"test"}

$ ./lsdocs test | ./jsonfmt
{
  "_id":  "bd670757cacde00b29fe77749001488e",
  "_rev":  "1-bc98e8ae0f9c89fbc8c237dfc9bfe478",
  "name":  "foo"
}
{
  "_id":  "bd670757cacde00b29fe7774900153bc",
  "_rev":  "1-62bc3c4d01e43ee9d0cead8cd7c76041",
  "name":  "bar"
}
{
  "_id":  "bd670757cacde00b29fe77749001583c",
  "_rev":  "1-49ce25e3db701c8cb613c1fd18d99619",
  "name":  "test"
}

License

Copyright (C) 2010,2011 Yasuhiro ABE <yasu@yasundial.org>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

EOF