xiaoxia-saas/docs/DATABASE-SWITCH.md

数据库切换指南

📚 概述

小虾 SaaS 支持两种数据存储方式：

1. InMemory（内存数据库） - 开发和测试环境
2. PostgreSQL - 生产环境

通过环境变量 USE_IN_MEMORY_DB 控制。

---

🔄 快速切换

方式 1: 环境变量

在 .env 文件中设置：

# 使用内存数据库（开发/测试）
USE_IN_MEMORY_DB=true

# 使用 PostgreSQL（生产）
USE_IN_MEMORY_DB=false
DATABASE_URL=postgresql://user:pass@localhost:5432/xiaoxia_saas

方式 2: 启动时指定

# 使用内存数据库
USE_IN_MEMORY_DB=true uvicorn apps.api.main:app --reload

# 使用 PostgreSQL
USE_IN_MEMORY_DB=false uvicorn apps.api.main:app --reload

---

💡 InMemory 数据库

特点：

• ✅ 无需安装 PostgreSQL
• ✅ 无需数据库迁移
• ✅ 快速启动
• ✅ 适合开发和测试
• ❌ 重启后数据丢失
• ❌ 不适合生产环境

使用场景：

• 本地开发
• 单元测试
• 集成测试
• 快速原型验证

启动：

# 设置环境变量
export USE_IN_MEMORY_DB=true

# 启动服务
uvicorn apps.api.main:app --reload

---

🗄️ PostgreSQL 数据库

特点：

• ✅ 数据持久化
• ✅ 支持事务
• ✅ 生产就绪
• ✅ 支持并发
• ❌ 需要安装 PostgreSQL
• ❌ 需要运行数据库迁移

使用场景：

• 生产环境
• 预发布环境
• 需要数据持久化的场景

设置步骤：

1. 安装 PostgreSQL

   # Ubuntu
   sudo apt-get install postgresql
   
   # macOS
   brew install postgresql
   

2. 创建数据库

   sudo -u postgres psql
   CREATE DATABASE xiaoxia_saas;
   CREATE USER xiaoxia_user WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE xiaoxia_saas TO xiaoxia_user;
   \q
   

3. 运行 Alembic 迁移

   alembic upgrade head
   

4. 配置环境变量

   USE_IN_MEMORY_DB=false
   DATABASE_URL=postgresql://xiaoxia_user:password@localhost:5432/xiaoxia_saas
   

5. 启动服务

   uvicorn apps.api.main:app --reload
   

---

🐳 Docker 环境

Canonical Docker Compose（自动配置 PostgreSQL）

# 自动启动 PostgreSQL 和应用
WEB_PORT=3001 docker compose -f infra/docker/compose.yml up -d --build

# 查看日志
docker compose -f infra/docker/compose.yml logs -f api

infra/docker/compose.yml 是当前唯一有效 compose 入口；根目录 docker-compose.yml 已退役。

---

🧪 测试环境

单元测试（推荐 InMemory）

# tests/conftest.py
import os
os.environ['USE_IN_MEMORY_DB'] = 'true'

集成测试（可选 PostgreSQL）

# 使用 PostgreSQL 进行集成测试
USE_IN_MEMORY_DB=false pytest tests/integration -v

---

🔧 实现原理

依赖注入容器根据配置自动选择：

# apps/api/app/dependencies.py
@property
def user_repository(self):
    if settings.USE_IN_MEMORY_DB:
        return InMemoryUserRepository()
    else:
        return PostgresUserRepository(settings.DATABASE_URL)

优点：

• 业务逻辑无需改动
• 切换透明
• 测试隔离

---

⚠️ 注意事项

1. 数据不兼容

   • InMemory 和 PostgreSQL 之间无法直接迁移数据
   • 切换前请备份重要数据

2. 性能差异

   • InMemory 更快（无 I/O）
   • PostgreSQL 支持更大数据量

3. 并发支持

   • InMemory 不支持多进程
   • PostgreSQL 支持多进程和集群

4. 环境一致性

   • 开发环境建议使用 InMemory
   • 生产环境必须使用 PostgreSQL

---

🚀 最佳实践

1. 开发流程

   开发（InMemory） → 测试（InMemory） → 预发布（PostgreSQL） → 生产（PostgreSQL）
   

2. 配置管理

   • 使用 .env 文件管理配置
   • 不要提交 .env 到版本控制
   • 使用 .env.example 作为模板

3. 数据库迁移

   • 所有 schema 变更都要有迁移脚本
   • 迁移脚本要幂等（可多次执行）
   • 测试迁移脚本后再应用到生产

---

最后更新: 2026-06-17