如何在Flask+Docker Compose环境下手动管理数据库迁移并解决连接问题？

一、解决本地执行迁移命令无法连接容器Postgres的问题 #

你遇到的sqlalchemy.exc.OperationalError是因为在主机上执行命令时，无法解析Docker容器的服务名db——只有Docker内部的网络才能识别这个服务名。下面有两种可行的解决方案：

方案1：修改本地数据库连接地址，直接连接主机映射的端口

你的db容器已经把5432端口映射到了主机的5432端口，所以可以临时调整Flask的数据库连接字符串，让本地应用连接到localhost而非容器服务名：

• 比如把SQLALCHEMY_DATABASE_URI从：

  SQLALCHEMY_DATABASE_URI = "postgresql://postgres:123456@db:5432/postgres"
  

  改成：

  SQLALCHEMY_DATABASE_URI = "postgresql://postgres:123456@localhost:5432/postgres"
  

• 更优雅的方式是用环境变量区分本地和容器环境，避免频繁修改代码：

  import os
  SQLALCHEMY_DATABASE_URI = os.getenv("DATABASE_URL", "postgresql://postgres:123456@db:5432/postgres")
  

  本地执行迁移前，设置环境变量：

  export DATABASE_URL="postgresql://postgres:123456@localhost:5432/postgres"
  

方案2：在Docker容器内执行迁移命令，将脚本同步到主机

这种方法不需要修改连接字符串，利用Docker Compose的网络让容器内的Web服务直接连接db服务，同时通过挂载卷将生成的迁移脚本同步到主机：

1. 先在docker-compose.yaml的web服务中添加卷挂载，把主机的migrations目录和容器内的目录同步：

   web:
     build:
       context: .
     expose:
       - "5000"
     depends_on:
       - db
     volumes:
       - ./migrations:/app/migrations  # 挂载迁移目录到主机，实现脚本同步
   db:
     image: postgres
     volumes:
       - my_volume:/var/lib/postgresql/data
     ports:
       - "5432:5432"
     environment:
       POSTGRES_PASSWORD: 123456
   

2. 执行以下命令在容器内生成迁移脚本：

   docker-compose run --rm web flask db migrate
   

   执行后，主机的migrations目录会生成对应的脚本，你可以直接在本地审核修改，之后提交到版本控制。

二、Docker环境下Flask-Migrate的规范管理机制 #

结合Flask-Migrate的提示和Docker最佳实践，推荐遵循以下规范：

• 迁移脚本必须纳入版本控制：生成并审核后的迁移脚本要和代码一起提交到Git等版本控制工具，确保所有环境（开发、测试、生产）使用完全一致的脚本，避免环境不一致导致的问题。
• 容器启动仅执行upgrade，禁止自动migrate：你当前的CMD flask db upgrade && flask run是合理的——生产环境绝对不能自动生成迁移脚本，必须使用预先审核好的脚本执行升级。
• 分环境管理迁移流程：
  • 开发环境：用上述两种方法生成脚本，仔细审核后提交；
  • 生产环境：拉取已审核的脚本，启动容器时自动执行upgrade，严禁在生产环境运行migrate。
• 利用Docker网络保证容器间通信：容器内的Web服务通过Docker Compose默认创建的网络，可以直接用服务名（比如db）连接数据库，生产环境可以去掉ports配置，避免不必要的端口暴露。
• 迁移前务必备份数据库：无论是开发还是生产环境，执行upgrade前都要备份数据库，避免迁移失败导致数据丢失。
• 严格审核迁移脚本：正如Flask-Migrate提示的：

  The migration script needs to be reviewed and edited, as Alembic currently does not detect every change you make to your models. In particular, Alembic is currently unable to detect table name changes, column name changes, or anonymously named constraints.
  每次生成脚本后，必须检查是否覆盖了所有模型变更，比如表名/列名修改、约束名称等，手动修正脚本后再提交。

内容的提问来源于stack exchange，提问作者adnanmuttaleb