grepai-storage-postgres · Agent Skill

用途

本技能介绍如何把 PostgreSQL 配合 pgvector 扩展用作 GrepAI 的存储后端（storage backend）。官方建议在团队环境与大型代码库中使用。

适用时机：

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

主要能力与优势

👥 团队共享：多个用户可以访问同一索引
📏 可扩展：能够处理大型代码库
🔄 并发：支持多个同时进行的搜索
💾 持久：数据在机器重启后仍然存在
🔧 熟悉：使用标准的数据库工具

前置条件

PostgreSQL 14+ 并安装 pgvector 扩展
具有建表权限的数据库用户
能够通过网络访问 PostgreSQL 服务器

使用方式

设置 PostgreSQL 与 pgvector

方式一：Docker（开发环境推荐）

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

方式二：在既有 PostgreSQL 上安装

sudo apt install postgresql-16-pgvector

或从源码编译：

git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

随后启用扩展：

CREATE EXTENSION IF NOT EXISTS vector;

方式三：托管服务

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 并验证证书，用于高安全性场景

生产环境示例：

store:
  backend: postgres
  postgres:
    dsn: postgres://user:pass@prod.db.com:5432/grepai?sslmode=require

数据库 Schema

GrepAI 会自动创建以下表：

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)
);

CREATE INDEX ON embeddings USING ivfflat (embedding vector_cosine_ops);

验证设置

检查 pgvector 扩展：

psql -U grepai -d grepai
SELECT * FROM pg_extension WHERE extname = 'vector';
\dt

从 GrepAI 测试连接：

grepai status

应显示 PostgreSQL 后端信息。

性能调优

PostgreSQL 配置（用于提升向量搜索性能）：

SET work_mem = '256MB';
SET effective_cache_size = '4GB';
SET shared_buffers = '1GB';

索引调优（针对大型索引调整 IVFFlat 索引）：

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 守护进程；许多用户可共享同一索引。

团队设置

共享数据库：所有团队成员指向同一个数据库，各自 .grepai/config.yaml：

store:
  backend: postgres
  postgres:
    dsn: postgres://team:secret@shared-db.company.com:5432/grepai

按项目隔离数据库：

createdb -U postgres grepai_projecta
createdb -U postgres grepai_projectb

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 迁移

设置 PostgreSQL 与 pgvector
更新配置：

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

删除旧索引：rm .grepai/index.gob
重新索引：grepai watch

常见问题

FATAL: password authentication failed → 检查 DSN 凭据与 pg_hba.conf
ERROR: extension "vector" is not available → 安装 pgvector：sudo apt install postgresql-16-pgvector，然后 CREATE EXTENSION vector;
ERROR: type "vector" does not exist → 在数据库中启用扩展：CREATE EXTENSION IF NOT EXISTS vector;
Connection refused → 检查 PostgreSQL 是否运行、确认主机与端口、检查防火墙规则
搜索缓慢 → 添加 IVFFlat 索引、增大 work_mem、对表执行 VACUUM ANALYZE

最佳实践

使用环境变量：不要提交凭据
启用 SSL：用于远程数据库
定期备份：重大变更前执行 pg_dump
监控性能：检查查询耗时
索引维护：定期执行 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

限制

资料未提供该技能的价格、收费模式、支持的平台清单及具体效果数据。