YALTools | Top Page | Command Reference

1. Command Reference

1-1. Overview

1-2. Common options

Most of commands have the following options.

1-2-1. -h: Showing help messages

This option shows the all available options.

$ ./lsdocs --help
  Usage: lsdocs dbname [-p page] [-u unit] [-i] [-d] [-y] [-x]

    -i, --show_index                 Display ["id","key","value"] tags only
    -u, --unit num_of_unit           Set the num of processing unit (default: 15)
    -p, --page page                  Set the num of pages (default: 1)
    -r, --reverse                    Enable reverse mode
    -m, --max_numrows                Enable max_numrows mode
    -o, --outfile outfile            Set output filename or '-'.
    -y, --yaml_conf filename         Set yaml conf file
    -x, --yml_label label            Set label name in the yaml conf file
    -d, --debug                      Enable the debug mode
    -h, --help                       Show this message

1-2-2. -d: Turning on debug mode

This option turns on the debug message output.

1-2-3. -f filename: Input filename (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.

1-2-4. -o filename: Output filename (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.

1-2-5. -x label_name: Config label name

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

The default value is default.user. It depends on the access requirement of each command.

This option is only available on the command which access to CouchDB.

1-2-6. -y filename: Config filename

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.

This option is only available on the command which access to CouchDB.

2. Commands for DB Admins

• mkdb
• lsdb
• rmdb
• senduri
• sendurl

2-1. sbin/mkdb

"mkdb" creates a new database.

$ ./mkdb dbname
{"ok":true}

2-2. sbin/lsdb

"lsdbs" shows the list of the existing databases.

$ ./lsdbs
{"database":[
  "_users",
  "dbname",
  "test"
]}

2-3. sbin/rmdb

"rmdb" deletes the existing database without notice.

$ ./rmdb dbname

3. Commands for Documents

3-1. bin/lsdocs

"lsdocs" sends a GET request and shows all documents through the /dbname/_all_docs interface.

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

$ ./lsdocs test
{"_id":"65f26940ca75a1a4c3e7c6c64700077f","_rev":"1-0e7d0229c150cae8d724af06e0344b51","name":"yasu","age":"20"}
{"_id":"65f26940ca75a1a4c3e7c6c647000791","_rev":"1-ab6f8885ac4a3fa94fb23cb84f6939dc","name":"abe","age":"18"}

3-1-1. -u number: set the number of proceesing unit (default: 15)

"lsdocs" outputs result lines by each specified number.

The bigger number might cause an ineffective performance.

3-1-2. -p number: set the specified page number.

To show only the specified page, the page number should be greater than one.

Zero means to show all pages.

3-2. bin/postdocs

"postdocs" is a tool to send a POST request throught the /_bulk_docs interface.

$ echo -e '{"name":"foo"}\n{"name":"bar"}' | ./postdocs test
{"failed_list":[]}
$ ./lsdocs test
{"_id":"65f26940ca75a1a4c3e7c6c64700077f","_rev":"1-0e7d0229c150cae8d724af06e0344b51","name":"yasu","age":"20"}
{"_id":"65f26940ca75a1a4c3e7c6c647000791","_rev":"1-ab6f8885ac4a3fa94fb23cb84f6939dc","name":"abe","age":"18"}
{"_id":"65f26940ca75a1a4c3e7c6c647001524","_rev":"1-bc98e8ae0f9c89fbc8c237dfc9bfe478","name":"foo"}
{"_id":"65f26940ca75a1a4c3e7c6c647001622","_rev":"1-62bc3c4d01e43ee9d0cead8cd7c76041","name":"bar"}

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

$ ./lsdocs test | ./chjson '["_deleted",true]' | ./postdocs test
{"failed_list":[]}
$ ./lsdocs test
$

4. Commands for Views

4-1. bin/putdesign

"putdesign" takes the two arguments, dbname and docname, and puts reading data into the given path, /dbname/_design/docname.

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

4-2. bin/lsviews

"lsviews" shows all documents of the specified view.

After executing the example of "putdesign" to the empty "test" database, following commands show the result of "lsviews."

$ echo -e '{"name":"foo"}\n{"name":"bar"}' | ./postdocs test
{"failed_list":[]}
$ ./lsviews test all all
{"_id":"65f26940ca75a1a4c3e7c6c647002514","_rev":"1-bc98e8ae0f9c89fbc8c237dfc9bfe478","name":"foo"}
{"_id":"65f26940ca75a1a4c3e7c6c647003231","_rev":"1-62bc3c4d01e43ee9d0cead8cd7c76041","name":"bar"}

5. Commands for JSON Stream

For json stream, YALTools provides some commands like "grep" in unix environment.

5-1. bin/grepjson

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

The condition is JSON arrays and specified by an array, such as ["key1","key2",...,"value"].

$ echo -e '{"a":"1"}\n{"b":{"c":30}}' | ./grepjson '["b","c"]'
{"b":{"c":30}}
$ echo -e '{"a":"1"}\n{"b":{"c":30}}' | ./grepjson '["b","c",30]'
{"b":{"c":30}}

5-2. bin/chjson

"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.

$ ./lsdocs test | ./chjson '["_deleted",true]'
{"_id":"65f26940ca75a1a4c3e7c6c647002514","_rev":"1-bc98e8ae0f9c89fbc8c237dfc9bfe478","name":"foo","_deleted":true}
{"_id":"65f26940ca75a1a4c3e7c6c647003231","_rev":"1-62bc3c4d01e43ee9d0cead8cd7c76041","name":"bar","_deleted":true}
{"_id":"_design/all","_rev":"17-a29e5cc677328801f05a869f76a2f0f4","views":{"all":{"map":"function(doc) { emit(doc._id,null); }"}},"_deleted":true}

5-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"}

5-3-1. -e: exclude option

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

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

5-4. bin/jsonfmt

The "jsonfmt" transforms the input JSON stream into a human readable text.

It reads each line from stdin or a file and pass it to YALTools::JsonFormatter#parse module method.

$ bin/lsdoc /
{"couchdb":"Welcome","version":"1.0.2"}
$ bin/lsdoc / | bin/jsonfmt
{
  "couchdb":  "Welcome",
  "version":  "1.0.2"
}

5-5. bin/csv2json

"csv2json" is a tool to parse a csv file and produce json format string.

However, this command is not well-known csv2json script. There are some unique rules for the transformation.

## rule 1.
    | key1 | key2 | 
    |=============|  => key1:val1,key2:val2
    | val1 | val2 |
    +-------------|
    
    $ echo -e "key1,key2\nval1,val2" | bin/csv2json
    > {"key1":"val1","key2":"val2"}

## rule 2.
    | key1 | key2 | 
    |=============|   => key1:{key2:val1}
    |      | val1 |
    +-------------+

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

## rule 3.
    | key1 | 
    |======|
    | val1 |   => key1:[val1,val2]
    |------|
    | val2 |
    +------+
    
    $ echo -e "key1\nval1\nval2" | bin/csv2json
    > {"key1":["val1","val2"]}

5-5-1. -s spliter: set the delimiter string (default: ',')

The "-s spliter" option changes the delimiter string.

5-5-2. -n: normal operation mode option

The "-n" options is available for the intuitive behavior.

$ echo -e "key1,key2\nval1,val2\nval3,val4" | bin/csv2json 
{"key1":["val1","val3"],"key2":["val2","val4"]}
$ echo -e "key1,key2\nval1,val2\nval3,val4" | bin/csv2json -n
{"key1":"val1","key2":"val2"}
{"key1":"val3","key2":"val4"}

6. Misc. Commands

6-1. bin/lsdoc

"lsdoc" is a tool to send a GET request to CouchDB.

$ bin/lsdoc /test/_security
	{"admin":{"names":[""],"roles":["fwadmin","fwwriter"]},"reader":{"names":[""],"roles":["fwreader"]}}

6-2. bin/putdoc

"putdoc" is a tool to send a PUT request to CouchDB.

6-3. bin/postdoc

"postdoc" is a tool to send a PUT request to CouchDB.

The functionality is same as the "putdoc" command.

The POST request is required to create "_id" less document and required for replication and compaction in CouchDB.

$ bin/postdoc /test/_compact < /dev/null
	{"ok":true}

6-4. sbin/senduri

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

$ ./senduri /test/_all_docs

6-5. 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

7. Configuration Files

The YAML configuration file, utils/conf/yalt.yaml, is the main configuration file.

Please refer the all available options at the YALTools::MainWrapper API documents.

7-1. The yalt.conf file format

A minimum setting was explained at the Installation section.

The file format for basic and digest authentications is the following.

---
label:
    host:
    port:
    user:
    password:
    password_salt:       ## option for encrypted password.
    password_pass_file:  ## option.
    digest_auth:         ## option for digest_auth.
    cacert:              ## option for ssl.

The net-http-digest_auth library is required for the digest auth.
    $ sudo gem install net-http-digest_auth

If you want to use an encrypted password, the encrypted text should be produced by the following method.

$ sbin/encpassword -p password
password_salt: 69fc92a2725fa2d0
password: c07b612f149f82afeb4fb762d98be8cf

After that, please copy password_salt: and password: lines into the yalt.yaml file.

---
default.user:
    host: 127.0.0.1
    port: 5984
    user: admin
    password_salt: 69fc92a2725fa2d0
    password: c07b612f149f82afeb4fb762d98be8cf

Before use the encpassword command, to set up the master_pw.json is required.
Please refer the Install instructions at Getting tarted page.

7-1-1. Basic authentication

The basic authentication is the most typical case, and most of user needs the following lines at the utils/conf/yalt.yaml file.

---
default.user
    host: 127.0.0.1
    port: 5984
    user: admin
    password: xxxx

7-1-2. Digest authentication

CouchDB does not have the diegst authentication feature, but it can be used to place a reverse proxy server in front of CouchDB.

To enable the digest authentication, it just adds the "digest_auth" key to the yalt.yaml file.

---
default.user
    host: 127.0.0.1
    port: 5984
    user: admin
    password: xxxx
    digest_auth: ""

It just needs the "digest_auth" key, so any value of the "digest_auth" enables the authentication.