Apache Airflow 元数据库 ERD 图解解析从 ER 图生成机制到 SQLAlchemy 模型与迁移体系【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文以 Airflow 官方文档 database-erd-ref.rst 为核心解读 Airflow 元数据库Metadata Database的 ERD实体关系图文档它的定位与使用边界、ERD 图在文档构建时如何自动生成、ERD 背后的核心 SQLAlchemy 模型集合以及配套的数据库迁移migration体系与db系列 CLI 命令。读完本文你将能够看懂 Airflow 内部数据库结构、在排查数据库故障或执行版本升级迁移时正确定位相关表与迁移记录并理解“不要直接读写元数据库”这一官方约束背后的工程原因。一、ERD 文档的定位内部细节快照而非对外数据接口airflow-core/docs/database-erd-ref.rst文档开篇即给出了一段重要的官方警告这段话是理解整个元数据库使用方式的基石ERD 图是当前 Airflow 版本本仓库对应版本为 3.4.0见 airflow-core/pyproject.toml 中version 3.4.0下数据库结构的快照应当被视为内部实现细节internal detail该结构随时可能变化因此不应直接访问数据库来读取或修改其中的数据获取和变更 Airflow 元数据的正确方式是使用 稳定 REST API这张图的主要用途是辅助故障排查troubleshooting——帮助你理解 Airflow 内部数据库架构例如在遇到数据库迁移migration相关问题时对照分析文档同时指向了两份配套资料数据库迁移参考migrations-ref 和 CLI 中 db 命令组。换言之ERD 文档本身并不承诺任何字段级、表级的稳定契约。它是一张“解剖图”当你需要诊断“为什么这次迁移失败”“为什么dag_run表膨胀”“Triggerer 到底往哪张表写状态”这类问题时它是第一参照物但把它当作查询 Airflow 数据的接口来用是官方明确反对的做法。二、ERD 图不是手工维护的文档构建期自动生成原文档中有一行注释揭示了关键实现img/airflow_erd.svg这张图在文档构建时由generate_erdSphinx 扩展自动生成而不是仓库中手工提交的一张静态图。这也解释了为什么在当前源码仓库的airflow-core/docs/img/目录下并不存在airflow_erd.svg文件——它是构建产物。生成逻辑完整实现在 devel-common/src/sphinx_exts/generate_erd.py 中可以从源码结构中梳理出以下机制2.1 按包区分生成目标扩展在builder-inited钩子generate_erd.py#L111-L122触发通过环境变量AIRFLOW_PACKAGE_NAME判断当前构建的是哪个包并映射到不同的模型收集器与输出文件名generate_erd.py#L104-L108构建包收集器输出文件apache-airflow_collect_core_metadata核心模型airflow_erd.svgapache-airflow-providers-fab_collect_fab_metadataFAB 认证模型fab_erd.svgapache-airflow-providers-edge3_collect_edge3_metadataEdge3 模型edge3_erd.svg也就是说主文档里的 ERD 只覆盖 Airflow 核心模型Provider如 FAB、Edge3各自在自己的文档包中生成独立的 ERD核心图不会掺杂 Provider 表。2.2 从 SQLAlchemy MetaData 渲染 SVG以核心包为例_collect_core_metadatagenerate_erd.py#L57-L70的执行链路是调用airflow.models.import_all_models()把所有核心模型模块导入确保每张 ORM 表都注册到元数据中从airflow.models.base.BaseSQLAlchemy 声明式基类的Base.metadata.tables中取出全部表通过table.to_metadata(metadata)把它们拷贝进一个新的MetaData容器交给eralchemy.render_er(metadata, svg_path, exclude_tables[sqlite_sequence])渲染成 SVG其中显式排除了 SQLite 的自动编号表sqlite_sequencegenerate_erd.py#L158-L162。2.3 依赖缺失时的降级策略从源码看generate_erald.py 的 builder_inited 流程渲染依赖两层工具链Python 侧需要eralchemy包系统侧需要 graphviz 的dot可执行文件shutil.which(dot)检查。任何一层缺失或未安装可选模型依赖导致ImportError扩展都会调用_write_placeholder写入一张占位 SVG提示“ERD diagram not generated: eralchemy or graphviz system package is not available”从而保证文档构建不会因缺图而失败。这个设计值得借鉴可视化产物被当作“尽力而为的派生数据”而不是构建的硬依赖。三、ERD 覆盖的模型核心数据库对象清单import_all_models()airflow-core/src/airflow/models/init.py#L59-L80是 ERD 的“取材范围”。它先通过模块级 PEP-562 懒加载机制__lazy_imports__getattr__拉取Job、Connection、DagModel、DagRun、TaskInstance、Variable、XCom、Pool、Trigger、Log、Deadline、Callback等主要模型再显式导入一组模块级表定义airflow.models.asset与asset_state_storeAsset数据集/数据资产及其状态存储airflow.models.backfillBackfill回填相关表airflow.models.connection_test、dag_favorite、dag_version、dagbag、dagbundle、dagwarningDAG 版本、Bundle、DAG 包解析状态、收藏与告警airflow.models.deadline_alert、errors、hitl、hitl_historyDeadline 告警、错误记录、Human-in-the-Loop 审批与历史airflow.models.revoked_token、serialized_dag、task_state_store、taskinstancehistory、tasklog、team、xcom等。对照 airflow-core/src/airflow/models/ 目录可以看到 ERD 中的每张核心表都对应一个模型文件例如dag.pyDagModel、dagrun.pyDagRun、taskinstance.pyTaskInstance、pool.py资源池、variable.py、xcom.py、trigger.pyTriggerer 的触发器状态、deadline.py、team.py、hitl.py等。排查“某张表是干什么的”这类问题时直接按表名到该目录下找同名模型文件通常就能读到字段级注释与 ORM 关系定义。一个值得注意的结构细节Airflow 3.x 引入了大量与 Asset由 Dataset 演进而来相关的表asset_state_store、task_state_store、partition相关迁移等以及 Team 模型team.py。这些新表都通过迁移脚本逐步加入见下一节而不是直接出现在旧版本数据库中——这正是 ERD“版本快照”属性的直接体现。四、ERD 中“看不出来”的底层约定命名规范、ID 长度与排序规则ERD 图展示的是表与列的静态关系而一些横切全库的约定定义在 airflow-core/src/airflow/models/base.py 中。理解它们能解释图中大量看似雷同的索引/约束命名4.1 全局命名约定naming conventionbase.py#L32-L38 为整个MetaData设置了 SQLAlchemy 命名约定naming_convention { ix: idx_%(column_0_N_label)s, # 索引 uq: %(table_name)s_%(column_0_N_name)s_uq, # 唯一约束 ck: ck_%(table_name)s_%(constraint_name)s, # 检查约束 fk: %(table_name)s_%(column_0_name)s_fkey, # 外键 pk: %(table_name)s_pkey, # 主键 }因此 ERD/数据库中出现的idx_...、..._fkey、..._pkey命名并非偶然而是全库统一的机器可预测命名——这也是 Alembic 迁移文件能够稳定地按名称创建/删除这些对象的基础。4.2 ID 列长度与排序规则collationID_LEN 250base.py#L59全库 ID 类字符串列dag_id、task_id、run_id等统一采用 250 字符上限StringID()辅助函数base.py#L86-L87会附带 collation 参数若配置了[database] sql_engine_collation_for_ids则使用配置值否则对 MySQL/MariaDB 自动使用utf8mb3_bin以保持与旧版本数据库的向后兼容并避免索引超过 MySQL 最大长度base.py#L62-L83所有表还共享由[database] SQL_ALCHEMY_SCHEMA配置项决定的 schemabase.py#L27-L47在 PostgreSQL 多 schema 部署中用于把 Airflow 表隔离到独立 schema。五、表结构如何演进迁移链与airflow db migrateERD 是“当前态”的截面而数据库的“历史”则记录在 migrations-ref.rst 中。该文档的迁移总表由scripts/ci/prek/migration_reference.py钩子自动从迁移文件抓取更新覆盖从2.6.2 的初始基线revision4bc4d934e2bc描述为 “Create initial database state from Airflow v2.6.2”到3.4.0 的 headrevisionf8c2a1d94e03描述为 “Add team_name and bundle_names scope columns to job table”的完整迁移链。从 3.0.0 区间的迁移记录可以看出 Airflow 3.x 数据库结构发生了哪些根本性变化这些正是 ERD 图相对 2.x 差异最大的地方Drop DAG picklingd03e4a635aa3彻底移除 DAG pickle 数据序列化 DAG 改由serialized_dag表承载Rename dataset as asset3a8972ecb8f9与Rename execution_date to logical_date1cdc775ca98f概念重命名直接落到表/列层面Add tables for backfill522625f6d606Backfill 成为一等公民有独立表Add dag versioning2b47dc6bc8dfDAG 版本化引入dag_version相关表Change TI table to have unique UUID id/pk per attempt29ce7909c52bTaskInstance 主键改为每次尝试唯一的 UUIDAdd deadline alerts table038dc8bc6284、Add Human In the Loop Detail tableffdb0566c7c0等对应 3.x 的 Deadline 与 HITL 功能。执行这些迁移的标准命令是airflow db migrate。从仓库文档中可以看到若干实操要点升级版本时必须运行airflow db migrate来应用新版本迁移upgrading.rst可以只生成 SQL 而不执行用于变更前人工审查airflow db migrate --show-sql-only --from-version 2.4.3 --to-version 2.7.3或使用--range/--revision-range逐条应用usage-cli.rst#L313-L318airflow db upgrade自 2.7.0 起已被airflow db migrate取代upgrading.rst#L81数据库连接健康可用airflow db check校验失败时命令会以非零退出码结束check-health.rst#L183适合放进部署后的健康检查流程。排查迁移问题时推荐的工作流是先在 ERD 上确认目标表/列的“应有状态”再到 migrations-ref.rst 的表中找到对应 revision 与版本用--show-sql-only预览该迁移的实际 DDL三者交叉验证。六、使用边界与排查建议小结结合 ERD 文档的原始声明与源码实现可以归纳出几条实用规则只读地看不要直接写任何数据获取与变更都应走 稳定 REST API如 Connection、Variable、DagRun、TaskInstance 等资源均有对应端点直接 SQL 读写不受版本兼容性保护ERD 是版本绑定的当前仓库版本 3.4.0 的 ERD 与 2.x 或未来版本差异显著dataset→asset、pickle 移除、backfill/HITL/Deadline 新表等跨版本对照时务必以对应版本的文档和迁移表为准核心图与 Provider 图分离核心 ERD 只含apache-airflow的模型FAB 认证表、Edge3 边缘执行表等分别生成在各自 Provider 文档包中fab_erd.svg、edge3_erd.svg排查涉及这些组件的表结构时不要只盯着核心图图是派生物模型文件是事实来源字段注释、关系、默认值有疑问时以 airflow-core/src/airflow/models/ 下的 ORM 定义为准ERD 图仅是它在构建时的一次可视化渲染渲染链路见 generate_erd.py。理解这套“文档快照 自动生成 迁移链 官方 API 边界”的组合你就能在 Airflow 的数据库层面做到升级前看清迁移影响面、故障时快速定位表与 revision、以及始终沿着官方支持的接口使用元数据。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考