postgresql-cleanup-guide.md

# PostgreSQL 数据库迁移失败清理指南

## 概述
本指南用于清理 AnythingLLM 项目中 PostgreSQL 数据库的失败迁移记录，特别是因 P3009 错误导致的迁移失败。

## 前提条件
- 数据库地址：`rag-ai.e.aivencloud.com:15005`
- 需要数据库连接凭证（用户名、密码、数据库名）

## 清理步骤

### 1. 连接到 PostgreSQL 数据库

使用 psql 命令行工具连接：

```bash
# 基本连接格式
psql -h rag-ai.e.aivencloud.com -p 15005 -U [用户名] -d [数据库名]

# 示例（需要替换实际凭证）
psql -h rag-ai.e.aivencloud.com -p 15005 -U postgres -d anythingllm
```

或者使用 pgAdmin、DBeaver 等 GUI 工具连接。

### 2. 检查 _prisma_migrations 表状态

连接后，首先查看迁移表的状态：

```sql
-- 查看所有迁移记录
SELECT * FROM _prisma_migrations ORDER BY finished_at DESC;

-- 查看失败的迁移
SELECT * FROM _prisma_migrations 
WHERE finished_at IS NULL 
   OR logs LIKE '%ERROR%' 
   OR logs LIKE '%P3009%'
ORDER BY started_at DESC;
```

### 3. 备份失败迁移记录（可选但推荐）

```sql
-- 创建备份表
CREATE TABLE _prisma_migrations_backup AS 
SELECT * FROM _prisma_migrations 
WHERE migration_name = '20230921191814_init';

-- 验证备份
SELECT COUNT(*) FROM _prisma_migrations_backup;
```

### 4. 清理失败记录

根据具体情况选择以下方案之一：

#### 方案 A：仅删除失败的迁移记录

```sql
-- 删除特定的失败迁移
DELETE FROM _prisma_migrations 
WHERE migration_name = '20230921191814_init'
AND (finished_at IS NULL OR logs LIKE '%P3009%');

-- 验证删除结果
SELECT * FROM _prisma_migrations WHERE migration_name = '20230921191814_init';
```

#### 方案 B：清理所有未完成的迁移

```sql
-- 删除所有未完成的迁移
DELETE FROM _prisma_migrations 
WHERE finished_at IS NULL;

-- 验证删除结果
SELECT * FROM _prisma_migrations WHERE finished_at IS NULL;
```

#### 方案 C：完全重置迁移表（谨慎使用）

```sql
-- 备份现有数据
CREATE TABLE _prisma_migrations_full_backup AS 
SELECT * FROM _prisma_migrations;

-- 清空迁移表
TRUNCATE _prisma_migrations;

-- 验证表已清空
SELECT COUNT(*) FROM _prisma_migrations;
```

### 5. 检查数据库表结构

```sql
-- 列出所有表
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public' 
AND table_type = 'BASE TABLE'
ORDER BY table_name;

-- 检查是否存在业务数据表
SELECT EXISTS (
   SELECT FROM information_schema.tables 
   WHERE table_schema = 'public' 
   AND table_name = 'users'
);
```

### 6. 验证清理结果

```sql
-- 确认迁移表状态
SELECT 
    migration_name,
    started_at,
    finished_at,
    CASE 
        WHEN finished_at IS NULL THEN 'FAILED'
        ELSE 'COMPLETED'
    END as status
FROM _prisma_migrations
ORDER BY started_at DESC;
```

## 重新执行迁移

清理完成后，可以重新执行迁移：

```bash
# 在项目根目录执行
cd server
npx prisma migrate dev

# 或者使用生产环境命令
npx prisma migrate deploy
```

## 常见问题处理

### 1. 连接问题
如果无法连接，检查：
- 防火墙设置
- SSL 配置（Aiven 通常需要 SSL）
- 连接凭证是否正确

```bash
# 带SSL连接示例
psql "host=rag-ai.e.aivencloud.com port=15005 user=[用户名] dbname=[数据库名] sslmode=require"
```

### 2. 权限问题
确保用户有足够的权限：
```sql
-- 检查用户权限
SELECT * FROM information_schema.role_table_grants 
WHERE grantee = '[用户名]';
```

### 3. 数据库不存在
如果数据库不存在，需要先创建：
```sql
-- 创建数据库（需要超级用户权限）
CREATE DATABASE anythingllm;
```

## 注意事项

1. **数据备份**：执行任何删除操作前，确保已备份重要数据
2. **生产环境**：在生产环境执行前，先在测试环境验证步骤
3. **迁移顺序**：确保迁移文件按正确顺序执行
4. **依赖关系**：注意迁移之间的依赖关系

## 验证清理成功

清理成功后，应该能够：
1. 成功连接到数据库
2. _prisma_migrations 表处于干净状态
3. 能够重新执行迁移命令
4. 迁移完成后所有表结构正确创建

## 联系支持

如果遇到问题，请提供：
- 错误信息和日志
- 执行的 SQL 命令
- 数据库版本信息
- Prisma 版本信息