droonga-engine-catalog-modify

概要

droonga-engine-catalog-modifyは、既存のcatalog.jsonを変更してDroongaクラスタの構成を変えます。

多くの場合において、このコマンドを使う必要はまずありません。代わりに、クラスタ構成の変更にはdroonga-engine-joinやdroonga-engine-unjoinのような管理コマンドを使って下さい。

例

例えば、/tmp/catalog.jsonの位置に以下のような内容のcatalog.jsonがあるとします：

{
  "version": 2,
  "effectiveDate": "2015-05-08T09:02:12+00:00",
  "datasets": {
    "Default": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.50:10031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.51:10031/droonga.000" } }
          ]
        }
      ]
    },
    "Testing": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.60:20031/droonga.000" } }
          ]
        }
      ]
    }
  }
}

新しいreplicaの追加

クラスタ内のデータセットDefaultに新しいreplicaノード192.168.100.52を加えるコマンド列は以下の通りです：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --no-update \
    --add-replica-hosts 192.168.100.52

省略されたオプションを含めた完全な指定はこのようになります：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --output - \
    --no-update \
    --dataset Default \
      --add-replica-hosts 192.168.100.52

このコマンドは既存の他のreplicaと同じポート番号とタグ名を自動的に適用します。 それらの情報を指定する必要はありません。

変更されたcatalog.jsonは以下の通りです：

{
  "version": 2,
  "effectiveDate": "2015-05-08T09:02:12+00:00",
  "datasets": {
    "Default": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.50:10031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.51:10031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.52:10031/droonga.000" } }
          ]
        }
      ]
    },
    "Testing": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.60:20031/droonga.000" } }
          ]
        }
      ]
    }
  }
}

既存のreplicaの削除

クラスタ内のデータセットDefaultから既存のreplicaノード192.168.100.51を取り除くコマンド列は以下の通りです：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --no-update \
    --remove-replica-hosts 192.168.100.51

省略されたオプションを含めた完全な指定はこのようになります：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --output - \
    --no-update \
    --dataset Default \
      --remove-replica-hosts 192.168.100.51

変更されたcatalog.jsonは以下の通りです：

{
  "version": 2,
  "effectiveDate": "2015-05-08T09:02:12+00:00",
  "datasets": {
    "Default": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.50:10031/droonga.000" } }
          ]
        }
      ]
    },
    "Testing": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.60:20031/droonga.000" } }
          ]
        }
      ]
    }
  }
}

データセットから全てのreplicaノードを取り除くこともできます：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --no-update \
    --remove-replica-hosts 192.168.100.52,192.168.100.51
{
  "version": 2,
  "effectiveDate": "2015-05-08T09:02:12+00:00",
  "datasets": {
    "Default": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": []
    },
    "Testing": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.60:20031/droonga.000" } }
          ]
        }
      ]
    }
  }
}

しかし、これはcatalog.jsonとしては不正な内容です。 このコマンドを使って空のデータセットに対し再びreplicaノードを追加することはできません。 このような壊れたcatalog.jsonを修復するには、droonga-engine-catalog-generateコマンドを使って再生成する必要があります。

複数のデータセットのreplicaノードのリストを一度に更新する

新しいreplicaノード192.168.100.52をデータセットDefaultへ、もう1つの新しいreplicaノード192.168.100.61をデータセットTestingへ追加するコマンド列は以下の通りです：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --no-update \
    --add-replica-hosts 192.168.100.52 \
    --dataset Testing \
    --add-replica-hosts 192.168.100.61

省略されたオプションを含めた完全な指定はこのようになります：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --output - \
    --no-update \
    --dataset Default \
      --add-replica-hosts 192.168.100.52 \
    --dataset Testing \
      --add-replica-hosts 192.168.100.61

変更されたcatalog.jsonは以下の通りです：

{
  "version": 2,
  "effectiveDate": "2015-05-08T09:02:12+00:00",
  "datasets": {
    "Default": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.50:10031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.51:10031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.52:10031/droonga.000" } }
          ]
        }
      ]
    },
    "Testing": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.60:20031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.61:20031/droonga.000" } }
          ]
        }
      ]
    }
  }
}

このコマンドはポート番号とタグ名をデータセット固有の設定として認識するため、Default配下の新しいreplicaにはポート番号として10031が、Testing配下の新しいreplicaにはポート番号として20031が使われています。

別の場合として、2つのデータセットDefaultとTestingの間でreplicaノードを交換するコマンド列も示します：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --no-update \
    --replica-hosts 192.168.100.60 \
    --dataset Testing \
    --replica-hosts 192.168.100.50,192.168.100.51

省略されたオプションを含めた完全な指定はこのようになります：

$ droonga-engine-catalog-modify \
    --source /tmp/catalog.json \
    --output - \
    --no-update \
    --dataset Default \
      --replica-hosts 192.168.100.60 \
    --dataset Testing \
      --replica-hosts 192.168.100.50,192.168.100.51

変更されたcatalog.jsonは以下の通りです：

{
  "version": 2,
  "effectiveDate": "2015-05-08T09:02:12+00:00",
  "datasets": {
    "Default": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.60:10031/droonga.000" } }
          ]
        }
      ]
    },
    "Testing": {
      "nWorkers": 4,
      "plugins": ["groonga", "search", "crud", "dump", "system", "catalog"],
      "schema": {},
      "replicas": [
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.50:20031/droonga.000" } }
          ]
        },
        {
          "dimension": "_key",
          "slicer": "hash",
          "slices": [
            { "weight": 100,
              "volume": { "address": "192.168.100.51:20031/droonga.000" } }
          ]
        }
      ]
    }
  }
}

個々のvolumeのポート番号が変化したことに注意して下さい。 ポート番号はデータセットの方に紐付けられているため、ポート番号が入れ替わっています。

パラメータ

--source=PATH
変更される対象のcatalog.jsonの読み込み元パス。 -を指定した場合は標準入力からcatalog.jsonを受け取ります。 指定されたパスの位置にある既存のファイルは、確認無しに上書きされます。 既定値は、そのコンピュータ上に設定されるdroonga-engineサービスのcatalog.jsonの位置（/home/droonga-engine/droonga/catalog.json）です。
--output=PATH
変更されたcatalog.jsonの保存先パス。 -を指定した場合は標準出力に対して出力します。 指定されたパスの位置にある既存のファイルは、確認無しに上書きされます。 既定値は-です。
--[no-]update
読み込んだファイル自体を更新するかどうか。
  • --updateは、--sourceオプションで指定された入力ファイル自体を上書きします。
  • --no-updateは、変更後のcatalog.jsonを--outputで指定された出力先に出力します。

既定値は--updateです。

--dataset=NAME
変更する対象の既存データセットの名前。 複数のデータセットを変更できるように、このオプションは複数回指定できます。 既定値はDefaultです。
--replica-hosts=NAME1,NAME2,...
先行する--datasetオプションで定義されたデータセットにおいて、replicaとして使う1つ以上のEngineノードのホスト名。 このオプションを指定した場合、データセット内の既存のreplicaノードは全て置き換えられます。
--add-replica-hosts=NAME1,NAME2,...
先行する--datasetオプションで定義されたデータセットに対して追加する、1つ以上のEngineノードのホスト名。
--remove-replica-hosts=NAME1,NAME2,...
先行する--datasetオプションで定義されたデータセットから取り除く、1つ以上のEngineノードのホスト名。

インストール方法

このコマンドは、Rubygemsのパッケージdroonga-engineの一部としてインストールされます。

# gem install droonga-engine