Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

docs(checkpointer): clarify v5 migration contract

xf gongbdf88a08855b
diff --git a/cubeloop/checkpointer/postgres/README.md b/cubeloop/checkpointer/postgres/README.md
index edd7a2c..0318ab7 100644
--- a/cubeloop/checkpointer/postgres/README.md
+++ b/cubeloop/checkpointer/postgres/README.md
@@ -108,7 +108,7 @@ def upgrade():
# cubepi_schema_version, and cubepi_messages (keep ALL columns;
# ensure cubepi_messages has postgresql_partition_by="HASH (thread_id)") ...
op.execute(create_message_partitions_op()) # the 64 child partitions
- op.execute(write_schema_version_op()) # record EXPECTED_SCHEMA_VERSION
+ op.execute(write_schema_version_op()) # record historical schema v5
```
> Do not hand-trim the `cubepi_messages` columns. The checkpointer writes
@@ -131,7 +131,7 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
def upgrade():
op.execute(add_pending_request_column_op()) # ADD COLUMN IF NOT EXISTS
- op.execute(write_schema_version_op()) # bump to EXPECTED_SCHEMA_VERSION
+ op.execute(write_schema_version_op()) # record historical schema v5
def downgrade():
op.execute("ALTER TABLE cubepi_threads DROP COLUMN IF EXISTS pending_request")
diff --git a/website/docs/guides/checkpointing/mysql.md b/website/docs/guides/checkpointing/mysql.md
index 40d602e..cc64412 100644
--- a/website/docs/guides/checkpointing/mysql.md
+++ b/website/docs/guides/checkpointing/mysql.md
@@ -120,10 +120,9 @@ def upgrade():
op.execute(stmt)
```
-`write_schema_version_op()` is idempotent: it deletes any rows from a
-prior CubeLoop version and inserts the current one. When CubeLoop later
-bumps `EXPECTED_SCHEMA_VERSION`, generate a new revision and run it
-again.
+`write_schema_version_op()` is the immutable historical v5 writer. It is
+idempotent, deleting other version rows before inserting 5. A future schema
+version must ship and use a new version-specific writer; do not reuse this one.
## Data model
diff --git a/website/docs/guides/checkpointing/postgres.md b/website/docs/guides/checkpointing/postgres.md
index 1500135..c691f64 100644
--- a/website/docs/guides/checkpointing/postgres.md
+++ b/website/docs/guides/checkpointing/postgres.md
@@ -106,16 +106,13 @@ def upgrade():
op.create_table(...) # auto-generated from cubeloop_metadata
op.execute(create_message_partitions_op()) # 64 hash partitions of cubepi_messages
op.execute(create_runs_partitions_op()) # 64 hash partitions of cubepi_runs
- op.execute(write_schema_version_op()) # records EXPECTED_SCHEMA_VERSION
+ op.execute(write_schema_version_op()) # records historical schema v5
```
Both helpers return a SQL string — you pass them to `op.execute(...)`.
-`write_schema_version_op()` is idempotent: it deletes any rows from a
-prior CubeLoop version and inserts the current one.
-
-When CubeLoop later upgrades and bumps `EXPECTED_SCHEMA_VERSION`, you
-generate a new revision and call `op.execute(write_schema_version_op())`
-again.
+`write_schema_version_op()` is the immutable historical v5 writer. It is
+idempotent, deleting other version rows before inserting 5. A future schema
+version must ship and use a new version-specific writer; do not reuse this one.
## Data model
diff --git a/website/docs/migration/from-cubepi.md b/website/docs/migration/from-cubepi.md
index c075245..91e929c 100644
--- a/website/docs/migration/from-cubepi.md
+++ b/website/docs/migration/from-cubepi.md
@@ -38,8 +38,9 @@ Historical host Alembic revisions may import helpers from
`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their original
v1–v5 SQL. Do not add a rename revision.
-Upgrade directly from 0.13.6 or earlier to 0.14.1 or later. No database
-migration is required.
+An existing schema-v5 database needs no rename migration. If the database is on
+an earlier schema version, run its normal host Alembic migrations through v5
+before opening the 0.14.1 checkpointer.
## Tracing
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md
index a975ede..e13e551 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/mysql.md
@@ -102,7 +102,9 @@ def upgrade():
op.execute(stmt)
```
-`write_schema_version_op()` 是幂等的:它会删除旧 CubeLoop 版本的记录行并插入当前版本。当 CubeLoop 之后更新 `EXPECTED_SCHEMA_VERSION` 时,生成新的 revision 并再次运行即可。
+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入 5,
+可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用这个
+helper。
## 数据模型
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md
index 34c8a1d..6deea7c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/checkpointing/postgres.md
@@ -90,15 +90,13 @@ def upgrade():
op.create_table(...) # 从 cubeloop_metadata 自动生成
op.execute(create_message_partitions_op()) # cubepi_messages 的 64 个哈希分区
op.execute(create_runs_partitions_op()) # cubepi_runs 的 64 个哈希分区
- op.execute(write_schema_version_op()) # 记录 EXPECTED_SCHEMA_VERSION
+ op.execute(write_schema_version_op()) # 记录历史 schema v5
```
两个辅助函数都返回 SQL 字符串——你需要传入 `op.execute(...)`。
-`write_schema_version_op()` 是幂等的:它会删除之前 CubeLoop 版本的所有行,
-然后插入当前版本。
-
-当 CubeLoop 后续升级并提升了 `EXPECTED_SCHEMA_VERSION` 时,生成一个新的
-revision,再次调用 `op.execute(write_schema_version_op())`。
+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入
+5,可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用
+这个 helper。
## 数据模型
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md
index 11a73e7..ac28432 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/migration/from-cubepi.md
@@ -34,7 +34,8 @@ Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*
历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`
导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。
-从 0.13.6 或更早版本直接升级到 0.14.1 或更高版本,不需要数据库迁移。
+已有 schema v5 数据库不需要表名迁移。如果数据库仍是更早的 schema version,
+请先通过宿主 Alembic migration 正常升级到 v5,再启动 0.14.1 checkpointer。
## Tracing
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md
index a975ede..e13e551 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/mysql.md
@@ -102,7 +102,9 @@ def upgrade():
op.execute(stmt)
```
-`write_schema_version_op()` 是幂等的:它会删除旧 CubeLoop 版本的记录行并插入当前版本。当 CubeLoop 之后更新 `EXPECTED_SCHEMA_VERSION` 时,生成新的 revision 并再次运行即可。
+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入 5,
+可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用这个
+helper。
## 数据模型
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md
index 34c8a1d..6deea7c 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/guides/checkpointing/postgres.md
@@ -90,15 +90,13 @@ def upgrade():
op.create_table(...) # 从 cubeloop_metadata 自动生成
op.execute(create_message_partitions_op()) # cubepi_messages 的 64 个哈希分区
op.execute(create_runs_partitions_op()) # cubepi_runs 的 64 个哈希分区
- op.execute(write_schema_version_op()) # 记录 EXPECTED_SCHEMA_VERSION
+ op.execute(write_schema_version_op()) # 记录历史 schema v5
```
两个辅助函数都返回 SQL 字符串——你需要传入 `op.execute(...)`。
-`write_schema_version_op()` 是幂等的:它会删除之前 CubeLoop 版本的所有行,
-然后插入当前版本。
-
-当 CubeLoop 后续升级并提升了 `EXPECTED_SCHEMA_VERSION` 时,生成一个新的
-revision,再次调用 `op.execute(write_schema_version_op())`。
+`write_schema_version_op()` 是不可变的历史 v5 writer:它会删除其他版本行并写入
+5,可以重复执行。未来 schema version 必须新增并调用对应版本的 writer,不能复用
+这个 helper。
## 数据模型
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md
index 11a73e7..ac28432 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.14/migration/from-cubepi.md
@@ -34,7 +34,8 @@ Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*
历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`
导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。
-从 0.13.6 或更早版本直接升级到 0.14.1 或更高版本,不需要数据库迁移。
+已有 schema v5 数据库不需要表名迁移。如果数据库仍是更早的 schema version,
+请先通过宿主 Alembic migration 正常升级到 v5,再启动 0.14.1 checkpointer。
## Tracing
diff --git a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md
index 40d602e..cc64412 100644
--- a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md
+++ b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md
@@ -120,10 +120,9 @@ def upgrade():
op.execute(stmt)
```
-`write_schema_version_op()` is idempotent: it deletes any rows from a
-prior CubeLoop version and inserts the current one. When CubeLoop later
-bumps `EXPECTED_SCHEMA_VERSION`, generate a new revision and run it
-again.
+`write_schema_version_op()` is the immutable historical v5 writer. It is
+idempotent, deleting other version rows before inserting 5. A future schema
+version must ship and use a new version-specific writer; do not reuse this one.
## Data model
diff --git a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md
index 1500135..c691f64 100644
--- a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md
+++ b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md
@@ -106,16 +106,13 @@ def upgrade():
op.create_table(...) # auto-generated from cubeloop_metadata
op.execute(create_message_partitions_op()) # 64 hash partitions of cubepi_messages
op.execute(create_runs_partitions_op()) # 64 hash partitions of cubepi_runs
- op.execute(write_schema_version_op()) # records EXPECTED_SCHEMA_VERSION
+ op.execute(write_schema_version_op()) # records historical schema v5
```
Both helpers return a SQL string — you pass them to `op.execute(...)`.
-`write_schema_version_op()` is idempotent: it deletes any rows from a
-prior CubeLoop version and inserts the current one.
-
-When CubeLoop later upgrades and bumps `EXPECTED_SCHEMA_VERSION`, you
-generate a new revision and call `op.execute(write_schema_version_op())`
-again.
+`write_schema_version_op()` is the immutable historical v5 writer. It is
+idempotent, deleting other version rows before inserting 5. A future schema
+version must ship and use a new version-specific writer; do not reuse this one.
## Data model
diff --git a/website/versioned_docs/version-0.14/migration/from-cubepi.md b/website/versioned_docs/version-0.14/migration/from-cubepi.md
index c075245..91e929c 100644
--- a/website/versioned_docs/version-0.14/migration/from-cubepi.md
+++ b/website/versioned_docs/version-0.14/migration/from-cubepi.md
@@ -38,8 +38,9 @@ Historical host Alembic revisions may import helpers from
`cubeloop.checkpointer.*.alembic_helpers`; those helpers retain their original
v1–v5 SQL. Do not add a rename revision.
-Upgrade directly from 0.13.6 or earlier to 0.14.1 or later. No database
-migration is required.
+An existing schema-v5 database needs no rename migration. If the database is on
+an earlier schema version, run its normal host Alembic migrations through v5
+before opening the 0.14.1 checkpointer.
## Tracing