| # PostgreSQL 迁移实施文档 | |
| ## 1. 问题描述 | |
| 在将 AnythingLLM 从 SQLite 迁移到 PostgreSQL 过程中，用户遇到了以下错误： | |
| ### 错误信息 | |
| - **P3018 错误**: `A migration failed to apply. New migration failed to apply` | |
| - **P3009 错误**: `migration found a failed migration` | |
| ### 具体错误详情 | |
| 执行 `npx prisma migrate dev` 时出现： | |
| ``` | |
| Error: P3018 | |
| A migration failed to apply. New migration failed to apply. | |
| Query failed: database error | |
| ERROR: syntax error at or near "AUTOINCREMENT" | |
| LINE 1: ...id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT | |
| ``` | |
| ## 2. 错误原因分析 | |
| ### 2.1 根本原因 | |
| Prisma 生成的迁移文件包含了 SQLite 特定的 `AUTOINCREMENT` 语法，但 PostgreSQL 不支持此语法。 | |
| ### 2.2 问题详情 | |
| - **SQLite 语法**: `PRIMARY KEY AUTOINCREMENT` | |
| - **PostgreSQL 语法**: 使用 `SERIAL` 或 `BIGSERIAL` 类型，或使用 `IDENTITY` 列 | |
| ### 2.3 受影响的表 | |
| 查看迁移文件发现以下表都使用了 `AUTOINCREMENT`： | |
| - `api_keys` | |
| - `workspace_documents` | |
| - `invites` | |
| - `system_settings` | |
| - `users` | |
| - `document_vectors` | |
| - `welcome_messages` | |
| - `workspaces` | |
| - `workspace_chats` | |
| - `workspace_users` | |
| - `workspace_parsed_files` | |
| ## 3. 解决方案 | |
| ### 方案一：重置迁移（推荐用于开发环境） | |
| ```bash | |
| # 1. 删除所有迁移文件 | |
| rm -rf server/prisma/migrations/* | |
| # 2. 重置数据库 | |
| npx prisma migrate reset --force | |
| # 3. 重新生成迁移 | |
| npx prisma migrate dev --name init | |
| ``` | |
| ### 方案二：手动修复迁移文件 | |
| ```bash | |
| # 1. 编辑迁移文件，将 AUTOINCREMENT 替换为 PostgreSQL 语法 | |
| # 例如： | |
| # 原始：id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT | |
| # 修改为：id SERIAL PRIMARY KEY | |
| # 2. 手动执行修复后的 SQL | |
| psql $DATABASE_URL -f server/prisma/migrations/20230921191814_init/migration.sql | |
| ``` | |
| ### 方案三：使用 Prisma 数据迁移功能 | |
| ```bash | |
| # 1. 创建新的空迁移 | |
| npx prisma migrate dev --name fix-postgresql-syntax --create-only | |
| # 2. 编辑新迁移文件，添加修复 SQL | |
| ``` | |
| ## 4. 具体实施步骤 | |
| ### 4.1 环境准备 | |
| ```bash | |
| # 1. 安装 PostgreSQL | |
| # Ubuntu/Debian | |
| sudo apt-get install postgresql postgresql-contrib | |
| # 2. 创建数据库和用户 | |
| sudo -u postgres psql | |
| CREATE USER anythingllm WITH PASSWORD 'your_password'; | |
| CREATE DATABASE anythingllm OWNER anythingllm; | |
| GRANT ALL PRIVILEGES ON DATABASE anythingllm TO anythingllm; | |
| \q | |
| # 3. 配置环境变量 | |
| export DATABASE_URL="postgresql://anythingllm:your_password@localhost:5432/anythingllm" | |
| ``` | |
| ### 4.2 使用方案一的实施步骤 | |
| ```bash | |
| # 进入项目目录 | |
| cd /path/to/anythingllm | |
| # 1. 备份现有数据（如果需要） | |
| sqlite3 server/storage/anythingllm.db ".backup backup.db" | |
| # 2. 删除现有迁移 | |
| rm -rf server/prisma/migrations/* | |
| # 3. 更新 schema.prisma 确保使用正确的数据库类型 | |
| # 确保 provider = "postgresql" | |
| # 4. 重置并重新生成迁移 | |
| npx prisma migrate reset --force | |
| npx prisma migrate dev --name init | |
| # 5. 生成客户端 | |
| npx prisma generate | |
| # 6. 运行种子数据（如果有） | |
| node server/prisma/seed.js | |
| ``` | |
| ### 4.3 手动迁移数据（从 SQLite 到 PostgreSQL） | |
| ```bash | |
| # 1. 安装迁移工具 | |
| npm install -g pgloader | |
| # 2. 创建迁移配置文件 load.command | |
| LOAD DATABASE | |
| FROM sqlite://server/storage/anythingllm.db | |
| INTO postgresql://anythingllm:your_password@localhost:5432/anythingllm | |
| WITH include no drop, create tables, create indexes, reset sequences, foreign keys | |
| SET maintenance_work_mem to '128MB', work_mem to '12MB'; | |
| CAST | |
| type datetime to timestamptz drop default drop not null using zero-datetime-to-timestamptz, | |
| type date drop not null drop default using zero-date-to-date; | |
| # 3. 执行迁移 | |
| pgloader load.command | |
| ``` | |
| ## 5. 预防措施 | |
| ### 5.1 开发实践 | |
| 1. **使用数据库抽象** | |
| - 在 schema.prisma 中使用 Prisma 的类型系统 | |
| - 避免使用特定数据库的原始 SQL | |
| 2. **多数据库测试** | |
| ```bash | |
| # 在 CI/CD 中测试多个数据库 | |
| # SQLite | |
| DATABASE_URL="file:./dev.db" npx prisma migrate dev | |
| # PostgreSQL | |
| DATABASE_URL="postgresql://user:pass@localhost/db" npx prisma migrate dev | |
| ``` | |
| 3. **迁移审查** | |
| - 所有迁移文件需要代码审查 | |
| - 检查是否使用了特定数据库语法 | |
| ### 5.2 配置管理 | |
| ```javascript | |
| // prisma/schema.prisma | |
| generator client { | |
| provider = "prisma-client-js" | |
| } | |
| datasource db { | |
| provider = "postgresql" // 明确指定数据库类型 | |
| url = env("DATABASE_URL") | |
| } | |
| ``` | |
| ## 6. 最佳实践 | |
| ### 6.1 多数据库支持建议 | |
| 1. ** schema 设计原则** | |
| - 使用 Prisma 的标准类型 | |
| - 避免使用特定数据库的功能 | |
| - 保持模型简单和可移植 | |
| 2. **迁移策略** | |
| ```bash | |
| # 创建迁移时指定数据库 | |
| npx prisma migrate dev --create-only --name add_new_feature | |
| # 检查生成的 SQL | |
| cat server/prisma/migrations/*/migration.sql | |
| # 应用迁移 | |
| npx prisma migrate dev | |
| ``` | |
| 3. **测试策略** | |
| - 在开发中使用 SQLite | |
| - 在测试和生产中使用 PostgreSQL | |
| - 定期在不同数据库间测试迁移 | |
| ### 6.2 生产环境部署 | |
| ```yaml | |
| # docker-compose.yml | |
| version: '3.8' | |
| services: | |
| postgres: | |
| image: postgres:15 | |
| environment: | |
| POSTGRES_DB: anythingllm | |
| POSTGRES_USER: anythingllm | |
| POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} | |
| volumes: | |
| - postgres_data:/var/lib/postgresql/data | |
| ports: | |
| - "5432:5432" | |
| anything-llm: | |
| build: . | |
| environment: | |
| DATABASE_URL: "postgresql://anythingllm:${POSTGRES_PASSWORD}@postgres:5432/anythingllm" | |
| depends_on: | |
| - postgres | |
| ports: | |
| - "3001:3001" | |
| volumes: | |
| postgres_data: | |
| ``` | |
| ### 6.3 监控和维护 | |
| 1. **数据库监控** | |
| ```sql | |
| -- 检查表大小 | |
| SELECT | |
| schemaname, | |
| tablename, | |
| pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size | |
| FROM pg_tables | |
| WHERE schemaname = 'public' | |
| ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC; | |
| ``` | |
| 2. **定期维护** | |
| ```bash | |
| # 更新统计信息 | |
| npx prisma db execute --stdin <<< "ANALYZE;" | |
| # 清理旧数据（根据需要） | |
| npx prisma db execute --stdin <<< "VACUUM;" | |
| ``` | |
| ## 7. 故障排除 | |
| ### 7.1 常见错误及解决方案 | |
| 1. **连接错误** | |
| ``` | |
| Error: P1001: Can't reach database server | |
| ``` | |
| 解决方案：检查 PostgreSQL 服务是否运行，验证连接字符串 | |
| 2. **权限错误** | |
| ``` | |
| Error: P1003: Database does not exist | |
| ``` | |
| 解决方案：创建数据库并授予正确权限 | |
| 3. **迁移冲突** | |
| ``` | |
| Error: P1010: Database error | |
| ``` | |
| 解决方案：使用 `prisma migrate resolve` 解决冲突 | |
| ### 7.2 调试命令 | |
| ```bash | |
| # 检查迁移状态 | |
| npx prisma migrate status | |
| # 查看数据库信息 | |
| npx prisma db execute --stdin <<< "SELECT version();" | |
| # 测试连接 | |
| npx prisma db push --preview-feature | |
| ``` | |
| ## 8. 总结 | |
| PostgreSQL 迁移的主要挑战在于数据库语法差异。通过遵循本文档的解决方案和最佳实践，可以成功将 AnythingLLM 从 SQLite 迁移到 PostgreSQL，并获得更好的性能和可扩展性。 | |
| 关键要点： | |
| 1. 使用 Prisma 的抽象层避免特定数据库语法 | |
| 2. 在开发早期测试多数据库兼容性 | |
| 3. 建立完善的迁移和测试流程 | |
| 4. 定期备份和维护数据库 |