基于CircleCI与Terraform构建AWS基础设施后，如何在Lambda中执行Alembic迁移？

针对你已经通过CircleCI+Terraform完成AWS基础设施搭建，现在需要在Lambda环境中运行Alembic迁移的场景，分享几个可落地的方案：

方案1：Lambda函数直接集成Alembic #

这是最直接的方式，把Alembic的迁移逻辑嵌入Lambda handler：

• 打包部署包时，把Alembic依赖、迁移脚本目录（versions/）和alembic.ini都包含进去
• 不要硬编码数据库URL到alembic.ini，改成从Lambda环境变量读取（从AWS Secrets Manager拉取会更安全）
• 编写handler代码调用Alembic API执行迁移：

  from alembic.config import Config
  from alembic import command
  import os
  import logging
  
  logger = logging.getLogger()
  logger.setLevel(logging.INFO)
  
  def lambda_handler(event, context):
      try:
          db_url = os.getenv("DATABASE_URL")
          if not db_url:
              raise ValueError("DATABASE_URL environment variable not set")
          
          alembic_cfg = Config("alembic.ini")
          alembic_cfg.set_main_option("sqlalchemy.url", db_url)
          command.upgrade(alembic_cfg, "head")
          
          logger.info("Database migration completed successfully")
          return {"statusCode": 200, "body": "Migration done"}
      except Exception as e:
          logger.error(f"Migration failed: {str(e)}")
          raise e
  

• 注意点：
  • 给Lambda执行角色配置好数据库访问权限（比如RDS的VPC权限、安全组放行规则）
  • 用pip install -r requirements.txt -t ./package把依赖装到部署包目录，再打包上传

方案2：CircleCI部署后触发Lambda迁移 #

既然已经用CircleCI做基础设施交付，可以把迁移和部署流程绑定：

• 在CircleCI的config.yml里加一个job，用AWS CLI调用Lambda函数：

  jobs:
    deploy-infra:
      # 你的Terraform部署步骤...
    run-migration:
      docker:
        - image: amazon/aws-cli:latest
      steps:
        - run:
            name: Trigger migration Lambda
            command: aws lambda invoke --function-name your-migration-lambda output.json
  workflows:
    deploy-and-migrate:
      jobs:
        - deploy-infra
        - run-migration:
            requires:
              - deploy-infra
  

• Lambda函数的逻辑和方案1一致，专门负责执行迁移
• 好处：每次基础设施更新后自动同步数据库schema，避免环境不一致

方案3：用Lambda层管理Alembic依赖 #

如果多个Lambda需要用到Alembic，用层来复用更高效：

• 创建层的目录结构：python/lib/python3.11/site-packages/（对应你的Lambda Python版本）
• 安装依赖到该目录：pip install alembic sqlalchemy -t python/lib/python3.11/site-packages/
• 把整个python/目录打包成zip，上传到Lambda层
• 你的Lambda部署包只需要包含迁移脚本、alembic.ini和handler函数，关联层即可使用依赖

必踩坑提醒 #

• 幂等性：所有Alembic迁移脚本必须是幂等的，比如用op.execute时要加判断，避免重复执行报错
• 日志排查：一定要把迁移日志输出到CloudWatch，出问题时能快速定位
• 环境隔离：不同环境（dev/staging/prod）的alembic.ini和数据库配置要分开，别搞混了
• 权限控制：Lambda角色只给必要的权限（比如数据库连接、Secrets Manager读取），不要用管理员权限

内容的提问来源于stack exchange，提问作者Claudio Shigueo Watanabe