xiamuceer
145 lines
4.0 KiB
Plaintext
145 lines
4.0 KiB
Plaintext
# Alembic 数据库迁移指南
|
||
|
||
本项目支持 **PostgreSQL** 和 **SQLite** 两种数据库，使用独立的 Alembic 配置管理迁移。
|
||
|
||
## 📁 目录结构
|
||
|
||
```
|
||
backend/
|
||
├── alembic-postgres.ini # PostgreSQL 配置文件
|
||
├── alembic-sqlite.ini # SQLite 配置文件
|
||
├── alembic/
|
||
│ ├── postgres/ # PostgreSQL 迁移脚本目录
|
||
│ │ ├── env.py
|
||
│ │ ├── script.py.mako
|
||
│ │ └── versions/ # PostgreSQL 迁移版本
|
||
│ │ ├── 20251226_1008_ee0a189f1532_初始数据库结构.py
|
||
│ │ └── 20251226_1102_e411428f00c0_初始化预置数据.py
|
||
│ └── sqlite/ # SQLite 迁移脚本目录
|
||
│ ├── env.py
|
||
│ ├── script.py.mako
|
||
│ └── versions/ # SQLite 迁移版本
|
||
│ └── 20251226_1322_fbeb1038c728_初始化sqlite数据库.py
|
||
```
|
||
|
||
## 🚀 使用方法
|
||
|
||
### 1. PostgreSQL 数据库
|
||
|
||
#### 配置环境变量
|
||
```bash
|
||
# .env 文件
|
||
DATABASE_URL=postgresql+asyncpg://username:password@localhost:5432/database_name
|
||
```
|
||
|
||
#### 生成迁移脚本
|
||
```bash
|
||
cd backend
|
||
alembic -c alembic-postgres.ini revision --autogenerate -m "描述信息"
|
||
```
|
||
|
||
#### 应用迁移
|
||
```bash
|
||
alembic -c alembic-postgres.ini upgrade head
|
||
```
|
||
|
||
#### 回退迁移
|
||
```bash
|
||
alembic -c alembic-postgres.ini downgrade -1
|
||
```
|
||
|
||
#### 查看迁移历史
|
||
```bash
|
||
alembic -c alembic-postgres.ini history
|
||
alembic -c alembic-postgres.ini current
|
||
```
|
||
|
||
### 2. SQLite 数据库
|
||
|
||
#### 配置环境变量
|
||
```bash
|
||
# .env 文件
|
||
DATABASE_URL=sqlite+aiosqlite:///./data/mumuai.db
|
||
```
|
||
|
||
#### 生成迁移脚本
|
||
```bash
|
||
cd backend
|
||
alembic -c alembic-sqlite.ini revision --autogenerate -m "描述信息"
|
||
```
|
||
|
||
#### 应用迁移
|
||
```bash
|
||
alembic -c alembic-sqlite.ini upgrade head
|
||
```
|
||
|
||
#### 回退迁移
|
||
```bash
|
||
alembic -c alembic-sqlite.ini downgrade -1
|
||
```
|
||
|
||
#### 查看迁移历史
|
||
```bash
|
||
alembic -c alembic-sqlite.ini history
|
||
alembic -c alembic-sqlite.ini current
|
||
```
|
||
|
||
## ⚙️ 关键配置差异
|
||
|
||
### PostgreSQL (alembic/postgres/env.py)
|
||
- `render_as_batch=False` - 直接支持 ALTER TABLE
|
||
- 使用 `server_default=sa.text('now()')`
|
||
|
||
### SQLite (alembic/sqlite/env.py)
|
||
- `render_as_batch=True` - 通过重建表实现 ALTER TABLE
|
||
- 使用 `server_default=sa.text('(CURRENT_TIMESTAMP)')` - SQLite 格式
|
||
|
||
## 📝 注意事项
|
||
|
||
### SQLite 限制
|
||
1. **并发写入**：同时只允许一个写操作
|
||
2. **ALTER TABLE 限制**：某些操作需要重建表（Alembic 的批处理模式会自动处理）
|
||
3. **类型映射**：
|
||
- `JSON` → `TEXT` (SQLAlchemy 自动处理)
|
||
- `BOOLEAN` → `INTEGER` (0/1)
|
||
- `DEFAULT now()` → `DEFAULT CURRENT_TIMESTAMP`
|
||
|
||
### PostgreSQL 优势
|
||
1. **高并发支持**：多用户同时读写
|
||
2. **完整的 ALTER TABLE 支持**
|
||
3. **高级特性**：全文搜索、JSON 操作符、数组类型等
|
||
|
||
## 🔄 切换数据库
|
||
|
||
只需修改 `.env` 文件中的 `DATABASE_URL`，然后使用对应的配置文件执行迁移：
|
||
|
||
```bash
|
||
# 切换到 SQLite
|
||
DATABASE_URL=sqlite+aiosqlite:///./data/mumuai.db
|
||
alembic -c alembic-sqlite.ini upgrade head
|
||
|
||
# 切换到 PostgreSQL
|
||
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/db
|
||
alembic -c alembic-postgres.ini upgrade head
|
||
```
|
||
|
||
## 💡 最佳实践
|
||
|
||
1. **开发环境**：使用 SQLite（简单、无需额外服务）
|
||
2. **生产环境**：使用 PostgreSQL（性能、并发、稳定性）
|
||
3. **保持同步**：两个数据库的模型定义必须一致
|
||
4. **测试迁移**：在两种数据库上都测试迁移脚本
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q: 迁移脚本生成后可以通用吗？
|
||
A: 不行。PostgreSQL 和 SQLite 的迁移脚本是独立的，因为：
|
||
- SQL 语法差异（如 DEFAULT 值）
|
||
- 类型差异（如 JSON、BOOLEAN）
|
||
- ALTER TABLE 能力差异
|
||
|
||
### Q: 如何从 PostgreSQL 迁移数据到 SQLite？
|
||
A: 需要编写数据导出/导入脚本，不能直接复用迁移脚本。
|
||
|
||
### Q: 为什么 SQLite 迁移这么慢？
|
||
A: SQLite 的 ALTER TABLE 限制导致需要重建表，这在大表时会很慢。 |