Couchbase Lite開発：cbliteツール解説

## `cblite`ツールとは

`cblite`は、Couchbase Liteデータベースを検査およびクエリするためのコマンドラインツールです。
以下のふたつのモードで利用することができます。

* ワンショット（非インタラクティブ）モード
* インタラクティブモード

### ワンショット（非インタラクティブ）モード

ワンショットモードでは、最初の引数がサブコマンドになり、その後にオプションのフラグ引数が続きます。また、データベースパスを指定します。

以下に、サブコマンドの概要を示します。

| コマンド| 目的|
| ---------------- | --------- |
| `cblite cat` | 1つ以上のドキュメントの本文を表示する|
| `cblite check` | データベースファイルの破損をチェックする|
| `cblite compact` | データベースファイルを圧縮し、ディスクスペースを解放する|
| `cblite cp` | データベースの複製、インポート、またはエクスポート|
| `cblite help` | ヘルプテキストを表示する|
| `cblite info` | データベースに関する情報を表示する|
| `cblite logcat` | バイナリログファイルをプレーンテキストに変換する|
| `cblite ls` | データベース内のドキュメントを一覧表示する|
| `cblite put` | ドキュメントを作成または更新する|
| `cblite query` | [JSONクエリスキーマ] [QUERY]を使用してクエリを実行する|
| `cblite reindex` | パフォーマンスを向上させる可能性のあるインデックスを再構築する|
| `cblite revs` | ドキュメントのリビジョンを一覧表示する|
| `cblite rm` | ドキュメントを削除する|
| `cblite select` | [N1QL] [N1QL]構文を使用してクエリを実行する|
| `cblite serve` | （初歩的な）RESTAPIリスナーを開始する|

### インタラクティブモード

インタラクティブモードでは、データベースパスを指定して実行後、インタラクティブにサブコマンドの入力を求められます。

`quit`を入力するか、Ctrl-Dを押して終了します。

以下は、実行例です。

```shell
$ cblite travel-sample.cblite2
Opened read-only database travel-sample.cblite2/
(cblite) ls -l --limit 5
Document ID             Rev ID     Flags   Seq     Size
airline_10              1-d70614ae ---       1     0.1K
airline_10123           1-091f80f6 ---       2     0.1K
airline_10226           1-928c43f4 ---       3     0.1K
airline_10642           1-5cb6252c ---       4     0.1K
airline_10748           1-630b0443 ---       5     0.1K
(Stopping after 5 docs)
(cblite) quit
$
```

### グローバルフラグ

これらのフラグは `cblite`の直後に指定します。

| フラグ| 効果|
| --------------- | --------- |
| `--color` | ANSIカラーを有効にします（または環境変数 `CLICOLOR`を設定します）。
| `--create` | パスが存在しない場合は、新しいデータベースを作成します。データベースを書き込み可能モードで開きます。|
| `--encrypted ` | 暗号化されたデータベースを開きます。パスワード/キーの入力が求められます。（インタラクティブモードでは、データベースが暗号化されていることが検出されると、ツールは自動的にプロンプ​​トを表示します。）|
| `--help` | ヘルプテキストを出力して終了します。|
| `--version ` | LiteCoreのバージョンを出力して、終了します。|
| `--writeable ` | データベースを書き込み可能モードで開き、 `compact`や` put`などのコマンドを使用できるようにします。|



## サブコマンド解説


>注：最初の引数が「 `-`」で始まる場合、それはフラグとして誤って解釈されます。これを回避するには、その前に空のフラグ引数「 `--`」を置きます。

## cat

ドキュメントIDがパターンに一致するすべてのドキュメントのJSON本文を表示します。

`cblite cat` _[flags]_ _databasepath_ _DOCID_ [_DOCID_ ...]

`cat` _[flags]_ _DOCID_ [_DOCID_ ...]

（DOCIDには、シェルスタイルのワイルドカード `*`、 `？`が含めることができます）

| フラグ| 効果|
| --------- | --------- |
| `--key KEY` | 単一のキー/値のみを表示する（複数回使用できます）|
| `--rev` | リビジョンIDを表示する|
| `--raw` | JSONを出力する|
| `--json5` | JSON5構文で出力する（dictキーを引用符で囲まない）|

## check

データベースの整合性チェックを実行します。

`cblite check` _databasepath_

`check`

## cp（別名export, import, push, pull）

データベースをコピーするか、JSONをインポートまたはエクスポートするか、複製します。

`cblite cp` _[flags]_ _source_ _destination_

_source_および_destination_は、データベースパス、レプリケーションURL、またはJSONファイルパスにすることができます。それらの1つは、 `* .cblite2`で終わるデータベースパスである必要があります。もう1つは、次のいずれかになります。

* `*.cblite2`: ローカルデータベースファイルをコピーし、新しいUUIDをターゲットに割り当てます
* `ws://*`: ネットワークレプリケーション
* `*.json`: JSONファイルをインポート/エクスポートします（1行に1つのドキュメント）
* `* /`: JSONファイル（ドキュメントごとに1ファイル）の含まれるディレクトリをインポート/エクスポートします

`--replicate`フラグを使用して、ローカルからローカルへのコピーにレプリケータを使用させることができます。コマンドが `push`または` pull`として呼び出された場合、このフラグは暗黙的に設定されます。

`cp` _[flags]_ _destination_

インタラクティブモードでは、データベースパスはすでにわかっているため、ソースとして使用され、 `cp`は宛先引数のみを取ります。オプションで、コマンド `push`または` export`を呼び出すことができます。または、インタラクティブモードで同義語 `pull`または` import`を使用する場合、指定したパラメーターは_source_として扱われ、現在のデータベースは_destination_です。

| フラグ| 効果|
| --------- | --------- |
| `--bidi` | 双方向（プッシュ+プル）レプリケーション|
| `-cacert` _file_ | _file_（PEMまたはDER形式）のX.509証明書を使用して、サーバーのTLS証明書を検証する。サーバーに自己署名証明書がある場合に必要です。|
| `--careful ` | エラーが発生した場合は中止する。|
| `-cert` _file_ | TLSクライアント認証には、_file_（PEMまたはDER形式）のX.509証明書を使用する。`--key`が必要です。|
| `--continuous` | 継続的レプリケーションを実行します|
| `--existing`または` -x` | _destination_がまだ存在しない場合は失敗します。|
| `--jsonid` _property_ | ドキュメントIDに使用するJSONプロパティを指定します。 |
| `--key` _file_ | TLSクライアント認証に_file_の秘密鍵を使用します。`--cert`が必要です。|
| `--limit` _n_ | _n_個のドキュメントの後で停止する。（レプリケーターはこれを無視します）|
| `--replicate` | ローカルからローカルにコピーするときにレプリケーターの使用を強制する。|
| `--user` _name [`:`password ]_ | リモートサーバーの資格情報。（パスワードが指定されていない場合、ツールはパスワードの入力を求めるプロンプトを表示します。）|
| `--verbose`または` -v` | 進捗情報をログに記録する。|

`--jsonid`は次のように機能します。

 - _source_がJSONの場合、これはプロパティ名/パスであり、その値はドキュメントIDとして使用されます。（省略した場合、ドキュメントにはUUIDが与えられます。）
 - _destination_がJSONの場合、これはJSONに追加されるプロパティ名であり、その値はドキュメントのIDです。（このフラグを省略すると、値はデフォルトで `_id`になります。）


## help

すべてのコマンドのリスト、または特定のコマンドの詳細を表示します。

`cblite help` _[サブコマンド名]_

`help` _[サブコマンド名]_

## info（別名file）

ドキュメント数や最新のシーケンス番号など、データベースに関する情報を表示します。 
サブサブコマンド `indexes`を使用すると、代わりにデータベース内のすべてのインデックスが一覧表示されます。 
サブサブコマンド `index`の後にインデックス名を付けると、代わりにそのインデックスの内容全体（キーと値）がダンプされます。

`cblite info` _databasepath_ 
`cblite info` _databasepath_` indexes` 
`cblite info` _databasepath_` index` _indexname_

`info` `info indexes` `info index` _indexname_ 

## logcat

Couchbase Liteバイナリログファイルを読み取り、stdoutと同等のプレーンテキストを書き込みます。

複数のファイルが、時系列で並べ替えられた行とともにマージされます。

ディレクトリパスを指定すると、そのディレクトリ内のすべての `.cbllog`ファイルが読み取られます。

`cblite logcat` _[logfile]_ [_logfile_ ...]
`cblite logcat` _ [directory] _

`logcat` _[logfile]_ [_logfile_ ...]
`logcat` _[directory]_

| フラグ| 効果|
| --------- | --------- |
| `--csv` | RFC4180に従って、CSV形式で出力する。|
| `--full ` | 完全なログ（すべてのレベル）が使用可能になると、最初に出力が開始されます。アクティブでないログレベルはより長い履歴を保持するため、これは多くの場合便利です。したがって、すべてがログに記録されると、出力の開始は古いエラーと警告に他なりません。|
| `--out` _filepath_ | stdoutではなくファイルに出力を書き込みます。|

## ls

データベース内のドキュメントのIDを一覧表示します。

`cblite ls` _[flags]_ _databasepath_ _[PATTERN]_

`ls` _[flags]_ _[PATTERN]_

| フラグ| 効果|
| --------- | --------- |
| `-l` | 長い形式（1行に1つのドキュメント、メタデータ付き）|
| `--offset ` _n_ | 最初の_n_ドキュメントをスキップ|
| `--limit` _n_ | _n_docsの後に停止する|
| `--desc` | 降順|
| `--seq` | docIDではなくシーケンスで並べ替え|
| `--del` | 削除されたドキュメントを含める|
| `--conf` | 競合するドキュメントのみを含める|
| `--body` | ドキュメント本文を表示する|
| `--pretty` | きれいに印刷されたドキュメント本文（ `--body`を意味します）|
| `--json5` | JSON5構文、つまり引用符で囲まれていないdictキー（ `--body`を意味します）|

（PATTERNは、シェルスタイルのワイルドカード `*`、 `？`を使用してdocIDを照合するためのオプションのパターンです）

## put

ドキュメントを作成または更新します。

`cblite put` _[flags]_ _databasepath_ _DOCID_ "_JSON_"

`put` _[flags]_ _DOCID_ "_JSON_"

| フラグ| 効果|
| --------- | --------- |
| `--create` | ドキュメントを作成する。ドキュメントが存在する場合は失敗します。|
| `--update` | 既存のドキュメントを更新する。ドキュメントが存在しない場合は失敗します。|


>注：対話モードでは、 `cblite`が` --writeable`または `--create`フラグで呼び出されない限り、このコマンドは失敗します。

## query

JSON構文を使用したデータベースクエリを実行します。

`cblite query` _[flags]_ _databasepath_ "_query_"

`query` _[flags]_ _query_

| フラグ| 効果|
| --------- | --------- |
| `--offset` _n_ | 最初の_n_行をスキップする|
| `--limit` _n_ | _n_行の後で停止する|

_query_は、JSONクエリスキーマ(下記URL参照)に従う必要があります。

http://json5.org


## reindex

インデックスを再構築します。再構築後のインデックスは、時間の経過とともに段階的に変更されてきたインデックスよりも効率的な構造になる可能性があるため、クエリのパフォーマンスが向上する可能性があります。

これは、アプリケーション内に埋め込むデータベースを準備する際の最終ステップとして実行する価値があります。

`cblite reindex` _databasepath_

`reindex`

>注：対話モードでは、 `cblite`が` --writeable`または `--create`フラグで呼び出されない限り、このコマンドは失敗します。

## revs

ドキュメントの改訂履歴を表示します。

`cblite revs` _databasepath_ _DOCID_

`revs` _DOCID_

## rm

ドキュメントを削除します。

`cblite rm` _databasepath_ _DOCID_

`rm` _DOCID_

>注：対話モードでは、 `cblite`が`--writeable`または `--create`フラグで呼び出されない限り、このコマンドは失敗します。

## select

N1QL構文を使用してデータベースを照会します。

`cblite select` _[flags]_ _databasepath _" _query_"

`select` _[flags]_ _query_

| フラグ| 効果|
| --------- | --------- |
| `--ofset` _n_ | 最初の_n_行をスキップする|
| `--limit` _n_ | _n_行の後で停止|

_query_の記述のベースは、N1QLの `SELECT`クエリですが、キーワード` SELECT`はコマンド名としてすでに指定されているため、これを除きます。また、キースペース（データベース）が1つしかないため、 `FROM`句も省略します。

## serve

REST APIに応答する簡易的なHTTPサーバーを実行します。REST APIのサブセットのみが実装されています。

`cblite serve` _[flags]_ _databasepath_

`serve` _[flags]_

| フラグ| 効果|
| --------- | --------- |
| `--port` _n_ | TCPポート番号を設定する（デフォルトは59840）|
| `--readonly` | REST呼び出しによるデータベースの変更を防止する|
| `--verbose`または`-v` | リクエストをログに記録する。|



## 実行例

```shell
$  cblite file travel-sample.cblite2
Database:   travel-sample.cblite2/
Total size: 34MB
Documents:  31591, last sequence 31591

$  cblite ls -l --limit 10 travel-sample.cblite2
Document ID     Rev ID     Flags   Seq     Size
airline_10      1-d70614ae ---       1     0.1K
airline_10123   1-091f80f6 ---       2     0.1K
airline_10226   1-928c43f4 ---       3     0.1K
airline_10642   1-5cb6252c ---       4     0.1K
airline_10748   1-630b0443 ---       5     0.1K
airline_10765   1-e7999661 ---       6     0.1K
airline_109     1-bd546abb ---       7     0.1K
airline_112     1-ca955c69 ---       8     0.1K
airline_1191    1-28dbba6e ---       9     0.1K
airline_1203    1-045b6947 ---      10     0.1K
(Stopping after 10 docs)

$  cblite travel-sample.cblite2
(cblite) query --limit 10 ["=", [".type"], "airline"]
["_id": "airline_10"]
["_id": "airline_10123"]
["_id": "airline_10226"]
["_id": "airline_10642"]
["_id": "airline_10748"]
["_id": "airline_10765"]
["_id": "airline_109"]
["_id": "airline_112"]
["_id": "airline_1191"]
["_id": "airline_1203"]
(Limit was 10 rows)
(cblite) query --limit 10 '{WHAT: [[".name"]], WHERE:  ["=", [".type"], "airline"], ORDER_BY: [[".name"]]}'
["40-Mile Air"]
["AD Aviation"]
["ATA Airlines"]
["Access Air"]
["Aigle Azur"]
["Air Austral"]
["Air Caledonie International"]
["Air CaraÃ¯bes"]
["Air Cargo Carriers"]
["Air Cudlua"]
(Limit was 10 rows)
(cblite) ^D
$
```

## 関連情報



https://github.com/couchbaselabs/couchbase-mobile-tools