From 9c688cd9e43430b4417d73abef52a084d63c5bbc Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:56:04 +0800 Subject: [PATCH 1/4] docs(en): add Read-Write Separation Cluster to nav.adoc --- EN/modules/ROOT/nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index a2026117..fb505ca1 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -6,6 +6,7 @@ * Deploy ** xref:master/installation_guide.adoc[Installation] ** xref:master/cluster_setup.adoc[Cluster] +** xref:master/read_write_separation_cluster.adoc[Read-Write Separation Cluster] * Oracle Compatibility ** xref:master/oracle_compatibility/compat_case_conversion.adoc[Case conversion] ** xref:master/oracle_compatibility/compat_like_operator.adoc[LIKE operator] From 67b60c6cd1b2b484eca6fe6483acdee6a9103118 Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:58:37 +0800 Subject: [PATCH 2/4] docs(cn): add Read-Write Separation Cluster to nav.adoc --- CN/modules/ROOT/nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index 66bc54e6..56cd6678 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -6,6 +6,7 @@ * 安装部署 ** xref:master/installation_guide.adoc[安装指南] ** xref:master/cluster_setup.adoc[集群搭建] +** xref:master/read_write_separation_cluster.adoc[读写分离集群] * Oracle兼容功能 ** xref:master/oracle_compatibility/compat_case_conversion.adoc[大小写转换] ** xref:master/oracle_compatibility/compat_like_operator.adoc[LIKE操作符] From 5139888db12bc5941a97ce8119394431cee4ad94 Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 21:59:41 +0800 Subject: [PATCH 3/4] docs(en): add read-write separation cluster guide --- .../master/read_write_separation_cluster.adoc | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 EN/modules/ROOT/pages/master/read_write_separation_cluster.adoc diff --git a/EN/modules/ROOT/pages/master/read_write_separation_cluster.adoc b/EN/modules/ROOT/pages/master/read_write_separation_cluster.adoc new file mode 100644 index 00000000..0539139c --- /dev/null +++ b/EN/modules/ROOT/pages/master/read_write_separation_cluster.adoc @@ -0,0 +1,142 @@ += Read-Write Separation Cluster + +== Overview + +In production environments with heavy read workloads, routing all queries to a single primary node can create CPU and I/O bottlenecks. A read-write separation cluster pairs an IvorySQL streaming replication topology (one primary node and one or more standby nodes) with a database middleware proxy that inspects incoming SQL requests, sends write transactions to the primary node, and distributes read-only `SELECT` queries across standby nodes. + +**Pgpool-II** is a widely used open-source middleware for PostgreSQL and IvorySQL that provides connection pooling, streaming-replication awareness, automatic load balancing, and health checking without requiring application-level sharding logic. + +* **Write routing**: `INSERT`, `UPDATE`, `DELETE`, DDL statements, and write transactions are routed to the primary node. +* **Read load balancing**: Read-only `SELECT` statements outside write transactions are distributed across healthy nodes according to configured `backend_weight` values. +* **Compatibility modes**: IvorySQL exposes PostgreSQL mode (default port `5432`) and Oracle-compatible mode (default port `1521`). Configure `Pgpool-II` backend ports consistently for the compatibility mode used by your applications. + +For setting up the underlying IvorySQL primary and standby nodes, see xref:master/cluster_setup.adoc[Cluster Setup]. + +== Deployment Steps + +=== Prerequisites + +1. Deploy a working IvorySQL streaming replication cluster (at least one primary node and one standby node). Refer to xref:master/cluster_setup.adoc[Cluster Setup] for primary/standby initialization. +2. Verify replication is active on the primary node: ++ +[source,sql] +---- +SELECT client_addr, state, sync_state FROM pg_stat_replication; +---- +3. Ensure network connectivity and `pg_hba.conf` rules on all IvorySQL nodes allow connections from the `Pgpool-II` host. + +=== Installing Pgpool-II + +Install `Pgpool-II` on the middleware host (or a dedicated proxy node) using your system package manager or from source: + +[source,bash] +---- +# Example on RHEL / Rocky Linux / CentOS +sudo dnf install -y pgpool-II + +# Example on Debian / Ubuntu +sudo apt-get update && sudo apt-get install -y pgpool2 +---- + +=== Configuring Backend Nodes and Load Balancing + +Edit `pgpool.conf` (typically under `/etc/pgpool-II/pgpool.conf` or `/usr/local/etc/pgpool.conf`) to define the IvorySQL primary and standby backends, streaming replication checks, and load balancing: + +[source,ini] +---- +# Listen settings +listen_addresses = '*' +port = 9999 + +# Backend mode +backend_clustering_mode = 'streaming_replication' + +# Primary node (node 0) +backend_hostname0 = '192.168.1.10' +backend_port0 = 5432 +backend_weight0 = 0 +backend_flag0 = 'ALLOW_TO_FAILOVER' + +# Standby node (node 1) +backend_hostname1 = '192.168.1.11' +backend_port1 = 5432 +backend_weight1 = 1 +backend_flag1 = 'ALLOW_TO_FAILOVER' + +# Enable read-write separation / load balancing +load_balance_mode = on + +# Streaming replication delay and health checks +sr_check_period = 10 +sr_check_user = 'ivorysql' +sr_check_database = 'postgres' + +health_check_period = 10 +health_check_user = 'ivorysql' +health_check_database = 'postgres' +---- + +[NOTE] +==== +Setting `backend_weight0 = 0` and `backend_weight1 = 1` routes read-only `SELECT` queries exclusively to the standby node while keeping all writes on the primary node. To share read traffic between primary and standby, set a positive weight on both nodes (for example, `backend_weight0 = 0.3` and `backend_weight1 = 0.7`). + +If your applications connect in IvorySQL Oracle-compatible mode, set `backend_port0` and `backend_port1` to `1521` (the IvorySQL Oracle listener port) rather than `5432`. +==== + +=== Configuring Authentication and Starting Pgpool-II + +1. Configure `pool_hba.conf` on the `Pgpool-II` host to allow client connections (set `enable_pool_hba = on` in `pgpool.conf`): ++ +[source,text] +---- +host all all 0.0.0.0/0 scram-sha-256 +---- + +2. Register database user credentials in `pool_passwd` using `pg_enc` so `Pgpool-II` can authenticate clients against IvorySQL: ++ +[source,bash] +---- +pg_enc -m -f /etc/pgpool-II/pgpool.conf -u ivorysql -p +---- + +3. Start and enable `Pgpool-II`: ++ +[source,bash] +---- +sudo systemctl enable --now pgpool +---- + +== Usage Configuration + +=== Verifying Node Roles and Routing + +Connect through the `Pgpool-II` port (`9999`) using `psql` and inspect node status: + +[source,bash] +---- +psql -h -p 9999 -U ivorysql -d postgres -c "SHOW pool_nodes;" +---- + +Confirm that node `0` reports `role = primary` and node `1` reports `role = standby`, both with `status = up`. + +You can also verify routing behavior with read and write queries: + +[source,sql] +---- +-- Read query: routed to standby (when backend_weight0 = 0) +SELECT inet_server_addr(), pg_is_in_recovery(); + +-- Write query: routed to primary +CREATE TABLE rw_test (id int, created_at timestamp DEFAULT now()); +INSERT INTO rw_test (id) VALUES (1); +---- + +=== Tuning Read-Write Routing Behavior + +Configure the following parameters in `pgpool.conf` based on your application's consistency requirements: + +* `disable_load_balance_on_write`: Controls how `SELECT` queries are routed after a write inside the same transaction or session. + - `transaction` (default): After a write, subsequent reads in the same transaction go to the primary; reads in a new transaction can return to standby nodes. + - `trans_transaction` / `dml_adaptive` / `always`: Keeps reads on the primary longer when strict read-your-own-writes consistency is needed. +* `delay_threshold`: Maximum WAL replay lag (in bytes) permitted on a standby before `Pgpool-II` temporarily stops routing read queries to that standby and falls back to the primary. +* `write_function_list` / `read_only_function_list`: Classify stored functions or procedures that modify data so `Pgpool-II` routes `SELECT my_write_func()` to the primary node rather than a standby. From 8c145ab2d1a4553eb4b8ffa8a9dc852c3dfa17bc Mon Sep 17 00:00:00 2001 From: taomaolou Date: Tue, 17 Nov 2026 22:01:04 +0800 Subject: [PATCH 4/4] docs(cn): add read-write separation cluster guide --- .../master/read_write_separation_cluster.adoc | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/read_write_separation_cluster.adoc diff --git a/CN/modules/ROOT/pages/master/read_write_separation_cluster.adoc b/CN/modules/ROOT/pages/master/read_write_separation_cluster.adoc new file mode 100644 index 00000000..a5686f3d --- /dev/null +++ b/CN/modules/ROOT/pages/master/read_write_separation_cluster.adoc @@ -0,0 +1,142 @@ += 读写分离集群 + +== 概述 + +在读多写少的生产业务场景下,将所有查询请求都发送到单一主节点容易引发 CPU 和 I/O 瓶颈。读写分离集群将 IvorySQL 流复制拓扑(一主多从)与数据库中间件代理结合,由代理层自动识别 SQL 请求类型,将写事务路由至主节点,并将只读 `SELECT` 查询分发至备节点执行。 + +**Pgpool-II** 是 PostgreSQL 与 IvorySQL 生态中常用的开源中间件,无需修改应用层分片逻辑即可提供连接池、流复制感知、自动负载均衡与节点健康检查能力。 + +* **写请求路由**:`INSERT`、`UPDATE`、`DELETE`、DDL 语句以及写事务均路由至主节点。 +* **读请求负载均衡**:不在写事务中的只读 `SELECT` 查询,会按配置的 `backend_weight` 权重分发至健康的备节点或主节点。 +* **兼容模式支持**:IvorySQL 提供 PostgreSQL 兼容模式(默认端口 `5432`)和 Oracle 兼容模式(默认端口 `1521`)。请根据业务实际使用的兼容模式统一配置 `Pgpool-II` 的后端端口。 + +关于底层 IvorySQL 主备流复制集群的初始化步骤,请参考 xref:master/cluster_setup.adoc[集群搭建]。 + +== 部署步骤 + +=== 前置条件 + +1. 已部署可正常运行的 IvorySQL 流复制集群(至少包含一个主节点和一个备节点),初始化方式可参考 xref:master/cluster_setup.adoc[集群搭建]。 +2. 在主节点上确认流复制状态正常: ++ +[source,sql] +---- +SELECT client_addr, state, sync_state FROM pg_stat_replication; +---- +3. 确保所有 IvorySQL 节点的防火墙及 `pg_hba.conf` 允许来自 `Pgpool-II` 所在主机的连接。 + +=== 安装 Pgpool-II + +在中间件节点(或独立代理服务器)上通过系统包管理器或源码安装 `Pgpool-II`: + +[source,bash] +---- +# RHEL / Rocky Linux / CentOS 示例 +sudo dnf install -y pgpool-II + +# Debian / Ubuntu 示例 +sudo apt-get update && sudo apt-get install -y pgpool2 +---- + +=== 配置后端节点与负载均衡 + +编辑 `pgpool.conf`(通常位于 `/etc/pgpool-II/pgpool.conf` 或 `/usr/local/etc/pgpool.conf`),配置 IvorySQL 主备节点、流复制检查和负载均衡参数: + +[source,ini] +---- +# 监听地址与端口 +listen_addresses = '*' +port = 9999 + +# 集群模式设为流复制 +backend_clustering_mode = 'streaming_replication' + +# 主节点(节点 0) +backend_hostname0 = '192.168.1.10' +backend_port0 = 5432 +backend_weight0 = 0 +backend_flag0 = 'ALLOW_TO_FAILOVER' + +# 备节点(节点 1) +backend_hostname1 = '192.168.1.11' +backend_port1 = 5432 +backend_weight1 = 1 +backend_flag1 = 'ALLOW_TO_FAILOVER' + +# 开启读写分离 / 负载均衡 +load_balance_mode = on + +# 流复制延迟检查与健康检查 +sr_check_period = 10 +sr_check_user = 'ivorysql' +sr_check_database = 'postgres' + +health_check_period = 10 +health_check_user = 'ivorysql' +health_check_database = 'postgres' +---- + +[NOTE] +==== +将 `backend_weight0` 设为 `0`、`backend_weight1` 设为 `1`,可使只读 `SELECT` 查询全部路由至备节点,主节点专注处理写请求;若希望主节点也分担部分读流量,可为两者设置正权重(例如 `backend_weight0 = 0.3`、`backend_weight1 = 0.7`)。 + +如果应用以 IvorySQL Oracle 兼容模式连接,请将 `backend_port0` 和 `backend_port1` 配置为 `1521`(IvorySQL Oracle 监听端口),而非 `5432`。 +==== + +=== 配置认证并启动服务 + +1. 在 `Pgpool-II` 主机配置 `pool_hba.conf` 允许客户端接入(同时在 `pgpool.conf` 中开启 `enable_pool_hba = on`): ++ +[source,text] +---- +host all all 0.0.0.0/0 scram-sha-256 +---- + +2. 使用 `pg_enc` 将数据库用户凭据写入 `pool_passwd`,以便 `Pgpool-II` 完成客户端认证: ++ +[source,bash] +---- +pg_enc -m -f /etc/pgpool-II/pgpool.conf -u ivorysql -p +---- + +3. 启动并设置 `Pgpool-II` 开机自启: ++ +[source,bash] +---- +sudo systemctl enable --now pgpool +---- + +== 使用配置 + +=== 验证节点角色与路由效果 + +通过 `Pgpool-II` 端口(`9999`)使用 `psql` 连接并查看集群节点状态: + +[source,bash] +---- +psql -h -p 9999 -U ivorysql -d postgres -c "SHOW pool_nodes;" +---- + +确认节点 `0` 的 `role` 为 `primary`、节点 `1` 的 `role` 为 `standby`,且两者 `status` 均为 `up`。 + +随后可通过读写测试验证分流是否生效: + +[source,sql] +---- +-- 读查询:在 backend_weight0 = 0 时将路由到备节点(pg_is_in_recovery() 返回 t) +SELECT inet_server_addr(), pg_is_in_recovery(); + +-- 写操作:自动路由到主节点 +CREATE TABLE rw_test (id int, created_at timestamp DEFAULT now()); +INSERT INTO rw_test (id) VALUES (1); +---- + +=== 读写路由关键参数调优 + +根据业务对数据一致性的要求,可在 `pgpool.conf` 中调整以下参数: + +* `disable_load_balance_on_write`:控制同一事务或会话中发生写操作后,后续 `SELECT` 的路由策略。 + - `transaction`(默认值):写操作后,同一事务内的后续读请求路由到主节点;新事务中的读请求可恢复分发至备节点。 + - `trans_transaction` / `dml_adaptive` / `always`:当业务需要更严格的“写后立即可读”一致性时,可延长读请求固定在主节点的时间范围。 +* `delay_threshold`:备节点允许的最大 WAL 回放延迟(字节数)。超过该阈值时,`Pgpool-II` 会暂停向该备节点分发读流量并回退至主节点。 +* `write_function_list` / `read_only_function_list`:显式标记会修改数据的自定义函数或存储过程,确保 `Pgpool-II` 将 `SELECT my_write_func()` 正确路由到主节点执行。