# データベース設計書

## 概要

本ドキュメントは、Nushellプロジェクトにおけるデータベース機能の設計を記述します。Nushellは主にSQLiteをデータベースエンジンとして使用し、インメモリデータベース機能（`stor`コマンド群）と外部SQLiteファイルとの相互運用機能（`into sqlite`、`open`、`query db`コマンド）を提供しています。

## テーブル一覧

### インメモリデータベース（stor）

インメモリデータベースのテーブルはユーザーが動的に作成するため、固定のテーブル定義は存在しません。ただし、以下のデータ型マッピングが適用されます。

| テーブル名 | 対応エンティティ | 説明 |
| --- | --- | --- |
| ユーザー定義テーブル | stor createで作成 | `stor create --table-name <name> --columns <record>`で作成される動的テーブル |
| std_kv_store | KVストア機能 | `std-rfc/kv`モジュールで使用されるキーバリューストア用テーブル |

### メタデータ構造体

| 構造体名 | 対応エンティティ | 説明 |
| --- | --- | --- |
| DbTable | テーブルメタデータ | SQLiteテーブルのメタデータを保持 |
| DbColumn | カラムメタデータ | SQLiteカラムのメタデータを保持 |
| DbConstraint | 制約メタデータ | インデックス制約のメタデータを保持 |
| DbForeignKey | 外部キーメタデータ | 外部キー関係のメタデータを保持 |
| DbIndex | インデックスメタデータ | インデックスのメタデータを保持 |

## 各テーブル定義

### 1. ユーザー定義テーブル（動的テーブル）

`stor create`コマンドで作成される動的テーブルです。ユーザーが指定したカラム名とデータ型に基づいてCREATE TABLE文が生成されます。

**サポートされるデータ型マッピング:**

| Nushell型 | SQLite型 | NULL | 説明 |
| --- | --- | --- | --- |
| int | INTEGER | YES | 整数値 |
| float | REAL | YES | 浮動小数点数 |
| str | VARCHAR(255) | YES | 文字列（最大255文字） |
| bool | BOOLEAN | YES | 真偽値 |
| datetime | DATETIME | YES | 日時（デフォルト: 現在時刻） |
| json | JSON | YES | JSON形式データ |
| jsonb | JSONB | YES | バイナリJSON形式データ |

### 2. std_kv_store テーブル

`std-rfc/kv`モジュールで使用されるキーバリューストア用テーブルです。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| session | str | YES | セッション識別子（プレースホルダー） |
| key | str | YES | キー名 |
| value | str | YES | 値（nuon形式で保存） |

### 3. DbTable 構造体

SQLiteテーブルのメタデータを表現する構造体です。

| フィールド名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | String | NO | テーブル名 |
| create_time | chrono::DateTime<chrono::Utc> | YES | 作成日時 |
| update_time | chrono::DateTime<chrono::Utc> | YES | 更新日時 |
| engine | String | YES | ストレージエンジン |
| schema | String | YES | スキーマ名 |

### 4. DbColumn 構造体

SQLiteカラムのメタデータを表現する構造体です。

| フィールド名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| cid | i32 | YES | カラムインデックス |
| name | String | YES | カラム名 |
| type | String | YES | カラムのデータ型 |
| notnull | i16 | YES | NOT NULL制約（1: あり、0: なし） |
| default | String | YES | デフォルト値 |
| pk | i16 | YES | 主キーフラグ（1: 主キー、0: 非主キー） |

### 5. DbConstraint 構造体

インデックス制約のメタデータを表現する構造体です。

| フィールド名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | String | NO | 制約名（インデックス名） |
| column_name | String | NO | 対象カラム名 |
| origin | String | NO | 制約の起源（pk: 主キー、u: ユニーク） |

### 6. DbForeignKey 構造体

外部キー関係のメタデータを表現する構造体です。

| フィールド名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| column_name | String | YES | 外部キーカラム名 |
| ref_table | String | YES | 参照先テーブル名 |
| ref_column | String | YES | 参照先カラム名 |

### 7. DbIndex 構造体

インデックスのメタデータを表現する構造体です。

| フィールド名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | String | YES | インデックス名 |
| column_name | String | YES | 対象カラム名 |
| seqno | i16 | YES | シーケンス番号（複合インデックスの順序） |

## SQLite型変換マッピング

### Nushell値からSQLite型への変換（into sqlite）

`into sqlite`コマンドでNushell値をSQLiteに保存する際の型変換マッピングです。

| Nushell Type | SQLite Type | 説明 |
| --- | --- | --- |
| String | TEXT | テキスト |
| Int | INTEGER | 整数 |
| Float | REAL | 浮動小数点 |
| Number | REAL | 数値 |
| Binary | BLOB | バイナリデータ |
| Bool | BOOLEAN | 真偽値 |
| Date | DATETIME | 日時 |
| Duration | BIGINT | 期間（ナノ秒） |
| Filesize | INTEGER | ファイルサイズ（バイト） |
| List / Record / Table | JSONB | 複合データ（JSON形式） |
| Nothing | TEXT | NULL値（TEXTとして扱う） |

### SQLite値からNushell値への変換

SQLiteからデータを読み取る際の型変換マッピングです。

| SQLite ValueRef | Nushell Value | 説明 |
| --- | --- | --- |
| Null | Nothing | NULL値 |
| Integer | Int | 整数 |
| Real | Float | 浮動小数点 |
| Text | String | テキスト |
| Text (JSON/JSONB) | Value | JSON/JSONBカラムはNu値に変換 |
| Blob | Binary | バイナリデータ |

## データベース接続設定

### インメモリデータベース

```
URI: file:memdb1?mode=memory&cache=shared
```

- 全ての`stor`コマンドで共有されるインメモリデータベース
- Nushellセッション終了時にデータは消失
- `stor export`で外部ファイルに保存可能
- `stor import`で外部ファイルから復元可能

### 外部SQLiteファイル

- `open`コマンドでSQLiteファイルを開くと自動検出
- SQLiteマジックバイト（`SQLite format 3\0`）でファイル形式を判定
- ビジーハンドラー設定: 250ミリ秒の待機後にリトライ

## 履歴データベース

Nushellはコマンド履歴をSQLite形式で保存するオプションをサポートしています。

### HistoryConfig

| フィールド名 | データ型 | デフォルト値 | 説明 |
| --- | --- | --- | --- |
| max_size | i64 | 100,000 | 履歴の最大エントリ数 |
| sync_on_enter | bool | true | コマンド実行時に同期 |
| file_format | HistoryFileFormat | Plaintext | 履歴ファイル形式（Sqlite/Plaintext） |
| isolation | bool | false | セッション分離（SQLite形式のみ） |

### 履歴ファイルパス

- Plaintext: `$nu.config-dir/history.txt`
- SQLite: `$nu.config-dir/history.sqlite3`

## 備考

### 動的型付け

SQLiteは動的型付けを採用しているため、Nushellでは以下の動作が発生します：

1. VARCHAR(255)に255文字を超える文字列を挿入してもエラーにならない
2. INTEGERカラムに文字列を挿入してもエラーにならない

### SQLiteQueryBuilder

Nushellは`SQLiteQueryBuilder`を使用してSQLプッシュダウン最適化を提供します。これにより、`length`、`select`、`first`、`last`などのコマンドが効率的にSQLクエリに変換されます。

### トランザクション

`into sqlite`コマンドは大量データの挿入時にトランザクションを使用し、エラー発生時にはロールバックを実行します。

### JSON/JSONB サポート

- Nushellのレコード、リスト、テーブルはJSONB型として保存
- 読み取り時に自動的にNushell値に変換
- `stor create`で明示的にJSON/JSONB型を指定可能
