basho 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5f5323bdc5e31562bad98e15914bb2c5f44d251331680bff9d72f62e98f3dd5
-  data.tar.gz: 2630ca02ae2b433e1ac8b07bd01ed2a433cb9a4c71129203f7eba97a33288f26
+  metadata.gz: a14446b90ac21440261e1558b52c2341bbe32fb4ab719c2b04932c3a7b34a5cf
+  data.tar.gz: 4416cb182886440853437ebc63c85d60028063fb9d282edd9a61883cb90060e5
 SHA512:
-  metadata.gz: a8568a1295db1355c61d52ac255ed88d6022c2443737511b68e7b94f1e99695881fb715d5d9ffc8eb54751f5229a3b9198bb7f2595ccc61361cf7fd90d2e7e22
-  data.tar.gz: d97d0878f043c93760069c843d0908649f5d152be57435b976cc21306fc1a61b217a3000a4bb76f81a131ac3be6f28dc43908023f45a77dfb820302e4413e003
+  metadata.gz: 01632dfab1fcbd4c3186cf289ceb9bcd0ddbe6aee1ad8253306e1c2cb08ea676b0d84cda27c7c7bbff7de47dd802c651eb876104e4d221793e0cffe7c868936d
+  data.tar.gz: cda91a973465799bc067da98d038339ad71cd9095be33fe7f86f7ab0679de57ad7c7927798bce0451a1a65c6d174bddaad9ae4eea086568035558a4269d2942e

data/.yardopts

@@ -0,0 +1,8 @@
+--markup markdown
+--charset utf-8
+--output-dir doc
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-02-11
+
+### Added
+
+- オプションDBバックエンド（`basho_prefectures` / `basho_cities` テーブル）
+- `rails generate basho:install_tables` マイグレーションジェネレータ
+- `rails basho:seed` Rakeタスク（冪等、JSON→DB一括投入）
+- `Basho::DB::Prefecture` / `Basho::DB::City` ActiveRecordモデル
+- `Basho.db?` によるDB自動検出（スレッドセーフ、キャッシュ付き）
+- テーブルが存在すれば公開API（`Prefecture.find`, `City.where`等）が自動でDB経由に切り替わる
+- READMEにDB Backendセクション追加（EN/JA）
+
 ## [0.3.0] - 2026-02-11
 
 ### Changed
@@ -85,6 +97,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - GitHub Actions CI（Ruby 3.2/3.3/3.4）
 - 月次データ自動更新ワークフロー
 
+[0.4.0]: https://github.com/wagai/basho/releases/tag/v0.4.0
 [0.3.0]: https://github.com/wagai/basho/releases/tag/v0.3.0
 [0.2.2]: https://github.com/wagai/basho/releases/tag/v0.2.2
 [0.2.1]: https://github.com/wagai/basho/releases/tag/v0.2.1

data/README.ja.md

@@ -18,6 +18,7 @@ Bashoはこれらをまとめて解決します。
 ## 特徴
 
 - **DBマイグレーション不要** -- 全データをJSON同梱。`gem install`だけで使える
+- **オプションDBバックエンド** -- テーブル生成でJOINや外部キー制約に対応。APIは自動で切り替わる
 - **フレームワーク非依存** -- 素のRuby、Sinatra、Rails API only、どこでも動く
 - **ActiveRecord統合** -- `include Basho` + 1行のマクロで郵便番号→住所の自動保存
 - **Hotwire対応** -- Turbo Frame + Stimulusによる郵便番号自動入力をビルトインEngine提供
@@ -388,6 +389,76 @@ class Shop < ApplicationRecord
 end
 ```
 
+## DBバックエンド（オプション）
+
+デフォルトではBashoは同梱のJSONファイルからデータを読み込みます。DB不要です。JOINや外部キー制約が必要な場合、または自前のテーブルから`basho_prefectures` / `basho_cities`を参照したい場合は、オプションでDBテーブルを生成できます。
+
+### セットアップ
+
+```bash
+rails generate basho:install_tables
+rails db:migrate
+rails basho:seed
+```
+
+2つのテーブルが作成されます:
+
+| テーブル | 主キー | 件数 |
+|---------|--------|------|
+| `basho_prefectures` | `code` (integer) | 47 |
+| `basho_cities` | `code` (string, 6桁) | 約1,900 |
+
+### 透過的な自動切り替え
+
+テーブルが存在すれば、公開API（`Basho::Prefecture.find`、`Basho::City.where`等）は自動的にDBバックエンドを使います。**コード変更は不要です。**
+
+```ruby
+# DBテーブルの有無に関わらず同じコードで動く
+Basho::Prefecture.find(13).name           # => "東京都"
+Basho::City.find("131016").full_name      # => "千代田区"
+Basho::City.where(prefecture_code: 13)    # => Array
+```
+
+検出は初回アクセス時に1度だけ行われ、プロセスの生存期間中キャッシュされます。
+
+### 自前テーブルからの外部キー
+
+```ruby
+# アプリ側のマイグレーション
+add_foreign_key :shops, :basho_cities, column: :city_code, primary_key: :code
+add_foreign_key :shops, :basho_prefectures, column: :prefecture_code, primary_key: :code
+```
+
+### DBモデルの直接利用
+
+ActiveRecordの機能（JOIN、スコープ、eager loading）が必要な場合は、DBモデルを直接使います:
+
+```ruby
+# JOIN
+Basho::DB::City.joins(:prefecture).where(basho_prefectures: { region_name: "関東" })
+
+# Eager loading
+Basho::DB::Prefecture.includes(:cities).find(13)
+
+# アソシエーション
+prefecture = Basho::DB::Prefecture.find(13)
+prefecture.cities    # => ActiveRecord::Relation
+prefecture.capital   # => Basho::DB::City
+```
+
+### 再シード
+
+`basho:seed`は冪等です。gem更新後に再実行すればデータが更新されます:
+
+```bash
+rails basho:seed
+```
+
+### 補足
+
+- 郵便番号はDBテーブルに**含まれません**（12万件以上、月次更新のため）。常にJSONファイルから提供されます。
+- `Basho.db?`はスレッドセーフでキャッシュされます。再検出が必要な場合（テスト中のマイグレーション後など）は`Basho.reset_db_cache!`を使ってください。
+
 ## データソース
 
 | データ | ソース | 更新頻度 |

data/README.md

@@ -18,6 +18,7 @@ Basho solves all of these.
 ## Features
 
 - **No DB migrations** -- All data is bundled as JSON. Just `gem install` and go
+- **Optional DB backend** -- Generate tables for JOINs and foreign keys. The API auto-switches transparently
 - **Framework-agnostic** -- Works with plain Ruby, Sinatra, Rails API-only, or any Ruby app
 - **ActiveRecord integration** -- `include Basho` + a one-line macro for automatic postal code to address resolution on save
 - **Hotwire-ready** -- Built-in Rails Engine with postal code auto-fill via Turbo Frame + Stimulus
@@ -388,6 +389,76 @@ class Shop < ApplicationRecord
 end
 ```
 
+## DB Backend (Optional)
+
+By default, Basho loads all data from bundled JSON files -- no database needed. If you need JOINs, foreign key constraints, or want to reference `basho_prefectures` / `basho_cities` from your own tables, you can optionally generate DB tables.
+
+### Setup
+
+```bash
+rails generate basho:install_tables
+rails db:migrate
+rails basho:seed
+```
+
+This creates two tables:
+
+| Table | Primary Key | Rows |
+|-------|------------|------|
+| `basho_prefectures` | `code` (integer) | 47 |
+| `basho_cities` | `code` (string, 6-digit) | ~1,900 |
+
+### Transparent Auto-switching
+
+Once the tables exist, the public API (`Basho::Prefecture.find`, `Basho::City.where`, etc.) automatically uses the DB backend. **No code changes required.**
+
+```ruby
+# Works exactly the same whether DB tables exist or not
+Basho::Prefecture.find(13).name           # => "東京都"
+Basho::City.find("131016").full_name      # => "千代田区"
+Basho::City.where(prefecture_code: 13)    # => Array
+```
+
+Detection happens once on first access via `Basho.db?` and is cached for the process lifetime.
+
+### Foreign Keys from Your Tables
+
+```ruby
+# Your app migration
+add_foreign_key :shops, :basho_cities, column: :city_code, primary_key: :code
+add_foreign_key :shops, :basho_prefectures, column: :prefecture_code, primary_key: :code
+```
+
+### Direct DB Model Access
+
+When you need ActiveRecord features (JOINs, scopes, eager loading), use the DB models directly:
+
+```ruby
+# JOINs
+Basho::DB::City.joins(:prefecture).where(basho_prefectures: { region_name: "関東" })
+
+# Eager loading
+Basho::DB::Prefecture.includes(:cities).find(13)
+
+# Associations
+prefecture = Basho::DB::Prefecture.find(13)
+prefecture.cities    # => ActiveRecord::Relation
+prefecture.capital   # => Basho::DB::City
+```
+
+### Re-seeding
+
+`basho:seed` is idempotent. Run it again after updating the gem to refresh the data:
+
+```bash
+rails basho:seed
+```
+
+### Notes
+
+- Postal codes are **not** included in the DB tables (120k+ rows, updated monthly). They are always served from bundled JSON files.
+- `Basho.db?` is thread-safe and cached. Use `Basho.reset_db_cache!` if you need to re-detect (e.g. after running migrations in a test).
+
 ## Data Sources
 
 | Data | Source | Update Frequency |

data/lib/basho/active_record/base.rb

@@ -3,9 +3,22 @@
 require_relative "postal_auto_resolve"
 
 module Basho
+  # ActiveRecord統合機能を提供する名前空間。
   module ActiveRecord
-    # ActiveRecordモデルにbasho / basho_postalマクロを提供する
+    # ActiveRecordモデルに +basho+ / +basho_postal+ マクロを提供するモジュール。
+    # +include Basho+ で自動的に extend される。
+    #
+    # @example
+    #   class Shop < ApplicationRecord
+    #     include Basho
+    #     basho :city_code
+    #     basho_postal :postal_code, prefecture: :pref_name, city: :city_name
+    #   end
     module Base
+      # 自治体コードカラムから +city+, +prefecture+, +full_address+ メソッドを定義する。
+      #
+      # @param column [Symbol, String] 6桁自治体コードを格納するカラム名
+      # @return [void]
       def basho(column)
         column_name = column.to_s
 
@@ -18,6 +31,17 @@ module Basho
         end
       end
 
+      # 郵便番号カラムから +postal_address+ メソッドを定義する。
+      # マッピングオプションを渡すと +before_save+ で住所カラムを自動入力する。
+      #
+      # @param column [Symbol, String] 郵便番号を格納するカラム名
+      # @param mappings [Hash] マッピングオプション
+      # @option mappings [Symbol] :prefecture 都道府県名の保存先カラム
+      # @option mappings [Symbol] :city 市区町村名の保存先カラム
+      # @option mappings [Symbol] :town 町域名の保存先カラム
+      # @option mappings [Symbol] :prefecture_code 都道府県コードの保存先カラム
+      # @option mappings [Symbol] :city_code 自治体コードの保存先カラム
+      # @return [void]
       def basho_postal(column, **mappings)
         column_name = column.to_s
 

data/lib/basho/active_record/postal_auto_resolve.rb

@@ -2,12 +2,22 @@
 
 module Basho
   module ActiveRecord
-    # 郵便番号変更時にbefore_saveで住所カラムを自動解決する
+    # 郵便番号変更時に +before_save+ で住所カラムを自動解決する。
+    # {Base#basho_postal} のマッピングオプション指定時に使用される。
+    #
+    # @api private
     module PostalAutoResolve
+      # サポートするマッピングキーの一覧
       MAPPING_KEYS = %i[prefecture city town prefecture_code city_code].freeze
 
       module_function
 
+      # モデルに +before_save+ コールバックを登録する。
+      #
+      # @param model_class [Class] ActiveRecordモデルクラス
+      # @param postal_column [String] 郵便番号カラム名
+      # @param mappings [Hash] マッピング設定
+      # @return [void]
       def install(model_class, postal_column, mappings)
         unless model_class.respond_to?(:before_save)
           raise Basho::Error, "#{model_class} does not support before_save callbacks"
@@ -27,6 +37,11 @@ module Basho
         end
       end
 
+      # マッピングキーに対応する値を郵便番号データから解決する。
+      #
+      # @param postal [PostalCode, nil] 郵便番号データ
+      # @param key [Symbol] マッピングキー
+      # @return [String, Integer, nil]
       def resolve_value(postal, key)
         return nil unless postal
 
@@ -39,6 +54,10 @@ module Basho
         end
       end
 
+      # 郵便番号データから自治体コードを逆引きする。
+      #
+      # @param postal [PostalCode] 郵便番号データ
+      # @return [String, nil] 6桁自治体コード
       def resolve_city_code(postal)
         City.where(prefecture_code: postal.prefecture_code)
             .find { |c| c.full_name == postal.city_name }&.code

data/lib/basho/city.rb

@@ -1,33 +1,73 @@
 # frozen_string_literal: true
 
 module Basho
+  # 市区町村を表すイミュータブルなデータクラス。
+  #
+  # DBバックエンドが有効な場合、クラスメソッドは自動的に {DB::City} 経由で検索する。
+  #
+  # @!attribute [r] code
+  #   @return [String] 6桁自治体コード（JIS X 0401 + チェックディジット、例: "131016"）
+  # @!attribute [r] prefecture_code
+  #   @return [Integer] 都道府県コード（1〜47）
+  # @!attribute [r] name
+  #   @return [String] 市区町村名（例: "千代田区"）
+  # @!attribute [r] name_kana
+  #   @return [String] カタカナ名（例: "チヨダク"）
+  # @!attribute [r] district
+  #   @return [String, nil] 郡名（例: "島尻郡"）。郡に属する町村のみ設定
+  # @!attribute [r] capital
+  #   @return [Boolean] 県庁所在地フラグ
   City = ::Data.define(:code, :prefecture_code, :name, :name_kana, :district, :capital) do
     def initialize(district: nil, capital: false, **)
       super
     end
 
+    # 県庁所在地かどうかを返す。
+    #
+    # @return [Boolean]
     def capital? = capital
 
+    # 郡名付きの正式名を返す。郡がない場合は {#name} と同じ。
+    #
+    # @return [String] 例: "島尻郡八重瀬町"
     def full_name
       district ? "#{district}#{name}" : name
     end
 
+    # 所属する都道府県を返す。
+    #
+    # @return [Prefecture, DB::Prefecture]
     def prefecture
       Prefecture.find(prefecture_code)
     end
 
     class << self
+      # 6桁自治体コードで市区町村を検索する。
+      #
+      # @param code [String] 6桁自治体コード（例: "131016"）
+      # @return [City, DB::City, nil]
       def find(code)
         return nil unless code.is_a?(String) && code.size == 6
+        return DB::City.find_by(code: code) if Basho.db?
 
-        prefecture_code = code[0..1].to_i
-        where(prefecture_code: prefecture_code).find { |city| city.code == code }
+        pref_code = code[0..1].to_i
+        where(prefecture_code: pref_code).find { |city| city.code == code }
       end
 
+      # 都道府県コードで市区町村を絞り込む。
+      #
+      # @param prefecture_code [Integer] 都道府県コード
+      # @return [Array<City>, Array<DB::City>]
       def where(prefecture_code:)
+        return DB::City.where(prefecture_code: prefecture_code).to_a if Basho.db?
+
         Data::Loader.cities(prefecture_code).map { |data| new(**data) }
       end
 
+      # JIS X 0401 チェックディジットで自治体コードを検証する。
+      #
+      # @param code [String] 6桁自治体コード
+      # @return [Boolean]
       def valid_code?(code)
         CodeValidator.valid?(code)
       end

data/lib/basho/code_validator.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 module Basho
-  # JIS X 0401 チェックディジットによる自治体コード検証
+  # JIS X 0401 チェックディジットによる6桁自治体コードの検証。
+  #
+  # @example
+  #   Basho::CodeValidator.valid?("131016") # => true
+  #   Basho::CodeValidator.valid?("131019") # => false
   module CodeValidator
+    # チェックディジットの桁位置（0始まり）
     CHECK_DIGITS_INDEX = 5
+    # モジュラス演算の基数
     CHECK_BASE = 11
+    # 有効な都道府県コード範囲
     PREFECTURE_RANGE = (1..47)
 
     module_function
 
+    # 自治体コードの形式とチェックディジットを検証する。
+    #
+    # @param code [String] 6桁自治体コード
+    # @return [Boolean]
     def valid?(code)
       return false unless code.is_a?(String) && code.match?(/\A\d{6}\z/)
       return false unless PREFECTURE_RANGE.cover?(code[0..1].to_i)
@@ -16,6 +27,10 @@ module Basho
       code[CHECK_DIGITS_INDEX].to_i == compute_check_digit(code)
     end
 
+    # チェックディジットを計算する。
+    #
+    # @param code [String] 6桁自治体コード
+    # @return [Integer] 0〜9のチェックディジット
     def compute_check_digit(code)
       sub_total = code.chars
                       .take(CHECK_DIGITS_INDEX)

data/lib/basho/data/loader.rb

@@ -3,24 +3,43 @@
 require "json"
 
 module Basho
+  # 同梱データの読み込みに関する名前空間。
   module Data
-    # 組み込みJSONデータの遅延読み込みとキャッシュ
+    # 同梱JSONデータの遅延読み込みとキャッシュ。
+    # 各メソッドは初回呼び出し時にJSONファイルを読み込み、以降はキャッシュを返す。
+    #
+    # @api private
     class Loader
+      # 同梱JSONデータのディレクトリパス
       DATA_DIR = File.expand_path("../../../data", __dir__)
 
       class << self
+        # 全47都道府県データを返す。
+        #
+        # @return [Array<Hash>]
         def prefectures
           @prefectures ||= load_json("prefectures.json")
         end
 
+        # 指定した都道府県の市区町村データを返す。
+        #
+        # @param prefecture_code [Integer] 都道府県コード
+        # @return [Array<Hash>]
         def cities(prefecture_code)
           cities_cache[prefecture_code] ||= load_json("cities/#{format("%02d", prefecture_code)}.json")
         end
 
+        # 指定したプレフィックスの郵便番号データを返す。
+        #
+        # @param prefix [String] 3桁プレフィックス（例: "154"）
+        # @return [Array<Hash>]
         def postal_codes(prefix)
           postal_cache[prefix] ||= load_json("postal_codes/#{prefix}.json")
         end
 
+        # 全キャッシュをクリアする。
+        #
+        # @return [void]
         def reset!
           instance_variables.each { |var| remove_instance_variable(var) }
         end

data/lib/basho/db/city.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Basho
+  module DB
+    # 市区町村のActiveRecordモデル（+basho_cities+ テーブル）。
+    # メモリ版 {Basho::City} と同じAPI（+full_name+, +capital?+）を提供する。
+    class City < ::ActiveRecord::Base
+      self.table_name = "basho_cities"
+      self.primary_key = "code"
+
+      belongs_to :prefecture,
+                 class_name: "Basho::DB::Prefecture",
+                 foreign_key: :prefecture_code,
+                 inverse_of: :cities
+
+      # 郡名付きの正式名を返す。
+      #
+      # @return [String]
+      def full_name
+        district ? "#{district}#{name}" : name
+      end
+    end
+  end
+end

data/lib/basho/db/prefecture.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Basho
+  module DB
+    # 都道府県のActiveRecordモデル（+basho_prefectures+ テーブル）。
+    # メモリ版 {Basho::Prefecture} と同じAPI（+type+, +region+, +capital+）を提供する。
+    class Prefecture < ::ActiveRecord::Base
+      self.table_name = "basho_prefectures"
+      self.primary_key = "code"
+
+      has_many :cities,
+               class_name: "Basho::DB::City",
+               foreign_key: :prefecture_code,
+               inverse_of: :prefecture
+
+      # @return [String] 種別（"都" / "道" / "府" / "県"）
+      def type = prefecture_type
+
+      # @return [Region]
+      def region = Region.find(region_name)
+
+      # @return [DB::City, nil] 県庁所在地
+      def capital = capital_code && Basho::DB::City.find_by(code: capital_code)
+    end
+  end
+end

data/lib/basho/db.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "db/prefecture"
+require_relative "db/city"
+
+module Basho
+  # ActiveRecordバックエンド（オプション）。
+  # +basho_prefectures+ / +basho_cities+ テーブルへのアクセスとシードを提供する。
+  module DB
+    # JSONデータをDBに一括投入する。冪等（何度実行しても同じ結果）。
+    #
+    # @return [Hash{Symbol => Integer}] 投入件数（+:prefectures+, +:cities+）
+    def self.seed!
+      prefs = prefecture_rows
+      cities = city_rows
+
+      ::ActiveRecord::Base.transaction do
+        City.delete_all
+        Prefecture.delete_all
+
+        Prefecture.insert_all!(prefs)
+        City.insert_all!(cities)
+      end
+
+      { prefectures: prefs.size, cities: cities.size }
+    end
+
+    def self.prefecture_rows
+      Data::Loader.prefectures.map do |pref|
+        pref.except(:type).merge(prefecture_type: pref[:type])
+      end
+    end
+    private_class_method :prefecture_rows
+
+    def self.city_rows
+      (1..47).flat_map do |code|
+        Data::Loader.cities(code).map do |city|
+          { district: nil, capital: false, **city }
+        end
+      end
+    end
+    private_class_method :city_rows
+  end
+end

data/lib/basho/engine.rb

@@ -18,5 +18,9 @@ module Basho
     initializer "basho.assets" do |app|
       app.config.assets.paths << root.join("app/assets/javascripts") if app.config.respond_to?(:assets)
     end
+
+    rake_tasks do
+      load File.expand_path("../../tasks/basho.rake", __dir__)
+    end
   end
 end

data/lib/basho/postal_code.rb

@@ -1,24 +1,52 @@
 # frozen_string_literal: true
 
 module Basho
+  # 郵便番号を表すイミュータブルなデータクラス。
+  # 常にJSONファイルから読み込む（DBバックエンド対象外）。
+  #
+  # @!attribute [r] code
+  #   @return [String] 7桁郵便番号（ハイフンなし、例: "1540011"）
+  # @!attribute [r] prefecture_code
+  #   @return [Integer] 都道府県コード（1〜47）
+  # @!attribute [r] city_name
+  #   @return [String] 市区町村名（例: "世田谷区"）
+  # @!attribute [r] town
+  #   @return [String] 町域名（例: "上馬"）
   PostalCode = ::Data.define(:code, :prefecture_code, :city_name, :town) do
+    # ハイフン付きの郵便番号を返す。
+    #
+    # @return [String] 例: "154-0011"
     def formatted_code
       "#{code[0..2]}-#{code[3..]}"
     end
 
+    # 都道府県名を返す。
+    #
+    # @return [String, nil] 例: "東京都"
     def prefecture_name
       prefecture&.name
     end
 
+    # 所属する都道府県を返す。
+    #
+    # @return [Prefecture, DB::Prefecture, nil]
     def prefecture
       Prefecture.find(prefecture_code)
     end
 
     class << self
+      # 郵便番号で検索する。ハイフン有無どちらも可。
+      #
+      # @param code [String] 郵便番号（例: "154-0011", "1540011"）
+      # @return [PostalCode, nil]
       def find(code)
         where(code: code).first
       end
 
+      # 郵便番号で検索し、配列で返す。共有郵便番号の場合は複数件。
+      #
+      # @param code [String] 郵便番号
+      # @return [Array<PostalCode>]
       def where(code:)
         normalized = code.to_s.delete("-")
         return [] unless normalized.match?(/\A\d{7}\z/)

data/lib/basho/prefecture.rb

@@ -1,46 +1,94 @@
 # frozen_string_literal: true
 
 module Basho
+  # 都道府県を表すイミュータブルなデータクラス。
+  #
+  # DBバックエンドが有効な場合、クラスメソッドは自動的に {DB::Prefecture} 経由で検索する。
+  #
+  # @!attribute [r] code
+  #   @return [Integer] JIS X 0401 都道府県コード（1〜47）
+  # @!attribute [r] name
+  #   @return [String] 都道府県名（例: "東京都"）
+  # @!attribute [r] name_en
+  #   @return [String] 英語名（例: "Tokyo"）
+  # @!attribute [r] name_kana
+  #   @return [String] カタカナ名（例: "トウキョウト"）
+  # @!attribute [r] name_hiragana
+  #   @return [String] ひらがな名（例: "とうきょうと"）
+  # @!attribute [r] region_name
+  #   @return [String] 地方名（例: "関東"）
+  # @!attribute [r] type
+  #   @return [String] 種別（"都" / "道" / "府" / "県"）
+  # @!attribute [r] capital_code
+  #   @return [String] 県庁所在地の6桁自治体コード（例: "131041"）
   Prefecture = ::Data.define(:code, :name, :name_en, :name_kana, :name_hiragana, :region_name, :type, :capital_code) do
+    # 所属する地方を返す。
+    #
+    # @return [Region]
     def region
       Region.find(region_name)
     end
 
+    # 所属する市区町村の一覧を返す。
+    #
+    # @return [Array<City>, Array<DB::City>]
     def cities
       City.where(prefecture_code: code)
     end
 
+    # 県庁所在地を返す。
+    #
+    # @return [City, DB::City, nil]
     def capital
       City.find(capital_code)
     end
 
     class << self
+      # 全47都道府県を返す。
+      #
+      # @return [Array<Prefecture>, Array<DB::Prefecture>]
       def all
-        @all ||= Data::Loader.prefectures.map { |data| new(**data) }
+        return DB::Prefecture.all.to_a if Basho.db?
+
+        @all ||= Data::Loader.prefectures.map { |data| new(**data) }.freeze
       end
 
+      # 都道府県を検索する。
+      #
+      # @overload find(code)
+      #   @param code [Integer] 都道府県コード
+      # @overload find(name:)
+      #   @param name [String] 日本語名（例: "東京都"）
+      # @overload find(name_en:)
+      #   @param name_en [String] 英語名（例: "Tokyo"）
+      # @return [Prefecture, DB::Prefecture, nil]
       def find(code = nil, **options)
-        if code
-          all.find { |pref| pref.code == code }
-        elsif options.any?
-          find_by_options(options)
-        end
+        attrs = code.nil? ? options : { code: code }
+        return if attrs.empty?
+
+        key, value = attrs.first
+        return DB::Prefecture.find_by(key => value) if Basho.db?
+
+        all.find { |pref| pref.public_send(key) == value }
       end
 
+      # 都道府県を地方名で絞り込む。引数なしで全件返す。
+      #
+      # @param region [String, nil] 地方名（例: "関東"）
+      # @return [Array<Prefecture>, Array<DB::Prefecture>]
       def where(region: nil)
         return all unless region
+        return DB::Prefecture.where(region_name: region).to_a if Basho.db?
 
-        all.select { |pref| pref.region&.name == region }
+        all.select { |pref| pref.region_name == region }
       end
 
-      private
-
-      def find_by_options(options)
-        if options[:name]
-          all.find { |pref| pref.name == options[:name] }
-        elsif options[:name_en]
-          all.find { |pref| pref.name_en == options[:name_en] }
-        end
+      # メモリキャッシュをクリアする。
+      #
+      # @return [void]
+      # @api private
+      def reset_cache!
+        remove_instance_variable(:@all) if defined?(@all)
       end
     end
   end

data/lib/basho/region.rb

@@ -1,12 +1,27 @@
 # frozen_string_literal: true
 
 module Basho
+  # 地方区分を表すイミュータブルなデータクラス。
+  # 北海道、東北、関東、中部、近畿、中国、四国、九州、沖縄の9地方。
+  #
+  # @!attribute [r] name
+  #   @return [String] 地方名（例: "関東"）
+  # @!attribute [r] name_en
+  #   @return [String] 英語名（例: "Kanto"）
+  # @!attribute [r] prefecture_codes
+  #   @return [Array<Integer>] 所属する都道府県コードの配列
   Region = ::Data.define(:name, :name_en, :prefecture_codes) do
+    # 所属する都道府県の一覧を返す。
+    #
+    # @return [Array<Prefecture>]
     def prefectures
       prefecture_codes.map { |code| Prefecture.find(code) }
     end
 
     class << self
+      # 全9地方を返す。
+      #
+      # @return [Array<Region>]
       def all
         @all ||= [
           new(name: "北海道", name_en: "Hokkaido", prefecture_codes: [1]),
@@ -21,6 +36,10 @@ module Basho
         ].freeze
       end
 
+      # 日本語名または英語名で地方を検索する。
+      #
+      # @param name [String] 地方名（例: "関東", "Kanto"）
+      # @return [Region, nil]
       def find(name)
         all.find { |region| region.name == name || region.name_en == name }
       end

data/lib/basho/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Basho
-  VERSION = "0.3.0"
+  # @return [String] 現在のgemバージョン
+  VERSION = "0.4.0"
 end

data/lib/basho.rb

@@ -10,10 +10,60 @@ require_relative "basho/postal_code"
 require_relative "basho/active_record/base"
 require_relative "basho/engine" if defined?(Rails::Engine)
 
-# 日本の住所データ（都道府県・市区町村・郵便番号・地方区分）を統一的に扱うgem
+# 日本の住所データ（都道府県・市区町村・郵便番号・地方区分）を統一的に扱うgem。
+#
+# デフォルトでは同梱のJSONファイルからデータを読み込む。
+# +basho_prefectures+ / +basho_cities+ テーブルが存在すれば自動的にDBバックエンドに切り替わる。
+#
+# @example ActiveRecordモデルでの利用
+#   class Shop < ApplicationRecord
+#     include Basho
+#     basho :city_code
+#     basho_postal :postal_code, prefecture: :pref_name, city: :city_name
+#   end
 module Basho
+  # basho gem固有のエラー基底クラス
   class Error < StandardError; end
 
+  @db_mutex = Mutex.new
+
+  # +basho_prefectures+ テーブルが存在するかを検出する。
+  # 結果はプロセスの生存期間中キャッシュされる。スレッドセーフ。
+  #
+  # @return [Boolean] DBバックエンドが利用可能なら +true+
+  def self.db?
+    return @db if defined?(@db)
+
+    @db_mutex.synchronize do
+      return @db if defined?(@db)
+
+      @db = defined?(::ActiveRecord::Base) &&
+            ::ActiveRecord::Base.connection.table_exists?("basho_prefectures")
+      require "basho/db" if @db
+      @db
+    end
+  rescue ::ActiveRecord::ConnectionNotEstablished, ::ActiveRecord::NoDatabaseError
+    @db = false
+  end
+
+  # DB検出キャッシュをリセットする。テスト時やマイグレーション後の再検出に使用。
+  #
+  # @return [void]
+  def self.reset_db_cache!
+    remove_instance_variable(:@db) if defined?(@db)
+    Prefecture.reset_cache! if Prefecture.respond_to?(:reset_cache!)
+  end
+
+  # バックエンドを強制指定する。主にテスト用。
+  #
+  # @param value [Boolean] +true+ でDBバックエンド、+false+ でメモリバックエンド
+  # @return [void]
+  def self.db=(value)
+    @db = value
+    require "basho/db" if value
+  end
+
+  # @private
   def self.included(base)
     base.extend ActiveRecord::Base
   end

data/lib/generators/basho/install_tables/install_tables_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Basho
+  # Railsジェネレータの名前空間。
+  module Generators
+    # +basho_prefectures+ / +basho_cities+ テーブルのマイグレーションジェネレータ。
+    #
+    # @example
+    #   rails generate basho:install_tables
+    class InstallTablesGenerator < Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "basho_prefectures / basho_cities テーブルのマイグレーションを生成"
+
+      # マイグレーションファイルを生成する。
+      # @return [void]
+      def create_migration_files
+        migration_template "create_basho_prefectures.rb.erb", "db/migrate/create_basho_prefectures.rb"
+        migration_template "create_basho_cities.rb.erb", "db/migrate/create_basho_cities.rb"
+      end
+    end
+  end
+end

data/lib/generators/basho/install_tables/templates/create_basho_cities.rb.erb

@@ -0,0 +1,15 @@
+class CreateBashoCities < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :basho_cities, id: false do |t|
+      t.string :code, limit: 6, null: false, primary_key: true
+      t.integer :prefecture_code, null: false
+      t.string :name, null: false
+      t.string :name_kana, null: false
+      t.string :district
+      t.boolean :capital, null: false, default: false
+    end
+
+    add_index :basho_cities, :prefecture_code
+    add_foreign_key :basho_cities, :basho_prefectures, column: :prefecture_code, primary_key: :code
+  end
+end

data/lib/generators/basho/install_tables/templates/create_basho_prefectures.rb.erb

@@ -0,0 +1,14 @@
+class CreateBashoPrefectures < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :basho_prefectures, id: false do |t|
+      t.integer :code, null: false, primary_key: true
+      t.string :name, null: false
+      t.string :name_en, null: false
+      t.string :name_kana, null: false
+      t.string :name_hiragana, null: false
+      t.string :region_name, null: false
+      t.string :prefecture_type, null: false
+      t.string :capital_code, limit: 6
+    end
+  end
+end

data/lib/tasks/basho.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+namespace :basho do
+  desc "basho_prefectures / basho_cities テーブルにデータを投入"
+  task seed: :environment do
+    require "basho/db"
+
+    counts = Basho::DB.seed!
+    puts "basho:seed 完了 — 都道府県: #{counts[:prefectures]}件, 市区町村: #{counts[:cities]}件"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basho
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Hirotaka Wagai
@@ -17,6 +17,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.ja.md
@@ -1030,11 +1031,18 @@ files:
 - lib/basho/city.rb
 - lib/basho/code_validator.rb
 - lib/basho/data/loader.rb
+- lib/basho/db.rb
+- lib/basho/db/city.rb
+- lib/basho/db/prefecture.rb
 - lib/basho/engine.rb
 - lib/basho/postal_code.rb
 - lib/basho/prefecture.rb
 - lib/basho/region.rb
 - lib/basho/version.rb
+- lib/generators/basho/install_tables/install_tables_generator.rb
+- lib/generators/basho/install_tables/templates/create_basho_cities.rb.erb
+- lib/generators/basho/install_tables/templates/create_basho_prefectures.rb.erb
+- lib/tasks/basho.rake
 - sig/basho.rbs
 homepage: https://github.com/wagai/basho
 licenses:
@@ -1058,7 +1066,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.4
 specification_version: 4
 summary: Japanese address data (prefectures, cities, postal codes, regions) in a single
   gem