PHP 8 连接 CockroachDB 必须使用 pgsql 扩展而非 MySQL 驱动，DSN 中强制指定 sslmode=require，启用 PDO 异常模式并捕获 SQLSTATE '40001' 重试；需确认 pgsql 扩展已加载、证书路径正确且用户权限完备。
确认CockroachDB驱动是否真正可用
PHP 8 连接 CockroachDB 不能直接用原生 MySQL 驱动——它虽兼容 PostgreSQL 协议，但必须走 pgsql 扩展，且需显式启用 SSL 模式。先验证基础环境：运行 php -m | grep pgsql，若无输出，说明 pgsql 扩展未启用或根本未安装。
检查 php.ini 中是否已取消注释：extension=pgsql 和 extension=pdo_pgsql；若使用 Docker 或编译安装，还需确认 libpq 开发库已就位（yum install -y postgresql-devel 或 apt-get install -y libpq-dev）。
DSN 字符串必须强制指定 sslmode=require
哪怕本地单节点测试，也必须在 DSN 中写明 sslmode=require，否则连接会静默失败或报错 SSL connection is required。
正确写法：pgsql:host=localhost;port=26257;dbname=testdb;user=root;password=;sslmode=require。漏掉 sslmode=require → CockroachDB 直接拒绝握手，PDO 不抛异常，只返回 false 或空结果。
立即学习“PHP免费学习笔记（深入）”；
注意：CockroachDB 22.2+ 默认禁用非 SSL 连接，不加 sslmode=require 就等于没连上。
处理证书路径与自签名证书信任
若部署在生产环境且启用了 TLS 证书（如 cockroach cert 命令生成的 ca.crt、client.root.crt、client.root.key），需在 DSN 中追加参数：sslcert=/path/to/client.root.crt;sslkey=/path/to/client.root.key;sslrootcert=/path/to/ca.crt。
关键点：PHP 的 pgsql 扩展不读取环境变量或系统证书库，所有路径必须为绝对路径，且 Web 进程用户（如 www-data）必须有读取权限。用 ls -l /path/to/client.root.crt 确认属主和权限，否则报错 could not read certificate file。
修复 Core bailout 状态损坏安全问题，以及 BZ2、DOM、PDO、Opcache/JIT 内存与执行错误，改进 Unicode 字素处理、URL 解析、TLS 流状态、信号分发及会话错误处理。
开发环境用自签名证书时，可临时绕过验证：把 sslmode=require 改为 sslmode=verify-full 并配齐三个证书文件；若仍报 certificate verify failed，说明 ca.crt 未被正确加载或时间不同步。
PDO 属性必须设为异常模式
第一步：创建 PDO 实例后，立即执行 $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION)。
原因：CockroachDB 在事务冲突（如 TransactionRetryWithProtoRefreshError）、序列化失败等场景下，会返回特定 SQLSTATE（如 40001），但默认 PDO::ERRMODE_SILENT 下你收不到任何提示，只会拿到空结果或 false。
第二步：捕获重试逻辑。典型代码结构：
do {<br> try {<br> $pdo->beginTransaction();<br> // 执行 INSERT/UPDATE<br> $pdo->commit();<br> $retry = false;<br> } catch (PDOException $e) {<br> if ($e->getCode() === '40001') {<br> usleep(rand(10000, 50000)); // 随机退避<br> continue;<br> } else {<br> throw $e;<br> }<br> }<br>} while ($retry);
检查 CockroachDB 用户权限与数据库存在性
方法一：用 cockroach sql --insecure（或带证书）登录，执行：SHOW DATABASES; 确认目标库存在；再执行：SELECT * FROM system.users; 查看用户列表。
方法二：确认用户具备 CONNECT 权限：GRANT CONNECT ON DATABASE testdb TO root;。CockroachDB 默认只给 root 用户全局权限，新建用户必须显式授权，否则报错 permission denied for database。
注意：DB_NAME 必须全小写且不含特殊字符，CockroachDB 对标识符大小写敏感，TestDB 和 testdb 是两个库。
