# Atlas 数据库迁移（版本化）

## 文件说明

- `atlas.hcl` - Atlas 配置文件
- `schema.sql` - 数据库 schema 定义（期望状态）
- `migrations/` - 版本化迁移文件目录
- `.env.local` - 本地环境配置
- `.env.example` - 生产环境配置示例
- `generate-migration.sh` - 生成新的迁移文件
- `Dockerfile` - Docker 镜像配置
- `docker-compose.yml` - Docker Compose 配置

## 使用步骤

### 1. 修改 schema.sql 定义期望状态

直接编辑 `schema.sql` 文件，定义期望的数据库结构。

### 2. 生成迁移文件

```bash
./generate-migration.sh
```

此命令会对比当前数据库和 schema.sql，生成新的迁移文件到 `migrations/` 目录。

### 3. 生产环境部署

#### 方式一：Docker Compose（推荐）

**首次部署到已有数据库：**

```bash
# 1. 复制环境变量配置
cp .env.example .env

# 2. 修改 .env 文件，填入生产数据库信息
# DB_USER=root
# DB_PASSWORD=your_password
# DB_HOST=mysql_host
# DB_PORT=3306
# DB_NAME=production_db
# BASELINE_VERSION=20251213191759  # 首次部署时取消注释

# 3. 执行迁移
docker-compose up db-migrate
```

**后续部署（数据库已有迁移历史）：**

```bash
# .env 文件中注释掉或删除 BASELINE_VERSION
# 然后执行：
docker-compose up db-migrate
```

#### 方式二：Docker Run

```bash
atlas schema inspect --env local --format '{{ sql . }}' > schema.sql && echo "已更新 schema.sql

docker build -t db-migrate:latest .
docker run --rm \
  -e DB_URL="mysql://user:password@host:3306/database" \
  db-migrate:latest migrate apply --url $DB_URL --dir file://migrations
```

## 注意事项

1. 使用版本化迁移，每次修改 schema.sql 后需运行 `generate-migration.sh` 生成迁移文件
2. 迁移文件会按顺序执行，确保数据库状态可追溯
3. 生产环境需配置 `.env` 文件或设置环境变量
4. **首次部署到已有数据库：**必须设置 `BASELINE_VERSION=20251213191759` 来标记现有数据库状态
5. **后续部署：**删除或注释 `BASELINE_VERSION` 环境变量