# データベース設計書

## 概要

本ドキュメントは、Ghosttyプロジェクトにおけるデータ永続化機構を記載します。

Ghosttyはターミナルエミュレータであり、従来のRDBMS（MySQL、PostgreSQLなど）やNoSQLデータベースは使用していません。代わりに、以下のファイルベースのデータ永続化機構を採用しています：

1. **SSHキャッシュ** - リモートホストへのterminfo送信履歴を管理するフラットファイル形式のキャッシュ
2. **設定ファイル** - テキストベースの設定ファイル（データベースではないため本書では対象外）
3. **クラッシュレポート** - Sentry envelope形式のクラッシュログファイル（データベースではないため本書では対象外）

本設計書では、構造化されたデータストレージとして機能するSSHキャッシュについて詳細を記載します。

## テーブル一覧

| テーブル名 | 対応エンティティ | 説明 |
| --- | --- | --- |
| ssh_cache | SSHキャッシュエントリ | リモートホストへのGhostty terminfo送信履歴を管理するキャッシュ |

## 各テーブル定義

### 1. ssh_cache

SSHセッションにおいて、リモートホストへGhostty terminfoを送信したかどうかを追跡するためのキャッシュストレージです。このキャッシュにより、同一ホストへの冗長なterminfo送信を回避します。

**ストレージ形式**: フラットファイル（テキストファイル）
**保存場所**: `${XDG_STATE_HOME}/ghostty/ssh_cache`（デフォルト: `~/.local/state/ghostty/ssh_cache`）
**最大サイズ**: 512KB（約10,000エントリに対応）
**ファイルパーミッション**: 0600（所有者のみ読み書き可能）

**レコード形式**: パイプ区切りのテキスト形式
```
{hostname}|{timestamp}|{terminfo_version}
```

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| hostname | 文字列 | 不可 | リモートホストの識別子。ホスト名のみ、またはuser@hostname形式。IPv4/IPv6アドレスもサポート |
| timestamp | 64bit整数（i64） | 不可 | terminfoを送信したUNIXタイムスタンプ（秒単位） |
| terminfo_version | 文字列 | 不可 | 送信したterminfoのバージョン（デフォルト: "xterm-ghostty"） |

**制約事項**:
- hostnameはユニークキーとして機能（重複エントリは新しいタイムスタンプで上書き）
- hostnameの形式: 有効なホスト名、IPv4アドレス、IPv6アドレス、またはuser@hostname形式
- usernameは最大64文字、使用可能文字: a-z, A-Z, 0-9, _, -, .
- ホスト名は標準的なホスト名形式に準拠

**操作**:
- **追加/更新** (`add`): ホスト名をキャッシュに追加、または既存エントリのタイムスタンプを更新
- **削除** (`remove`): 指定ホスト名のエントリを削除
- **検索** (`contains`): 指定ホスト名がキャッシュに存在するか確認
- **一覧** (`list`): 全キャッシュエントリを取得
- **クリア** (`clear`): 全キャッシュを削除

**有効期限**:
- デフォルトでは無期限
- `--expire-days`オプションで有効期限を設定可能
- 期限切れエントリは書き込み操作時に自動的に除外

**排他制御**:
- ファイルロック（exclusive lock）による排他制御
- ロック取得失敗時は `CacheIsLocked` エラーを返却
- Windows環境ではファイルロックが無効（Zig標準ライブラリの制限）

**アトミック書き込み**:
- 一時ファイルへの書き込み後、アトミックにリネーム
- データ破損を防止

## 備考

### データベースを使用しない設計理由

Ghosttyは以下の理由により、従来のデータベースシステムを採用していません：

1. **依存関係の最小化**: ターミナルエミュレータとして外部データベースへの依存を避け、ポータビリティを確保
2. **シンプルなデータ構造**: 保存するデータがキー・値ペア程度の単純な構造であり、RDBMSのオーバーヘッドが不要
3. **セキュリティ**: キャッシュにはセンシティブな情報（パスワード、認証情報など）を保存しない設計
4. **パフォーマンス**: ファイルベースのキャッシュで十分な性能を確保可能

### 将来的な拡張

現時点ではファイルベースの単純なキャッシュのみですが、libghosttyライブラリとしての活用を見据え、データ永続化の仕組みが拡張される可能性があります。

### 関連ファイル

- `src/cli/ssh_cache.zig` - SSHキャッシュCLIコマンド実装
- `src/cli/ssh-cache/DiskCache.zig` - ディスクキャッシュ実装
- `src/cli/ssh-cache/Entry.zig` - キャッシュエントリ構造体定義
