diff --git a/PGRAC_VERSION b/PGRAC_VERSION index 6834ad9434..156fe0ca7d 100644 --- a/PGRAC_VERSION +++ b/PGRAC_VERSION @@ -1 +1 @@ -0.130.0-mvp.1 +0.130.0 diff --git a/README.md b/README.md index 49764fd432..f3f9e35f86 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,14 @@ PostgreSQL has never had a shared-disk, multi-active cluster (its HA is shared-nothing replication). pgrac brings the Oracle RAC model — many nodes, one shared database, Cache Fusion / SCN / GES — to PostgreSQL 16.13. -> **MVP 1: [v0.130.0-mvp.1](docs/release-notes/v0.130.0-mvp.1.md).** +> **First stable MVP: [v0.130.0](docs/release-notes/v0.130.0.md).** > -> The first frozen MVP has passed four-node point-update workloads with 8 and -> 16 clients per node, complete million-row data comparisons, health and -> outstanding-work checks, coordinated normal shutdown, same-data normal -> restart, and another workload with all checks repeated after restart. +> The CI-qualified MVP now has four valid four-node point-update samples with +> 32 clients per node, complete million-row data comparisons, health and +> outstanding-work checks, and normal shutdown. It also retains the earlier +> 8/16-client, soak, block-transfer and same-data normal-restart acceptance. > -> **Evaluation only, not production certified.** This acceptance does not +> **Stable within the tested MVP scope, not production certified.** This does not > certify crash recovery, failover, rolling upgrades, all SQL features or > performance targets. See the release notes for the exact scope and limitations. > @@ -63,10 +63,11 @@ More diagrams and deep-dives at **[pgrac.dev](https://pgrac.dev)**. ## Documentation -Start with the version-pinned [MVP 1 manual](docs/mvp/v0.130.0-mvp.1/README.md): -Linux four-node deployment and shared-storage prerequisites, all added -parameters, all system-view fields, and core capabilities. It distinguishes -the validated evaluation scope from unqualified multi-host/failover deployment. +Start with the [stable MVP guide](docs/mvp/v0.130.0/README.md) and +[single-host Linux Quick Start](docs/mvp/v0.130.0/quickstart-linux-single-host.md). +The guide links the parameter, system-view and capability references, and +distinguishes tested single-host operation from unqualified multi-host/failover +deployment. The historical prerelease manual remains available unchanged. User-facing manual: @@ -85,19 +86,19 @@ from the upstream tree. ## Quick start -For the frozen MVP, first read the -[deployment guide and known build limits](docs/mvp/v0.130.0-mvp.1/01-linux-four-node-deployment.md). -The tag is an evaluation source snapshot, not a turnkey production installer. +For the stable MVP, follow the +[single-host Linux guide](docs/mvp/v0.130.0/quickstart-linux-single-host.md). +This is a source release, not a turnkey production installer. ```bash -git clone --branch v0.130.0-mvp.1 --single-branch \ +git clone --branch v0.130.0 --single-branch \ https://github.com/sqlrush/pgrac.git pgrac-mvp1 cd pgrac-mvp1 git rev-parse HEAD cat PGRAC_VERSION ``` -Follow the pinned guide for compilation, initialization and the explicit +Follow the guide for compilation, initialization and the explicit four-host deployment-validation boundary. Do not independently initialize four databases or share one PGDATA among four postmasters. diff --git a/docs/mvp/v0.130.0/README.md b/docs/mvp/v0.130.0/README.md new file mode 100644 index 0000000000..df1d3696ad --- /dev/null +++ b/docs/mvp/v0.130.0/README.md @@ -0,0 +1,25 @@ +# PGRAC 首个 MVP 稳定版使用入口 + +Author: SqlRush + +版本：`v0.130.0`；PostgreSQL 基线：16.13；发布日期：2026-09-17。 + +“稳定”限定于已通过的 MVP 验收范围：CI、四实例正确性 PRE、正常关机及原数据正常启动。不代表生产 HA、崩溃恢复、四台独立主机共享 LUN 或性能目标已经认证。完整结果与限制见[发布说明](../../release-notes/v0.130.0.md)。 + +## 从这里开始 + +按[单机四实例 Quick Start（Linux）](quickstart-linux-single-host.md)拉取稳定标签、编译、初始化及连接。使用本机文件系统上的四个独立 PGDATA，共享业务数据；不是四台主机，不需要容器或 GFS2。 + +## 参考手册 + +下面保留的是首个预发布版的详细接口与部署参考，没有将旧标签改写成稳定版。新版本的获取命令、CI 状态、验收范围以本目录及新发布说明为准；旧文档中的固定源码提交、旧构建限制和验收声明仅属于旧版。 + +| 内容 | 文档 | +|---|---| +| 共享存储准备、检查与四机边界 | [存储准备](../v0.130.0-mvp.1/storage-preparation.md)、[四节点部署参考](../v0.130.0-mvp.1/01-linux-four-node-deployment.md) | +| 参数、默认值与配置组合 | [参数手册](../v0.130.0-mvp.1/02-parameters.md) | +| 系统视图与字段 | [系统视图](../v0.130.0-mvp.1/03-system-views.md) | +| 核心能力 | [功能与运行机制](../v0.130.0-mvp.1/04-core-capabilities.md) | +| 当前源码安装选项 | [安装指南](../../user-guide/install.md) | + +本次版本发布只更新版本资料与用户文档，不再修改已通过最新 PRE 的内核，也不重建已保留的数据。发布为源码版本，不提供生产认证二进制。安装后保留标签、完整 commit、编译参数、配置与二进制 SHA-256；不要仅用旧的 `pgrac_version()` 字符串识别版本。 diff --git a/docs/mvp/v0.130.0/quickstart-linux-single-host.md b/docs/mvp/v0.130.0/quickstart-linux-single-host.md new file mode 100644 index 0000000000..d32c6f7819 --- /dev/null +++ b/docs/mvp/v0.130.0/quickstart-linux-single-host.md @@ -0,0 +1,147 @@ +# 单机四实例 Quick Start（Linux，MVP 稳定版） + +Author: SqlRush + +目标：一台 Linux 主机、四个 PGRAC 实例、同一份共享业务数据。版本固定为 `v0.130.0`。这是隔离环境中的源码安装示例，不是四机共享 LUN 或生产 HA 安装器。 + +沿用已演练的 Rocky Linux 9 / Btrfs 单机步骤与初始化示例；本次更新标签和脚本获取路径，不声称重新运行了 Quick Start 演练。稳定版 CI 与 PRE 范围见[发布说明](../../release-notes/v0.130.0.md)。 + +## 1. 准备主机 + +使用有 `sudo` 权限的普通账号，预留充足内存和至少 20 GiB 磁盘空间。在同一个 Bash 终端执行，不要用 root 运行数据库。 + +```bash +bash +set -euo pipefail +test "$(id -u)" -ne 0 +umask 077 + +sudo dnf install -y dnf-plugins-core +sudo dnf config-manager --set-enabled crb +sudo dnf install -y gcc make git pkgconf-pkg-config bison flex \ + perl perl-IPC-Run perl-Test-Simple perl-Time-HiRes \ + readline-devel zlib-devel libicu-devel lz4-devel libzstd-devel \ + util-linux procps-ng tar kmod +test -c /dev/loop-control || sudo modprobe loop +sudo losetup --find + +export PGRAC_QS_ROOT="$(mktemp -d /var/tmp/pgrac-quickstart.XXXXXX)" +findmnt -T "$PGRAC_QS_ROOT" +df -h "$PGRAC_QS_ROOT" +printf '本次安装目录：%s\n' "$PGRAC_QS_ROOT" +``` + +目录必须位于本机磁盘，不能使用 NFS 或主机共享映射目录。本机 ext4/XFS 不涉及跨主机挂载，但既有演练使用 Btrfs。示例仅创建自己的三个投票文件及对应 loop 设备，不格式化现有盘。 + +## 2. 拉取稳定版源码 + +```bash +git clone --depth 1 --branch v0.130.0 --single-branch \ + https://github.com/sqlrush/pgrac.git "$PGRAC_QS_ROOT/source" +git -C "$PGRAC_QS_ROOT/source" describe --exact-match --tags +git -C "$PGRAC_QS_ROOT/source" rev-parse HEAD +test "$(cat "$PGRAC_QS_ROOT/source/PGRAC_VERSION")" = 0.130.0 +``` + +## 3. 编译安装 + +示例继续使用不启用 OpenSSL 的本机构建；SQL 只使用 Unix socket，不开放外部 SQL 端口。这不是稳定版的 OpenSSL 构建限制。 + +```bash +mkdir "$PGRAC_QS_ROOT/build" +cd "$PGRAC_QS_ROOT/build" +../source/configure --prefix="$PGRAC_QS_ROOT/install" \ + --enable-cluster --enable-cassert --enable-debug --enable-tap-tests \ + --with-icu --with-lz4 --with-zstd +make -j4 +make install +make -C src/test/cluster_tap all +make -C src/test/regress pg_regress + +export PATH="$PGRAC_QS_ROOT/install/bin:$PATH" +pg_config --configure +``` + +## 4. 准备初始化示例 + +`run-quad.pl` 来自刚拉取的稳定标签中的文档示例，不是额外下载的未知脚本。目录名保留其首次发布版本；示例字节未修改。 + +```bash +cp "$PGRAC_QS_ROOT/source/docs/mvp/v0.130.0-mvp.1/quickstart-single-host.pl" \ + "$PGRAC_QS_ROOT/run-quad.pl" +printf '%s %s\n' \ + 0e5fe8670349c33485474f4757744507c9939a4149d2adef06a23f538ae9f4c9 \ + "$PGRAC_QS_ROOT/run-quad.pl" | sha256sum -c - + +mkdir "$PGRAC_QS_ROOT/data" "$PGRAC_QS_ROOT/log" +cat > "$PGRAC_QS_ROOT/seed.conf" <<'CONF' +fsync = on +full_page_writes = on +synchronous_commit = on +CONF + +export LC_ALL=C +export PERL5LIB="$PGRAC_QS_ROOT/source/src/test/perl" +export PG_REGRESS="$PGRAC_QS_ROOT/build/src/test/regress/pg_regress" +export PGRAC_DIRECT_IO_PROBE="$PGRAC_QS_ROOT/build/src/test/cluster_tap/pgrac_direct_io_probe" +export top_builddir="$PGRAC_QS_ROOT/build" +export TEMP_CONFIG="$PGRAC_QS_ROOT/seed.conf" +export TESTDATADIR="$PGRAC_QS_ROOT/data" +export TESTLOGDIR="$PGRAC_QS_ROOT/log" +export PG_TEST_NOCLEAN=1 PG_TEST_TIMEOUT_DEFAULT=180 +export PGRAC_STAGE8_HAPPY_PATH_ONLY=1 +unset PGRAC_TEST_TWO_STAGE_VOTING_LOOP +``` + +## 5. 初始化并启动四实例 + +脚本建立一个数据库身份及四个独立 PGDATA，共享业务数据，自动配置端口、互联与投票设备。`postgres` 数据库中的 `quickstart_demo` 表在 seed 阶段创建后克隆。本示例不启用共享系统目录，运行后不要单独建表、改表或执行 `CREATE DATABASE`。 + +```bash +sudo -v +perl "$PGRAC_QS_ROOT/run-quad.pl" > "$PGRAC_QS_ROOT/launcher.out" 2>&1 & +export PGRAC_QS_PID=$! + +for attempt in $(seq 1 360); do + test ! -f "$PGRAC_QS_ROOT/READY" || break + if ! kill -0 "$PGRAC_QS_PID" 2>/dev/null; then + tail -n 60 "$PGRAC_QS_ROOT/launcher.out" + tail -n 60 "$PGRAC_QS_ROOT/log/regress_log_run-quad" + exit 1 + fi + sleep 1 +done +test -f "$PGRAC_QS_ROOT/READY" +source "$PGRAC_QS_ROOT/connect.env" +``` + +`READY` 表示四实例已依次更新同一行并都读到 `value=4`。连接端口和四份 PGDATA 路径见 `connect.env`。 + +## 6. 验证共享读写 + +```bash +for port in "$PGPORT_0" "$PGPORT_1" "$PGPORT_2" "$PGPORT_3"; do + psql -X -v ON_ERROR_STOP=1 -p "$port" -c 'TABLE quickstart_demo' +done + +psql -X -v ON_ERROR_STOP=1 -p "$PGPORT_3" \ + -c 'UPDATE quickstart_demo SET value=value+10 WHERE id=1 RETURNING *' +psql -X -v ON_ERROR_STOP=1 -p "$PGPORT_0" -c 'TABLE quickstart_demo' +``` + +第一次四次查询均应为 `id=1, value=4`；最后 node0 应读到 `value=14`。 + +## 7. 全体正常关机 + +```bash +sudo -v +touch "$PGRAC_QS_ROOT/STOP" +wait "$PGRAC_QS_PID" +test -f "$PGRAC_QS_ROOT/STOPPED" + +for datadir in "$PGDATA_0" "$PGDATA_1" "$PGDATA_2" "$PGDATA_3"; do + pg_controldata "$datadir" | grep 'Database cluster state' +done +``` + +预期四行均为 `shut down`。脚本完成正常关机验证后仅释放自己创建的 loop 设备，不删除数据。不要强杀、执行 `losetup -D` 或在原目录重复初始化。该脚本只用于新建示例，不是原数据重启工具；失败时保留目录与日志，不能把失败现场当作干净关机数据。 diff --git a/docs/release-notes/README.md b/docs/release-notes/README.md index ce68e32f02..373702464b 100644 --- a/docs/release-notes/README.md +++ b/docs/release-notes/README.md @@ -4,10 +4,14 @@ Author: SqlRush ## Current release -[v0.130.0-mvp.1 — MVP 1](v0.130.0-mvp.1.md) is the first MVP baseline. -It is an evaluation prerelease, not a production or general-availability release. -Its release notes explicitly retain the outstanding CI limitation; that -snapshot-specific publication does not waive stable-release qualification. +[v0.130.0 — first stable MVP](v0.130.0.md) is the current release. It combines +the MVP release CI gate with four valid four-node correctness samples on the +CI-fixed kernel. Stable means the documented MVP scope, not production HA, +independent-host shared-storage certification or a performance guarantee. + +[v0.130.0-mvp.1](v0.130.0-mvp.1.md) remains the immutable first evaluation +snapshot. Its original CI limitation is retained in its historical notes; +it is not retroactively qualified by this release. ## Identifying a release @@ -29,6 +33,7 @@ Versions use `MAJOR.MINOR.PATCH`, optionally followed by a prerelease label: | Label | Meaning | |---|---| | `v0.130.0-mvp.1` | First frozen MVP baseline | +| `v0.130.0` | First stable release within the documented MVP scope | | `-mvp.N`, `-alpha.N`, `-beta.N` | Numbered evaluation prereleases | | `-rc.N` | Release candidates with their own published qualification scope | | No suffix | Stable release; only after its acceptance criteria pass | @@ -36,8 +41,8 @@ Versions use `MAJOR.MINOR.PATCH`, optionally followed by a prerelease label: Existing historical tags remain unchanged. New feature milestones increment the minor version; maintenance releases increment the patch version. Revisions within one prerelease line increment its numbered suffix. The `1.0.0` name is -reserved for the first formally qualified stable release; MVP acceptance does -not grant that status. +reserved for the first formally qualified full-product stable release; +qualification of this narrower MVP scope does not grant that status. `main` is the integration branch. Feature and fix branches start from an exact commit; releases are selected commits, not moving branch names. Published tags @@ -47,8 +52,8 @@ the superseded release's evidence and limitations. ## Selecting a version ```sh -git fetch origin tag v0.130.0-mvp.1 -git switch --detach v0.130.0-mvp.1 +git fetch origin tag v0.130.0 +git switch --detach v0.130.0 git rev-parse HEAD cat PGRAC_VERSION ``` diff --git a/docs/release-notes/v0.130.0.md b/docs/release-notes/v0.130.0.md new file mode 100644 index 0000000000..c1f9291ba9 --- /dev/null +++ b/docs/release-notes/v0.130.0.md @@ -0,0 +1,93 @@ +# PGRAC v0.130.0 — first stable MVP + +Author: SqlRush + +Release date: 2026-09-17. PostgreSQL base: 16.13. Distribution: source. + +This is the first **stable MVP** release, succeeding `v0.130.0-mvp.1`. +Stable applies to the tested scope below. It is not a production-HA or +general-purpose PostgreSQL compatibility certification. + +## What is qualified + +- Four active instances sharing the same business data on one Linux host. +- Four-node point `UPDATE` + `COMMIT`, with 32 clients per node and four valid + correctness samples. All nodes committed transactions in every sample. +- Zero unexpected SQL/server errors, complete ordered comparisons of all + 1,000,000 rows from every node, health and outstanding-work checks. +- Normal startup on retained cleanly stopped data, full-row verification before + work, and coordinated normal shutdown with all four control files shut down. +- Earlier MVP acceptance also covers 8/16 clients per node, soak including + commit/rollback negative cases, six block-transfer microbenchmark phases, + focused integration tests, and normal restart followed by further business. + Those earlier results retain their original candidate identities; they are + not described as new executions on this release commit. + +The final PRE correctness run used kernel commit +[`f6e213574952f81ad652cdeb76191b3a534f2fe4`](https://github.com/sqlrush/pgrac/commit/f6e213574952f81ad652cdeb76191b3a534f2fe4). +The release changes only version metadata and user documentation from that +commit; kernel, build and test-runner sources are unchanged. + +| Final PRE sample | Committed measurement transactions | Cluster TPS | +|---|---:|---:| +| 1 | 18,726 | 535.03 | +| 2 | 19,143 | 546.95 | +| 3 | 19,960 | 570.28 | +| 4 | 20,234 | 578.11 | + +Each sample used a 5-second warmup and 35-second measurement. Median TPS was +**558.615**, peak **578.11**. These are laboratory observations, not release +performance thresholds, a saturation result or an Oracle comparison. +Clients completed naturally; raw late-completion exit codes were retained and +accepted only after the natural-completion and all correctness checks passed. + +The tested assertion-enabled PostgreSQL binary SHA-256 was +`daf9edf47fdb87aa6831e7ef972e8e47afa8fcc39858acf43a35704da6d56824`. +This identifies the tested binary, not every locally compiled installation. + +## CI and packaging + +The release requires successful **Fast CI and MVP Nightly CI on the exact tagged +commit**, with every required job executed. This includes Linux cluster-enabled +and cluster-disabled builds/tests, PostgreSQL regression, selected MVP cluster +tests, macOS build/test coverage, formatting and static/security checks. +The GitHub Release carries the exact-commit CI evidence. + +The prerelease formatting and OpenSSL-linking CI debt is resolved. Historical +tests outside the current MVP scope remain present with their failure records; +they have not been renamed to PASS or claimed as qualified functionality. See +the [MVP CI policy](../../scripts/ci/README.md). + +This release provides source, not a signed, portable or production-certified +binary package. Keep the Git commit, build flags, configuration and installed +binary hash with your deployment. The legacy compiled `pgrac_version()` string +is not the release identifier; use `PGRAC_VERSION` and the immutable Git tag. + +## Limits and upgrade guidance + +- Four independent hosts concurrently mounting one shared LUN, GFS2 and + hardware/storage failure behavior are **not certified** by this release. +- Crash/forced-kill recovery, automatic failover, external-fencing deployment, + backup restore, rolling/mixed-version upgrades and full SQL/2PC compatibility + are outside the accepted MVP scope. +- A clean normal restart is not evidence of crash recovery. Do not use an + abnormally stopped data directory as if it were cleanly stopped. +- Normal restart of the retained test dataset passed. This is not a general + cross-version migration or downgrade guarantee. Preserve existing data and + use a separate installation/environment when evaluating a new version. +- Performance optimization and broader production certification remain future + work; neither is implied by the stable MVP label. + +## Get started + +```sh +git clone --branch v0.130.0 --single-branch \ + https://github.com/sqlrush/pgrac.git pgrac-mvp1 +cd pgrac-mvp1 +git rev-parse HEAD +cat PGRAC_VERSION +``` + +Follow the [stable MVP guide](../mvp/v0.130.0/README.md) and +[Linux single-host four-instance Quick Start](../mvp/v0.130.0/quickstart-linux-single-host.md). +The [previous prerelease notes](v0.130.0-mvp.1.md) and tag remain unchanged.