AI 記事

設定ファイル操作の決定版！yqでYAML/JSON/TOMLを自在に操る

設定ファイル操作の決定版！yqでYAML/JSON/TOMLを自在に操る

設定ファイルの変更、いつも手作業で消耗していませんか？

開発現場では、YAMLやJSON、TOML形式の設定ファイルが頻繁に使われます。複数の環境で異なる設定を管理したり、デプロイ時に一部の値を書き換えたりする作業は日常茶飯事です。しかし、手作業での編集はミスを誘発し、時間もかかります。シェルスクリプトで自動化しようにも、複雑なパース処理に頭を悩ませることは少なくありません。

そんな悩みを解決するCLIツールが「yq」です。yqは、YAML、JSON、TOMLなど様々な形式の設定ファイルをコマンドラインで簡単に操作できます。jqに似た構文で、これらのファイルを一元的に扱えるのです。Go言語製のため、単一バイナリで動作し、インストールも手軽です。この記事では、yqの基本的な使い方から、つまずきやすいポイントまでをチュートリアル形式で紹介します。

設定ファイルの変更、手作業で消耗していませんか？

現代のソフトウェア開発において、設定ファイルはプロジェクトの根幹を支えます。データベース接続情報、APIキー、環境変数など、多岐にわたる設定がYAMLやJSON、TOMLファイルに記述されることは一般的です。

しかし、これらのファイルを直接編集する作業には、いくつかの課題があります。

  • ヒューマンエラーのリスク: 手作業でのタイポやインデントミスは、予期せぬエラーを引き起こします。
  • 作業の非効率性: 複数の環境で同じような変更を繰り返す場合、多くの時間がかかります。
  • スクリプト化の難しさ: シェルスクリプトで設定値を変更しようとすると、正規表現やawkコマンドを駆使する必要があり、可読性が低くなりがちです。

yqは、これらの課題を解決する強力なツールです。jqコマンドの使いやすさをYAMLファイルにもたらし、さらにJSONやTOML、XMLなど多くの形式に対応します。これにより、設定ファイルの操作が劇的にシンプルになります。

yqを今すぐ使い始めるには：インストールと準備

yqの導入は非常に簡単です。Go言語で書かれているため、依存関係なしの単一バイナリで動作します。お使いのOSや環境に合わせて、以下のいずれかの方法でインストールしてください。

Homebrewでのインストール（macOS/Linux）

macOSやLinuxユーザーの場合、Homebrewを使えば1分でインストールが完了します。

brew install yq

バイナリの直接ダウンロード（あらゆるプラットフォーム）

公式GitHubリポジトリから、お使いのシステムに合ったバイナリを直接ダウンロードすることも可能です。ダウンロード後、実行パスの通ったディレクトリに配置してください。

# Linuxの場合の例
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yq

Dockerでの利用

Docker環境があれば、イメージを使ってすぐにyqを実行できます。インストール不要です。

docker run --rm -v "$(pwd)":/workdir mikefarah/yq yq --version

バージョンの確認

インストールが完了したら、以下のコマンドでyqのバージョンを確認しましょう。

yq --version

バージョン情報が表示されれば、準備は万端です。

サンプルファイルの準備

チュートリアルを進めるために、以下のconfig.yamlファイルを作成してください。

# config.yaml
server:
  host: localhost
  port: 8080
database:
  type: postgres
  user: admin
  password: secure_password
features:
  enabled: true
  list:
    - item1
    - item2

基本をマスター：yqで値を読み書きする3つの方法

yqの基本的な操作は、主に「値の読み取り」「値の変更」「要素の追加・削除」の3つです。これらの操作をマスターすれば、設定ファイルの編集作業が格段に楽になります。

1. 特定の値を読み取る

yqは、ドット記法を使って設定ファイル内の特定の値を簡単に読み取れます。

  • 基本的な値の読み取り

server.portの値を読み取るには、次のようにコマンドを実行します。

yq '.server.port' config.yaml

出力結果は「8080」となります。

  • リスト要素の読み取り

features.listの最初の要素を読み取るには、インデックスを指定します。

yq '.features.list[0]' config.yaml

出力結果は「item1」となります。

  • 複数の値を一度に読み取る

複数のパスを指定すると、それぞれの値が新しいYAML構造として出力されます。

yq '{port: .server.port, database_user: .database.user}' config.yaml

出力例は以下の通りです。

port: 8080
database_user: admin

2. 値を変更する

yqで既存の値を変更するには、=演算子を使います。変更をファイルに直接反映させる場合は、-iオプション（インプレース編集）を付けます。

  • 文字列の値を変更する

server.hostの値をlocalhostから0.0.0.0に変更します。

yq -i '.server.host = "0.0.0.0"' config.yaml

このコマンドを実行後、config.yamlを開くとhostの値が変更されているのを確認できます。

  • 真偽値（boolean）を変更する

features.enabledをtrueからfalseに変更します。

yq -i '.features.enabled = false' config.yaml
  • 数値の値を変更する

server.portの値を8080から80に変更します。

yq -i '.server.port = 80' config.yaml

3. 新しい要素を追加・削除する

yqを使えば、新しいキーやリスト要素の追加、不要な要素の削除も簡単です。

  • 新しいキーと値を追加する

server配下にtimeoutキーを30という値で追加します。

yq -i '.server.timeout = 30' config.yaml
  • 要素を削除する

database.passwordキーを削除します。del関数を使います。

yq -i 'del(.database.password)' config.yaml
  • リストに新しい要素を追加する

features.listにitem3を追加します。+=演算子を使います。

yq -i '.features.list += ["item3"]' config.yaml

これらの基本的な操作を組み合わせることで、ほとんどの設定ファイル編集タスクをyqで自動化できます。

yqでハマりがちな落とし穴と解決策

yqは非常に便利ですが、いくつかの点でつまずきやすいこともあります。ここでは、よくある落とし穴とその解決策を紹介します。

1. 引用符の扱い

文字列にスペースや特殊文字が含まれる場合、値を適切に引用符で囲む必要があります。囲まないと、パースエラーになることがあります。

  • 問題のある例（スペースを含む文字列）
# エラーになる可能性
# yq -i '.message = Hello World' config.yaml
  • 正しい例
yq -i '.message = "Hello World"' config.yaml

また、既に引用符で囲まれた文字列をyqで出力する場合、デフォルトでは引用符なしで表示されます。引用符を付けて出力したい場合は、-sオプション（--style）や@jsonフィルターを使います。

2. YAMLとJSONの入力/出力形式

yqは入力ファイルの形式を自動的に判別します。しかし、出力形式は指定しないと入力と同じ形式になります。

  • YAMLファイルをJSON形式で出力する

config.yamlをJSON形式で標準出力に表示するには、-o jsonオプションを使います。

yq -o json '.' config.yaml

出力例は以下の通りです。

{
  "server": {
    "host": "0.0.0.0",
    "port": 80,
    "timeout": 30
  },
  "database": {
    "type": "postgres",
    "user": "admin"
  },
  "features": {
    "enabled": false,
    "list": [
      "item1",
      "item2",
      "item3"
    ]
  },
  "message": "Hello World"
}
  • JSONファイルをYAML形式で出力する

例えば、data.jsonというファイルがあるとします。

{
  "name": "example",
  "version": "1.0.0"
}

これをYAML形式で出力するには、次のようにします。

yq -o yaml '.' data.json

3. 空のリストやマップの扱い

新しいリストやマップを追加する際、そのまま要素を追加しようとするとエラーになることがあります。先に空のリスト[]やマップ{}で初期化してから要素を追加するのが安全です。

  • 新しい空のリストを追加してから要素を入れる

new_featuresという新しいリストを追加し、そこに要素を追加する例です。

yq -i '.new_features = [] | .new_features += ["new_item"]' config.yaml

このコマンドは、new_featuresキーを空のリストとして追加し、その後new_itemを追加します。

4. 複数ファイルの処理

複数の設定ファイルに対して同じ変更を適用したい場合、findコマンドなどと組み合わせると非常に強力です。

  • 複数のYAMLファイルを一括で変更する

カレントディレクトリとそのサブディレクトリにあるすべての.yamlファイルのversionキーを2.0.0に更新する例です。

find . -name "*.yaml" -exec yq -i '.version = "2.0.0"' {} \;

このコマンドは、見つかった各*.yamlファイルに対してyq -i '.version = "2.0.0"' <ファイル名>を実行します。

これらのポイントを押さえることで、yqをよりスムーズに活用できるでしょう。

yqで設定ファイル操作を自動化する

yqは、設定ファイル操作の強い味方です。手作業によるミスを減らし、開発作業をスムーズにします。基本的な使い方をマスターするだけで、日々の業務における設定ファイルの取り扱いが大きく変わります。

CI/CDパイプラインでの設定値の動的な変更、開発環境と本番環境で異なる設定の自動生成、あるいはシンプルな設定ファイルのバージョン管理など、yqの活用シーンは多岐にわたります。コマンドラインでの一貫した操作は、スクリプト化のしやすさにも直結します。

今日から設定ファイルの編集を自動化しましょう。

今日から実行できるアクションプラン

  • yqを今すぐインストールしてみる。
  • 手元のYAMLまたはJSONファイルで、この記事で紹介した値の読み取りを試す。
  • 練習用のファイルを作成し、簡単な値の変更や新しい要素の追加・削除を実行してみる。

参考文献

まとめ・次のステップ

この記事が役に立ったら、ブログのメールマガジンへ登録してください。 AI活用・個人開発・副業に関する最新情報を週1回お届けします。

👉 無料メルマガに登録する（Waitlist）

このブログでは、会社員をしながら副業でSaaSを開発する過程をリアルに発信しています。使用スタック: Next.js / Supabase / Claude API / Vercel

広告

-AI, 記事