PHP连接Citus协调节点与普通PostgreSQL无区别，直连coordinator即可；关键在于SQL编写：需显式执行create_distributed_table()、查询必须包含分布列条件、JOIN需对齐分布键、reference表仅限只读。
PHP 连接 Citus 协调节点和普通 PostgreSQL 没区别
只要 Citus 扩展已正确安装并启用，PHP 应用无需任何特殊驱动或库变更——PDO_PGSQL 或 pg_connect() 直连 coordinator 节点即可，Citus 在协议层完全兼容 PostgreSQL。关键不是“PHP 怎么连”，而是“连上去之后怎么写 SQL 才不踩坑”。
create_distributed_table() 必须在 coordinator 上执行，且不能由 PHP 自动触发
分布式表的创建是元数据操作，必须由 DBA 或部署脚本在 coordinator 上显式执行，PHP 应用运行时调用 CREATE TABLE 不会自动分片。常见错误是误以为建表语句发给 coordinator 就能自动分布。
- 必须先在 coordinator 上手动执行：
SELECT create_distributed_table('orders', 'user_id'); - 表必须已存在（即先
CREATE TABLE orders(...)），再调用该函数指定分布列 - 如果表已有数据，
create_distributed_table()会自动触发跨 worker 的数据重分布（耗时，需评估窗口） - PHP 中执行该函数返回结果为一行一列（如
(complete)），但失败时抛出 PostgreSQL 错误，例如：ERROR: relation "orders" is already distributed
PHP 查询里漏掉分布列条件，性能直接崩
Citus 只有在 WHERE、JOIN 或 GROUP BY 中包含分布列时，才能把查询下推到单个 worker 并行执行；否则会广播到所有 worker，再在 coordinator 合并，吞吐骤降、内存暴涨。
- 反例（全节点扫描）：
SELECT * FROM orders WHERE status = 'shipped';（假设分布列为user_id） - 正例（路由到单 worker）：
SELECT * FROM orders WHERE user_id = 123 AND status = 'shipped'; - JOIN 场景更敏感：和分布式表
JOIN的另一张表，也必须用分布列对齐，否则降级为repartition join，产生大量网络 shuffle - PHP 中拼接 SQL 时，务必校验
user_id类参数是否始终传入且非空，避免隐式全表扫
reference 表要提前建好，PHP 写入时别当普通表用
create_reference_table('countries') 会把小表完整复制到每个 worker。它适合维度表，但不适合被 PHP 频繁 INSERT/UPDATE ——每次修改都会同步到所有节点，锁粒度大、延迟高。
立即学习“PHP免费学习笔记（深入）”；
- 只读场景安全：PHP 查询
SELECT name FROM countries WHERE code = 'CN'会被下推到任意 worker 执行 - 写入场景危险：PHP 执行
INSERT INTO countries ...会触发全节点事务，失败概率随 worker 数量上升 - 若业务真需动态维护，改用分布式表 + 合理分布键（如用
code分布），而非 reference 表 - PHP 初始化逻辑中检查
pg_get_viewdef('countries')或查citus_tables系统视图确认表类型，比硬编码更可靠
实际部署中最容易被忽略的，是应用层对「分布列」的强依赖——它不像索引可以事后加，而是一旦选错或漏传，查询就退化成单点瓶颈。PHP 代码里每个涉及分布式表的 SQL，都该有一行注释标明所依赖的分布列及其来源（比如来自 session、JWT payload 还是 URL path），否则半年后没人敢动。
