waiting for table metadata lock 是 mysql 元数据锁（mdl）阻塞，非传统死锁；需通过 performance_schema.metadata_locks 定位 lock_status='granted' 的持锁线程，优先 kill 未提交事务的 sleep 连接，而非等待线程，并结合 innodb_trx 和 schema_table_lock_waits 精准排查。
MySQL 中 Waiting for table metadata lock 是什么
这不是传统意义上的事务死锁，而是 MySQL 的元数据锁（MDL）阻塞。当一个长事务或未提交的查询持有表的 MDL 时，后续所有 DDL（如 ALTER TABLE）和部分 DML（如大范围 SELECT）都会卡在 Waiting for table metadata lock 状态。Alembic 的 upgrade 默认执行 DDL，一旦遇到这种锁，就会无限等待。
怎么快速定位并释放元数据锁
直接查 processlist 并 kill 掉阻塞源是最有效的方式：
- 连接 MySQL：用
mysql -u root -p登录目标库 - 运行
SHOW PROCESSLIST;，重点看State列为Waiting for table metadata lock的行，以及它们前面那个Command为Query且Time很大的“源头”连接（通常是长时间未提交的事务或未关闭的连接） - 对源头 ID 执行
KILL <id></id>，不是杀等待中的，是杀那个正在 hold 锁的 - 确认无残留后，再跑
alembic upgrade head
注意：KILL 不会丢数据，但会中断当前事务——前提是它还没 commit。所以别在生产环境盲目 kill，先 SELECT * FROM information_schema.INNODB_TRX 看事务状态。
如何避免 Alembic 迁移再次触发 MDL 死锁
根本不在运行时抢锁，而是在迁移设计阶段规避：
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
- 所有涉及
op.add_column()、op.alter_column()、op.drop_column()的操作，必须确保目标表没有长事务、没有未关闭的连接（比如 Flask 开发模式下 debug toolbar 的自动查询） - 禁止在
upgrade()中混写大量op.execute("UPDATE ...")—— 这类 DML 如果没加WHERE或数据量大，会拖长事务时间，间接导致后续 DDL 被锁 - MySQL 5.6+ 可开启
lock_wait_timeout（默认 31536000 秒），但更推荐在迁移脚本开头加超时控制：op.execute("SET SESSION lock_wait_timeout = 10") - 生产环境升级前，用
alembic upgrade head --sql导出 SQL，人工审查是否含高风险语句（如ALTER TABLE ... MODIFY COLUMN），再配合pt-online-schema-change执行
为什么 autogenerate 容易引发锁问题
因为 alembic revision --autogenerate 在生成迁移前，会主动连接数据库并读取当前 schema —— 这个读操作本身可能开启隐式事务，若环境中有其他连接正在写，就可能被卡住，反过来又让后续 upgrade 等待。
真正安全的做法是：
- 开发机/测试环境：确保无其他应用连接该库，或用独立数据库实例
- CI/CD 流水线：在 migration job 前加健康检查，例如
mysqladmin ping -u $DB_USER -p$DB_PASS -h $DB_HOST，失败则 abort - 永远不要在生产库上直接跑
--autogenerate；应基于空库或备份库生成初稿，再人工校验
MDL 锁不是 bug，是 MySQL 保证 DDL 安全性的机制。问题不在 Alembic，而在你有没有控制好数据库连接生命周期和迁移粒度。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
