Relevant source files

The following files were used as context for generating this wiki page: - [server/initialize/gorm.go](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/initialize/gorm.go) - [server/docs/swagger.yaml](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/docs/swagger.yaml) - [server/config/gorm_pgsql.go](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/config/gorm_pgsql.go) - [server/config/gorm_mysql.go](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/config/gorm_mysql.go) - [server/config.yaml](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/config.yaml)

# 数据库配置 ## 概述 `gin-vue-admin` 支持多种主流数据库类型，包括 `MySQL`, `PostgreSQL` (pgsql), `Oracle`, `MSSQL` 和 `SQLite`。系统通过读取配置文件（`config.yaml`）中的 `system.db-type` 字段来动态初始化数据库连接。数据库连接的建立与表结构的自动迁移（AutoMigrate）主要在 `server/initialize/gorm.go` 中完成。本模块不仅负责建立底层数据库连接，还提供了统一的配置结构体（如 `Mysql`, `Pgsql` 等），用于生成不同数据库所需的 DSN (Data Source Name) 连接字符串。 ## 数据库初始化流程系统启动时，会根据配置文件中的设置执行数据库初始化逻辑。下图展示了从读取配置到成功建立连接并注册表结构的完整流程： ```mermaid graph TB A[系统启动] --> B[读取 config.yaml] B --> C{获取 system.db-type} C -->|mysql| D[设置 GVA_ACTIVE_DBNAME
为 Mysql.Dbname] C -->|pgsql| E[设置 GVA_ACTIVE_DBNAME
为 Pgsql.Dbname] C -->|oracle| F[设置 GVA_ACTIVE_DBNAME
为 Oracle.Dbname] C -->|mssql| G[设置 GVA_ACTIVE_DBNAME
为 Mssql.Dbname] C -->|sqlite| H[设置 GVA_ACTIVE_DBNAME
为 Sqlite.Dbname] C -->|default| D D --> I[调用 GormMysql 初始化] E --> J[调用 GormPgSql 初始化] F --> K[调用 GormOracle 初始化] G --> L[调用 GormMssql 初始化] H --> M[调用 GormSqlite 初始化] I --> N[返回 GORM DB 实例] J --> N K --> N L --> N M --> N N --> O{检查
disable-auto-migrate} O -->|false| P[执行 RegisterTables] O -->|true| Q[跳过表结构迁移] P --> R[遍历 System & Example 模型] R --> S[执行 db.AutoMigrate] S --> T[表结构注册成功] Q --> T ``` ## 配置文件详解所有的数据库配置均定义在 `server/config.yaml` 文件中。系统通过 `system.db-type` 指定当前使用的数据库类型，并读取对应区块的配置信息。 ### 通用配置参数无论是哪种数据库，以下参数在 `config.Mysql`, `config.Pgsql`, `config.Oracle` 等结构体中是通用的（继承自 `GeneralDB`）： | 参数名 | 类型 | 描述 | 默认值 | | :--- | :--- | :--- | :--- | | `path` | string | 数据库地址 (IP 或域名) | "" | | `port` | string | 数据库端口 | "" | | `config` | string | 高级配置 (如 charset) | "" | | `db-name` | string | 数据库名称 | "" | | `username` | string | 数据库账号 | "" | | `password` | string | 数据库密码 | "" | | `max-idle-conns` | int | 空闲中的最大连接数 | 10 | | `max-open-conns` | int | 打开到数据库的最大连接数 | 100 | | `log-mode` | string | 是否开启 Gorm 全局日志 | "" | | `log-zap` | bool | 是否通过 zap 写入日志文件 | false | | `singular` | bool | 是否开启全局禁用复数 (true表示表名不加s) | false | ### MySQL 配置示例在 `config.yaml` 中，MySQL 的配置块如下： ```yaml # mysql connect configuration mysql: path: "127.0.0.1" # 数据库地址 port: "3306" # 端口 config: "charset=utf8mb4&parseTime=True&loc=Local" # 高级配置 db-name: "gorm_v2" # 数据库名 username: "root" # 账号 password: "password" # 密码 max-idle-conns: 10 max-open-conns: 100 log-mode: "error" log-zap: false ``` **DSN 生成逻辑**: 在代码中，`Mysql` 结构体通过 `Dsn()` 方法拼接连接字符串 [server/config/gorm_mysql.go](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/config/gorm_mysql.go)： ```go // Username:Password@tcp(Path:Port)/Dbname?Config return m.Username + ":" + m.Password + "@tcp(" + m.Path + ":" + m.Port + ")/" + m.Dbname + "?" + m.Config ``` ### PostgreSQL 配置示例 PostgreSQL 的配置结构与 MySQL 类似，但 DSN 的拼接方式有所不同。 ```yaml # pgsql connect configuration pgsql: path: "127.0.0.1" port: "5432" config: "sslmode=disable TimeZone=Asia/Shanghai" db-name: "gorm_v2" username: "postgres" password: "password" max-idle-conns: 10 max-open-conns: 100 log-mode: "error" log-zap: false ``` **DSN 生成逻辑**: `Pgsql` 结构体使用 `host=... user=...` 的格式拼接 [server/config/gorm_pgsql.go](https://github.com/flipped-aurora/gin-vue-admin/blob/main/server/config/gorm_pgsql.go)： ```go // host=Path user=Username password=Password dbname=Dbname port=Port Config return "host=" + p.Path + " user=" + p.Username + " password=" + p.Password + " dbname=" + p.Dbname + " port=" + p.Port + " " + p.Config ``` ## 数据库表结构迁移系统使用 GORM 的 `AutoMigrate` 功能自动维护数据库表结构。此逻辑封装在 `initialize/gorm.go` 的 `RegisterTables` 函数中。 ### 迁移控制可以通过 `server/config.yaml` 中的 `system` 节点控制是否开启自动迁移： * **disable-auto-migrate: false**: 系统启动时自动检查并迁移表结构（开发环境推荐）。 * **disable-auto-migrate: true**: 跳过表结构迁移（生产环境推荐，防止误操作修改数据结构）。 ### 迁移的模型列表系统默认迁移以下核心模型（位于 `model/system` 和 `model/example` 包中）： **System (系统核心表):** * `SysApi`: API 接口记录 * `SysUser`: 用户表 * `SysBaseMenu`: 基础菜单表 * `SysAuthority`: 角色/权限表 * `JwtBlacklist`: JWT 黑名单 * `SysDictionary`: 字典管理 * `SysOperationRecord`: 操作记录 * `SysAutoCodeHistory`: 自动代码生成历史 * ...以及其他系统配置表。 **Example (示例表):** * `ExaFile`: 文件记录 * `ExaCustomer`: 客户示例 * `ExaFileUploadAndDownload`: 文件上传下载记录 ### 代码逻辑 ```go // 摘自 server/initialize/gorm.go func RegisterTables() { if global.GVA_CONFIG.System.DisableAutoMigrate { global.GVA_LOG.Info("auto-migrate is disabled, skipping table registration") return } db := global.GVA_DB err := db.AutoMigrate( system.SysApi{}, system.SysUser{}, // ... 其他模型 ) if err != nil { global.GVA_LOG.Error("register table failed", zap.Error(err)) os.Exit(0) } } ``` ## 多数据库支持除了主数据库（通过 `db-type` 指定），`gin-vue-admin` 还支持配置 `db-list` 来连接多个不同类型的数据库实例。这在需要同时操作 MySQL 业务库和 PostgreSQL 分析库的场景下非常有用。 `db-list` 配置结构包含： * `type`: 数据库类型 (mysql, pgsql, etc.) * `alias-name`: 数据库别名 (用于代码中区分) * `disable`: 是否禁用该连接 * 以及标准的连接参数 ## 总结 `gin-vue-admin` 的数据库配置模块提供了灵活且强大的多数据库支持。通过统一的配置结构和 GORM 的初始化流程，开发者可以轻松切换底层数据源。在生产环境部署时，请务必确认 `system.db-type` 设置正确，并根据需要调整 `disable-auto-migrate` 选项以确保数据安全。