本文将深入介绍 Apache DolphinScheduler 所采用的数据库模式，此模式主要用于持久化存储工作流定义、执行状态、调度信息以及系统元数据。它具备广泛的兼容性，可支持 MySQL、PostgreSQL 和 H2 等多种数据库，其具体定义存储在 dolphinscheduler - dao/src/main/resources/sql 目录下。
模式架构
DolphinScheduler 的数据库模式分为七个主要功能组：
| 组 | 目的 | 关键表 |
|---|---|---|
| 工作流管理 | 存储带有版本控制的工作流和任务定义 | t_ds_workflow_definition、t_ds_task_definition、t_ds_workflow_task_relation |
| 执行状态 | 跟踪运行时实例及其状态 | t_ds_workflow_instance、t_ds_task_instance、t_ds_command |
| 调度 | 通过 Quartz 管理基于 cron 的调度 | t_ds_schedules、QRTZ_* 表 |
| 资源管理 | 数据源、文件和 UDF 元数据 | t_ds_datasource、t_ds_resources、t_ds_udfs |
| 管理 | 用户、租户、项目和权限 | t_ds_user、t_ds_tenant、t_ds_project |
| 告警 | 告警配置和历史记录 | t_ds_alert、t_ds_alertgroup |
| 服务注册 | 基于 JDBC 的协调（ZooKeeper 的替代方案） | t_ds_jdbc_registry_* 表 |
工作流和任务定义模型
定义与实例分离
DolphinScheduler 严格区分定义（模板）和实例（执行）。这实现了版本控制、并发执行和审计跟踪。
关键设计原则：
- 基于代码的标识：工作流和任务都使用代码（bigint）作为跨版本的稳定标识符。
- 复合键：定义使用（代码，版本）作为复合自然键。
- 版本不可变性：每个版本都是不可变的；更改会创建新版本。
- 实例引用：实例引用特定版本的定义。
核心表参考
工作流定义表
t_ds_workflow_definition
工作流模板的主表。
| 列 | 类型 | 描述 |
|---|---|---|
| id | int | 自动递增主键 |
| code | bigint | 唯一工作流标识符（跨版本稳定） |
| version | int | 版本号（默认 1） |
| name | varchar(255) | 工作流名称 |
| project_code | bigint | 所属项目 |
| release_state | tinyint | 0 = 离线，1 = 在线 |
| global_params | text | JSON 格式的全局参数 |
| execution_type | tinyint | 0 = 并行，1 = 串行等待，2 = 串行丢弃，3 = 串行优先级 |
| timeout | int | 超时时间（分钟） |
| user_id | int | 创建者用户 ID |
索引：
UNIQUE KEY workflow_unique (name, project_code)UNIQUE KEY uniq_workflow_definition_code (code)KEY idx_project_code (project_code)
t_ds_workflow_definition_log
存储工作流定义所有版本的审计日志。
镜像 t_ds_workflow_definition 的结构，额外列：operator、operate_time，主键：(code, version)。
t_ds_task_definition
可在工作流中重用的任务模板。
| 列 | 类型 | 描述 |
|---|---|---|
| code | bigint | 唯一任务标识符 |
| version | int | 版本号 |
| task_type | varchar(50) | Shell、SQL、Python、Spark 等 |
| task_params | longtext | JSON 格式的任务配置 |
| worker_group | varchar(255) | 目标工作线程组 |
| fail_retry_times | int | 失败重试次数 |
| fail_retry_interval | int | 重试间隔（分钟） |
| timeout | int | 任务超时时间（分钟） |
| cpu_quota | int | CPU 限制（-1 = 无限制） |
| memory_max | int | 内存限制（MB，-1 = 无限制） |
t_ds_workflow_task_relation
通过指定任务之间的边来定义 DAG 结构。
| 列 | 类型 | 描述 |
|---|---|---|
| workflow_definition_code | bigint | 父工作流 |
| workflow_definition_version | int | 工作流版本 |
| pre_task_code | bigint | 前置任务（根节点为 0） |
| post_task_code | bigint | 后置任务 |
| condition_type | tinyint | 0 = 无，1 = 判断，2 = 延迟 |
| condition_params | text | JSON 格式的条件配置 |
注意：pre_task_code = 0 表示根节点（无前驱任务）。
执行状态表
t_ds_workflow_instance
工作流的运行时执行记录。
| 列 | 类型 | 描述 |
|---|---|---|
| id | int | 主键 |
| workflow_definition_code | bigint | 引用定义 |
| workflow_definition_version | int | 本次执行锁定的版本 |
| state | tinyint | 0 = 提交，1 = 运行中，2 = 暂停准备，3 = 已暂停，4 = 停止准备，5 = 已停止，6 = 失败，7 = 成功，8 = 需要容错，9 = 已终止，10 = 等待，11 = 等待依赖 |
| state_history | text | 状态转换日志 |
| start_time | datetime | 执行开始时间 |
| end_time | datetime | 执行结束时间 |
| command_type | tinyint | 0 = 开始，1 = 从当前开始，2 = 恢复，3 = 恢复暂停，4 = 从失败处开始，5 = 补充，6 = 调度，7 = 重新运行，8 = 暂停，9 = 停止，10 = 恢复等待 |
| host | varchar(135) | 执行此工作流的主服务器主机 |
| executor_id | int | 触发执行的用户 |
| tenant_code | varchar(64) | 用于资源隔离的租户 |
| next_workflow_instance_id | int | 用于串行执行模式 |
索引：
KEY workflow_instance_index (workflow_definition_code, id)KEY start_time_index (start_time, end_time)
t_ds_task_instance
单个任务的运行时执行记录。
| 列 | 类型 | 描述 |
|---|---|---|
| id | int | 主键 |
| task_code | bigint | 引用任务定义 |
| task_definition_version | int | 锁定的版本 |
| workflow_instance_id | int | 父工作流实例 |
| state | tinyint | 与 workflow_instance 相同的状态值 |
| submit_time | datetime | 提交到队列的时间 |
| start_time | datetime | 实际执行开始时间 |
| end_time | datetime | 执行结束时间 |
| host | varchar(135) | 执行任务的工作线程主机 |
| execute_path | varchar(200) | 工作线程上的工作目录 |
| log_path | text | 日志文件路径 |
| retry_times | int | 当前重试次数 |
| var_pool | text | 供下游任务使用的变量 |
索引：KEY idx_task_instance_code_version (task_code, task_definition_version)
命令模式与工作流执行
命令队列
t_ds_command 表实现了基于队列的执行模型，其中命令触发工作流实例。
t_ds_command 结构
| 列 | 类型 | 描述 |
|---|---|---|
| command_type | tinyint | 0 = 开始，1 = 从当前开始，2 = 恢复，3 = 恢复暂停，4 = 从失败处开始，5 = 补充，6 = 调度，7 = 重新运行，8 = 暂停，9 = 停止 |
| workflow_definition_code | bigint | 目标工作流 |
| workflow_instance_id | int | 用于恢复/重新执行操作 |
| workflow_instance_priority | int | 0 = 最高，1 = 高，2 = 中，3 = 低，4 = 最低 |
| command_param | text | JSON 格式的执行参数 |
| worker_group | varchar(255) | 目标工作线程组 |
| tenant_code | varchar(64) | 执行的租户 |
| dry_run | tinyint | 0 = 正常，1 = 试运行（无实际执行） |
处理流程：
- 通过 API、调度程序或重试逻辑将命令插入
t_ds_command。 - 主服务器的
MasterSchedulerThread持续扫描该表（按优先级、id 排序）。 - 主服务器生成
t_ds_workflow_instance记录。 - 主服务器分析 DAG 并为就绪任务创建
t_ds_task_instance记录。 - 成功处理的命令将被删除；失败的命令将移动到
t_ds_error_command。
版本控制系统
基于代码的版本控制模型
DolphinScheduler 使用复杂的版本控制系统，支持：
- 不同版本的并发执行。
- 安全更新而不影响正在运行的实例。
- 完整的变更审计跟踪。
版本管理规则
- 当前版本表：只有“当前”版本存在于
t_ds_workflow_definition和t_ds_task_definition中。 - 日志表：所有版本保存在
*_log表中，具有UNIQUE KEY (code, version)。 - 在线状态：每个代码只能有一个版本的
release_state = 1（在线）。 - 实例锁定：工作流实例在创建时锁定到特定版本。
- 版本不可变性：一旦某个版本被实例引用，其日志记录即为不可变。
调度体系架构
Quartz 集成
DolphinScheduler 集成了 Quartz 调度程序以实现基于 cron 的调度。模式包括标准 Quartz 表以及一个映射表。
t_ds_schedules
| 列 | 类型 | 描述 |
|---|---|---|
| workflow_definition_code | bigint | 目标工作流（唯一） |
| start_time | datetime | 调度活动开始时间 |
| end_time | datetime | 调度活动结束时间 |
| timezone_id | varchar(40) | cron 表达式的时区 |
| crontab | varchar(255) | cron 表达式 |
| release_state | int | 0 = 离线，1 = 在线 |
| failure_strategy | int | 失败时的行为 |
| workflow_instance_priority | int | 实例的默认优先级 |
Quartz 表要点：
QRTZ_TRIGGERS.NEXT_FIRE_TIME：已索引，便于高效扫描。QRTZ_CRON_TRIGGERS.CRON_EXPRESSION：解析后的 cron 定义。QRTZ_SCHEDULER_STATE：跟踪 Quartz 调度程序实例。
资源和配置表
数据源管理
t_ds_datasource
存储 SQL 任务的数据库连接配置。
| 列 | 类型 | 描述 |
|---|---|---|
| name | varchar(64) | 数据源名称 |
| type | tinyint | 数据库类型（MySQL、PostgreSQL、Hive 等） |
| connection_params | text | JSON 格式的连接配置（主机、端口、数据库、凭据） |
| user_id | int | 所有者用户 |
约束：UNIQUE KEY (name, type) - 防止数据源重复。
文件资源
t_ds_resources（已弃用）
注意：此表在模式中已标记为弃用。资源元数据正在迁移到单独的存储后端。
| 列 | 类型 | 描述 |
|---|---|---|
| full_name | varchar(128) | 包括租户的完整路径 |
| type | int | 文件类型（文件/UDF） |
| size | bigint | 文件大小（字节） |
| is_directory | boolean | 目录标志 |
| pid | int | 父目录 ID |
多租户与管理
项目、用户和租户层次结构
关键管理表
t_ds_tenant
| 列 | 类型 | 描述 |
|---|---|---|
| tenant_code | varchar(64) | 唯一租户标识符（唯一） |
| queue_id | int | 任务的默认 YARN 队列 |
| description | varchar(255) | 租户描述 |
默认租户：系统创建一个默认租户，id = -1，tenant_code = 'default'。
t_ds_user
| 列 | 类型 | 描述 |
|---|---|---|
| user_name | varchar(64) | 登录用户名（唯一） |
| user_password | varchar(64) | 哈希密码 |
| user_type | tinyint | 0 = 普通用户，1 = 管理员 |
| tenant_id | int | 关联的租户（默认 -1） |
| varchar(64) | 电子邮件地址 | |
| state | tinyint | 0 = 禁用，1 = 启用 |
t_ds_project
| 列 | 类型 | 描述 |
|---|---|---|
| code | bigint | 唯一项目代码（唯一） |
| name | varchar(255) | 项目名称（唯一） |
| user_id | int | 创建者/所有者 |
| description | varchar(255) | 项目描述 |
JDBC 注册表
对于不使用 ZooKeeper 的部署，DolphinScheduler 提供基于 JDBC 的注册表用于服务协调。
注册表详情
t_ds_jdbc_registry_data
存储类似于 ZooKeeper 节点的注册表项。
| 列 | 类型 | 描述 |
|---|---|---|
| data_key | varchar(256) | 类似路径的键（唯一） |
| data_value | text | 序列化数据 |
| data_type | varchar(64) | EPHEMERAL（客户端断开连接时删除）或 PERSISTENT |
| client_id | bigint | 所属客户端 |
| 列 | 类型 | 描述 |
|---|---|---|
| last_update_time | timestamp | 上次修改时间 |
t_ds_jdbc_registry_lock
实现分布式锁。
| 列 | 类型 | 描述 |
|---|---|---|
| lock_key | varchar(256) | 锁标识符（唯一） |
| lock_owner | varchar(256) | 持有锁的客户端（格式：ip_processId） |
| client_id | bigint | 所属客户端 |
t_ds_jdbc_registry_client_heartbeat
跟踪活动客户端以清理临时数据。
| 列 | 类型 | 描述 |
|---|---|---|
| id | bigint | 客户端 ID（主键） |
| client_name | varchar(256) | 客户端标识符 |
| last_heartbeat_time | bigint | 上次心跳时间戳 |
| connection_config | text | 连接元数据 |
清理逻辑：当客户端的心跳过期时，其临时注册表数据和锁将自动删除。
告警系统
告警表
t_ds_alert
由工作流/任务失败或完成生成的告警记录。
| 列 | 类型 | 描述 |
|---|---|---|
| title | varchar(512) | 告警标题 |
| sign | char(40) | 内容的 SHA1 哈希值（用于去重） |
| content | text | 告警消息正文 |
| alert_status | tinyint | 0 = 等待，1 = 成功，2 = 失败 |
| warning_type | tinyint | 1 = 工作流成功，2 = 工作流/任务失败 |
| workflow_instance_id | int | 源工作流实例 |
| alertgroup_id | int | 目标告警组 |
索引：KEY idx_sign (sign) - 实现去重。
t_ds_alertgroup
告警通道组。
| 列 | 类型 | 描述 |
|---|---|---|
| group_name | varchar(255) | 唯一组名 |
| alert_instance_ids | varchar(255) | 逗号分隔的插件实例 ID |
| description | varchar(255) | 组描述 |
索引与查询优化
关键索引
该模式包含针对常见查询模式精心设计的索引：
- 工作流和任务查找
- 按定义查询工作流实例：
`KEY workflow_instance_index (workflow_definition_code, id)`
- 按定义查询任务实例：
`KEY idx_task_instance_code_version (task_code, task_definition_version)`
- 用于监控的时间范围查询*：
`KEY start_time_index (start_time, end_time)`
- 命令处理：
基于优先级的命令扫描：
`KEY priority_id_index (workflow_instance_priority, id)`
- DAG 关系查询
- 正向和反向 DAG 遍历：
`KEY idx_pre_task_code_version (pre_task_code, pre_task_version)`
正向和反向 DAG 遍历：
`KEY idx_post_task_code_version (post_task_code, post_task_version)`
`KEY idx_code (project_code, workflow_definition_code)`
唯一约束
在数据库级别强制执行的关键业务规则：
| 表 | 约束 | 目的 |
|---|---|---|
t_ds_workflow_definition | UNIQUE (name, project_code) | 项目中无重复的工作流名称 |
t_ds_workflow_definition | UNIQUE (code) | 全局工作流标识符 |
t_ds_workflow_definition_log | UNIQUE (code, version) | 每个版本一条记录 |
t_ds_datasource | UNIQUE (name, type) | 每种类型无重复的数据源名称 |
t_ds_schedules | UNIQUE (workflow_definition_code) | 每个工作流一个调度 |
模式演变与升级
DolphinScheduler 在 dolphinscheduler - dao/src/main/resources/sql/upgrade 中维护用于跨版本模式迁移的升级脚本。
近期模式变更
3.3.0 变更
- 将表和列从“process”重命名为“workflow”。
- 删除数据质量表（
t_ds_dq_*）。 - 添加用于替代 ZooKeeper 的 JDBC 注册表。
- 从任务表中删除与缓存相关的列。
3.2.0 变更
- 向工作流定义中添加
execution_type（并行/串行模式）。 - 为串行执行链添加
next_workflow_instance_id。 - 向命令和实例表中添加
tenant_code。 - 创建
t_ds_project_parameter和t_ds_project_preference。
数据库交互模式
服务层访问
数据库访问通过 dolphinscheduler - dao 中的 DAO 层进行抽象。
关键服务类：
ProcessService：工作流/任务定义和实例的 CRUD 操作。CommandService：命令队列管理。ProjectService：项目和权限管理。ResourcesService：资源元数据操作。
事务管理
大多数操作使用 Spring 的 @Transactional 注解实现：
- 原子性地创建工作流实例及其任务实例。
- 消费命令并创建实例。
- 版本更新与日志表同步。
连接池
系统使用 HikariCP 进行连接池，在 application.yaml 中配置：
- 默认池大小：50 个连接。
- 连接超时：30 秒。
- 空闲超时：600 秒。
