FastAPI集成PostgreSQL时Alembic迁移失效及数据库连接报错问题

• 迁移文件丢失、upgrade无生效记录
  • 路径挂载不匹配：my_api服务的挂载卷仅同步本地项目目录到容器内的/app路径，你生成的迁移文件存储在容器内的/my_api/alembic/versions/路径下，该路径不在挂载同步范围内，既无法同步到本地，后续alembic执行升级时也无法读取到对应迁移文件。
  • 工作目录配置异常：容器默认工作目录和alembic配置的文件生成目录不一致，也会导致迁移文件生成到非预期路径。
• PostgreSQL连接拒绝
  • 启动顺序逻辑缺陷：depends_on仅控制容器的启动先后，不会等待PostgreSQL完成初始化（首次启动需创建库、配置权限，耗时较长），my_api启动时数据库还未就绪，导致连接失败。
  • 旧数据残留异常：之前启动的PostgreSQL容器残留的匿名卷存在数据损坏、配置冲突问题，会导致PostgreSQL启动失败、端口未正常监听。

1. 修复迁移文件路径问题

   • 在docker-compose.yml的my_api服务配置中新增working_dir: /app，强制指定容器工作目录为挂载同步路径。
   • 修改项目根目录的alembic.ini文件，将script_location参数设置为alembic（相对路径），确保迁移文件生成到/app/alembic/versions目录下，自动同步到本地。
   • 重新执行迁移生成命令：docker-compose run my_api alembic revision --autogenerate -m "New Migration"，即可在本地alembic/versions目录下看到生成的迁移文件。

2. 解决数据库连接异常问题

   • 先清理旧容器和残留卷，避免旧数据干扰：执行docker-compose down -v
   • 给database服务增加健康检查配置，确保PostgreSQL完全就绪后再启动my_api，修改后的database配置如下：

     database:
       container_name: postgresql_db
       image: postgres
       restart: always
       ports:
         - "5432:5432"
       environment:
         - POSTGRES_USER=${DB_USER}
         - POSTGRES_PASSWORD=${DB_PASSWORD}
         - POSTGRES_DB=${DB_NAME}
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d ${DB_NAME}"]
         interval: 5s
         timeout: 5s
         retries: 5
     

   • 修改my_api服务的depends_on配置，改为依赖数据库健康状态：

     depends_on:
       database:
         condition: service_healthy
     

3. 验证效果
   执行docker-compose up --build重新构建启动所有服务，启动完成后执行docker-compose exec my_api alembic current确认迁移版本生效，登录pgadmin即可看到数据库中已生成对应表。

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