HN 日本語サマリー

← 一覧へ戻る
プログラミング

SQLite用ゼロ依存、超軽量データベースタイムマシン

A zero-dependency, ultra-lightweight database time machine for SQLite (github.com)

12 pointsby thunderbong2 コメント

要約

このツールは、SQLiteデータベースファイルをローカル開発中に任意の過去の状態に即座に巻き戻すことができる、ゼロ依存の超軽量WebアプリケーションおよびCLIデーモンです。PHP 8+とVanilla JSのみで構築されており、依存関係がありません。スナップショットの視覚的な比較やピン留め、エクスポート機能も備えています。

全文翻訳

⏱️ Time-Travel SQLite Debugger (データベース時間旅行)

ローカル開発中に破損または変更されたSQLiteデータベースファイルを、ビデオを早送り・巻き戻しするように、過去の任意の時点(例: 3分前)に即座に巻き戻すことができる、オープンソースで超軽量なWebアプリケーションおよびCLIデーモンです。

🇹🇷 トルコ語ドキュメント: トルコ語のガイドについては、README.tr.md を参照してください。


⚠️ アーキテクチャとローカル開発に関する重要事項

  • ローカル開発専用: このツールは、依存関係ゼロのローカル開発デバッグ専用に設計されています。
  • WALチェックポイントとアボート保護: スナップショットの作成またはリストアを実行する前に、ツールはPDO経由で PRAGMA wal_checkpoint(TRUNCATE); を実行します。WALチェックポイントが失敗した場合(例: データベースがビジーまたはロックされている)、フラッシュされていないデータの記録や読み込みを防ぐため、操作は厳密に中止されます。成功した場合、すべてのWALフレームはメインの.sqliteファイルに書き込まれ、個別の-walまたは-shmバックアップファイルを必要とせずに競合状態を排除します。
  • リストア前のセーフティネットと検証: リストアの前に、自動的に pre-restore-safety-snapshot が生成されます。セーフティスナップショットの作成に失敗した場合、現在の状態を保護するためにリストアプロセスは直ちに中止されます。リストア後、PRAGMA integrity_check; がデータベース構造を検証します。
  • ローカルホストセキュリティとクォータ: APIアクセスはソケットピアIP (127.0.0.1 / ::1) に厳密に制限され、ディスク使用量は50個のピン留めされていないスナップショット数と1 GBのストレージ制限によって管理されます。

🚀 機能

  • ⚡ 依存関係ゼロ: 純粋なPHP 8+とVanilla JSで構築されています。重いフレームワークやnpmパッケージは不要です。
  • 💾 WALチェックポイントとコア整合性: スナップショット生成前に PRAGMA wal_checkpoint(TRUNCATE); を介してすべてのWALフレームをフラッシュします。チェックポイントが失敗した場合は、スナップショット生成を厳密に中止します。
  • ⏱️ マイクロ秒タイムスタンプと一意ID識別: microtime(true) + uniqid() ({timestamp}_{uniqid}_database.sqlite) を使用して、スナップショット名の衝突を防ぎます。
  • 🛡️ リストア前のセーフティネット: アクティブなデータベースを上書きする直前に、自動的に pre-restore-safety-snapshot を作成します。セーフバックアップが失敗した場合は、直ちにリストアを中止します。
  • ✅ リストア後の整合性検証: リストア直後に PRAGMA integrity_check; を実行し、検証結果をフロントエンドに報告します。
  • 🔍 ビジュアルデータとテーブル差分ビューア: リストア前に、履歴スナップショットと現在のライブデータベースとの間で、行数やテーブルの変更(例: liveに+3 rows)を比較できます。
  • ⚠️ アプリケーションワーカー再起動警告: リストア完了後、実行中のアプリワーカー(例: Laravel/PHPワーカー)にキャッシュされたSQLite接続をクリアするために再起動するよう、開発者に目立つように警告します。
  • 📌 スナップショットのピン留めとタグ付け: 重要なスナップショットをワンクリックでピン留めし、自動クリーンアップから保護します。ピン留めされたスナップショットは削除されず、バックアップの総数が公称の50ファイル制限を超える原因となる可能性があります。
  • 📥 ワンクリックスナップショットエクスポート: 履歴の任意のデータベース状態を.sqliteファイルとして直接ダウンロードできます。
  • 🧹 デュアルストレージクリーンアップ制限: 50個のピン留めされていないバックアップ数と1 GBのストレージ制限の両方を自動的に強制し、ピン留めされたスナップショットを保持しながら、必要に応じて古いピン留めされていないスナップショットをパージします。
  • 🔒 ローカルホストセキュリティチェック: APIリクエスト (api.php) をソケットピアIP (REMOTE_ADDRが127.0.0.1 / ::1と一致) に厳密に制限し、信頼できないプロキシヘッダー (X-Forwarded-For, X-Real-IP) は意図的に無視します。
  • 🌐 完全なi18n / 多言語対応: 翻訳ファイルは lang/ に分離されています(🇹🇷トルコ語、🇬🇧英語)。UIから動的に言語を切り替えることができます。

📁 プロジェクトレイアウト

time-travel/
├── index.html        # Chrono Console UI (Tailwind CSS + Vanilla JS + i18n Engine)
├── api.php           # スナップショット一覧、リストア、WALチェックポイント、整合性チェック & API
├── watcher.php       # CLIバックグラウンドリスナーデーモンスクリプト (WALチェックポイント & ストレージクォータ対応)
├── lang.php          # 多言語 (i18n) ヘルパークラス
├── lang/             # JSON言語ファイルディレクトリ
│   ├── tr.json       # トルコ語言語ファイル
│   └── en.json       # 英語言語ファイル
├── database.sqlite   # 対象SQLiteデータベースファイル (自動作成)
├── backups/          # タイムスタンプ付きバックアップディレクトリ (自動作成)
├── README.md         # 主要な英語ドキュメント
└── README.tr.md      # トルコ語ドキュメント & ガイド

🌍 翻訳ガイド: 言語ファイルの追加と更新

1. 新しい言語の追加

ISOコードに一致するJSONファイルを lang/ 内に作成します(例: lang/es.json, lang/de.json)。

{
  "code": "es",
  "name": "Español",
  "flag": "🇪🇸",
  "cli": { ... },
  "api": { ... },
  "ui":  { ... }
}
2. 既存の翻訳の更新

lang/*.json のいずれかのファイルを開いて文字列を編集します。変更はWeb UIとCLIにサーバーを再起動せずに即座に反映されます。


💻 インストールと使用方法

1. ウォッチャーデーモンの起動 (ターミナル1)
php watcher.php

カスタム言語またはデータベースファイルを指定する場合:

php watcher.php database.sqlite en
2. ローカルWebサーバーの起動 (ターミナル2)
php -S 127.0.0.1:8000
3. Webインターフェースを開く

ブラウザを開き、以下にアクセスします: http://127.0.0.1:8000


🧪 テスト方法

  1. Webインターフェースを開きます。
  2. 「✍️ テストデータ追加 (DB書き込み)」 をクリックします。
  3. watcher.php からのターミナル出力を観察します: [+] Created snapshot: 1770752711.1234_65c3b1a209e8f_database.sqlite
  4. タイムラインスライダーをドラッグするか、⬅️ / ➡️ 矢印キーを使用します。
  5. 「🔍 差分比較」 をクリックして、テーブルの行数を調べます。
  6. 「⚡ この状態に復元」 をクリックしてデータベースを巻き戻します!リストア前のセーフスナップショット作成、PRAGMA integrity_check 検証、ワーカー再起動の通知を確認します。

🔒 ファイルパーミッション (Linux / Unix)

SQLiteデータファイルやソースファイルに実行権限を付与せずにクリーンなローカルファイルパーミッションを設定するには、以下を実行します:

# ディレクトリパーミッション (775)
find . -type d -exec chmod 775 {} +

# ファイルパーミッション (664)
find . -type f -exec chmod 664 {} +

📄 ライセンス

このプロジェクトは MIT ライセンスの下でオープンソースとして公開されています。