docs(pre2): add VM image test guide

docs/pre2/README.md

@@ -14,6 +14,7 @@ Author: SqlRush <sqlrush@gmail.com>
 | [等待事件参考](reference/wait-events.md) | 活动等待查询、事件含义和名称目录 | 区分可解码名称与目录收录项，不据名称判断功能已验收 |
 | [视图、SQL 函数与命令参考](reference/commands.md) | 状态查询、管理入口及命令使用边界 | 标注权限、版本与受限入口；部署仍按安装手册执行 |
 | [镜像使用说明](vm-image.md) | ARM64 Mac 运行环境、镜像校验与合并、一键启停及示例查询 | 按镜像清单核对版本和运行环境 |
+| [VM 镜像测试手册](vm-test-guide.md) | 在单机镜像上分步体验集群状态、Cache Fusion、全局锁、一致读、并发提交和死锁检测 | 文中 SQL 与示例输出均在本镜像上实测 |
 
 ## 选择版本
 
@@ -23,7 +24,7 @@ Author: SqlRush <sqlrush@gmail.com>
 
 ## 开始前
 
-以下要求适用于按[安装手册](install.md)进行的四节点安装部署。ARM64 单机镜像是另一条评估路径，运行要求和操作方法见[镜像使用说明](vm-image.md)。
+以下要求适用于按[安装手册](install.md)进行的四节点安装部署。ARM64 单机镜像是另一条评估路径，运行要求和操作方法见[镜像使用说明](vm-image.md)，启动后的动手实验见[VM 镜像测试手册](vm-test-guide.md)。
 
 - 使用四个独立 Linux 节点以及经过准备的共享存储；单机四进程不等于本文的四节点环境。
 - 四节点安装部署中设置 `cluster.lms_workers=2`，业务连接池配置为每节点不超过 16 个并发连接；其他值按安装手册的参数表设置。

docs/pre2/sql/cf-baseline.sql

@@ -0,0 +1,16 @@
+-- PGRAC PRE2 v0.135.0 VM 镜像测试手册（docs/pre2/vm-test-guide.md）
+-- 实验 3：在每个节点的会话中执行，记录 Cache Fusion 计数基线（保存为 psql 变量 :cf_*）。
+
+SELECT max(value) FILTER (WHERE key = 'block_request_count')::bigint          AS req,
+       max(value) FILTER (WHERE key = 'install_copy_count')::bigint           AS recv,
+       max(value) FILTER (WHERE key = 'block_ship_bytes_total')::bigint / 8192 AS shipped,
+       max(value) FILTER (WHERE key = 'block_forward_sent_count')::bigint     AS fwd,
+       max(value) FILTER (WHERE key = 'block_from_holder_ship_count')::bigint
+     + max(value) FILTER (WHERE key = 'cf_xheld_read_ship_count')::bigint     AS holder_ship,
+       max(value) FILTER (WHERE key = 'trans_n_to_s_count')::bigint           AS to_s,
+       max(value) FILTER (WHERE key = 'trans_n_to_x_count')::bigint
+     + max(value) FILTER (WHERE key = 'trans_s_to_x_upgrade_count')::bigint   AS to_x,
+       max(value) FILTER (WHERE key = 'trans_x_to_n_downgrade_count')::bigint
+     + max(value) FILTER (WHERE key = 'trans_x_to_s_downgrade_count')::bigint AS x_down
+FROM pg_cluster_state
+WHERE category IN ('gcs', 'pcm') \gset cf_

docs/pre2/sql/cf-delta.sql

@@ -0,0 +1,17 @@
+-- PGRAC PRE2 v0.135.0 VM 镜像测试手册（docs/pre2/vm-test-guide.md）
+-- 实验 3：在执行过 cf-baseline.sql 的同一会话中执行，显示自基线以来的增量。
+
+SELECT current_setting('cluster.node_id') AS node,
+       max(value) FILTER (WHERE key = 'block_request_count')::bigint - :cf_req              AS req,
+       max(value) FILTER (WHERE key = 'install_copy_count')::bigint - :cf_recv              AS recv,
+       max(value) FILTER (WHERE key = 'block_ship_bytes_total')::bigint / 8192 - :cf_shipped AS shipped,
+       max(value) FILTER (WHERE key = 'block_forward_sent_count')::bigint - :cf_fwd         AS fwd,
+       max(value) FILTER (WHERE key = 'block_from_holder_ship_count')::bigint
+     + max(value) FILTER (WHERE key = 'cf_xheld_read_ship_count')::bigint - :cf_holder_ship AS holder_ship,
+       max(value) FILTER (WHERE key = 'trans_n_to_s_count')::bigint - :cf_to_s             AS to_s,
+       max(value) FILTER (WHERE key = 'trans_n_to_x_count')::bigint
+     + max(value) FILTER (WHERE key = 'trans_s_to_x_upgrade_count')::bigint - :cf_to_x     AS to_x,
+       max(value) FILTER (WHERE key = 'trans_x_to_n_downgrade_count')::bigint
+     + max(value) FILTER (WHERE key = 'trans_x_to_s_downgrade_count')::bigint - :cf_x_down AS x_down
+FROM pg_cluster_state
+WHERE category IN ('gcs', 'pcm');

docs/pre2/sql/cluster-status.sql

@@ -0,0 +1,31 @@
+-- PGRAC PRE2 v0.135.0 VM 镜像测试手册（docs/pre2/vm-test-guide.md）
+-- 实验 1 集群状态检查：在任一节点执行（pgnode 0，然后 \i ~/cluster-status.sql）。
+
+\echo '== 成员状态'
+SELECT n.node_id, n.is_self, m.state, m.admitted_epoch, m.removed
+FROM pg_cluster_nodes AS n
+LEFT JOIN pg_cluster_membership AS m USING (node_id)
+ORDER BY n.node_id;
+
+\echo '== quorum'
+SELECT in_quorum, quorum_size, disks_ok, disks_total, collision_state
+FROM pg_cluster_quorum_state;
+
+\echo '== 实例间心跳'
+SELECT node_id, state, heartbeat_send_count, heartbeat_recv_count
+FROM pg_cluster_cssd_peers
+ORDER BY node_id;
+
+\echo '== 互联连接'
+SELECT node_id, state, heartbeat_recv_count, bytes_recv > 0 AS has_traffic
+FROM pg_cluster_ic_peers
+WHERE node_id <> current_setting('cluster.node_id')::int
+ORDER BY node_id;
+
+\echo '== 集群后台进程'
+SELECT backend_type, count(*) AS processes
+FROM pg_stat_activity
+WHERE backend_type IN ('lmon', 'lms', 'lms worker', 'lmd', 'lck', 'cssd', 'qvotec',
+                       'diag', 'cluster stats', 'sinval broadcaster', 'undo cleaner')
+GROUP BY backend_type
+ORDER BY backend_type;

docs/pre2/sql/lab-setup.sql

@@ -0,0 +1,33 @@
+-- PGRAC PRE2 v0.135.0 VM 镜像测试手册（docs/pre2/vm-test-guide.md）
+-- 7.0 准备实验数据：在节点 0 上执行一次（pgnode 0，然后 \i ~/lab-setup.sql）。
+
+CREATE SCHEMA lab;
+
+CREATE TABLE lab.accounts (
+    id      integer PRIMARY KEY,
+    balance bigint  NOT NULL
+);
+INSERT INTO lab.accounts (id, balance)
+SELECT g, 1000 FROM generate_series(1, 10000) AS g;
+
+CREATE TABLE lab.hot (
+    id integer PRIMARY KEY,
+    v  integer NOT NULL
+);
+INSERT INTO lab.hot SELECT g, 0 FROM generate_series(1, 20) AS g;
+
+CREATE TABLE lab.lock_demo (
+    id integer PRIMARY KEY,
+    v  integer NOT NULL
+);
+INSERT INTO lab.lock_demo VALUES (1, 0), (2, 0);
+
+CREATE TABLE lab.tlock_demo (
+    id integer PRIMARY KEY
+);
+INSERT INTO lab.tlock_demo VALUES (1);
+
+ANALYZE lab.accounts;
+ANALYZE lab.hot;
+ANALYZE lab.lock_demo;
+ANALYZE lab.tlock_demo;

docs/pre2/sql/lab-update.sql

@@ -0,0 +1,4 @@
+\set id random(1, 10000)
+BEGIN;
+UPDATE lab.accounts SET balance = balance + 1 WHERE id = :id;
+COMMIT;

docs/pre2/vm-image.md

@@ -6,6 +6,8 @@ Author: SqlRush <sqlrush@gmail.com>
 
 镜像的公开启动、示例、测速和停止工具统一位于 [`scripts/deploy/pre2/appliance/`](../../scripts/deploy/pre2/appliance/)，全部面向这一台 VM 内的四个数据库实例。交付包根目录已放好这些入口脚本。
 
+启动镜像后，可按 [VM 镜像测试手册](vm-test-guide.md) 用分步 SQL 体验 Cache Fusion、全局锁、一致读和多节点并发提交等集群功能。
+
 ## Mac 最低配置
 
 | 项目 | 本镜像要求 |