PHP连接TimescaleDB与PostgreSQL完全一致，需启用pdo_pgsql扩展、确保数据库已执行CREATE EXTENSION timescaledb，并使用time_bucket()等特有函数及create_hypertable()建表。
PHP 连接 TimescaleDB 和连接普通 PostgreSQL 完全一致，不需要额外驱动或特殊配置 —— 但必须确保 TimescaleDB 扩展已在目标数据库中启用，否则 time_bucket() 等函数会报错。
pdo_pgsql 扩展是否已启用
TimescaleDB 本身不提供 PHP 驱动，它完全依赖 PostgreSQL 的标准协议。PHP 必须启用 pdo_pgsql（推荐）或 pgsql 扩展：
- 检查是否加载：
php -m | grep pgsql；若无输出，需安装并启用扩展 - Debian/Ubuntu：
sudo apt install php-pgsql，然后确认/etc/php/*/apache2/conf.d/20-pdo_pgsql.ini存在且未被注释 - CentOS/RHEL/麒麟OS：
sudo yum install php-pgsql或dnf install php-pgsql，注意 PHP 版本匹配（如 php82-php-pgsql） - 统信UOS 同样走 APT，但需确认源中含对应 PHP 版本的包（如
php8.1-pgsql）
连接字符串与认证参数
使用 PDO 时，DSN 格式与 PostgreSQL 完全相同，postgresql:// 或 pgsql: 均可：
$dsn = 'pgsql:host=localhost;port=5432;dbname=mydb;user=postgres;password=mypass';
$pdo = new PDO($dsn, '', '', [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
- SSL 模式需显式指定：加
sslmode=require（若服务端强制 SSL），否则默认prefer - 连接池或高并发场景下，建议复用
$pdo实例，避免频繁建立连接 - 不要在 DSN 中硬编码密码；生产环境应通过环境变量或配置中心注入
CREATE EXTENSION 是否已执行
这是 PHP 连接后操作失败最常见的原因 —— 函数不存在、超表创建失败等错误，90% 源于此步遗漏：
立即学习“PHP免费学习笔记（深入）”；
- 必须由有
CREATEDB权限的用户（如postgres）在目标库内执行：CREATE EXTENSION IF NOT EXISTS timescaledb; - 验证命令：
SELECT * FROM pg_available_extensions WHERE name = 'timescaledb';，看installed_version是否非空 - 若用非超级用户操作，需先授权：
GRANT USAGE ON SCHEMA public TO myuser; - 某些国产 OS（如麒麟、UOS）还要求检查
shared_preload_libraries = 'timescaledb'是否写入postgresql.conf并重启服务
时序特性的 PHP 使用注意事项
连接通了不等于能用好 TimescaleDB。关键点不在连接层，而在 SQL 层调用习惯：
- 建表必须用
create_hypertable()而非CREATE TABLE，例如：SELECT create_hypertable('metrics', 'time'); - 查询时间范围务必用
time_bucket()，别写GROUP BY date_trunc('hour', time)—— 后者无法利用 chunk 分区剪枝 - 插入大量数据时，用
PDO::prepare() + execute()批量提交，比单条INSERT快数倍；更优方案是pg_copy_from()（需扩展支持） - PHP 的
DateTime对象传入时，确保带时区（如new DateTime('2026-09-27T10:00:00+08:00')），否则可能被 PostgreSQL 当作本地时间处理导致偏移
最容易被忽略的是：TimescaleDB 的功能完全运行在 PostgreSQL 进程内，PHP 层看不到任何“TimescaleDB 特有协议”。所有问题本质都是 PostgreSQL 配置、权限或 SQL 写法问题 —— 别被名字带偏了方向。
