この記事はカオナビ Advent Calendar 2025 シリーズ3の14日目です。

みなさん、リレーショナルデータベースのJSON型カラムは使っていますか？
JSON型カラムは、NoSQLのような柔軟性をRDBMSに持ち込める便利な機能ですが、使い方を一歩間違えると「巨大な技術負債」になりかねない危険性も持ち合わせていると思います。

JSON型カラムとどう付き合うべきかを考え、特にGo言語での実装パターンについて書いてみます。

※この記事では、JSON型カラムに対するインデックスを用いた検索パフォーマンス等の話は扱いません。「データの整合性」と「保守性」にフォーカスします。

1. きっかけ：このカラムには何が入っているんだ？

以下のようなコードをみかけました（簡略化＆わかりやすいデータにしています）。

// フロントエンドから送られてきたJSONボディ
// 内容はユーザー設定のような、不定形のデータ
var data map[string]interface{}

if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
    // エラーハンドリング
}

// そのままDBへ保存
jsonBytes, _ := json.Marshal(data)
_, err := db.Exec("INSERT INTO user_settings (setting_json) VALUES (?)", jsonBytes)

このコードをみて非常に困りました。

中身がわからない: バックエンドのコードを読んでも、setting_json に何が入るかがさっぱりわかりません。
バリデーションがない: フロントエンドがバグで { "theme": "dark", "retry_count": "無限" } みたいなデータを送ってきても、そのまま保存されます。

これは、将来的に「データが壊れていてReadで落ちる」「何が入っているのが正解かわからない」という地獄を生み出します。

2. JSON型が“悪”ではないケース

誤解しないでいただきたいのは、「JSON型を使うな」と言いたいわけではないということです。

『SQLアンチパターン第2版』では、属性が動的に増減する要件に対して EAVというアンチパターンが紹介されています。これは attr_name と attr_value といったカラムで属性を管理する方法ですが、クエリが複雑化し、データ整合性を保つのが難しいという欠点があります。

同書では、このEAVの代替案の一つとして「半構造化データ（JSONやXML）」を挙げています。

JSON型の採用が適しているのは以下のようなケースです。

属性の増減が激しい: 頻繁な ALTER TABLE が現実的ではない場合。
サブタイプが多い: 商品カタログのように、「本」にはISBNが必要だが「服」にはサイズが必要、といった構造の違いがある場合。
外部APIのレスポンス保存: 外部サービスのレスポンスをそのまま監査ログとして残したい場合。

つまり、「スキーマレスな柔軟性が必要な箇所」にJSONを使うこと自体は正当な設計判断です。
問題は、「柔軟性にかこつけて、アプリケーション側での規律まで捨ててしまうこと」にあります。

3. アンチパターン：Mapで受けてバリデーションなしで保存

先ほどの map[string]interface{} で受けるパターンの何が問題か、もう少し掘り下げます。

DBは何も守ってくれない

通常のカラムであれば、INT型に文字列を入れようとすれば DB がエラーを吐きます。NOT NULL 制約も効きます。しかし、JSON型の中身に対して DB は（CHECK制約などを駆使しない限り）基本的に無関心です。

『SQLアンチパターン第2版』でも指摘されていますが、半構造化データやEAVのような設計では、「無効なデータを拒否する方法がない」という問題が発生します。
結果として、データの整合性を担保する責任は、データベースからアプリケーションコードへと委譲されます。

アプリケーションも守っていない

ここでアプリ側も map型で受けてスルーしてしまうと、誰もデータをチェックしない状態になります。「フロントエンドでバリデーションしているから大丈夫」は危険な妄言です。

4. 改善案：アプリ側でスキーマを持つ + バリデーション

JSON型を使うとしても、「バックエンドのコード上では厳格なスキーマを持つ」べきです。DBスキーマが緩い分、アプリ層のスキーマでカバーします。

Step 1: Goの構造体で「正解」を定義する

map ではなく、ちゃんと構造体を定義します。

// UserSetting はDBのJSONカラムに格納される構造
type UserSetting struct {
    Theme        string `json:"theme" validate:"required,oneof=light dark system"`
    ShowProfile  bool   `json:"show_profile"`
    NotificationConfig NotificationConfig `json:"notification"`
}

type NotificationConfig struct {
    EmailEnabled bool `json:"email_enabled"`
    PushEnabled  bool `json:"push_enabled"`
}

これで、コードを読むだけで「user_setting が持つプロパティ」や「theme には light, dark, system のいずれかが入ること」がわかります。ドキュメントとしての価値が生まれます。

Step 2: 保存前にバリデーションを通す

go-playground/validator などを使って、「DBに保存する前に」不正なデータを弾きます。

import (
    "encoding/json"
    "github.com/go-playground/validator/v10"
)

var validate = validator.New()

func CreateUserSetting(db *sql.DB, rawJSON []byte) error {
    var setting UserSetting

    // 1. 構造体へデコード（型チェック）
    // 数値フィールドに文字列が来るなどの型レベルの矛盾はここで落ちる
    if err := json.Unmarshal(rawJSON, &setting); err != nil {
        return fmt.Errorf("invalid json structure: %w", err)
    }

    // 2. バリデーション（値の整合性チェック）
    // 必須項目や、enum的な値の制約をチェック
    if err := validate.Struct(setting); err != nil {
        return fmt.Errorf("validation failed: %w", err)
    }

    // 3. 正規化されたJSONとして再エンコード
    // 入力JSONに余計なフィールドが含まれていても、ここで削ぎ落とされる
    saveBytes, err := json.Marshal(setting)
    if err != nil {
        return err
    }

    // 4. 保存
    _, err = db.Exec("INSERT INTO user_settings (setting_json) VALUES (?)", saveBytes)
    return err
}

この実装のメリット

仕様の明文化: 構造体がそのまま仕様書になります。
サニタイズ効果: 一度 Unmarshal して Marshal し直すことで、構造体に定義されていない「謎のフィールド」がDBに混入するのを防げます。
後方互換性の担保: DBからReadする際もこの構造体を通すことで、予期せぬデータ形式によるパニックを防ぎやすくなります。

※サンプルコードのため非常に簡易的ですが、実際にはもっとバリデーションが必要です。

5. (プラスアルファ) 運用：JSONのバージョニング

JSONデータ構造を変えたくなった場合（例: theme を廃止して color_mode にしたい）、既存データとの整合性問題が発生するので、JSONのルートに version フィールドを持たせておくと良いと思います。

type UserSetting struct {
    Version int    `json:"v"` // 1, 2, ...
    Data    any    `json:"data"`
}

あるいは、読み出し時にフィールドの有無で判断するロジックを組むかです。
いずれにせよ、「アプリケーションコード内で、新旧データの差異を吸収するロジック」が必要になります。JSON型を採用するなら、この「マイグレーションの複雑さ」をアプリ側で引き受ける覚悟も必要になると思います。

6. まとめ

JSON型カラムは、うまく使えばEAVの複雑さを回避しつつ、柔軟な設計を実現できると思います。
しかし、DBが許すから「何も考えずに何でも入れて良い」わけではないことを肝に銘じるのが良いと思います。
なんか至極当然な帰結になった気がすると思います。
そう思います。