# 数据库初始化

本章节介绍如何初始化项目数据库，包括建库、建表、导入种子数据以及后续的数据库迁移管理。

项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等多种数据库，通过 `.env` 中的 `DB_DRIVER` 切换驱动。

:::tip 温馨提示
数据库初始化前，请确保已完成以下准备工作：
1. 目标数据库服务已启动（如 MySQL 8.0+）
2. `.env` 文件中的 `DB_DRIVER` 和数据库连接信息已正确配置
3. Python 依赖已安装（`poetry install`）
:::

## 方式一：手动初始化（推荐）

手动初始化是最直接、最可控的方式，适合开发环境和生产环境。

### 第一步：创建数据库

根据你使用的数据库类型，手动创建数据库。

**MySQL**：

```sql
CREATE DATABASE `djangoadmin.tornado.elevue`
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_general_ci;
```

**PostgreSQL**：

```sql
CREATE DATABASE "djangoadmin.tornado.elevue"
  WITH ENCODING 'UTF8'
  LC_COLLATE = 'zh_CN.UTF-8'
  LC_CTYPE = 'zh_CN.UTF-8';
```

**SQL Server**：

```sql
CREATE DATABASE [djangoadmin.tornado.elevue];
```

### 第二步：导入数据库脚本

MySQL 数据库脚本位于 `document/` 目录下：

```bash
# 登录 MySQL
mysql -uroot -p

# 导入脚本
mysql -uroot -p djangoadmin.tornado.elevue < document/djangoadmin.tornado.elevue.sql
```

:::tip 温馨提示
`document/djangoadmin.tornado.elevue.sql` 是 MySQL 专用脚本。对于 PostgreSQL / SQL Server / SQLite / Oracle，建议使用 Alembic 方式初始化。
:::

### 第三步：导入字典种子数据

```bash
# 导入业务字典数据（性别、友链类型、通知来源等）
python scripts/seed_dict.py
```

:::tip 温馨提示
`seed_dict.py` 是幂等脚本，可重复执行不会产生重复数据。
:::

## 方式二：Alembic 迁移初始化

适合非 MySQL 数据库，或需要版本化管理数据库结构的场景。

### 第一步：创建数据库

同方式一的手动建库步骤。

### 第二步：执行迁移

```bash
# 根据 models 定义自动建表
poetry run alembic upgrade head
```

### 第三步：导入种子数据

```bash
python scripts/seed_dict.py
```

## 方式三：脚本初始化（备选）

```bash
# 自动完成建库、建表、导入种子数据
python scripts/init_db.py
```

:::tip 温馨提示
`init_db.py` 会根据 `.env` 中的 `DB_DRIVER` 配置自动初始化数据库。适合快速搭建开发环境。
:::

## 多数据库驱动配置

项目通过 `DB_DRIVER` 环境变量切换数据库驱动：

| DB_DRIVER | 别名 | Python 驱动 | 安装方式 |
|:----------|:-----|:------------|:---------|
| `mysql` | — | pymysql | 默认已安装 |
| `postgresql` | `postgres` | psycopg2-binary | `poetry install -E postgresql` |
| `mssql` | `sqlserver` | pymssql | `poetry install -E mssql` |
| `sqlite` | `sqlite3` | sqlite3 | 内置，无需额外安装 |
| `oracle` | — | oracledb | `poetry install -E oracle` |

### SQLite 配置示例

```bash
# .env
DB_DRIVER=sqlite
DB_DATABASE=/path/to/djangoadmin.db
```

:::tip SQLite 说明
当 `DB_DRIVER=sqlite` 时，`DB_DATABASE` 为数据库文件的完整路径（相对或绝对路径），`DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD` 均被忽略。
:::

### PostgreSQL 配置示例

```bash
# .env
DB_DRIVER=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=postgres
DB_PASSWORD=your_password
```

### Oracle 配置示例

```bash
# .env
DB_DRIVER=oracle
DB_HOST=127.0.0.1
DB_PORT=1521
DB_DATABASE=XEPDB1  # SERVICE_NAME
DB_USERNAME=system
DB_PASSWORD=your_password
```

## 初始化完成后

数据库初始化完成后，系统包含以下默认数据：

| 数据 | 说明 |
|:-----|:-----|
| 管理员账号 | admin / 123456（超级管理员，ID=1，跳过权限校验） |
| 默认角色 | 超级管理员角色 |
| 默认菜单 | 系统管理、内容管理、监控管理等菜单及权限节点 |
| 数据字典 | 性别、状态、类型等系统内置字典数据 |
| 系统配置 | 系统默认配置项 |

## 跨库数据迁移

项目提供 `scripts/migrate_db.py` 脚本，支持在不同数据库之间迁移数据（如 MySQL → PostgreSQL）。详细说明请参考 [跨库数据迁移](/zh/volume6/db-cross-migrate) 章节。

## 常见问题

+ 数据库连接失败

```
1. 检查数据库服务是否已启动
2. 检查 .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
3. 检查防火墙是否放行了数据库端口
4. 检查数据库用户是否有建库/建表权限
```

+ 导入脚本报错

```
1. 确认数据库字符集为 utf8mb4（MySQL）
2. 确认数据库版本符合要求（MySQL 8.0+）
3. 检查脚本文件是否完整（未被截断）
```

+ Alembic 迁移失败

```
1. 确认 alembic.ini 中的数据库连接配置正确
2. 检查是否存在版本冲突：poetry run alembic history
3. 如需重置：poetry run alembic downgrade base，然后 poetry run alembic upgrade head
```

## 总结

本章节介绍了三种数据库初始化方式：手动导入 SQL 脚本（推荐）、Alembic 迁移、脚本自动初始化。项目支持 MySQL / PostgreSQL / SQL Server / SQLite / Oracle 五种数据库，通过 `DB_DRIVER` 环境变量切换。初始化完成后即可启动后端服务。