CodeIgniter4 项目中使用 PostgreSQL 数据库的注意事项

在使用 CodeIgniter4 框架开发项目时，许多开发者会遇到数据库连接相关的问题，特别是当使用 PostgreSQL 作为后端数据库时。本文将深入分析一个典型问题场景，并提供完整的解决方案。

问题现象

在 FreeBSD 13 系统上运行 CodeIgniter4 4.4.7 版本的项目时，Web 界面能够正常连接 PostgreSQL 16 数据库并执行用户注册、登录等操作，但在使用命令行工具执行 spark migrate:status 时却出现错误提示："Unable to connect to the database" 并指出 "call to undefined function pg_connect()"。

问题本质

这个问题的核心在于 PHP 运行环境的差异。虽然 Web 服务器环境已经正确配置了 PostgreSQL 扩展，但命令行环境(CLI)可能没有加载相同的扩展配置。

技术背景

PostgreSQL 数据库连接需要 PHP 的 pgsql 扩展支持。在大多数 Linux/Unix 系统中，PHP 的 Web 模块和 CLI 模块实际上是两个独立的运行环境，它们可能有不同的 php.ini 配置文件或加载不同的扩展。

解决方案

1. 验证 PostgreSQL 扩展安装 首先确认系统是否已安装 PHP 的 PostgreSQL 扩展。可以通过以下命令检查：

   php -m | grep pgsql
   

2. 安装缺失的扩展 如果扩展未安装，需要根据操作系统安装对应的包：

   • 在 FreeBSD 上：

     pkg install php83-pgsql
     

3. 配置 CLI 环境 确保 CLI 环境的 php.ini 文件启用了 pgsql 扩展。通常 CLI 的 php.ini 文件位于：

   /usr/local/etc/php.ini
   

   检查并确保包含以下行：

   extension=pgsql
   

4. 验证 CLI 环境 安装配置完成后，再次运行：

   php -m | grep pgsql
   

   应该能看到 pgsql 出现在已加载模块列表中。

最佳实践

1. 环境一致性检查 建议开发者在部署前后使用以下命令检查 Web 和 CLI 环境的一致性：

   # Web 环境检查
   php -r 'phpinfo();' | grep pgsql
   
   # CLI 环境检查
   php -i | grep pgsql
   

2. 自动化部署检查 在部署脚本中加入环境检查步骤，确保所有必要的扩展都已加载。

3. 多环境测试 在开发、测试和生产环境中都应测试 CLI 工具的功能，避免只在 Web 界面测试数据库连接。

总结

CodeIgniter4 框架的数据库迁移工具依赖正确的 PHP 环境配置。当遇到数据库连接问题时，开发者需要全面检查 Web 和 CLI 两种运行环境下的扩展加载情况。特别是在使用 PostgreSQL 这类需要额外扩展的数据库时，确保环境一致性是解决问题的关键。通过系统化的环境检查和配置管理，可以避免类似问题的发生，保证项目的顺利开发和部署。