MygramDB

日本語

English

日本語

English

Appearance

スナップショットコマンド ​

MygramDB は、検索インデックスの状態を保存・復元するためのスナップショットコマンドを提供します。スナップショットには、インデックス化されたデータ、設定、レプリケーション位置（GTID）が含まれます。

用語補足

このページでは「スナップショット」と「ダンプ」はほぼ同じ意味で使っています。どちらも、MygramDBのメモリ上の検索インデックスをファイルに保存したものです。

概要 ​

スナップショットは、以下を含む単一のバイナリファイル（.dmp）です：

  • MygramDB側の検索状態（すべてのテーブル、ドキュメント、インデックス）
  • 設定情報
  • 復旧時にbinlogを再開するためのレプリケーション位置（GTID）
  • 破損検出のための整合性チェックサム（CRC32）

v1.7.0以降、スナップショットメタデータには各テーブルのDB名も保存されます。これは、1つのMygramDBインスタンスに app_db.articles と archive_db.articles が共存するような複数DB構成で必要です。

MySQLのバックアップではありません

MygramDBのダンプは、MygramDBを速く復旧するためのファイルです。MySQL本体のバックアップではありません。MySQLのデータ保護には、別途MySQL側のバックアップを用意してください。

コマンド ​

コマンド目的既存データへの影響
DUMP SAVE現在の検索状態をファイルに保存置き換えなし
DUMP VERIFYファイル破損がないか検証置き換えなし
DUMP INFOGTID、テーブル数、作成時刻などを表示置き換えなし
DUMP LOADファイルから検索状態を復元現在の検索状態を置き換える

DUMP SAVE - スナップショット作成 ​

現在のMygramDBの検索状態をスナップショットファイルに保存します。

構文:

DUMP SAVE <filepath> [WITH STATISTICS]

パラメータ:

  • <filepath>: スナップショットファイルの保存先パス
  • WITH STATISTICS（オプション）: パフォーマンス統計情報をスナップショットに含める

例:

sql
-- 基本的なスナップショット
DUMP SAVE /var/lib/mygramdb/dumps/mygramdb.dmp

-- 統計情報付きスナップショット
DUMP SAVE /var/lib/mygramdb/dumps/mygramdb.dmp WITH STATISTICS

レスポンス:

OK SAVE /var/lib/mygramdb/dumps/mygramdb.dmp
tables: 2
size: 1234567 bytes
gtid: 3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10

DUMP LOAD - スナップショット復元 ​

スナップショットファイルを読み込み、MygramDBの検索状態を復元します。

構文:

DUMP LOAD <filepath>

パラメータ:

  • <filepath>: 読み込むスナップショットファイルのパス

例:

sql
DUMP LOAD /var/lib/mygramdb/dumps/mygramdb.dmp

レスポンス:

OK LOAD /var/lib/mygramdb/dumps/mygramdb.dmp
tables: 2
documents: 10000
gtid: 3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10

DUMP LOAD の重要事項

DUMP LOAD は現在のインデックスを置き換えます。誤ったファイルを読み込むと検索結果が古い状態に戻るため、必ず DUMP VERIFY と DUMP INFO でGTID・テーブル数・作成時刻を確認してから実行してください。

  • 読み込み後は、スナップショットに保存されたGTIDからレプリケーションを再開します。
  • すべてのテーブルが現在の設定ファイルに定義されている必要があります。
  • 複数DB構成では、設定済みテーブル識別子がダンプメタデータ（<database>.<table>）と一致している必要があります。
  • MygramDBは起動時にダンプファイルを自動読み込みしません。再起動後にダンプから復旧する場合は、MygramDBを起動してから手動で DUMP LOAD を実行してください。

DUMP VERIFY - 整合性チェック ​

スナップショットファイルを読み込まずに整合性を検証します。

構文:

DUMP VERIFY <filepath>

パラメータ:

  • <filepath>: 検証するスナップショットファイルのパス

例:

sql
DUMP VERIFY /var/lib/mygramdb/dumps/mygramdb.dmp

レスポンス（成功）:

OK VERIFY /var/lib/mygramdb/dumps/mygramdb.dmp
status: valid
crc: verified
size: verified

レスポンス（失敗）:

ERROR CRC mismatch: file may be corrupted
expected: 0x12345678
actual: 0x87654321

DUMP INFO - スナップショットメタデータ表示 ​

スナップショットファイルを読み込まずにメタデータを表示します。

構文:

DUMP INFO <filepath>

パラメータ:

  • <filepath>: スナップショットファイルのパス

例:

sql
DUMP INFO /var/lib/mygramdb/dumps/mygramdb.dmp

レスポンス:

OK INFO /var/lib/mygramdb/dumps/mygramdb.dmp
version: 1
gtid: 3E11FA47-71CA-11E1-9E33-C80AA9429562:1-10
tables: 2
flags: 0x18
  statistics: yes
size: 1234567 bytes
timestamp: 1672531200 (2023-01-01 00:00:00 UTC)

整合性保護 ​

CRC32チェックサム ​

すべてのスナップショットファイルには、複数レベルのCRC32チェックサムが含まれます：

  • ファイルレベルCRC: ファイル全体の破損を検出
  • セクションレベルCRC: 個別セクション（設定、統計、インデックス、ドキュメントストア）を検証

用語補足

CRC32 はファイルが壊れていないかを検出するための短い検査値です。暗号学的な改ざん検知ではありませんが、途中で切れたファイルやディスク破損の検出に役立ちます。

ファイルサイズ検証 ​

スナップショットヘッダーには期待されるファイルサイズが含まれます：

  • 不完全な書き込みを検出
  • ネットワーク転送の失敗をキャッチ
  • 切り詰められたファイルを識別

検証ワークフロー ​

読み込み前に必ずスナップショットの整合性を検証してください：

sql
-- 1. 整合性を検証
DUMP VERIFY mygramdb.dmp

-- 2. メタデータを確認
DUMP INFO mygramdb.dmp

-- 3. 問題なければ読み込み
DUMP LOAD mygramdb.dmp

エラーハンドリング ​

CRC不一致 ​

CRC検証が失敗した場合、スナップショットファイルが破損しています：

ERROR CRC32 mismatch: expected 0x12345678, got 0x87654321 (file may be corrupted)

対処方法:

  1. 破損したスナップショットは読み込まない
  2. バックアップコピーから復元を試みる
  3. 破損が頻繁に発生する場合はディスクの健全性をチェック

ファイル切り詰め ​

ファイルサイズが期待値と一致しない場合：

ERROR File size mismatch: expected 1234567 bytes, got 1000000 bytes (file may be truncated or corrupted)

対処方法:

  1. ファイルが完全に書き込まれなかった
  2. SAVE操作を再試行
  3. 利用可能なディスク容量を確認

バージョン不一致 ​

スナップショットのバージョンが新しすぎる場合：

ERROR Snapshot file version 2 is newer than supported version 1

対処方法:

  1. MygramDBを新しいバージョンにアップグレード
  2. または互換性のあるバージョンで作成されたスナップショットを使用

推奨事項 ​

自動スナップショット ​

MygramDBは、定期的にスナップショットを保存する設定に対応しています。

yaml
# config.yaml
dump:
  dir: /var/lib/mygramdb/dumps    # ダンプファイルのディレクトリ
  interval_sec: 600                 # 10分ごとに自動保存（0 = 無効）
  retain: 3                         # 最新の3つの自動保存ダンプを保持

機能:

  • 自動スナップショットはタイムスタンプベースのファイル名（auto_YYYYMMDD_HHMMSS.dmp）で保存されます
  • retainカウントに基づいて古い自動保存ファイルが自動的にクリーンアップされます
  • 手動スナップショット（DUMP SAVE経由）は自動クリーンアップの影響を受けません
  • ディレクトリのパーミッションは起動時に検証されます
  • 自動保存スナップショットはバックアップファイルであり、サーバー起動時に自動復元されるものではありません。

手動バックアップ ​

災害復旧のために手動スナップショットをスケジュールすることもできます：

bash
# 例: 日次バックアップスクリプト
#!/bin/bash
DATE=$(date +%Y%m%d)
echo "DUMP SAVE /var/lib/mygramdb/dumps/manual_${DATE}.dmp WITH STATISTICS" | mygram-cli

保持ポリシー ​

複数のスナップショットバージョンを保持します：

yaml
# config.yaml
dump:
  dir: /var/lib/mygramdb/dumps
  default_filename: mygramdb.dmp
  interval_sec: 600      # 10分ごとに保存
  retain: 3              # 最新の3つを保持

読み込み前の検証 ​

読み込み前に必ず整合性を検証します：

bash
# まず検証
echo "DUMP VERIFY mygramdb.dmp" | mygram-cli

# その後読み込み
echo "DUMP LOAD mygramdb.dmp" | mygram-cli

安全な保存 ​

スナップショットには機密データが含まれます：

  • MySQL接続認証情報
  • すべてのドキュメント内容
  • レプリケーション位置

推奨事項:

  1. ファイル権限を600（所有者の読み書きのみ）に設定
  2. 暗号化されたボリュームにスナップショットを保存
  3. リモートストレージには安全な転送プロトコル（SFTP、SCP）を使用
  4. アクセスログを監査

スナップショットサイズの監視 ​

スナップショットファイルサイズを経時的に追跡します：

bash
# スナップショットメタデータを確認
echo "DUMP INFO mygramdb.dmp" | mygram-cli

スナップショットサイズが予期せず増加する場合：

  • インデックスの肥大化をチェック
  • ドキュメント保持ポリシーを確認
  • データアーカイブを検討

パフォーマンス特性 ​

SAVE パフォーマンス ​

ドキュメント数平均テキスト長保存時間ファイルサイズ
10万100バイト~1-2秒~20 MB
100万100バイト~10-15秒~200 MB
1000万100バイト~2-3分~2 GB

LOAD パフォーマンス ​

ドキュメント数平均テキスト長読み込み時間
10万100バイト~2-3秒
100万100バイト~15-20秒
1000万100バイト~3-5分

パフォーマンスはハードウェア、ディスクI/O、データ特性によって異なります

設定 ​

ダンプの動作は config.yaml で設定できます：

yaml
dump:
  # ダンプファイルのディレクトリ
  dir: /var/lib/mygramdb/dumps

  # 指定されない場合のデフォルトファイル名（手動DUMP SAVEコマンド用）
  default_filename: mygramdb.dmp

  # 自動ダンプ間隔（秒、0 = 無効）
  interval_sec: 600  # 10分ごとに自動保存

  # 保持する自動保存ダンプ数（手動ダンプは影響を受けません）
  retain: 3  # 最新の3つの自動保存ダンプを保持

起動時チェック:

  • MygramDBは起動時にダンプディレクトリの権限を検証します
  • ディレクトリが存在しない場合は自動的に作成されます
  • ディレクトリが書き込み不可の場合、サーバーはエラーで起動に失敗します

レプリケーションリカバリ ​

ダンプからの復旧は運用者が明示的に実行します。MygramDBは起動時に dump.dirをスキャンしたり、最新ダンプを読み込んだりしません。まずサーバーを 起動し、対象ダンプを検証してからDUMP LOADを実行してください。

DUMP LOADが完了すると、MygramDBは自動的にレプリケーションを再開します：

  1. GTID抽出: スナップショットからレプリケーション位置を読み取り
  2. BinlogReader再開: 保存されたGTIDから継続
  3. 追いつき: 見逃したトランザクションを処理
  4. 通常運用: binlogレプリケーションに戻る

例:

# 1. サーバーがGTID 1-100でクラッシュ
# 2. MygramDBを再起動
# 3. GTID 1-80のスナップショットを検証して読み込み
DUMP VERIFY mygramdb.dmp
DUMP LOAD mygramdb.dmp

# 4. MygramDBは自動的にトランザクション81-100を処理
# 5. 101+からbinlogレプリケーションを再開

トラブルシューティング ​

"Failed to open snapshot file" ​

原因: ファイルが存在しないか、権限が不十分

解決方法:

bash
# ファイルの存在を確認
ls -l /path/to/snapshot.dmp

# 権限を確認
chmod 600 /path/to/snapshot.dmp

"Invalid snapshot version" ​

原因: 互換性のないMygramDBバージョンで作成されたスナップショット

解決方法:

  • MygramDBバージョンの互換性を確認
  • 同じメジャーバージョンで作成されたスナップショットを使用

"Table not found in config" ​

原因: スナップショットに現在の設定で定義されていないテーブルが含まれる

解決方法:

  • config.yamlを更新してスナップショットのすべてのテーブルを含める
  • または現在の設定で新しいスナップショットを作成

"CRC mismatch during load" ​

原因: スナップショットファイルが破損

解決方法:

  1. DUMP VERIFYを実行して破損セクションを特定
  2. バックアップコピーから復元
  3. ディスクの健全性とネットワークの信頼性を確認

関連コマンド ​

  • SEARCH: インデックス化されたドキュメントをクエリ
  • STATUS: データベースステータスとレプリケーション位置を確認
  • CONFIG RELOAD: 再起動なしで設定を再読み込み

参照 ​