YALTools | Top Page | Introduction / Getting Started

Navigator Menu

1. YALTools - Yet Another L-Tools for CouchDB.

This project is hosted at sf.net.

Japanese version (日本語版) of this document is available.

1-1. Introduction

YALTools (a.k.a. lscouchdb) is a set of command line tools and library for Apache CouchDB.

It is written in Ruby and provides a UNIX like command set, such as mkdb, lsdbs, lsdocs and postdocs.

YALTools brings the power of filters and pipes on the UNIX like environment to CouchDB and aims to provide a relax environment for CouchDB administrators.

[ chapter top | page top ]

2. Getting Started

Indexes

YALTools - Yet Another L-Tools for CouchDB.
1. Introduction
Getting Started

2-1. Features

YALTools provides a command set for system/database administrators.

"lsdocs" and "postdocs" commands work with /_all_docs and /_bulk_docs interfaces. These can handle a mount of documents using a pipe.

## Example: copy documents of database:test01 to database:test02 including attachments.
$ bin/lsdocs -a test01 | bin/reducejson -e '["_rev"]' | bin/postdocs test02

2-1-1. About YALTools libraries

Each command is developed using the YALTools library which supports to develop applications, especially a pagination application.

YALTools library is designed to process a huge amount of documents using limit and skip query parameters which is calculated automatically.

[ chapter top | page top ]

2-2. Prerequisites

Ruby 1.9.2
CouchDB 1.0.2

2-2-1. Option: group_numrows

For pagination, YALTools have to know the total number of rows for iteration.

It might take a time to handle the total number of rows without retrieving all results when group query option is true.

The group_numrows view query option enables to get just a total number of rows like the "SELECT COUNT(DISTINCT column)" query of SQL.

https://github.com/YasuhiroABE/CouchDB-Group_NumRows

2-2-2. Option: JRuby

YALTools is working well with JRuby 1.6.0, but have to install jruby-json package additionally.

JRuby 1.6.0 + (jruby-json and jruby-openssl)

$ jruby-1.6.0/bin/jgem install jruby-json jruby-openssl
$ export JRUBY_OPTS="--1.9"

The jruby-openssl package is optional, but it's recommended.

The JRUBY_OPTS="--1.9" is essential for the csv2json command.

[ chapter top | page top ]

2-3. Installation

Unpack the package into arbitrary directory.

$ tar xvjf lscouchdb.20110418.tar.bz2

Otherwise, it is recommended to retrieve files from Github.

$ git clone git://lscouchdb.git.sourceforge.net/gitroot/lscouchdb/lscouchdb

2-3-1. Setting up the configuration file

Please edit the utils/conf/yalt.yaml configuration file, and add authentication information for the "default.user" label.

$ cd lscouchdb/utils
$ vi conf/yalt.yaml
---
default.user:
  host: 127.0.0.1
  port: 5984
  user: admin
  password: xxxxxx

If you do not use the authentication, then the yalt.yaml file will be;

---
default.user:
  host: 127.0.0.1
  port: 5984

Most of the default CouchDB installation requires no authentication. If so, please remove the "user:" and the "password:" lines.

2-3-2. Changing pathname of ruby-1.9

Each command uses the "/usr/local/bin/ruby" command as a default behavior.

In MacOS X Snow Leopard (10.6) environment, for instance, the "ruby1.9" is available instead of "ruby".

In that case, please run the lscouchdb/sbin/change_ruby_command_name.sh script.

$ ../sbin/change_ruby_command_name.sh ruby1.9
using temporary file: /tmp/replrubycmd.YCnn4iRPaD

Selected ruby command name: /opt/local/bin/ruby1.9

writing script: sbin/../utils/bin/chjson 
writing script: sbin/../utils/bin/csv2json 
...
finished.

2-3-3. Option: Setting up 'master_pw.json' for the encrypted password

If you want not to write the raw password string in the configuration file, the encrypted password text can be used instead.

Before use the encpassword command, please prepare the common password text.

$ mv -i conf/master_pw.json conf/master_pw.json.orig
$ sbin/encpassword -i

If success, you will see a SHA2 digest text and new conf/master_pw was created.

3da100258120ea71ea02e7d25204581bede52ebee920f3fea048e1bf00ebdb17

If failed, you will see the following messages.

[error] Cannot initialize the master password file.
[error] Please delete or rename the master password file, .../conf/master_pw.json, first.

About the usage of encpassword command, please refer the yalt.conf file format at the Command Reference page.

2-3-4. Let's try to execute command.

$ sbin/lsdbs | bin/jsonfmt 
{"database":[
  "_users",
  "test"
]}

2-3-5. Next step is ...

Please see the Case Studies part.

[ chapter top | page top ]

Permalink: /1.0/index.html