| # 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. 定期备份和维护数据库 |
