ThinkPHP配置PostgreSQL数据库：连接驱动选择与字符集避坑指南-ThinkPHP-PHP中文网

thinkphp 连 postgresql 失败主因是 pdo_pgsql 扩展未启用、'charset' 参数触发 pdo 构造失败、或 pg_hba.conf 未放行 tcp 连接；需验证驱动、删 charset、用 127.0.0.1 显式端口、设 errmode_exception 并配置 pg_hba.conf。

thinkphp配置postgresql数据库：连接驱动选择与字符集避坑指南

ThinkPHP 连 PostgreSQL 不是改个 type 就能通的，连不上大概率卡在驱动没加载、charset 参数触发 PDO 构造失败、或连接被 pg_hba.conf 拦截这三处。下面直奔实操要点。

确认 pdo_pgsql 扩展已真正启用

光看 php -m | grep pgsql 不够，得验证 PDO 是否识别到 pgsql 驱动：

运行 php -r "print_r(PDO::getAvailableDrivers());"，输出数组里必须含 "pgsql"
Windows 下检查 php.ini 有且仅启用这两行：extension=php_pdo_pgsql.dll 和 extension=php_pgsql.dll（顺序不能反）
Linux/macOS 确认 extension=pdo_pgsql.so 已取消注释，且 pdo.so 在它之前加载
Docker 用户需在镜像中显式安装扩展包，例如 apk add php82-pgsql 或 apt install php-pgsql

database.php 中必须删掉 'charset' => 'utf8'

PostgreSQL 不接受 charset 连接参数，TP6/TP7 里加了会直接抛 InvalidArgumentException，但框架常把原始异常吞成空 QueryException，debug 时完全看不出原因。

PostgreSQL 18.4 ubuntu

PostgreSQL 18.4 官方 Ubuntu 安装包现已发布，这是目前最新的稳定版本。推荐通过官方 APT 仓库安装：先执行 sudo apt update 更新索引，再运行 sudo apt install postgresql-18 即可完成部署。新版本引入了异步 I/O 子系统，在顺序扫描与 VACUUM 场景下性能提升显著，同时支持 UUID v7 原生生成函数与虚拟生成列。

下载

'charset' => 'utf8' 或 'charset' => 'utf8mb4' 全部删掉，一行都不要留
字符集由 PostgreSQL 服务端控制，建库时用 CREATE DATABASE mydb ENCODING 'UTF8' 即可
如果要用 pg_set_client_encoding() 动态设编码，得在底层连接后手动调，不是配置项能解决的

hostname 写 127.0.0.1 而非 localhost，hostport 必须显式写

写 localhost 会让 PDO 尝试走 Unix socket，而多数 PG 安装默认不监听 socket 或路径不对，结果报错模糊；hostport 不显式写，某些环境 fallback 到 0 端口，直接连不上。

'hostname' => '127.0.0.1'（不是 'localhost'）
'hostport' => '5432'（哪怕端口没改也得写，Docker 场景下填容器名如 'db'）
TP3.2 注意 DB_TYPE 必须大写 Pgsql，小写会 fallback 到 MySQL 驱动
DSN 字符串方式（如 Db::connect('pgsql:host=127.0.0.1;port=5432;dbname=myapp;user=postgres;password=xxx')）同样要遵守 host+port 显式规则

务必设置 PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION

TP 默认已设该参数，但如果你重写了底层连接逻辑、或用了 new PDO()，漏掉这句就会让 PG 错误静默：权限不足、schema 不存在、表名拼错，全返回 false 或空结果，查半天才发现不是代码问题。

在 database.php 的 'params' 里补上：'params' => [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
否则 $db->table('nonexistent')->select() 可能只返回 []，而不是明确报错
这个设置还能捕获 PG 的 NOTICE 级警告（比如隐式类型转换），避免后期数据异常难定位

最容易被忽略的是 pg_hba.conf 配置——哪怕所有 PHP 和 TP 配置全对，只要这一行没加，就永远连不上：host all all 127.0.0.1/32 md5。别信“本地不用配”，PostgreSQL 默认只认 Unix socket，TCP 连接必须显式放行。