grepai-storage-postgres

GrepAI の PostgreSQL ストレージ

このスキルでは、GrepAI のストレージバックエンドとして pgvector 拡張機能を備えた PostgreSQL を使用する方法を説明します。

このスキルを使用する場面

• インデックスを共有するチーム環境
• 大規模なコードベース（10K 以上のファイル）
• 同時アクセスが必要な場合
• 既存の PostgreSQL インフラストラクチャとの統合

前提条件

1. pgvector 拡張機能を備えた PostgreSQL 14 以降
2. テーブルを作成する権限を持つデータベースユーザー
3. PostgreSQL サーバーへのネットワークアクセス

利点

利点	説明
👥 チームでの共有	複数のユーザーが同じインデックスにアクセスできます
📏 スケーラブル	大規模なコードベースに対応します
🔄 同時実行	複数の検索を同時に実行できます
💾 永続的	マシンを再起動してもデータが保持されます
🔧 使い慣れたツール	標準的なデータベースツールを利用できます

pgvector を使用した PostgreSQL のセットアップ

オプション 1：Docker（開発に推奨）

# Run PostgreSQL with pgvector
docker run -d \
  --name grepai-postgres \
  -e POSTGRES_USER=grepai \
  -e POSTGRES_PASSWORD=grepai \
  -e POSTGRES_DB=grepai \
  -p 5432:5432 \
  pgvector/pgvector:pg16

オプション 2：既存の PostgreSQL へのインストール

# Install pgvector extension (Ubuntu/Debian)
sudo apt install postgresql-16-pgvector

# Or compile from source
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

次に、拡張機能を有効にします。

-- Connect to your database
CREATE EXTENSION IF NOT EXISTS vector;

オプション 3：マネージドサービス

• Supabase： pgvector がデフォルトで含まれています
• Neon： pgvector を利用できます
• AWS RDS： pgvector 拡張機能をインストールします
• Azure Database： pgvector を利用できます

設定

基本設定

# .grepai/config.yaml
store:
  backend: postgres
  postgres:
    dsn: postgres://user:password@localhost:5432/grepai

環境変数を使用する場合

store:
  backend: postgres
  postgres:
    dsn: ${DATABASE_URL}

環境変数を設定します。

export DATABASE_URL="postgres://user:password@localhost:5432/grepai"

DSN の全オプション

store:
  backend: postgres
  postgres:
    dsn: postgres://user:password@host:5432/database?sslmode=require

DSN の構成要素：

• user：データベースのユーザー名
• password：データベースのパスワード
• host：サーバーのホスト名または IP アドレス
• 5432：ポート（デフォルト：5432）
• database：データベース名
• sslmode：SSL モード（disable、require、verify-full）

SSL モード

モード	説明	使用例
disable	SSL なし	ローカル開発
require	SSL が必須	本番環境
verify-full	SSL を使用し、証明書を検証	高いセキュリティが必要な場合

# Production with SSL
store:
  backend: postgres
  postgres:
    dsn: postgres://user:[email protected]:5432/grepai?sslmode=require

データベーススキーマ

GrepAI は次のテーブルを自動的に作成します。

-- Vector embeddings table
CREATE TABLE IF NOT EXISTS embeddings (
    id SERIAL PRIMARY KEY,
    file_path TEXT NOT NULL,
    chunk_index INTEGER NOT NULL,
    content TEXT NOT NULL,
    start_line INTEGER,
    end_line INTEGER,
    embedding vector(768),  -- Dimension matches your model
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(file_path, chunk_index)
);

-- Index for vector similarity search
CREATE INDEX ON embeddings USING ivfflat (embedding vector_cosine_ops);

セットアップの確認

pgvector 拡張機能の確認

-- Connect to database
psql -U grepai -d grepai

-- Check extension is installed
SELECT * FROM pg_extension WHERE extname = 'vector';

-- Check GrepAI tables exist (after first grepai watch)
\dt

GrepAI からの接続テスト

# Check status
grepai status

# Should show PostgreSQL backend info

パフォーマンスのチューニング

PostgreSQL の設定

ベクトル検索のパフォーマンスを向上させるには、次のように設定します。

-- Increase work memory for vector operations
SET work_mem = '256MB';

-- Adjust for your hardware
SET effective_cache_size = '4GB';
SET shared_buffers = '1GB';

インデックスのチューニング

大規模なインデックスでは、IVFFlat インデックスを調整します。

-- More lists = faster search, more memory
CREATE INDEX ON embeddings
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);  -- Adjust based on row count

目安：lists = sqrt(rows)

同時アクセス

PostgreSQL は同時アクセスを自動的に処理します。

• 複数の grepai search コマンドを同時に実行できます
• コードベースごとに grepai watch デーモンを 1 つ実行します
• 多数のユーザーで同じインデックスを共有できます

チームでのセットアップ

共有データベース

チームメンバー全員が同じデータベースを指定します。

# Each developer's .grepai/config.yaml
store:
  backend: postgres
  postgres:
    dsn: postgres://team:[email protected]:5432/grepai

プロジェクトごとのデータベース

プロジェクトを分離するには、別々のデータベースを使用します。

# Create databases
createdb -U postgres grepai_projecta
createdb -U postgres grepai_projectb

# Project A config
store:
  backend: postgres
  postgres:
    dsn: postgres://user:pass@localhost:5432/grepai_projecta

バックアップと復元

バックアップ

pg_dump -U grepai -d grepai > grepai_backup.sql

復元

psql -U grepai -d grepai < grepai_backup.sql

GOB からの移行

1. pgvector を使用して PostgreSQL をセットアップします
2. 設定を更新します。

store:
  backend: postgres
  postgres:
    dsn: postgres://user:pass@localhost:5432/grepai

3. 古いインデックスを削除します。

rm .grepai/index.gob

4. インデックスを再作成します。

grepai watch

よくある問題

❌ 問題： FATAL: password authentication failed ✅ 解決策： DSN の認証情報と pg_hba.conf を確認します

❌ 問題： ERROR: extension "vector" is not available ✅ 解決策： pgvector をインストールします。

sudo apt install postgresql-16-pgvector
# Then: CREATE EXTENSION vector;

❌ 問題： ERROR: type "vector" does not exist ✅ 解決策： データベースで拡張機能を有効にします。

CREATE EXTENSION IF NOT EXISTS vector;

❌ 問題： 接続が拒否される ✅ 解決策：

• PostgreSQL が実行中であることを確認します
• ホストとポートを確認します
• ファイアウォールのルールを確認します

❌ 問題： 検索が遅い ✅ 解決策：

• IVFFlat インデックスを追加します
• work_mem を増やします
• テーブルを VACUUM して分析します

ベストプラクティス

1. 環境変数を使用する： 認証情報をコミットしないでください
2. SSL を有効にする： リモートデータベースの場合
3. 定期的にバックアップする： 大きな変更の前に pg_dump を実行します
4. パフォーマンスを監視する： クエリ時間を確認します
5. インデックスをメンテナンスする： 定期的に VACUUM ANALYZE を実行します

出力形式

PostgreSQL ストレージのステータス：

✅ PostgreSQL Storage Configured

   Backend: PostgreSQL + pgvector
   Host: localhost:5432
   Database: grepai
   SSL: disabled

   Contents:
   - Files: 2,450
   - Chunks: 12,340
   - Vector dimension: 768

   Performance:
   - Connection: OK
   - IVFFlat index: Yes
   - Search latency: ~50ms