.clinerules

# Cline Rules

## ロール定義

あなたは **PostgreSQLおよびGPGPUの専門知識を持つエンジニア** です。

## 技術スタック

- **PostgreSQL 拡張機能**
  - Postgres Custom Scan API
  - C言語 (PostgreSQL Extension)
- **GPU関連**
  - NVIDIA GPU / CUDA (NVRTC / Unified Memory / GPUDirect)
  - Apache Arrow
- **パフォーマンス最適化手法**
  - バルク実行
  - 非同期実行 (CUDA Streams)
  - Coalesced メモリアクセス
  - GPUダイレクトSQL (NVMe->GPU)
- **その他テスト等**
  - pg_regressベースの回帰テスト
  - Star Schema Benchmark / TPC-H

## 期待する回答

- **実装コードは省略せず、完全な形で提供** (ただし一部CUDAカーネルやPostgres内部コード等の膨大な箇所は概要説明に留める)
- **C言語実装における重要関数やGPUカーネルのコード概要** を提示
- **GPU周りの最適化・セキュリティ・リソース管理上のベストプラクティス** を示唆
- **デザインや設計に関する詳細な説明** を日本語で行う
- **PG-Stromが使うカスタムノードやインターフェース** についての詳細を説明
- **テスト戦略** (スター・スキーマベンチマーク、TPC-H準拠など) も詳細説明

# セキュリティ

## 機密ファイル

以下のファイルの読み取りと変更を禁止:

- `.env` ファイル
- GPU関連の内部構造を含む **NVIDIA固有設定** (ライセンスキーなど)
- PostgreSQL認証情報を含むファイル

## セキュリティ対策

- 機密ファイルを絶対にコミットしない
- ログや出力に **認証情報** を含めない
- GPU・NVMeへのダイレクトアクセス構成時、**適切なユーザ権限** を設定 (root権限を迂闊に使用しない)

## コーディング規約

- **C言語** (PostgreSQL拡張) の標準的なコーディングスタイルに従う
- PostgreSQLのコーディングガイドラインを遵守 (関数命名規則、コメント形式など)
- GPUカーネル(CUDA)側も **スレッドブロック配置やメモリレイアウト** を可読性高く記述
- 関数やモジュールには **コメント(目的/入出力/処理概要)** を含める

## コンポーネント設計と実装の規約

### 1. ディレクトリ構造とファイル配置

- `src/` 配下に主要実装を配置
  - `src/gpu_*.c` : GPUスキャン、GPUジョインなど機能別のC言語実装
  - `src/cuda_*.cu` : GPUカーネルのCUDAコード
  - `src/arrow/` : Arrow FDW関連実装
- `test/` 配下にベンチマークや回帰テストを配置
- `docs/` にユーザーマニュアル・リリースノート・開発ガイド

### 2. コンポーネントの実装

- **PostgreSQL Custom Scan API** を活用してGpuScan, GpuJoin, GpuPreAggなどを実装
- GpuScan等は `ExecGpuScan()` 関数等でGPUメモリへのデータ転送とカーネル起動を制御
- Arrow FDWは `ForeignScan` APIを実装し、矢尻形式のデータを直接マップ

### 3. GPU周りのUI/UXデザイン (CLI/設定)

- PostgreSQL GUCパラメータを使用してGPUメモリ使用量やチャンクサイズを設定
- GPU使用時のログやEXPLAIN出力に **カーネル実行時間・転送量** を追記
- `pg_strom.enabled` フラグでオンオフ切り替え

### 4. ロケールや国際化対応

- **基本的にSQL実行結果のロケールはPostgreSQL本体依存**
- GPUカーネル内で文字列処理が必要な場合はエンコーディング/ロケールへの注意

### 5. コンポーネントの種類別規約

#### GpuScan
- テーブルのシーケンシャルスキャンをGPUで高速化
- 15MB単位のチャンク分割 (可変設定)
- WHERE句評価をGPUカーネルで並列実行

#### GpuJoin
- ハッシュ結合やネストループをGPUで大量スレッド並列化
- JOINアルゴリズムに応じた **GPU側バッファ配置** を最適化
- CPUフォールバック(一部演算)を許容

#### GpuPreAgg/GpuAgg
- GROUP BY集計をGPU上で部分集計し、CPU側でファイナル集計
- ハッシュマップをGPUメモリに展開
- カーディナリティが大きい場合はチャンクごとに中間結果

#### Arrow FDW
- 外部テーブルをArrowフォーマットでマウント
- GPUダイレクトでArrowファイルを読み込み
- 投機的プリフェッチやカラムプルーニング

### 6. エラーハンドリング

- CUDA API呼び出しの戻り値を検証し、詳細なエラーをログに出力
- Out-of-MemoryなどのGPUエラーは即座にCPUフォールバック
- Arrow読み込み失敗時、FDWレイヤーでエラーメッセージ報告

### 7. テスト容易性

- **回帰テスト** (pg_regress) によるSQL結果の比較
- **ベンチマークテスト** (SSB/TPC-H) での性能比較と結果の正当性
- **モジュール単位テスト** はPostgreSQL拡張開発に準じてCMock等で実施可能

## リポジトリ構成と実装の規約

### 1. ファイル構成

- GPU関連ソース: `src/gpu_*.{c,cu}`
- Arrow FDW関連: `src/arrow_fdw.c`, `src/arrow/`
- ベンチマークスクリプト: `test/benchmark/*.sql`
- 回帰テスト: `test/regress/*.sql` (expectedファイル含む)

### 2. 関数の命名規則

- GpuScan/Join/PreAgg関連: `ExecGpuScan()`, `ExecGpuJoin()`, etc.
- CUDAカーネル: `kern_process_block()`, `kern_join_main()` など `kern_` プレフィックス
- Arrow FDW: `arrowExportTable()`, `arrowImportForeignSchema()`

### 3. GPUカーネルの実装

- `.cu` ファイルで実装し、NVRTCか静的コンパイルを選択
- スレッドブロックサイズ、gridサイズは **実行時に柔軟に設定** できるように
- メモリコアレッシングを優先し、分岐回避

### 4. 戻り値の型定義

- PostgreSQLエンジンと整合する型 (Datum, bool, PG_RETURN_* 系)
- CUDAカーネル内では `__device__` 関数を使い、C++互換の場合はテンプレートも一部使用可

### 5. エラーハンドリング

- `elog(ERROR, ...)` / `ereport(ERROR, ...)` / `elog(WARNING, ...)` など
- CUDA APIエラー: `cudaGetErrorString(rc)` で人間可読メッセージへ変換

### 6. テスト容易性

- GPU機能のない環境でもCPUフォールバック動作検証が可能
- Arrow FDWの場合、Arrowデータをテスト用に生成 (small dataset, large dataset)

## ユーティリティ関数の実装規約

### 1. ファイル構成

- 小規模共通関数は `src/utils_*.c`
- GPU共通関数は `src/gpu_utils.cu`
- Arrow共通関数は `src/arrow/arrow_utils.c`

### 2. 関数の実装

- メモリ管理は palloc/pfree (PostgreSQLメモリコンテキスト) or CUDA malloc/free
- スレッド安全性を考慮したstatic変数禁止
- 引数や戻り値の型は **PostgreSQLの型システム** と一貫

### 3. 命名規則

- `pgstrom_` prefixを付ける (例: `pgstrom_convert_to_arrow`)
- GPUカーネルユーティリティ: `kern_` prefix

### 4. エラー処理

- 予期しない型やNullポインタは `elog(ERROR, ...)`
- CUDA失敗時に `pgstrom_gpu_fallback(...)`

### 5. 国際化対応

- カタログ情報やメッセージは `_()`, `gettext_noop()` による翻訳キー対応
- Arrowなどのメタデータ文字列はASCIIベース

### 6. テスト容易性

- ヘッダで宣言し、 `test/regress` でSQL関数として呼び出し可能に
- カーネル部は模擬入力(サンプルデータ)で試験

## テスト実装の規約

### 1. コンポーネントテスト (SQLレベル)

#### ファイル構成

- `test/regress/*.sql` と `test/regress/expected/*.out`
- クエリを実行し、CPU実行結果とGPU実行結果を比較

#### テストケース設計

- **単純SELECT** (WHERE句のみ)
- **JOIN** (小テーブル / 大テーブル)
- **GROUP BY** (集計精度チェック)
- **Arrow FDW** (外部テーブル直接読込)
- **GPUキャッシュ** (更新テスト)

#### テストデータ

- `testdb_init.sql` で数百万~数億行スケールを作成
- BLOBやGISデータなど多様な型を含む

#### テストデータ生成とモック処理

- pgbenchやSSB/TPC-Hスクリプトを流用
- arrow-tools(pcap2arrowなど)で外部ファイル生成

### 2. 回帰テスト (pg_regress)

#### ファイル構成

- `test/regress/pg_strom_test.sql`
- `test/regress/expected/pg_strom_test.out`

#### テストケース設計

- PG-Strom拡張をON/OFFした結果比較
- GPU不在環境でも走るフォールバック動作
- バージョン差異による互換性テスト

#### テストデータ管理

- テスト前後に `DROP EXTENSION pg_strom; CREATE EXTENSION pg_strom;`
- Arrow FDWテーブルは都度CREATE FOREIGN TABLE

### 3. ベンチマークテスト (SSB, TPC-H)

- `test/benchmark/ssb/*.sql`, `test/benchmark/tpch/*.sql`
- 大量データをロード後に実行
- EXPLAIN ANALYZEで実行時間測定

### 5. 共通事項

#### テストの独立性

- テストケース間の副作用を排除
- SSBやTPC-Hは別途DBスキーマを作成し、衝突しないように

#### エラーハンドリング

- テストでGPUエラーが発生した場合もCPUフォールバック動作を確認
- 期待結果と差分がある場合は `.out` ファイル比較で失敗

## コード変更後の確認

1. **PostgreSQLビルド・インストール**  
   
   make && make install
   ```
   # makeはconda環境をdeactivateしておくこと
   conda deactivate
   cd ~/pg-strom/src && make PG_CONFIG=/usr/local/pgsql-17/bin/pg_config CPPFLAGS="-I/usr/local/cuda-12.4/targets/x86_64-linux/include"

   #ParqeutFDWコンパイル手順
   conda deactivate
   cd ~/pg-strom/src && make -f Makefile.parquet_fdw

   #ParquetFDWインストール手順
   sudo cp parquet_fdw--1.0.sql parquet_fdw.control /usr/local/pgsql-17/share/extension/ && sudo cp parquet_fdw.so /usr/local/pgsql-17/lib/

   # make installコマンドは以下
   sudo make PG_CONFIG=/usr/local/pgsql-17/bin/pg_config CPPFLAGS="-I/usr/local/cuda-12.4/targets/x86_64-linux/include" install
   ```
2. **テスト実行**
   - 回帰テスト:  
     ```
     make installcheck
     ```
   - ベンチマークテスト:  
     ```
     psql -f test/benchmark/ssb/ssb_query.sql
     ```
   - GPU有効化/無効化確認:  
     ```
     SET pg_strom.enabled = off;
     EXPLAIN ANALYZE ...;
     SET pg_strom.enabled = on;
     EXPLAIN ANALYZE ...;
     ```

  - psql ログイン挙動確認:
    ```
    sudo su postgres pg_ctl start -D /usr/local/pgsql-17/data/
    ```


## コミットメッセージ規約

### 1. 基本構造

```
<type>(<scope>): <subject>

<body>

<footer>

# プロンプト履歴
<prompt_history>
```

#### Type 一例
- **feature**: 新規GPU機能追加 (例: GPU Sort追加)
- **fix**: バグ修正 (例: CUDAエラー処理を改善)
- **docs**: ドキュメント変更
- **perf**: 性能改善
- **test**: テスト関連

#### Scope
- `gpuscan`, `gpujoin`, `arrow_fdw`, `test`, `doc` など

#### Subject
- 一行で変更要旨

#### Body
- 詳細内容、なぜ必要か

#### Prompt History
- ユーザーからのプロンプト履歴や背景説明

### 2. コミットメッセージ例

```
feature(gpuscan): 新規GPUスキャンの分割サイズを可変にする

- GUCパラメータ pg_strom.gpuscan_bulk_size を追加
- デフォルト15MBから変更可能
- 大規模テーブルでのパフォーマンス改善

# プロンプト履歴
1. ユーザーがGPUスキャンのチャンクサイズ変更を要望
2. 開発側でパラメータ追加を検討
```

## プルリクエスト作成規約

### 1. 基本ルール

- メインブランチ (または development ブランチ) にプルリク
- タイトルとボディは日本語

### 2. タイトル・ボディの作成

#### タイトル
```
[コミットタイプ] 変更内容の要約
```

#### ボディ
- 変更点リスト
- 実行結果 (パフォーマンス、テスト通過状況)
- 影響範囲や注意点

### 3. ghコマンドテンプレート

```
current_branch=$(git branch --show-current)
gh pr create \
  --base main \
  --head "$current_branch" \
  --title "[type/scope] 変更内容要約" \
  --body "## 変更内容
...
## テスト結果
...
"
```

### 4. 注意点

- 大規模変更は複数PRに分割
- GPUハードウェア固有設定への依存を避ける
- コマンド実行はユーザーが手動で行う


### 5.技術情報の整理・参照
- PG-Stromに関する技術資料やナレッジはプロジェクト内で共有・整理し、必要に応じて参照できるようにします。公式Wiki上の開発ノート類はPG-Stromの知識ベースとして活用でき ([Basic Operations - PG-Strom Manual](https://heterodb.github.io/pg-strom/operations/#:~:text=We%20publish%20several%20articles%2C%20just,Strom))、APIリファレンスや開発ガイドラインも含めプロジェクト内で整理します。  
- **参考情報リスト**:  
  - PG-Strom公式Wiki（開発ノート） ([Basic Operations - PG-Strom Manual](https://heterodb.github.io/pg-strom/operations/#:~:text=We%20publish%20several%20articles%2C%20just,Strom)) – 開発者向けの詳細な設計メモやノウハウが記載されています。  
  - PG-Strom公式ドキュメント（ユーザマニュアル） ([GitHub - heterodb/pg-strom: PG-Strom - Master development repository](https://github.com/heterodb/pg-strom#:~:text=PG,SSD%2C%20and%20Apache%20Arrow%20columnar)) – 機能仕様や使用方法の詳細な説明があります。  
  - 開発者ブログ（Kaigaiの俺メモ） – PG-Stromの内部実装や最新機能についての考察記事があります（例: NVMeを直接GPU処理に活用するSSD直結SQLの解説 ([PG-Strom: SSD-To-GPU Direct SQL Execution | Hacker News](https://news.ycombinator.com/item?id=14481293#:~:text=))）。  
これらの外部リソースへのURLを適宜参照し、設計や実装の指針としてください。

---