grepai-storage-postgres

使用 PostgreSQL 存储 GrepAI

本技能介绍如何使用带有 pgvector 扩展的 PostgreSQL 作为 GrepAI 的存储后端。

何时使用此技能

• 需要共享索引的团队环境
• 大型代码库（10K+ 个文件）
• 需要并发访问
• 需要与现有 PostgreSQL 基础设施集成

前提条件

1. PostgreSQL 14+，并安装 pgvector 扩展
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 守护进程
• 多位用户可以共享同一索引

团队设置

共享数据库

所有团队成员都连接到同一个数据库：

# 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 和 ANALYZE

最佳实践

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