Laravel中Collection each()方法下数据库事务失效问题排查

我编写了一个Laravel服务类EPayrollUpload，用于遍历Excel文件并将有效行数据插入数据库。代码中使用Collection的each()方法循环处理每行数据，且嵌套了数据库事务控制。单元测试执行正常，数据可成功插入数据库，但在Docker容器化部署的开发环境中调用上传API时，事务未生效，无任何报错信息，salaries表和periods表始终为空。当前服务运行在Laravel容器中，连接同网络的PostgreSQL容器，请问是否存在配置遗漏或each()方法导致的问题？

排查方向与解决方案 #

一、each()方法与事务嵌套的潜在问题 #

Collection的each()方法本身不会干扰事务，但如果你的事务逻辑嵌套在each()循环内部，可能引发以下问题：

• 若循环内每次处理都开启新事务，某行数据的隐性错误（比如模型验证未通过但未抛出异常）会导致当前行事务回滚，但之前行的事务已提交——不过你这里是完全无数据插入，更可能是全局事务未正确提交。
• 建议将事务逻辑提到each()循环外部，用全局事务包裹整个批量处理流程，避免嵌套事务的不确定性：

DB::transaction(function () use ($rows) {
    $rows->each(function ($row) {
        // 单条数据插入逻辑，无需再嵌套事务
        $period = Period::firstOrCreate(['xxx' => $row['xxx']]);
        $period->salaries()->create($row['salary_data']);
    });
});

二、Docker环境数据库配置排查 #

1. 核对.env连接信息：
   • DB_HOST必须填写PostgreSQL容器的服务名（即docker-compose.yml中定义的service名称），不能用localhost或127.0.0.1（容器内的localhost指向自身，而非PostgreSQL容器）。
   • 确认DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD与PostgreSQL容器初始化的配置完全一致。
2. 验证容器网络连通性：
   在Laravel容器内执行命令测试连接：

   psql -h <postgres-service-name> -U <db-username> -d <db-name>
   

   若无法连接，检查docker-compose的网络配置，确保两个容器处于同一自定义网络中。
3. 查看PostgreSQL日志：
   执行docker logs <postgres-container-name>，排查是否有连接拒绝、权限错误或事务提交失败的日志记录。

三、事务提交的隐性问题排查 #

• 检查代码中是否存在**手动调用DB::rollBack()**的逻辑，或者事务闭包是否返回了false（Laravel的transaction()闭包返回false会触发自动回滚）。
• 开启查询日志验证SQL执行情况：

  DB::enableQueryLog();
  // 执行上传逻辑
  dd(DB::getQueryLog());
  

  确认是否有INSERT语句生成，以及最终是否执行了COMMIT命令。
• 检查模型的$timestamps属性：若关闭了该属性但数据库表中存在created_at/updated_at字段，会导致插入失败但不抛出异常。

四、其他容器环境相关排查 #

• 清除Laravel配置缓存：容器环境中可能加载了旧配置，执行php artisan config:clear刷新配置。
• 检查Excel文件上传权限：确认容器内的文件存储目录（如storage/app）权限正确，避免因文件无法读取导致解析出空数据集合。

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