# PostgreSQL

**Repository Path**: middleware-lab/postgre-sql

## Basic Information

- **Project Name**: PostgreSQL
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PGSQL Lab

用 Go 把 PostgreSQL 里最常见的用法、特性和线上问题跑一遍，再用 React 做成可点击的实验台。数据库镜像带有 **pgvector**，向量检索是重点模块。

## 能看到什么

- 基础 CRUD、事务隔离（含 PostgreSQL 特有的「没有脏读」和写偏斜）
- 死锁、丢失更新、唯一约束并发冲突、NULL 三值逻辑
- 索引与 `EXPLAIN ANALYZE`、JSONB、全文检索、N+1、连接池排队
- **pgvector**：语义搜索、余弦 / L2 / 内积、HNSW 计划、维度不匹配、算子与 opclass 不一致、过滤后召回下降

## 启动

需要本机已安装 Docker、Go 1.22+、Node.js 18+。

```bash
docker compose up -d
cd backend && go mod tidy && go run .
```

另开一个终端：

```bash
cd frontend && npm install && npm run dev
```

浏览器打开 [http://127.0.0.1:5173](http://127.0.0.1:5173)。首次迁移会写入约 1200 条向量文档并创建 HNSW 索引，可能需要几十秒。

默认连接串：

```
postgres://lab:lab@127.0.0.1:5432/pglab?sslmode=disable
```

## 为什么向量部分要单独讲

pgvector 让 Postgres 同时存关系数据和 embedding，RAG 可以写成：

```sql
SELECT title, content
FROM knowledge_docs
WHERE category = 'core'
ORDER BY embedding <=> $query_vector
LIMIT 5;
```

这看起来只是多了一个距离算子，但线上事故几乎都出在「向量库语义」而不是 SQL 语法：

1. **维度是表结构**。`vector(384)` 不能写入别的维度。换 embedding 模型必须改列、重刷数据、重建索引。
2. **算子和索引绑定**。余弦索引 `vector_cosine_ops` 只加速 `<=>`。用 `<->` 会变成顺序扫描。
3. **ANN 是近似的**。HNSW 不保证精确最近邻；小数据量上看耗时没有意义，要看 `EXPLAIN`。
4. **后过滤会掉召回**。`WHERE tenant_id = ... ORDER BY dist LIMIT k` 可能先取近邻再丢弃，结果不足 k 条。
5. **本实验台的向量是特征哈希**，只为离线演示距离和计划。生产必须换真实模型，并且查询、入库用同一套。

建议在前端「向量数据库」页按这个顺序点：概览 → 语义搜索 → 距离对比 → 索引计划 → 过滤召回 → 维度失败 → 算子不一致。

## 目录

```
backend/     Go API，启动时迁移并灌数
frontend/    React + Vite 实验台
docker-compose.yml   pgvector/pgvector:pg16
```