Skip to content

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

fix(checkpointer): retain cubepi persistence schema

xf gonge014981e88c9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7c587e..da7237b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,17 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
-## [0.14.0] - 2026-09-10
+## [0.14.1] - 2026-09-10
+
+### Fixed
+
+- **The CubeLoop rename no longer renames the persistent Postgres/MySQL
+ schema.** Physical tables, partitions, indexes, and the version marker remain
+ `cubepi_*` at schema version 5, so an existing 0.13.6 database opens without
+ DDL and historical host Alembic revisions remain reproducible. The withdrawn
+ 0.14.0 release briefly used `cubeloop_*`; see the migration guide for the
+ exceptional recovery procedure.
+- **The transitional `cubepi` package accepts compatible 0.14 patch releases.**
+ Its dependency and forwarded extras now use `cubeloop>=0.14.1,<0.15`.
+
+## [0.14.0] - 2026-09-10 [YANKED]
### Breaking
- **Renamed CubePi / `cubepi` to CubeLoop / `cubeloop`.** The import path,
PyPI project, CLI, docs site (`https://cubeloop.dev`), OTel vendor
- namespace (`cubeloop.*`), and Postgres/MySQL table names (`cubeloop_*`)
- all move. `pip install cubepi` 0.14+ is a transitional wrapper that
- depends on `cubeloop` and warns. Postgres/MySQL hosts must run
- `upgrade_v5_to_v6_op()` before opening 0.14. SQLite table names are
- unchanged. See the [migration guide](https://cubeloop.dev/docs/migration/from-cubepi).
+ namespace (`cubeloop.*`), and — incorrectly — Postgres/MySQL table names
+ (`cubeloop_*`) all moved. This release was withdrawn because the database
+ rename broke reproducible host Alembic histories and safe rollback. Use
+ 0.14.1 or later. See the
+ [migration guide](https://cubeloop.dev/docs/migration/from-cubepi).
## [0.13.6] - 2026-09-04
@@ -811,7 +824,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **[0.2.0]** - 2026-05-10 — see the [release notes](https://github.com/cubeplexai/cubepi/releases/tag/v0.2.0).
- **[0.1.0]** - 2026-05-09 — initial release. See the [release notes](https://github.com/cubeplexai/cubepi/releases/tag/v0.1.0).
-[Unreleased]: https://github.com/cubeplexai/cubeloop/compare/v0.14.0...HEAD
+[Unreleased]: https://github.com/cubeplexai/cubeloop/compare/v0.14.1...HEAD
+[0.14.1]: https://github.com/cubeplexai/cubeloop/compare/v0.14.0...v0.14.1
[0.14.0]: https://github.com/cubeplexai/cubeloop/compare/v0.13.6...v0.14.0
[0.13.6]: https://github.com/cubeplexai/cubeloop/compare/v0.13.5...v0.13.6
[0.13.5]: https://github.com/cubeplexai/cubeloop/compare/v0.13.4...v0.13.5
diff --git a/compat/cubepi/README.md b/compat/cubepi/README.md
index ac4d47d..e247b4f 100644
--- a/compat/cubepi/README.md
+++ b/compat/cubepi/README.md
@@ -10,7 +10,8 @@ pip install cubeloop
from cubeloop import Agent, tool
```
-This distribution is a transitional wrapper: it depends on `cubeloop==0.14.0`,
+This distribution is a transitional wrapper: it depends on a compatible
+`cubeloop>=0.14.1,<0.15`,
re-exports the public API, and aliases `cubepi.*` imports onto `cubeloop.*`.
Installing it prints a deprecation warning on first import.
diff --git a/compat/cubepi/pyproject.toml b/compat/cubepi/pyproject.toml
index 605754d..cc57425 100644
--- a/compat/cubepi/pyproject.toml
+++ b/compat/cubepi/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "cubepi"
-version = "0.14.0"
+version = "0.14.1"
description = "DEPRECATED: Cubepi has been renamed to cubeloop. This package is a transitional wrapper."
readme = "README.md"
license = "MIT"
@@ -13,17 +13,17 @@ classifiers = [
"Programming Language :: Python :: 3.14",
]
dependencies = [
- "cubeloop==0.14.0",
+ "cubeloop>=0.14.1,<0.15",
]
[project.optional-dependencies]
-sqlite = ["cubeloop[sqlite]==0.14.0"]
-postgres = ["cubeloop[postgres]==0.14.0"]
-mysql = ["cubeloop[mysql]==0.14.0"]
-mcp = ["cubeloop[mcp]==0.14.0"]
-tracing = ["cubeloop[tracing]==0.14.0"]
-tracing-otlp = ["cubeloop[tracing-otlp]==0.14.0"]
-trace-cli = ["cubeloop[trace-cli]==0.14.0"]
+sqlite = ["cubeloop[sqlite]>=0.14.1,<0.15"]
+postgres = ["cubeloop[postgres]>=0.14.1,<0.15"]
+mysql = ["cubeloop[mysql]>=0.14.1,<0.15"]
+mcp = ["cubeloop[mcp]>=0.14.1,<0.15"]
+tracing = ["cubeloop[tracing]>=0.14.1,<0.15"]
+tracing-otlp = ["cubeloop[tracing-otlp]>=0.14.1,<0.15"]
+trace-cli = ["cubeloop[trace-cli]>=0.14.1,<0.15"]
[project.scripts]
cubepi = "cubepi.__main__:main"
diff --git a/cubeloop/__init__.py b/cubeloop/__init__.py
index 4982ab3..2cc26d2 100644
--- a/cubeloop/__init__.py
+++ b/cubeloop/__init__.py
@@ -1,4 +1,4 @@
-"""cubepi — Pythonic async-native agent framework."""
+"""CubeLoop — Pythonic async-native agent framework."""
from importlib.metadata import PackageNotFoundError, version as _pkg_version
diff --git a/cubeloop/checkpointer/mysql/README.md b/cubeloop/checkpointer/mysql/README.md
index d5fcf96..9daef31 100644
--- a/cubeloop/checkpointer/mysql/README.md
+++ b/cubeloop/checkpointer/mysql/README.md
@@ -43,13 +43,13 @@ from cubeloop.checkpointer.mysql import cubeloop_metadata, EXPECTED_SCHEMA_VERSI
| Symbol | Use |
|---|---|
| `cubeloop_metadata` | SQLAlchemy `MetaData` — set as Alembic `target_metadata` |
-| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `6`) |
+| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `5`) |
The SQL helpers live in the `alembic_helpers` submodule:
```python
from cubeloop.checkpointer.mysql.alembic_helpers import (
- messages_partition_clause, # the PARTITION BY KEY (...) clause for cubeloop_messages
+ messages_partition_clause, # the PARTITION BY KEY (...) clause for cubepi_messages
add_pending_request_column_op, # v1→v2 column add
write_schema_version_op, # returns two ';'-separated statements
)
@@ -57,19 +57,19 @@ from cubeloop.checkpointer.mysql.alembic_helpers import (
## Tables
-`cubeloop_metadata` defines the current (v6) tables:
+`cubeloop_metadata` defines the current (v5) tables:
| Table | Purpose |
|---|---|
-| `cubeloop_threads` | One row per thread; holds `pending_request JSON NULL` (HITL, v2+) |
-| `cubeloop_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, `PARTITION BY KEY (thread_id)` into 64 partitions |
-| `cubeloop_runs` | Per-run claim/completion (v4+) |
-| `cubeloop_hitl_answers` | Durable HITL answers (v5+) |
-| `cubeloop_schema_version` | Single-row version marker verified on connect |
+| `cubepi_threads` | One row per thread; holds `pending_request JSON NULL` (HITL, v2+) |
+| `cubepi_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, `PARTITION BY KEY (thread_id)` into 64 partitions |
+| `cubepi_runs` | Per-run claim/completion (v4+) |
+| `cubepi_hitl_answers` | Durable HITL answers (v5+) |
+| `cubepi_schema_version` | Single-row version marker verified on connect |
MySQL declares all partitions inline in the `CREATE TABLE` (unlike
-Postgres, which uses one child table per partition). The `cubeloop_messages`
-table has **no foreign key** to `cubeloop_threads` — MySQL forbids FKs on
+Postgres, which uses one child table per partition). The `cubepi_messages`
+table has **no foreign key** to `cubepi_threads` — MySQL forbids FKs on
partitioned tables.
## Wiring Alembic (`env.py`)
@@ -94,13 +94,13 @@ correct columns** (from `cubeloop_metadata`). Two things to add by hand:
1. **KEY partitioning.** SQLAlchemy autogenerate cannot express MySQL
`KEY` partitioning, so append the partition clause to the
- `cubeloop_messages` table. Keep the autogenerated column list and add
+ `cubepi_messages` table. Keep the autogenerated column list and add
the clause via `op.execute`:
```python
from cubeloop.checkpointer.mysql.alembic_helpers import messages_partition_clause
- op.execute("ALTER TABLE cubeloop_messages " + messages_partition_clause())
+ op.execute("ALTER TABLE cubepi_messages " + messages_partition_clause())
```
`KEY` (not `HASH`) is required because `thread_id` is a `VARCHAR` —
@@ -118,14 +118,14 @@ correct columns** (from `cubeloop_metadata`). Two things to add by hand:
op.execute(stmt)
```
-> Do not hand-trim the `cubeloop_messages` columns. The checkpointer writes
+> Do not hand-trim the `cubepi_messages` columns. The checkpointer writes
> and reads `(thread_id, seq, role, metadata, payload)`; dropping any of
> them causes runtime SQL errors on the first append.
## Upgrading schema versions
CubeLoop bumps `EXPECTED_SCHEMA_VERSION` when the schema changes; the
-checkpointer refuses to connect if the row in `cubeloop_schema_version`
+checkpointer refuses to connect if the row in `cubepi_schema_version`
doesn't match. Each bump is one host migration.
**v1 → v2** (HITL): adds `pending_request JSON NULL` to `cubepi_threads`.
diff --git a/cubeloop/checkpointer/mysql/alembic_helpers.py b/cubeloop/checkpointer/mysql/alembic_helpers.py
index 1a218c8..f5528f3 100644
--- a/cubeloop/checkpointer/mysql/alembic_helpers.py
+++ b/cubeloop/checkpointer/mysql/alembic_helpers.py
@@ -1,9 +1,6 @@
"""SQL helpers for host application alembic migrations (MySQL)."""
-from cubeloop.checkpointer.mysql.models import (
- EXPECTED_SCHEMA_VERSION,
- PARTITION_COUNT,
-)
+from cubeloop.checkpointer.mysql.models import PARTITION_COUNT
def messages_partition_clause() -> str:
@@ -80,21 +77,19 @@ def add_messages_run_id_column_op() -> str:
def create_runs_table_op() -> str:
- """Return SQL creating the partitioned ``cubeloop_runs`` parent table.
+ """Return SQL creating the partitioned ``cubepi_runs`` parent table.
- Current-schema factory (v6 names). Historical v3→v4 inlines the old
- cubepi_runs CREATE and must not call this helper. NO FK to
- ``cubeloop_threads`` — MySQL forbids FKs on partitioned tables.
+ NO FK to ``cubepi_threads`` — MySQL forbids FKs on partitioned tables.
"""
return (
- "CREATE TABLE cubeloop_runs ("
+ "CREATE TABLE cubepi_runs ("
" thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,"
" run_id VARCHAR(255) NOT NULL,"
" claimed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,"
" completed_at TIMESTAMP NULL,"
" completion_seq BIGINT NULL,"
" PRIMARY KEY (thread_id, run_id),"
- " KEY ix_cubeloop_runs_thread_seq (thread_id, completion_seq)"
+ " KEY ix_cubepi_runs_thread_seq (thread_id, completion_seq)"
") ENGINE=InnoDB " + runs_partition_clause()
)
@@ -126,20 +121,7 @@ def upgrade_v3_to_v4_op() -> str:
if stmt.strip():
op.execute(stmt)
"""
- # Inline the pre-rename cubepi_runs CREATE. create_runs_table_op() now
- # emits cubeloop_runs names for fresh installs.
- legacy_runs = (
- "CREATE TABLE cubepi_runs ("
- " thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,"
- " run_id VARCHAR(255) NOT NULL,"
- " claimed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,"
- " completed_at TIMESTAMP NULL,"
- " completion_seq BIGINT NULL,"
- " PRIMARY KEY (thread_id, run_id),"
- " KEY ix_cubepi_runs_thread_seq (thread_id, completion_seq)"
- ") ENGINE=InnoDB " + runs_partition_clause()
- )
- return f"{add_messages_run_id_column_op()} {legacy_runs};"
+ return f"{add_messages_run_id_column_op()} {create_runs_table_op()};"
def create_hitl_answers_table_op() -> str:
@@ -166,59 +148,8 @@ def upgrade_v4_to_v5_op() -> str:
return create_hitl_answers_table_op() + ";"
-def upgrade_v5_to_v6_op() -> str:
- """Rename cubepi_* tables to cubeloop_* in one atomic RENAME TABLE.
-
- Includes cubepi_schema_version. KEY partitions ride with the table.
-
- Returns ';'-joined standalone statements (SET / PREPARE / EXECUTE).
- Hosts must split the same way as ``write_schema_version_op``::
-
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
-
- Complete (no-op) iff both cubeloop_threads and cubeloop_schema_version
- already exist. If data tables moved but the version table did not,
- only the leftover version table is renamed. Requires a complete v5;
- missing cubepi_schema_version fails the whole rename.
- """
- rename_all = (
- "RENAME TABLE "
- "cubepi_threads TO cubeloop_threads, "
- "cubepi_messages TO cubeloop_messages, "
- "cubepi_runs TO cubeloop_runs, "
- "cubepi_hitl_answers TO cubeloop_hitl_answers, "
- "cubepi_schema_version TO cubeloop_schema_version"
- )
- rename_ver = "RENAME TABLE cubepi_schema_version TO cubeloop_schema_version"
- return (
- "SET @cp_new_th = ("
- "SELECT COUNT(*) FROM information_schema.tables "
- "WHERE table_schema = DATABASE() "
- "AND table_name = 'cubeloop_threads'); "
- "SET @cp_new_ver = ("
- "SELECT COUNT(*) FROM information_schema.tables "
- "WHERE table_schema = DATABASE() "
- "AND table_name = 'cubeloop_schema_version'); "
- "SET @cp_old_ver = ("
- "SELECT COUNT(*) FROM information_schema.tables "
- "WHERE table_schema = DATABASE() "
- "AND table_name = 'cubepi_schema_version'); "
- "SET @cp_sql = IF(@cp_new_th > 0 AND @cp_new_ver > 0, "
- "'DO 0', "
- "IF(@cp_new_th > 0 AND @cp_old_ver > 0, "
- f"'{rename_ver}', "
- f"'{rename_all}')); "
- "PREPARE cp_v6 FROM @cp_sql; "
- "EXECUTE cp_v6; "
- "DEALLOCATE PREPARE cp_v6;"
- )
-
-
def write_schema_version_op() -> str:
- """Write EXPECTED_SCHEMA_VERSION to cubeloop_schema_version if that
- table exists, else to cubepi_schema_version.
+ """Return the immutable v5 schema-version write used by host migrations.
Returns ';'-joined **standalone** statements. Hosts must split::
@@ -226,24 +157,9 @@ def write_schema_version_op() -> str:
if stmt.strip():
op.execute(stmt)
- No compound IF/THEN — internal semicolons would break the split contract.
+ The two standalone statements preserve the documented split contract.
"""
- n = EXPECTED_SCHEMA_VERSION
return (
- "SET @cp_ver_new = ("
- "SELECT COUNT(*) FROM information_schema.tables "
- "WHERE table_schema = DATABASE() "
- "AND table_name = 'cubeloop_schema_version'); "
- f"SET @cp_del = IF(@cp_ver_new > 0, "
- f"'DELETE FROM cubeloop_schema_version WHERE version <> {n}', "
- f"'DELETE FROM cubepi_schema_version WHERE version <> {n}'); "
- "PREPARE cp_stmt FROM @cp_del; "
- "EXECUTE cp_stmt; "
- "DEALLOCATE PREPARE cp_stmt; "
- f"SET @cp_ins = IF(@cp_ver_new > 0, "
- f"'INSERT IGNORE INTO cubeloop_schema_version (version) VALUES ({n})', "
- f"'INSERT IGNORE INTO cubepi_schema_version (version) VALUES ({n})'); "
- "PREPARE cp_stmt FROM @cp_ins; "
- "EXECUTE cp_stmt; "
- "DEALLOCATE PREPARE cp_stmt;"
+ "DELETE FROM cubepi_schema_version WHERE version <> 5; "
+ "INSERT IGNORE INTO cubepi_schema_version (version) VALUES (5);"
)
diff --git a/cubeloop/checkpointer/mysql/checkpointer.py b/cubeloop/checkpointer/mysql/checkpointer.py
index ef69737..17a537f 100644
--- a/cubeloop/checkpointer/mysql/checkpointer.py
+++ b/cubeloop/checkpointer/mysql/checkpointer.py
@@ -68,7 +68,7 @@ _ROLE_TO_CLS: dict[str, type[Message]] = {
def _deserialize_row(
thread_id: str, seq: int, role: str, metadata: Any, payload: Any
) -> Message:
- """Deserialize one cubeloop_messages row; corruption raises typed."""
+ """Deserialize one cubepi_messages row; corruption raises typed."""
try:
cls = _ROLE_TO_CLS.get(role)
if cls is None:
@@ -80,7 +80,7 @@ def _deserialize_row(
raise CheckpointCorruptionError(
thread_id=thread_id,
backend="mysql",
- row_ref=f"cubeloop_messages.seq={seq}",
+ row_ref=f"cubepi_messages.seq={seq}",
cause=exc,
) from exc
@@ -175,18 +175,29 @@ class MySQLCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
- row, missing = await self._select_version(
- cur, "cubeloop_schema_version"
- )
+ row, missing = await self._select_version(cur, "cubepi_schema_version")
if not missing:
if row is None:
raise CubeloopSchemaUninitialized(
- "cubeloop_schema_version table is empty. Host "
+ "cubepi_schema_version table is empty. Host "
"alembic migration must INSERT the current version "
"(use write_schema_version_op())."
)
actual = row[0]
if actual != EXPECTED_SCHEMA_VERSION:
+ if actual > EXPECTED_SCHEMA_VERSION:
+ raise CubeloopSchemaMismatch(
+ expected=EXPECTED_SCHEMA_VERSION,
+ actual=actual,
+ hint=(
+ "database schema is newer than this CubeLoop "
+ "release. If withdrawn 0.14.0 wrote version 6, "
+ "inspect the database and follow "
+ "https://cubeloop.dev/docs/migration/"
+ "from-cubepi#emergency-recovery-from-withdrawn-0140; "
+ "do not run a forward migration."
+ ),
+ )
steps = ", ".join(
f"upgrade_v{v}_to_v{v + 1}_op()"
for v in range(actual, EXPECTED_SCHEMA_VERSION)
@@ -205,20 +216,20 @@ class MySQLCheckpointer:
)
return
- legacy, legacy_missing = await self._select_version(
- cur, "cubepi_schema_version"
+ withdrawn, withdrawn_missing = await self._select_version(
+ cur, "cubeloop_schema_version"
)
- if not legacy_missing:
- actual = 0 if legacy is None else int(legacy[0])
+ if not withdrawn_missing and withdrawn is not None:
+ actual = int(withdrawn[0])
raise CubeloopSchemaMismatch(
expected=EXPECTED_SCHEMA_VERSION,
actual=actual,
hint=(
- "Generate a new alembic revision that calls "
- "upgrade_v5_to_v6_op() + write_schema_version_op() "
- "(see cubeloop.checkpointer.mysql.alembic_helpers) "
- "and run `alembic upgrade head` against this "
- "database."
+ "database uses the withdrawn 0.14.0 cubeloop_* "
+ "schema. Inspect it and follow "
+ "https://cubeloop.dev/docs/migration/"
+ "from-cubepi#emergency-recovery-from-withdrawn-0140; "
+ "do not run a forward migration."
),
)
@@ -234,14 +245,13 @@ class MySQLCheckpointer:
actual=0,
hint=(
"data tables exist but schema_version is missing; "
- "cannot auto-classify. If tables are still cubepi_*, "
- "CREATE TABLE cubepi_schema_version and INSERT 5, "
- "then run upgrade_v5_to_v6_op(). Do not apply fresh "
- "v6 CREATE TABLE on existing data."
+ "cannot auto-classify. Restore cubepi_schema_version "
+ "from the host's Alembic history; do not apply fresh "
+ "CREATE TABLE statements on existing data."
),
)
raise CubeloopSchemaUninitialized(
- "cubeloop tables not found. Run host application's alembic upgrade."
+ "cubepi tables not found. Run host application's alembic upgrade."
)
@staticmethod
@@ -264,13 +274,13 @@ class MySQLCheckpointer:
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT seq, role, metadata, payload FROM cubeloop_messages "
+ "SELECT seq, role, metadata, payload FROM cubepi_messages "
"WHERE thread_id = %s ORDER BY seq",
(thread_id,),
)
msg_rows = await cur.fetchall()
await cur.execute(
- "SELECT extra, parent_thread_id FROM cubeloop_threads "
+ "SELECT extra, parent_thread_id FROM cubepi_threads "
"WHERE thread_id = %s",
(thread_id,),
)
@@ -310,12 +320,12 @@ class MySQLCheckpointer:
# also swallow unrelated errors and emit a duplicate-key
# warning when the row already exists.
await cur.execute(
- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "
+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) "
"ON DUPLICATE KEY UPDATE thread_id = thread_id",
(thread_id,),
)
await cur.execute(
- "SELECT thread_id FROM cubeloop_threads "
+ "SELECT thread_id FROM cubepi_threads "
"WHERE thread_id = %s FOR UPDATE",
(thread_id,),
)
@@ -323,7 +333,7 @@ class MySQLCheckpointer:
if run_ids:
placeholders = ", ".join(["%s"] * len(run_ids))
await cur.execute(
- f"SELECT run_id FROM cubeloop_runs "
+ f"SELECT run_id FROM cubepi_runs "
f"WHERE thread_id = %s "
f"AND run_id IN ({placeholders}) "
f"AND completed_at IS NOT NULL",
@@ -336,7 +346,7 @@ class MySQLCheckpointer:
f"append on completed run thread={thread_id} runs={bad}"
)
await cur.execute(
- "SELECT COALESCE(MAX(seq), 0) FROM cubeloop_messages "
+ "SELECT COALESCE(MAX(seq), 0) FROM cubepi_messages "
"WHERE thread_id = %s",
(thread_id,),
)
@@ -358,7 +368,7 @@ class MySQLCheckpointer:
)
)
await cur.executemany(
- "INSERT INTO cubeloop_messages "
+ "INSERT INTO cubepi_messages "
"(thread_id, seq, role, metadata, payload, run_id) "
"VALUES (%s, %s, %s, %s, %s, %s)",
rows,
@@ -371,9 +381,9 @@ class MySQLCheckpointer:
async def claim_run(self, thread_id: str, run_id: str) -> None:
"""Atomically claim a run_id on a thread.
- Lazy-creates the cubeloop_threads row, takes a per-thread FOR UPDATE
+ Lazy-creates the cubepi_threads row, takes a per-thread FOR UPDATE
lock to serialize concurrent claims for the same thread, then
- checks cubeloop_runs for an existing row before inserting. The
+ checks cubepi_runs for an existing row before inserting. The
pre-check matches the Postgres approach — using INSERT + catching
IntegrityError would also work, but a pre-SELECT lets us
distinguish in-flight vs completed cleanly without relying on the
@@ -386,19 +396,19 @@ class MySQLCheckpointer:
async with conn.cursor() as cur:
# Lazy thread row creation (claim may precede any append).
await cur.execute(
- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "
+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) "
"ON DUPLICATE KEY UPDATE thread_id = thread_id",
(thread_id,),
)
# Per-thread fence: serializes claim_run/append/fork on
# the same thread (matches Postgres's pg_advisory_xact_lock).
await cur.execute(
- "SELECT thread_id FROM cubeloop_threads "
+ "SELECT thread_id FROM cubepi_threads "
"WHERE thread_id = %s FOR UPDATE",
(thread_id,),
)
await cur.execute(
- "SELECT completed_at FROM cubeloop_runs "
+ "SELECT completed_at FROM cubepi_runs "
"WHERE thread_id = %s AND run_id = %s",
(thread_id, run_id),
)
@@ -412,7 +422,7 @@ class MySQLCheckpointer:
f"thread={thread_id} run={run_id} in flight"
)
await cur.execute(
- "INSERT INTO cubeloop_runs (thread_id, run_id) VALUES (%s, %s)",
+ "INSERT INTO cubepi_runs (thread_id, run_id) VALUES (%s, %s)",
(thread_id, run_id),
)
await conn.commit()
@@ -434,12 +444,12 @@ class MySQLCheckpointer:
try:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT thread_id FROM cubeloop_threads "
+ "SELECT thread_id FROM cubepi_threads "
"WHERE thread_id = %s FOR UPDATE",
(thread_id,),
)
await cur.execute(
- "SELECT completed_at FROM cubeloop_runs "
+ "SELECT completed_at FROM cubepi_runs "
"WHERE thread_id = %s AND run_id = %s",
(thread_id, run_id),
)
@@ -453,13 +463,13 @@ class MySQLCheckpointer:
return # idempotent success
await cur.execute(
"SELECT COALESCE(MAX(completion_seq), 0) + 1 "
- "FROM cubeloop_runs WHERE thread_id = %s "
+ "FROM cubepi_runs WHERE thread_id = %s "
"AND completion_seq IS NOT NULL",
(thread_id,),
)
(next_seq,) = await cur.fetchone()
await cur.execute(
- "UPDATE cubeloop_runs SET completed_at = CURRENT_TIMESTAMP, "
+ "UPDATE cubepi_runs SET completed_at = CURRENT_TIMESTAMP, "
"completion_seq = %s "
"WHERE thread_id = %s AND run_id = %s",
(next_seq, thread_id, run_id),
@@ -482,7 +492,7 @@ class MySQLCheckpointer:
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT pending_request, run_id FROM cubeloop_threads "
+ "SELECT pending_request, run_id FROM cubepi_threads "
"WHERE thread_id = %s",
(thread_id,),
)
@@ -509,13 +519,13 @@ class MySQLCheckpointer:
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT 1 FROM cubeloop_threads WHERE thread_id = %s",
+ "SELECT 1 FROM cubepi_threads WHERE thread_id = %s",
(thread_id,),
)
if await cur.fetchone() is None:
raise ThreadNotFoundError(f"thread={thread_id}")
await cur.execute(
- "SELECT completion_seq FROM cubeloop_runs "
+ "SELECT completion_seq FROM cubepi_runs "
"WHERE thread_id = %s AND run_id = %s",
(thread_id, after_run_id),
)
@@ -526,10 +536,10 @@ class MySQLCheckpointer:
)
cutoff = cutoff_row[0]
await cur.execute(
- "SELECT seq, role, metadata, payload FROM cubeloop_messages "
+ "SELECT seq, role, metadata, payload FROM cubepi_messages "
"WHERE thread_id = %s AND ("
" run_id IS NULL OR run_id IN ("
- " SELECT run_id FROM cubeloop_runs "
+ " SELECT run_id FROM cubepi_runs "
" WHERE thread_id = %s "
" AND completion_seq IS NOT NULL "
" AND completion_seq <= %s"
@@ -553,10 +563,10 @@ class MySQLCheckpointer:
) -> None:
"""Copy completed prefix of ``src_thread_id`` into ``new_thread_id``.
- Threads-row first: the destination ``cubeloop_threads`` row is
+ Threads-row first: the destination ``cubepi_threads`` row is
inserted before the message + runs copies so callers see a
- complete view if they probe mid-fork. There is no cubeloop_runs ->
- cubeloop_threads FK on MySQL (partition limitation), but we keep
+ complete view if they probe mid-fork. There is no cubepi_runs ->
+ cubepi_threads FK on MySQL (partition limitation), but we keep
the same ordering for semantic parity with Postgres.
Per-thread serialization: a ``SELECT … FOR UPDATE`` on the source
@@ -571,7 +581,7 @@ class MySQLCheckpointer:
async with conn.cursor() as cur:
# Per-thread fence on the source thread.
await cur.execute(
- "SELECT thread_id FROM cubeloop_threads "
+ "SELECT thread_id FROM cubepi_threads "
"WHERE thread_id = %s FOR UPDATE",
(src_thread_id,),
)
@@ -579,14 +589,14 @@ class MySQLCheckpointer:
raise ThreadNotFoundError(f"thread={src_thread_id}")
# Destination must not exist.
await cur.execute(
- "SELECT 1 FROM cubeloop_threads WHERE thread_id = %s",
+ "SELECT 1 FROM cubepi_threads WHERE thread_id = %s",
(new_thread_id,),
)
if await cur.fetchone() is not None:
raise ThreadAlreadyExistsError(f"thread={new_thread_id}")
# Cutoff: after_run_id must be completed on src.
await cur.execute(
- "SELECT completion_seq FROM cubeloop_runs "
+ "SELECT completion_seq FROM cubepi_runs "
"WHERE thread_id = %s AND run_id = %s",
(src_thread_id, after_run_id),
)
@@ -598,7 +608,7 @@ class MySQLCheckpointer:
cutoff = cutoff_row[0]
# Build merged extra (carry parent's extra + fork metadata).
await cur.execute(
- "SELECT extra FROM cubeloop_threads WHERE thread_id = %s",
+ "SELECT extra FROM cubepi_threads WHERE thread_id = %s",
(src_thread_id,),
)
extra_row = await cur.fetchone()
@@ -612,7 +622,7 @@ class MySQLCheckpointer:
# with the Postgres FK-driven ordering, even though MySQL
# has no FK on the partitioned messages/runs tables).
await cur.execute(
- "INSERT INTO cubeloop_threads "
+ "INSERT INTO cubepi_threads "
"(thread_id, parent_thread_id, forked_at_seq, extra) "
"VALUES (%s, %s, %s, %s)",
(
@@ -624,13 +634,13 @@ class MySQLCheckpointer:
)
# Copy messages: legacy NULL run_id OR completed-at-cutoff.
await cur.execute(
- "INSERT INTO cubeloop_messages "
+ "INSERT INTO cubepi_messages "
"(thread_id, seq, role, metadata, payload, run_id) "
"SELECT %s, seq, role, metadata, payload, run_id "
- "FROM cubeloop_messages "
+ "FROM cubepi_messages "
"WHERE thread_id = %s AND ("
" run_id IS NULL OR run_id IN ("
- " SELECT run_id FROM cubeloop_runs "
+ " SELECT run_id FROM cubepi_runs "
" WHERE thread_id = %s "
" AND completion_seq IS NOT NULL "
" AND completion_seq <= %s"
@@ -640,12 +650,12 @@ class MySQLCheckpointer:
)
# Copy completed runs satisfying the cutoff.
await cur.execute(
- "INSERT INTO cubeloop_runs "
+ "INSERT INTO cubepi_runs "
"(thread_id, run_id, claimed_at, completed_at, "
" completion_seq) "
"SELECT %s, run_id, claimed_at, completed_at, "
" completion_seq "
- "FROM cubeloop_runs "
+ "FROM cubepi_runs "
"WHERE thread_id = %s "
"AND completion_seq IS NOT NULL "
"AND completion_seq <= %s",
@@ -667,12 +677,12 @@ class MySQLCheckpointer:
# also swallow unrelated errors and emit a duplicate-key
# warning when the row already exists.
await cur.execute(
- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "
+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) "
"ON DUPLICATE KEY UPDATE thread_id = thread_id",
(thread_id,),
)
await cur.execute(
- "SELECT extra FROM cubeloop_threads "
+ "SELECT extra FROM cubepi_threads "
"WHERE thread_id = %s FOR UPDATE",
(thread_id,),
)
@@ -680,7 +690,7 @@ class MySQLCheckpointer:
current = _decode_json(row[0]) if row is not None else {}
merged = {**current, **extra}
await cur.execute(
- "UPDATE cubeloop_threads "
+ "UPDATE cubepi_threads "
"SET extra = %s, updated_at = CURRENT_TIMESTAMP "
"WHERE thread_id = %s",
(json.dumps(merged), thread_id),
@@ -712,13 +722,13 @@ class MySQLCheckpointer:
try:
async with conn.cursor() as cur:
await cur.execute(
- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "
+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) "
"ON DUPLICATE KEY UPDATE thread_id = thread_id",
(thread_id,),
)
if request is None:
await cur.execute(
- "UPDATE cubeloop_threads "
+ "UPDATE cubepi_threads "
"SET pending_request = NULL, run_id = NULL, "
"updated_at = CURRENT_TIMESTAMP WHERE thread_id = %s",
(thread_id,),
@@ -726,7 +736,7 @@ class MySQLCheckpointer:
else:
payload = request.model_dump_json()
await cur.execute(
- "UPDATE cubeloop_threads "
+ "UPDATE cubepi_threads "
"SET pending_request = %s, run_id = %s, "
"updated_at = CURRENT_TIMESTAMP WHERE thread_id = %s",
(payload, run_id, thread_id),
@@ -741,7 +751,7 @@ class MySQLCheckpointer:
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT pending_request FROM cubeloop_threads WHERE thread_id = %s",
+ "SELECT pending_request FROM cubepi_threads WHERE thread_id = %s",
(thread_id,),
)
row = await cur.fetchone()
@@ -766,7 +776,7 @@ class MySQLCheckpointer:
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT run_id FROM cubeloop_threads "
+ "SELECT run_id FROM cubepi_threads "
"WHERE thread_id = %s AND pending_request IS NOT NULL",
(thread_id,),
)
@@ -788,12 +798,12 @@ class MySQLCheckpointer:
try:
async with conn.cursor() as cur:
await cur.execute(
- "INSERT INTO cubeloop_threads (thread_id) VALUES (%s) "
+ "INSERT INTO cubepi_threads (thread_id) VALUES (%s) "
"ON DUPLICATE KEY UPDATE thread_id = thread_id",
(thread_id,),
)
await cur.execute(
- "INSERT INTO cubeloop_hitl_answers "
+ "INSERT INTO cubepi_hitl_answers "
"(thread_id, run_id, question_id, answer) "
"VALUES (%s, %s, %s, %s) "
"ON DUPLICATE KEY UPDATE "
@@ -817,7 +827,7 @@ class MySQLCheckpointer:
async with self._pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT answer FROM cubeloop_hitl_answers "
+ "SELECT answer FROM cubepi_hitl_answers "
"WHERE thread_id = %s AND run_id = %s AND question_id = %s",
(thread_id, _run_key(run_id), question_id),
)
@@ -841,7 +851,7 @@ class MySQLCheckpointer:
async with conn.cursor() as cur:
if question_ids is None:
await cur.execute(
- "DELETE FROM cubeloop_hitl_answers "
+ "DELETE FROM cubepi_hitl_answers "
"WHERE thread_id = %s AND run_id = %s",
(thread_id, run_key),
)
@@ -850,7 +860,7 @@ class MySQLCheckpointer:
if qids:
placeholders = ",".join("%s" for _ in qids)
await cur.execute(
- "DELETE FROM cubeloop_hitl_answers "
+ "DELETE FROM cubepi_hitl_answers "
"WHERE thread_id = %s AND run_id = %s "
f"AND question_id IN ({placeholders})",
(thread_id, run_key, *qids),
diff --git a/cubeloop/checkpointer/mysql/models.py b/cubeloop/checkpointer/mysql/models.py
index 7c79f4b..473c35e 100644
--- a/cubeloop/checkpointer/mysql/models.py
+++ b/cubeloop/checkpointer/mysql/models.py
@@ -16,7 +16,7 @@ import sqlalchemy as sa
from sqlalchemy.dialects.mysql import JSON, LONGBLOB, VARCHAR
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-EXPECTED_SCHEMA_VERSION = 6
+EXPECTED_SCHEMA_VERSION = 5
PARTITION_COUNT = 64
cubeloop_metadata = sa.MetaData()
@@ -29,13 +29,13 @@ class CubeloopBase(DeclarativeBase):
class CubeloopThread(CubeloopBase):
- __tablename__ = "cubeloop_threads"
+ __tablename__ = "cubepi_threads"
__table_args__ = {"mysql_engine": "InnoDB"}
thread_id: Mapped[str] = mapped_column(_TID, primary_key=True)
parent_thread_id: Mapped[str | None] = mapped_column(
_TID,
- sa.ForeignKey("cubeloop_threads.thread_id"),
+ sa.ForeignKey("cubepi_threads.thread_id"),
nullable=True,
)
forked_at_seq: Mapped[int | None] = mapped_column(sa.BigInteger, nullable=True)
@@ -72,9 +72,9 @@ class CubeloopThread(CubeloopBase):
class CubeloopMessage(CubeloopBase):
- __tablename__ = "cubeloop_messages"
+ __tablename__ = "cubepi_messages"
__table_args__ = (
- sa.Index("ix_cubeloop_messages_thread_run", "thread_id", "run_id"),
+ sa.Index("ix_cubepi_messages_thread_run", "thread_id", "run_id"),
{"mysql_engine": "InnoDB"},
)
@@ -92,7 +92,7 @@ class CubeloopMessage(CubeloopBase):
payload: Mapped[bytes] = mapped_column(LONGBLOB, nullable=False)
# v4: opaque host-side run identifier stamped on each message. Lets
# fork/snapshot include only messages from completed runs. VARCHAR(255)
- # to match the cubeloop_messages indexing convention (thread_id is also
+ # to match the cubepi_messages indexing convention (thread_id is also
# VARCHAR(255) — keeps the composite index cardinality consistent).
run_id: Mapped[str | None] = mapped_column(
VARCHAR(255),
@@ -109,15 +109,15 @@ class CubeloopRun(CubeloopBase):
"""v4 per-run lifecycle row.
Primary key (thread_id, run_id). KEY-partitioned by thread_id to match
- cubeloop_messages. NO FK to cubeloop_threads — MySQL forbids FKs on
+ cubepi_messages. NO FK to cubepi_threads — MySQL forbids FKs on
partitioned tables. The partition clause cannot be expressed in
SQLAlchemy declarative and lives in
``alembic_helpers.runs_partition_clause()``.
"""
- __tablename__ = "cubeloop_runs"
+ __tablename__ = "cubepi_runs"
__table_args__ = (
- sa.Index("ix_cubeloop_runs_thread_seq", "thread_id", "completion_seq"),
+ sa.Index("ix_cubepi_runs_thread_seq", "thread_id", "completion_seq"),
{"mysql_engine": "InnoDB"},
)
@@ -136,7 +136,7 @@ class CubeloopRun(CubeloopBase):
class CubeloopHitlAnswer(CubeloopBase):
- __tablename__ = "cubeloop_hitl_answers"
+ __tablename__ = "cubepi_hitl_answers"
__table_args__ = {"mysql_engine": "InnoDB"}
thread_id: Mapped[str] = mapped_column(_TID, primary_key=True)
@@ -151,7 +151,7 @@ class CubeloopHitlAnswer(CubeloopBase):
class CubeloopSchemaVersion(CubeloopBase):
- __tablename__ = "cubeloop_schema_version"
+ __tablename__ = "cubepi_schema_version"
__table_args__ = {"mysql_engine": "InnoDB"}
version: Mapped[int] = mapped_column(sa.Integer, primary_key=True)
diff --git a/cubeloop/checkpointer/postgres/README.md b/cubeloop/checkpointer/postgres/README.md
index a585811..edd7a2c 100644
--- a/cubeloop/checkpointer/postgres/README.md
+++ b/cubeloop/checkpointer/postgres/README.md
@@ -39,13 +39,13 @@ from cubeloop.checkpointer.postgres import cubeloop_metadata, EXPECTED_SCHEMA_VE
| Symbol | Use |
|---|---|
| `cubeloop_metadata` | SQLAlchemy `MetaData` — set as Alembic `target_metadata` |
-| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `6`) |
+| `EXPECTED_SCHEMA_VERSION` | The version cubeloop verifies on connect (currently `5`) |
The SQL helpers live in the `alembic_helpers` submodule:
```python
from cubeloop.checkpointer.postgres.alembic_helpers import (
- create_message_partitions_op, # DDL for the 64 hash partitions of cubeloop_messages
+ create_message_partitions_op, # DDL for the 64 hash partitions of cubepi_messages
add_pending_request_column_op, # v1→v2 column add (idempotent, IF NOT EXISTS)
write_schema_version_op, # sets schema_version to EXPECTED_SCHEMA_VERSION
)
@@ -53,15 +53,15 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
## Tables
-`cubeloop_metadata` defines the current (v6) tables:
+`cubeloop_metadata` defines the current (v5) tables:
| Table | Purpose |
|---|---|
-| `cubeloop_threads` | One row per thread; holds `pending_request JSONB NULL` (HITL, v2+) |
-| `cubeloop_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, **HASH-partitioned** on `thread_id` into 64 partitions |
-| `cubeloop_runs` | Per-run claim/completion (v4+), HASH-partitioned |
-| `cubeloop_hitl_answers` | Durable HITL answers (v5+) |
-| `cubeloop_schema_version` | Single-row version marker verified on connect |
+| `cubepi_threads` | One row per thread; holds `pending_request JSONB NULL` (HITL, v2+) |
+| `cubepi_messages` | Append-only message log — `(thread_id, seq, role, metadata, payload, created_at)`, **HASH-partitioned** on `thread_id` into 64 partitions |
+| `cubepi_runs` | Per-run claim/completion (v4+), HASH-partitioned |
+| `cubepi_hitl_answers` | Durable HITL answers (v5+) |
+| `cubepi_schema_version` | Single-row version marker verified on connect |
## Wiring Alembic (`env.py`)
@@ -87,14 +87,14 @@ correct columns** (they come straight from `cubeloop_metadata`). Two things
SQLAlchemy autogenerate does not reliably produce, so add them to the
generated migration yourself:
-1. **Child partitions.** `cubeloop_messages` is HASH-partitioned on
+1. **Child partitions.** `cubepi_messages` is HASH-partitioned on
`thread_id` (the model declares this via
`__table_args__["postgresql_partition_by"]`). Keep the autogenerated
- `create_table` for `cubeloop_messages` — including all its columns — and
+ `create_table` for `cubepi_messages` — including all its columns — and
make sure it carries `postgresql_partition_by="HASH (thread_id)"`. The
64 child partitions are not autogenerated; create them with the helper.
-2. **The version row.** Autogenerate creates the `cubeloop_schema_version`
+2. **The version row.** Autogenerate creates the `cubepi_schema_version`
table but never inserts a row.
```python
@@ -104,21 +104,21 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
)
def upgrade():
- # ... autogenerated create_table() for cubeloop_threads,
- # cubeloop_schema_version, and cubeloop_messages (keep ALL columns;
- # ensure cubeloop_messages has postgresql_partition_by="HASH (thread_id)") ...
+ # ... autogenerated create_table() for cubepi_threads,
+ # 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
```
-> Do not hand-trim the `cubeloop_messages` columns. The checkpointer writes
+> Do not hand-trim the `cubepi_messages` columns. The checkpointer writes
> and reads `(thread_id, seq, role, metadata, payload)`; dropping any of
> them causes runtime SQL errors on the first append.
## Upgrading schema versions
CubeLoop bumps `EXPECTED_SCHEMA_VERSION` when the schema changes; the
-checkpointer refuses to connect if the row in `cubeloop_schema_version`
+checkpointer refuses to connect if the row in `cubepi_schema_version`
doesn't match. Each bump is one host migration.
**v1 → v2** (HITL): adds `pending_request JSONB NULL` to `cubepi_threads`.
diff --git a/cubeloop/checkpointer/postgres/alembic_helpers.py b/cubeloop/checkpointer/postgres/alembic_helpers.py
index e46f513..f58e2ed 100644
--- a/cubeloop/checkpointer/postgres/alembic_helpers.py
+++ b/cubeloop/checkpointer/postgres/alembic_helpers.py
@@ -1,20 +1,17 @@
"""SQL helpers for host application alembic migrations."""
-from cubeloop.checkpointer.postgres.models import (
- EXPECTED_SCHEMA_VERSION,
- PARTITION_COUNT,
-)
+from cubeloop.checkpointer.postgres.models import PARTITION_COUNT
def create_message_partitions_op() -> str:
- """Return SQL DDL creating all 64 child partitions of cubeloop_messages.
+ """Return SQL DDL creating all 64 child partitions of cubepi_messages.
Call inside an alembic upgrade() via op.execute(), AFTER the parent
- cubeloop_messages table has been created. Emits current (v6) names.
+ cubepi_messages table has been created.
"""
return "\n".join(
- f"CREATE TABLE cubeloop_messages_p{i:02d} "
- f"PARTITION OF cubeloop_messages "
+ f"CREATE TABLE cubepi_messages_p{i:02d} "
+ f"PARTITION OF cubepi_messages "
f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i});"
for i in range(PARTITION_COUNT)
)
@@ -23,9 +20,8 @@ def create_message_partitions_op() -> str:
def add_pending_request_column_op() -> str:
"""Return SQL adding the v2 `pending_request` column to cubepi_threads.
- Historical helper: still targets the pre-rename table name. Call inside
- the host's alembic v1→v2 upgrade() via op.execute(). Idempotent under
- repeated execution via IF NOT EXISTS.
+ Call inside the host's alembic v1→v2 upgrade() via op.execute(). Idempotent
+ under repeated execution via IF NOT EXISTS.
"""
return "ALTER TABLE cubepi_threads ADD COLUMN IF NOT EXISTS pending_request JSONB"
@@ -33,20 +29,19 @@ def add_pending_request_column_op() -> str:
def add_run_id_column_op() -> str:
"""Return SQL adding the v3 `run_id` column to cubepi_threads.
- Historical helper: still targets the pre-rename table name.
+ Call inside the host's alembic v2→v3 upgrade() via op.execute().
"""
return "ALTER TABLE cubepi_threads ADD COLUMN IF NOT EXISTS run_id TEXT"
def create_runs_partitions_op() -> str:
- """Return SQL DDL creating all child partitions of cubeloop_runs.
+ """Return SQL DDL creating all child partitions of cubepi_runs.
- Current-schema factory (v6 names). Historical v3→v4 inlines the old
- cubepi_runs_pXX names and must not call this helper.
+ Call after the partitioned cubepi_runs parent has been created.
"""
return "\n".join(
- f"CREATE TABLE cubeloop_runs_p{i:02d} "
- f"PARTITION OF cubeloop_runs "
+ f"CREATE TABLE cubepi_runs_p{i:02d} "
+ f"PARTITION OF cubepi_runs "
f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i});"
for i in range(PARTITION_COUNT)
)
@@ -55,15 +50,9 @@ def create_runs_partitions_op() -> str:
def upgrade_v3_to_v4_op() -> str:
"""Return SQL applying the v3→v4 schema changes.
- Historical helper: still emits cubepi_* names, including inlined
- cubepi_runs_pXX partitions (do not call create_runs_partitions_op()).
+ Adds the run_id column and index, then creates cubepi_runs and its
+ partitions.
"""
- run_partitions = "\n".join(
- f"CREATE TABLE cubepi_runs_p{i:02d} "
- f"PARTITION OF cubepi_runs "
- f"FOR VALUES WITH (modulus {PARTITION_COUNT}, remainder {i});"
- for i in range(PARTITION_COUNT)
- )
parts = [
"ALTER TABLE cubepi_messages ADD COLUMN IF NOT EXISTS run_id TEXT;",
(
@@ -85,7 +74,7 @@ def upgrade_v3_to_v4_op() -> str:
"CREATE INDEX IF NOT EXISTS ix_cubepi_runs_thread_seq "
"ON cubepi_runs (thread_id, completion_seq);"
),
- run_partitions,
+ create_runs_partitions_op(),
]
return "\n".join(parts)
@@ -93,7 +82,7 @@ def upgrade_v3_to_v4_op() -> str:
def upgrade_v4_to_v5_op() -> str:
"""Return SQL applying the v4->v5 schema changes.
- Historical helper: still emits cubepi_* names.
+ Creates the durable HITL answer ledger table.
"""
return (
"CREATE TABLE IF NOT EXISTS cubepi_hitl_answers ("
@@ -108,74 +97,10 @@ def upgrade_v4_to_v5_op() -> str:
)
-def upgrade_v5_to_v6_op() -> str:
- """Rename cubepi_* tables/indexes/partitions to cubeloop_*.
-
- Complete (no-op) iff both cubeloop_threads and cubeloop_schema_version
- exist. If data tables already moved but the version table did not,
- rename the leftover. cubeloop_threads alone is not a no-op sentinel.
-
- Requires a complete v5 (including cubepi_schema_version). Missing
- version table makes the rename fail as a whole.
- """
- message_parts = "\n".join(
- f" ALTER TABLE cubepi_messages_p{i:02d} "
- f"RENAME TO cubeloop_messages_p{i:02d};"
- for i in range(PARTITION_COUNT)
- )
- run_parts = "\n".join(
- f" ALTER TABLE cubepi_runs_p{i:02d} RENAME TO cubeloop_runs_p{i:02d};"
- for i in range(PARTITION_COUNT)
- )
- return f"""
-DO $$
-BEGIN
- IF to_regclass('cubeloop_threads') IS NOT NULL
- AND to_regclass('cubeloop_schema_version') IS NOT NULL THEN
- RETURN;
- END IF;
-
- IF to_regclass('cubeloop_threads') IS NOT NULL
- AND to_regclass('cubepi_schema_version') IS NOT NULL THEN
- ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version;
- RETURN;
- END IF;
-
- ALTER TABLE cubepi_threads RENAME TO cubeloop_threads;
- ALTER TABLE cubepi_messages RENAME TO cubeloop_messages;
-{message_parts}
- ALTER TABLE cubepi_runs RENAME TO cubeloop_runs;
-{run_parts}
- ALTER TABLE cubepi_hitl_answers RENAME TO cubeloop_hitl_answers;
- ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version;
- ALTER INDEX IF EXISTS ix_cubepi_messages_metadata_gin
- RENAME TO ix_cubeloop_messages_metadata_gin;
- ALTER INDEX IF EXISTS ix_cubepi_messages_thread_run
- RENAME TO ix_cubeloop_messages_thread_run;
- ALTER INDEX IF EXISTS ix_cubepi_runs_thread_seq
- RENAME TO ix_cubeloop_runs_thread_seq;
-END $$;
-"""
-
-
def write_schema_version_op() -> str:
- """Write EXPECTED_SCHEMA_VERSION to cubeloop_schema_version if that
- table exists, else to cubepi_schema_version.
-
- One ``DO $$`` block so asyncpg / Alembic send it as a single statement.
- """
- n = EXPECTED_SCHEMA_VERSION
- return f"""
-DO $$
-BEGIN
- IF to_regclass('cubeloop_schema_version') IS NOT NULL THEN
- DELETE FROM cubeloop_schema_version WHERE version <> {n};
- INSERT INTO cubeloop_schema_version (version) VALUES ({n})
- ON CONFLICT DO NOTHING;
- ELSE
- DELETE FROM cubepi_schema_version WHERE version <> {n};
- INSERT INTO cubepi_schema_version (version) VALUES ({n})
- ON CONFLICT DO NOTHING;
- END IF;
-END $$;
-"""
+ """Return the immutable v5 schema-version write used by host migrations."""
+ return (
+ "DELETE FROM cubepi_schema_version WHERE version <> 5; "
+ "INSERT INTO cubepi_schema_version (version) VALUES (5) "
+ "ON CONFLICT DO NOTHING;"
+ )
diff --git a/cubeloop/checkpointer/postgres/checkpointer.py b/cubeloop/checkpointer/postgres/checkpointer.py
index 3f5bf4e..0e2d0b2 100644
--- a/cubeloop/checkpointer/postgres/checkpointer.py
+++ b/cubeloop/checkpointer/postgres/checkpointer.py
@@ -52,6 +52,13 @@ def _schema_mismatch_hint(actual: int, expected: int) -> str:
between ``actual`` and ``expected``, rather than hardcoding one version
transition, so the hint stays correct as EXPECTED_SCHEMA_VERSION grows.
"""
+ if actual > expected:
+ return (
+ "database schema is newer than this CubeLoop release. If withdrawn "
+ "0.14.0 wrote version 6, inspect the database and follow "
+ "https://cubeloop.dev/docs/migration/from-cubepi#emergency-recovery-"
+ "from-withdrawn-0140; do not run a forward migration."
+ )
steps = ", ".join(f"upgrade_v{v}_to_v{v + 1}_op()" for v in range(actual, expected))
return (
"cubeloop was upgraded but host alembic is behind. "
@@ -62,18 +69,16 @@ def _schema_mismatch_hint(actual: int, expected: int) -> str:
)
-_V5_TO_V6_HINT = (
- "Generate a new alembic revision that calls "
- "upgrade_v5_to_v6_op() + write_schema_version_op() "
- "(see cubeloop.checkpointer.postgres.alembic_helpers) and run "
- "`alembic upgrade head` against this database."
-)
-
_MISSING_VERSION_TABLE_HINT = (
"data tables exist but schema_version is missing; cannot auto-classify. "
- "If tables are still cubepi_*, CREATE TABLE cubepi_schema_version and "
- "INSERT 5, then run upgrade_v5_to_v6_op(). Do not apply fresh v6 "
- "CREATE TABLE on existing data."
+ "Restore cubepi_schema_version from the host's Alembic history; do not "
+ "apply fresh CREATE TABLE statements on existing data."
+)
+
+_WITHDRAWN_V6_HINT = (
+ "database uses the withdrawn 0.14.0 cubeloop_* schema. Inspect it and "
+ "follow https://cubeloop.dev/docs/migration/from-cubepi#emergency-recovery-"
+ "from-withdrawn-0140; do not run a forward migration."
)
@@ -105,7 +110,7 @@ _ROLE_TO_CLS: dict[str, type[Message]] = {
def _deserialize_row(thread_id: str, r: Any) -> Message:
- """Deserialize one cubeloop_messages row; corruption raises typed."""
+ """Deserialize one cubepi_messages row; corruption raises typed."""
try:
cls = _ROLE_TO_CLS.get(r["role"])
if cls is None:
@@ -122,7 +127,7 @@ def _deserialize_row(thread_id: str, r: Any) -> Message:
raise CheckpointCorruptionError(
thread_id=thread_id,
backend="postgres",
- row_ref=f"cubeloop_messages.seq={r['seq']}",
+ row_ref=f"cubepi_messages.seq={r['seq']}",
cause=exc,
) from exc
@@ -172,37 +177,38 @@ class PostgresCheckpointer:
async with self._pool.acquire() as conn:
try:
row = await conn.fetchrow(
- "SELECT version FROM cubeloop_schema_version LIMIT 1"
+ "SELECT version FROM cubepi_schema_version LIMIT 1"
)
except asyncpg.UndefinedTableError:
try:
- legacy = await conn.fetchrow(
- "SELECT version FROM cubepi_schema_version LIMIT 1"
+ withdrawn = await conn.fetchrow(
+ "SELECT version FROM cubeloop_schema_version LIMIT 1"
)
- except asyncpg.UndefinedTableError as e:
- has_data = await conn.fetchval(
- "SELECT to_regclass('cubepi_threads') IS NOT NULL "
- "OR to_regclass('cubeloop_threads') IS NOT NULL"
+ except asyncpg.UndefinedTableError:
+ withdrawn = None
+ if withdrawn is not None:
+ actual = int(withdrawn["version"])
+ raise CubeloopSchemaMismatch(
+ expected=EXPECTED_SCHEMA_VERSION,
+ actual=actual,
+ hint=_WITHDRAWN_V6_HINT,
)
- if has_data:
- raise CubeloopSchemaMismatch(
- expected=EXPECTED_SCHEMA_VERSION,
- actual=0,
- hint=_MISSING_VERSION_TABLE_HINT,
- ) from e
- raise CubeloopSchemaUninitialized(
- "cubeloop tables not found. Run host application's "
- "alembic upgrade."
- ) from e
- actual = 0 if legacy is None else int(legacy["version"])
- raise CubeloopSchemaMismatch(
- expected=EXPECTED_SCHEMA_VERSION,
- actual=actual,
- hint=_V5_TO_V6_HINT,
+ has_data = await conn.fetchval(
+ "SELECT to_regclass('cubepi_threads') IS NOT NULL "
+ "OR to_regclass('cubeloop_threads') IS NOT NULL"
+ )
+ if has_data:
+ raise CubeloopSchemaMismatch(
+ expected=EXPECTED_SCHEMA_VERSION,
+ actual=0,
+ hint=_MISSING_VERSION_TABLE_HINT,
+ )
+ raise CubeloopSchemaUninitialized(
+ "cubepi tables not found. Run host application's alembic upgrade."
)
if row is None:
raise CubeloopSchemaUninitialized(
- "cubeloop_schema_version table is empty. Host alembic "
+ "cubepi_schema_version table is empty. Host alembic "
"migration must INSERT the current version "
"(use write_schema_version_op())."
)
@@ -217,12 +223,12 @@ class PostgresCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
msg_rows = await conn.fetch(
- "SELECT seq, role, metadata, payload FROM cubeloop_messages "
+ "SELECT seq, role, metadata, payload FROM cubepi_messages "
"WHERE thread_id = $1 ORDER BY seq",
thread_id,
)
extra_row = await conn.fetchrow(
- "SELECT extra, parent_thread_id FROM cubeloop_threads "
+ "SELECT extra, parent_thread_id FROM cubepi_threads "
"WHERE thread_id = $1",
thread_id,
)
@@ -264,14 +270,14 @@ class PostgresCheckpointer:
)
# Lazy thread row creation
await conn.execute(
- "INSERT INTO cubeloop_threads (thread_id) "
+ "INSERT INTO cubepi_threads (thread_id) "
"VALUES ($1) ON CONFLICT DO NOTHING",
thread_id,
)
# Pre-flight: reject append on any completed run_id.
if run_ids:
done_rows = await conn.fetch(
- "SELECT run_id FROM cubeloop_runs "
+ "SELECT run_id FROM cubepi_runs "
"WHERE thread_id = $1 AND run_id = ANY($2::text[]) "
"AND completed_at IS NOT NULL",
thread_id,
@@ -284,7 +290,7 @@ class PostgresCheckpointer:
)
last_seq = (
await conn.fetchval(
- "SELECT COALESCE(MAX(seq), 0) FROM cubeloop_messages "
+ "SELECT COALESCE(MAX(seq), 0) FROM cubepi_messages "
"WHERE thread_id = $1",
thread_id,
)
@@ -308,7 +314,7 @@ class PostgresCheckpointer:
)
)
await conn.executemany(
- "INSERT INTO cubeloop_messages "
+ "INSERT INTO cubepi_messages "
"(thread_id, seq, role, metadata, payload, run_id) "
"VALUES ($1, $2, $3, $4, $5, $6)",
rows,
@@ -324,7 +330,7 @@ class PostgresCheckpointer:
)
# Lazy thread row creation (claim may precede any append).
await conn.execute(
- "INSERT INTO cubeloop_threads (thread_id) "
+ "INSERT INTO cubepi_threads (thread_id) "
"VALUES ($1) ON CONFLICT (thread_id) DO NOTHING",
thread_id,
)
@@ -332,7 +338,7 @@ class PostgresCheckpointer:
# raise UniqueViolation (which would abort the txn before
# we could distinguish in-flight vs completed).
row = await conn.fetchrow(
- "SELECT completed_at FROM cubeloop_runs "
+ "SELECT completed_at FROM cubepi_runs "
"WHERE thread_id = $1 AND run_id = $2",
thread_id,
run_id,
@@ -346,7 +352,7 @@ class PostgresCheckpointer:
f"thread={thread_id} run={run_id} in flight"
)
await conn.execute(
- "INSERT INTO cubeloop_runs (thread_id, run_id) VALUES ($1, $2)",
+ "INSERT INTO cubepi_runs (thread_id, run_id) VALUES ($1, $2)",
thread_id,
run_id,
)
@@ -360,7 +366,7 @@ class PostgresCheckpointer:
thread_id,
)
row = await conn.fetchrow(
- "SELECT completed_at FROM cubeloop_runs "
+ "SELECT completed_at FROM cubepi_runs "
"WHERE thread_id = $1 AND run_id = $2",
thread_id,
run_id,
@@ -373,12 +379,12 @@ class PostgresCheckpointer:
return # idempotent success
next_seq = await conn.fetchval(
"SELECT COALESCE(MAX(completion_seq), 0) + 1 "
- "FROM cubeloop_runs WHERE thread_id = $1 "
+ "FROM cubepi_runs WHERE thread_id = $1 "
"AND completion_seq IS NOT NULL",
thread_id,
)
await conn.execute(
- "UPDATE cubeloop_runs SET completed_at = now(), "
+ "UPDATE cubepi_runs SET completed_at = now(), "
"completion_seq = $3 "
"WHERE thread_id = $1 AND run_id = $2",
thread_id,
@@ -392,7 +398,7 @@ class PostgresCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
row = await conn.fetchrow(
- "SELECT pending_request, run_id FROM cubeloop_threads "
+ "SELECT pending_request, run_id FROM cubepi_threads "
"WHERE thread_id = $1",
thread_id,
)
@@ -410,13 +416,13 @@ class PostgresCheckpointer:
async with self._pool.acquire() as conn:
# Source thread must exist.
t_row = await conn.fetchrow(
- "SELECT 1 FROM cubeloop_threads WHERE thread_id = $1",
+ "SELECT 1 FROM cubepi_threads WHERE thread_id = $1",
thread_id,
)
if t_row is None:
raise ThreadNotFoundError(f"thread={thread_id}")
cutoff = await conn.fetchval(
- "SELECT completion_seq FROM cubeloop_runs "
+ "SELECT completion_seq FROM cubepi_runs "
"WHERE thread_id = $1 AND run_id = $2",
thread_id,
after_run_id,
@@ -426,10 +432,10 @@ class PostgresCheckpointer:
f"thread={thread_id} run={after_run_id} not completed"
)
rows = await conn.fetch(
- "SELECT seq, role, metadata, payload FROM cubeloop_messages "
+ "SELECT seq, role, metadata, payload FROM cubepi_messages "
"WHERE thread_id = $1 AND ("
" run_id IS NULL OR run_id IN ("
- " SELECT run_id FROM cubeloop_runs "
+ " SELECT run_id FROM cubepi_runs "
" WHERE thread_id = $1 "
" AND completion_seq IS NOT NULL "
" AND completion_seq <= $2"
@@ -461,21 +467,21 @@ class PostgresCheckpointer:
# / claim_run / save_extra / save_pending_request — so its
# presence is the canonical "thread exists" gate).
t_row = await conn.fetchrow(
- "SELECT 1 FROM cubeloop_threads WHERE thread_id = $1",
+ "SELECT 1 FROM cubepi_threads WHERE thread_id = $1",
src_thread_id,
)
if t_row is None:
raise ThreadNotFoundError(f"thread={src_thread_id}")
# Destination must not exist.
dst_row = await conn.fetchrow(
- "SELECT 1 FROM cubeloop_threads WHERE thread_id = $1",
+ "SELECT 1 FROM cubepi_threads WHERE thread_id = $1",
new_thread_id,
)
if dst_row is not None:
raise ThreadAlreadyExistsError(f"thread={new_thread_id}")
# Cutoff: after_run_id must be completed on src.
cutoff = await conn.fetchval(
- "SELECT completion_seq FROM cubeloop_runs "
+ "SELECT completion_seq FROM cubepi_runs "
"WHERE thread_id = $1 AND run_id = $2",
src_thread_id,
after_run_id,
@@ -486,7 +492,7 @@ class PostgresCheckpointer:
)
# Build merged extra (carry parent's extra + fork metadata).
src_extra_row = await conn.fetchrow(
- "SELECT extra FROM cubeloop_threads WHERE thread_id = $1",
+ "SELECT extra FROM cubepi_threads WHERE thread_id = $1",
src_thread_id,
)
raw_extra = (
@@ -499,9 +505,9 @@ class PostgresCheckpointer:
if metadata is not None:
base_extra["fork"] = json.loads(json.dumps(metadata))
# INSERT destination threads row first to satisfy the
- # cubeloop_messages / cubeloop_runs FKs on subsequent copies.
+ # cubepi_messages / cubepi_runs FKs on subsequent copies.
await conn.execute(
- "INSERT INTO cubeloop_threads "
+ "INSERT INTO cubepi_threads "
"(thread_id, parent_thread_id, forked_at_seq, extra) "
"VALUES ($1, $2, $3, $4::jsonb)",
new_thread_id,
@@ -512,13 +518,13 @@ class PostgresCheckpointer:
# Copy messages whose run is NULL (legacy prefix) or completed
# at or before cutoff. Preserve seq from the source.
await conn.execute(
- "INSERT INTO cubeloop_messages "
+ "INSERT INTO cubepi_messages "
"(thread_id, seq, role, metadata, payload, run_id) "
"SELECT $1, seq, role, metadata, payload, run_id "
- "FROM cubeloop_messages "
+ "FROM cubepi_messages "
"WHERE thread_id = $2 AND ("
" run_id IS NULL OR run_id IN ("
- " SELECT run_id FROM cubeloop_runs "
+ " SELECT run_id FROM cubepi_runs "
" WHERE thread_id = $2 "
" AND completion_seq IS NOT NULL "
" AND completion_seq <= $3"
@@ -530,10 +536,10 @@ class PostgresCheckpointer:
)
# Copy completed runs satisfying the cutoff.
await conn.execute(
- "INSERT INTO cubeloop_runs "
+ "INSERT INTO cubepi_runs "
"(thread_id, run_id, claimed_at, completed_at, completion_seq) "
"SELECT $1, run_id, claimed_at, completed_at, completion_seq "
- "FROM cubeloop_runs "
+ "FROM cubepi_runs "
"WHERE thread_id = $2 "
"AND completion_seq IS NOT NULL "
"AND completion_seq <= $3",
@@ -546,10 +552,10 @@ class PostgresCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
await conn.execute(
- "INSERT INTO cubeloop_threads (thread_id, extra, updated_at) "
+ "INSERT INTO cubepi_threads (thread_id, extra, updated_at) "
"VALUES ($1, $2::jsonb, now()) "
"ON CONFLICT (thread_id) DO UPDATE "
- "SET extra = cubeloop_threads.extra || EXCLUDED.extra, "
+ "SET extra = cubepi_threads.extra || EXCLUDED.extra, "
" updated_at = now()",
thread_id,
json.dumps(extra),
@@ -576,13 +582,13 @@ class PostgresCheckpointer:
async with conn.transaction():
# Ensure thread row exists (lazy creation matches save_extra path).
await conn.execute(
- "INSERT INTO cubeloop_threads (thread_id) "
+ "INSERT INTO cubepi_threads (thread_id) "
"VALUES ($1) ON CONFLICT DO NOTHING",
thread_id,
)
if request is None:
await conn.execute(
- "UPDATE cubeloop_threads "
+ "UPDATE cubepi_threads "
"SET pending_request = NULL, run_id = NULL, "
"updated_at = now() WHERE thread_id = $1",
thread_id,
@@ -590,7 +596,7 @@ class PostgresCheckpointer:
else:
payload = request.model_dump_json()
await conn.execute(
- "UPDATE cubeloop_threads "
+ "UPDATE cubepi_threads "
"SET pending_request = $2::jsonb, run_id = $3, "
"updated_at = now() WHERE thread_id = $1",
thread_id,
@@ -602,7 +608,7 @@ class PostgresCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
row = await conn.fetchrow(
- "SELECT pending_request FROM cubeloop_threads WHERE thread_id = $1",
+ "SELECT pending_request FROM cubepi_threads WHERE thread_id = $1",
thread_id,
)
if row is None or row["pending_request"] is None:
@@ -624,7 +630,7 @@ class PostgresCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
row = await conn.fetchrow(
- "SELECT run_id FROM cubeloop_threads "
+ "SELECT run_id FROM cubepi_threads "
"WHERE thread_id = $1 AND pending_request IS NOT NULL",
thread_id,
)
@@ -643,12 +649,12 @@ class PostgresCheckpointer:
async with self._pool.acquire() as conn:
async with conn.transaction():
await conn.execute(
- "INSERT INTO cubeloop_threads (thread_id) "
+ "INSERT INTO cubepi_threads (thread_id) "
"VALUES ($1) ON CONFLICT DO NOTHING",
thread_id,
)
await conn.execute(
- "INSERT INTO cubeloop_hitl_answers "
+ "INSERT INTO cubepi_hitl_answers "
"(thread_id, run_id, question_id, answer) "
"VALUES ($1, $2, $3, $4::jsonb) "
"ON CONFLICT (thread_id, run_id, question_id) DO UPDATE "
@@ -669,7 +675,7 @@ class PostgresCheckpointer:
assert self._pool is not None
async with self._pool.acquire() as conn:
row = await conn.fetchrow(
- "SELECT answer FROM cubeloop_hitl_answers "
+ "SELECT answer FROM cubepi_hitl_answers "
"WHERE thread_id = $1 AND run_id = $2 AND question_id = $3",
thread_id,
_run_key(run_id),
@@ -691,7 +697,7 @@ class PostgresCheckpointer:
async with self._pool.acquire() as conn:
if question_ids is None:
await conn.execute(
- "DELETE FROM cubeloop_hitl_answers "
+ "DELETE FROM cubepi_hitl_answers "
"WHERE thread_id = $1 AND run_id = $2",
thread_id,
run_key,
@@ -701,7 +707,7 @@ class PostgresCheckpointer:
if not qids:
return
await conn.execute(
- "DELETE FROM cubeloop_hitl_answers "
+ "DELETE FROM cubepi_hitl_answers "
"WHERE thread_id = $1 AND run_id = $2 "
"AND question_id = ANY($3::text[])",
thread_id,
diff --git a/cubeloop/checkpointer/postgres/models.py b/cubeloop/checkpointer/postgres/models.py
index fcc4edb..81bdf92 100644
--- a/cubeloop/checkpointer/postgres/models.py
+++ b/cubeloop/checkpointer/postgres/models.py
@@ -15,7 +15,7 @@ import sqlalchemy as sa
from sqlalchemy.dialects.postgresql import JSONB
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-EXPECTED_SCHEMA_VERSION = 6
+EXPECTED_SCHEMA_VERSION = 5
PARTITION_COUNT = 64
cubeloop_metadata = sa.MetaData()
@@ -26,12 +26,12 @@ class CubeloopBase(DeclarativeBase):
class CubeloopThread(CubeloopBase):
- __tablename__ = "cubeloop_threads"
+ __tablename__ = "cubepi_threads"
thread_id: Mapped[str] = mapped_column(sa.Text, primary_key=True)
parent_thread_id: Mapped[str | None] = mapped_column(
sa.Text,
- sa.ForeignKey("cubeloop_threads.thread_id"),
+ sa.ForeignKey("cubepi_threads.thread_id"),
nullable=True,
)
forked_at_seq: Mapped[int | None] = mapped_column(sa.BigInteger, nullable=True)
@@ -67,21 +67,21 @@ class CubeloopThread(CubeloopBase):
class CubeloopMessage(CubeloopBase):
- __tablename__ = "cubeloop_messages"
+ __tablename__ = "cubepi_messages"
__table_args__ = (
sa.Index(
- "ix_cubeloop_messages_metadata_gin",
+ "ix_cubepi_messages_metadata_gin",
"metadata",
postgresql_using="gin",
postgresql_ops={"metadata": "jsonb_path_ops"},
),
- sa.Index("ix_cubeloop_messages_thread_run", "thread_id", "run_id"),
+ sa.Index("ix_cubepi_messages_thread_run", "thread_id", "run_id"),
{"postgresql_partition_by": "HASH (thread_id)"},
)
thread_id: Mapped[str] = mapped_column(
sa.Text,
- sa.ForeignKey("cubeloop_threads.thread_id", ondelete="CASCADE"),
+ sa.ForeignKey("cubepi_threads.thread_id", ondelete="CASCADE"),
primary_key=True,
)
seq: Mapped[int] = mapped_column(sa.BigInteger, primary_key=True)
@@ -107,14 +107,14 @@ class CubeloopMessage(CubeloopBase):
class CubeloopRun(CubeloopBase):
- __tablename__ = "cubeloop_runs"
+ __tablename__ = "cubepi_runs"
__table_args__ = (
- sa.Index("ix_cubeloop_runs_thread_seq", "thread_id", "completion_seq"),
+ sa.Index("ix_cubepi_runs_thread_seq", "thread_id", "completion_seq"),
{"postgresql_partition_by": "HASH (thread_id)"},
)
thread_id: Mapped[str] = mapped_column(
sa.Text,
- sa.ForeignKey("cubeloop_threads.thread_id", ondelete="CASCADE"),
+ sa.ForeignKey("cubepi_threads.thread_id", ondelete="CASCADE"),
primary_key=True,
)
run_id: Mapped[str] = mapped_column(sa.Text, primary_key=True)
@@ -130,11 +130,11 @@ class CubeloopRun(CubeloopBase):
class CubeloopHitlAnswer(CubeloopBase):
- __tablename__ = "cubeloop_hitl_answers"
+ __tablename__ = "cubepi_hitl_answers"
thread_id: Mapped[str] = mapped_column(
sa.Text,
- sa.ForeignKey("cubeloop_threads.thread_id", ondelete="CASCADE"),
+ sa.ForeignKey("cubepi_threads.thread_id", ondelete="CASCADE"),
primary_key=True,
)
run_id: Mapped[str] = mapped_column(sa.Text, primary_key=True)
@@ -148,6 +148,6 @@ class CubeloopHitlAnswer(CubeloopBase):
class CubeloopSchemaVersion(CubeloopBase):
- __tablename__ = "cubeloop_schema_version"
+ __tablename__ = "cubepi_schema_version"
version: Mapped[int] = mapped_column(sa.Integer, primary_key=True)
diff --git a/dev/plans/2026-09-10-retain-cubepi-schema.md b/dev/plans/2026-09-10-retain-cubepi-schema.md
new file mode 100644
index 0000000..c1fa372
--- /dev/null
+++ b/dev/plans/2026-09-10-retain-cubepi-schema.md
@@ -0,0 +1,84 @@
+# Retain `cubepi_*` persistence schema — implementation plan
+
+**Spec:** [`dev/specs/2026-09-10-retain-cubepi-schema.md`](../specs/2026-09-10-retain-cubepi-schema.md)
+
+**Worktree:** `.worktrees/2026-09-10-retain-cubepi-schema` on branch
+`2026-09-10-retain-cubepi-schema`.
+
+## 1. Prepare withdrawal communication
+
+- Prepare the public incident/recovery page and v0.14.0 release-note amendment.
+- Do not yank until the recovery page is merged and deployed (or the release note
+ contains the complete recovery procedure inline).
+
+## 2. Restore the v5 persistence contract
+
+- Change Postgres/MySQL model table/index names back to `cubepi_*` while retaining
+ `Cubeloop*` Python names and `cubeloop_metadata`.
+- Set both database `EXPECTED_SCHEMA_VERSION` constants to 5.
+- Restore all runtime and verification SQL identifiers to `cubepi_*`; remove the
+ v6-specific diagnosis path.
+- Restore Alembic helper SQL to the exact 0.13.6 storage semantics and remove
+ `upgrade_v5_to_v6_op()`.
+- Restore examples and backend READMEs.
+
+## 3. Create and test the recovery source
+
+- Add canonical machine-readable scripts at
+ `website/static/recovery/0.14.0/postgres-v6-to-v5.sql` and
+ `website/static/recovery/0.14.0/mysql-v6-to-v5.sql`. These are the only
+ executable recovery source; EN/zh-Hans docs link to the same downloads and
+ explain backup, stop-the-world, execution, and verification rather than
+ maintaining translated SQL copies.
+- Each script performs collision/mixed-state preflight before mutation and
+ restores tables, Postgres partitions, indexes, and schema version 5.
+- Test both scripts against an exact v6 fixture with data, indexes, constraints,
+ and partitions; prove preflight failure leaves mixed/colliding schemas intact.
+
+## 4. Lock down migration reproducibility
+
+- Add golden exact-output tests for every 0.13.6 helper, including order, types,
+ terminators, partition count, and MySQL statement splitting.
+- Add representative host migration-chain fixtures for Postgres and MySQL.
+- Test empty database → v5 replay, prebuilt v5 → open, and data round trips.
+- Add a regression assertion that normal schema code contains no physical
+ `cubeloop_*` identifiers.
+
+## 5. Repair packaging and documentation
+
+- Bump root and shim projects to 0.14.1 and change shim dependency/extras to
+ `>=0.14.1,<0.15`.
+- Rewrite the current and version-0.14 migration/checkpoint docs in English and
+ zh-Hans; include isolated emergency reverse-rename instructions for 0.14.0.
+- Correct the existing 0.14 pages in place; do not rerun docs version creation or
+ alter versions/sidebars/latest-version state.
+- Update recipes, generated API references as required, changelog, and release
+ notes. Record why the 0.14 snapshot was corrected.
+
+## 6. Verify locally
+
+- `uv sync --all-extras --dev`
+- Targeted Postgres/MySQL/helper/shim tests.
+- `uv run pytest tests/`
+- `uv run ruff check cubeloop/ tests/`
+- `uv run ruff format --check cubeloop/ tests/`
+- `uv run mypy cubeloop`
+- Website tests and production build.
+- Build both distributions and smoke-test them from a clean temporary venv.
+
+## 7. Reviews, PR, and release
+
+- Ask the user before entering the local Codex review loop.
+- Run spec → plan → code reviews with `codex:rescue`, fixing until clean.
+- Commit and push the branch; open the replacement PR with test evidence.
+- Run the PR Codex poll/fix/`@codex` loop until clean and wait for CI.
+- Merge and wait for the recovery page and downloadable scripts to deploy.
+- Amend the v0.14.0 GitHub release, yank both 0.14.0 PyPI projects with the
+ approved reason, verify their JSON metadata, and close #223 as superseded.
+- Verify the merged `main` commit already contains the reviewed 0.14.1 versions
+ and changelog from this PR. Explicitly skip `dev/runbooks/cut-doc-version.md`
+ and never run `docusaurus docs:version 0.14`; the existing snapshot was
+ corrected in place.
+- Tag that exact clean `main` commit as v0.14.1, publish both wheels, then verify
+ PyPI metadata and clean-machine installation of both `cubeloop==0.14.1` and
+ `cubepi==0.14.1`.
diff --git a/dev/specs/2026-09-10-retain-cubepi-schema.md b/dev/specs/2026-09-10-retain-cubepi-schema.md
new file mode 100644
index 0000000..034788f
--- /dev/null
+++ b/dev/specs/2026-09-10-retain-cubepi-schema.md
@@ -0,0 +1,164 @@
+# Keep the CubePi persistence schema after the CubeLoop rename
+
+- **Date:** 2026-09-10
+- **Status:** Approved for implementation
+- **Branch / worktree:** `2026-09-10-retain-cubepi-schema` → `.worktrees/2026-09-10-retain-cubepi-schema`
+- **Supersedes:** the database-rename portions of [`2026-09-09-rename-cubeloop.md`](2026-09-09-rename-cubeloop.md)
+- **Incident release:** `cubeloop==0.14.0` / `cubepi==0.14.0`
+
+## Confirmed decisions
+
+| Decision | Choice |
+|---|---|
+| Product, package, imports, CLI | Remain CubeLoop / `cubeloop` |
+| Postgres and MySQL physical names | Keep `cubepi_*` permanently |
+| Schema version | Remain v5; the brand rename is not a schema change |
+| 0.14.0 | Yank both PyPI distributions, without deleting files or the GitHub tag/release |
+| Recovery scope | No runtime dual-schema support; document an emergency reverse rename for any early adopter |
+| Replacement | Publish 0.14.1 after clean review and CI |
+
+## 1. Problem
+
+The 0.14.0 brand rename also renamed Postgres/MySQL tables and indexes and raised
+the schema version from 5 to 6. That coupled a public identity change to a
+persistent storage protocol. It made rolling deploys and application rollback
+unsafe and, more importantly, changed the output of helpers imported by
+historical host Alembic revisions. A v1 revision that was valid with 0.13 can
+therefore fail when replayed with 0.14.
+
+Migration files must be reproducible. A helper already used by a released host
+migration must retain its original SQL semantics regardless of the installed
+CubeLoop version.
+
+## 2. Prior art and deliberate divergence
+
+- LangGraph's Postgres checkpointer keeps an append-only ordered list of literal
+ migrations; a migration's position is its version and old entries are not
+ rewritten. CubeLoop keeps host-owned Alembic rather than adopting runtime DDL,
+ but adopts the same immutability rule for exported helpers.
+- pi-agent-core / the pi coding agent versions its persisted session format
+ independently of its presentation and repository identity. Claude Code also
+ treats on-disk project/user state as a compatibility surface rather than a
+ branding surface.
+- CubeLoop deliberately keeps the historical `cubepi_*` SQL namespace while its
+ Python and product namespace is `cubeloop`. The storage name is a wire-format
+ identifier, not user-facing branding.
+
+## 3. Required behavior
+
+### 3.1 Models and runtime SQL
+
+Postgres and MySQL SQLAlchemy models, metadata, verification queries, runtime
+queries, error row references, examples, and DDL documentation use:
+
+- `cubepi_threads`
+- `cubepi_messages` and Postgres `cubepi_messages_p00`…`p63`
+- `cubepi_runs` and Postgres `cubepi_runs_p00`…`p63`
+- `cubepi_hitl_answers`
+- `cubepi_schema_version`
+- `ix_cubepi_*` indexes
+
+Python class names and metadata variables remain `Cubeloop*` and
+`cubeloop_metadata`; only their physical SQL names retain the legacy namespace.
+SQLite remains unchanged.
+
+`EXPECTED_SCHEMA_VERSION` is 5 for Postgres and MySQL. A valid 0.13.6 database
+must open directly under 0.14.1 without DDL.
+
+### 3.2 Alembic helpers are immutable
+
+Restore the complete Postgres and MySQL helper output to the 0.13.6 semantics.
+Remove `upgrade_v5_to_v6_op()` from the supported public API and documentation.
+`write_schema_version_op()` writes version 5 to `cubepi_schema_version` only.
+
+Golden tests freeze the exact normalized output of every exported 0.13.6 helper,
+including statement order, types, partition count, terminators, and MySQL's
+semicolon-splitting contract. `write_schema_version_op()` becomes a permanently
+frozen v5 writer rather than tracking `EXPECTED_SCHEMA_VERSION`. Future schema
+work adds explicitly versioned writers and helpers; it must not retarget an
+existing helper or derive historical SQL from a mutable package constant.
+
+### 3.3 0.14.0 early-adopter recovery
+
+0.14.1 does not silently detect or mutate `cubeloop_*` databases. The migration
+guide contains conspicuous, dialect-specific emergency reverse-rename SQL for a
+database that actually ran the withdrawn v6 migration. It instructs operators to:
+
+1. stop all application instances;
+2. back up the database;
+3. rename tables, all Postgres child partitions, and indexes back;
+4. write schema version 5;
+5. verify object names and row counts before starting 0.14.1.
+
+The recovery is not part of the normal upgrade path.
+
+The documented SQL is executable source, not an untested snippet. Integration
+tests create the exact withdrawn 0.14.0 v6 schema, insert representative data,
+execute the documented recovery statements from a shared source verbatim, and
+verify v5 names, partitions, indexes, constraints, row counts, version 5, and a
+successful 0.14.1 checkpointer round trip. A preflight must detect name
+collisions or mixed v5/v6 schemas and fail before executing any rename.
+
+### 3.4 Compatibility distribution
+
+Publish `cubepi==0.14.1` with the real package. Its dependency and forwarded
+extras use `cubeloop>=0.14.1,<0.15`, allowing compatible 0.14 patch fixes while
+preventing an unreviewed minor-version jump. Both distributions remain versioned
+and published together.
+
+### 3.5 Documentation and frozen 0.14 snapshot
+
+Update current English and zh-Hans checkpointing/migration docs, backend READMEs,
+examples, API reference inputs, and the existing 0.14 versioned snapshot.
+Although frozen snapshots normally do not change, 0.14.0 is withdrawn and 0.14.1
+is the supported 0.14 release, so the snapshot must describe the safe 0.14
+contract. Correct only the affected persistence/migration pages in place and
+keep those pages at current/snapshot parity. Do **not** rerun
+`docusaurus docs:version 0.14` or change version/sidebars/latest-version state.
+Record this exception in the changelog and release notes.
+
+Close PR #223 as superseded, preserving it as incident context.
+
+## 4. Yank and release operations
+
+Yank both `cubeloop==0.14.0` and `cubepi==0.14.0` on PyPI with the reason:
+
+> Withdrawn: the database table rename breaks reproducible host Alembic history
+> and safe rollback. Use 0.14.1 or later.
+
+The public incident/recovery page must be live before its link is used. Release
+order is: merge and deploy that page; amend the GitHub 0.14.0 release notes;
+yank both PyPI projects; then publish 0.14.1. If an emergency yank must happen
+before the docs deploy, put self-contained recovery instructions in the GitHub
+release notes first. Do not delete artifacts, tags, or the GitHub release.
+TestPyPI may be yanked too if supported, but PyPI is the release blocker.
+
+The 0.14.1 release follows the normal patch-release runbook, but does not rerun
+the docs-version creation runbook. Do not tag or publish until local Codex review
+is clean, CI passes, and the PR Codex review loop is clean.
+
+## 5. Acceptance criteria
+
+- Both PyPI 0.14.0 projects report all files as yanked with the agreed reason.
+- A v5 Postgres/MySQL fixture opens and preserves data with 0.14.1 code and no DDL.
+- Fresh host Alembic history creates only `cubepi_*`, ends at version 5, and the
+ checkpointer operates on it.
+- Golden tests prove the complete 0.13.6 helper output and MySQL split contract
+ remain unchanged.
+- Both dialects recover an exact v6 fixture with representative data by executing
+ the shipped recovery source; mixed/colliding schemas fail before mutation.
+- No supported code or normal docs reference `upgrade_v5_to_v6_op()` or require
+ `cubeloop_*` database objects.
+- Unit/integration tests, Ruff, formatting, mypy, and docs build pass.
+- 0.14.1 wheels smoke-test both `cubeloop` and the `cubepi` shim.
+- Current and version-0.14 English/zh-Hans docs state that physical DB names stay
+ `cubepi_*` and include the exceptional 0.14.0 recovery path.
+
+## 6. Out of scope
+
+- Reverting the Python/package/CLI/domain/GitHub rename.
+- Reverting the new tracing namespace or trace directory.
+- Supporting mixed old/new table sets at runtime.
+- Yanking any 0.13.x release.
+- Renaming the physical database namespace in a later release without a new,
+ separately approved expand/migrate/contract design.
diff --git a/examples/checkpointing_mysql.py b/examples/checkpointing_mysql.py
index e4af062..c852e2d 100644
--- a/examples/checkpointing_mysql.py
+++ b/examples/checkpointing_mysql.py
@@ -49,16 +49,15 @@ THREAD_ID = "user-42"
async def bootstrap_schema(dsn: str) -> None:
- """Create the cubeloop v6 schema.
+ """Create the CubeLoop checkpointer schema v5.
- In a real deployment this is your Alembic migration. Existing v5
- databases should call upgrade_v5_to_v6_op() instead of this CREATE.
+ In a real deployment this DDL belongs in the host's Alembic history.
"""
conn = await aiomysql.connect(autocommit=True, **_parse_dsn(dsn))
try:
async with conn.cursor() as cur:
await cur.execute("""
- CREATE TABLE cubeloop_threads (
+ CREATE TABLE cubepi_threads (
thread_id VARCHAR(255) COLLATE utf8mb4_bin PRIMARY KEY,
parent_thread_id VARCHAR(255) COLLATE utf8mb4_bin NULL,
forked_at_seq BIGINT NULL,
@@ -69,12 +68,12 @@ async def bootstrap_schema(dsn: str) -> None:
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP,
CONSTRAINT fk_parent FOREIGN KEY (parent_thread_id)
- REFERENCES cubeloop_threads (thread_id)
+ REFERENCES cubepi_threads (thread_id)
) ENGINE=InnoDB
""")
await cur.execute(
"""
- CREATE TABLE cubeloop_messages (
+ CREATE TABLE cubepi_messages (
thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,
seq BIGINT NOT NULL,
role VARCHAR(32) NOT NULL,
@@ -83,17 +82,17 @@ async def bootstrap_schema(dsn: str) -> None:
run_id VARCHAR(255) NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (thread_id, seq),
- KEY ix_cubeloop_messages_thread_run (thread_id, run_id)
+ KEY ix_cubepi_messages_thread_run (thread_id, run_id)
) ENGINE=InnoDB """
+ messages_partition_clause()
)
await cur.execute(
- "CREATE TABLE cubeloop_schema_version (version INT PRIMARY KEY) "
+ "CREATE TABLE cubepi_schema_version (version INT PRIMARY KEY) "
"ENGINE=InnoDB"
)
await cur.execute(create_runs_table_op())
await cur.execute("""
- CREATE TABLE cubeloop_hitl_answers (
+ CREATE TABLE cubepi_hitl_answers (
thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,
run_id VARCHAR(255) NOT NULL,
question_id VARCHAR(255) NOT NULL,
diff --git a/examples/checkpointing_postgres.py b/examples/checkpointing_postgres.py
index 378557e..598e58b 100644
--- a/examples/checkpointing_postgres.py
+++ b/examples/checkpointing_postgres.py
@@ -48,17 +48,16 @@ THREAD_ID = "user-42"
async def bootstrap_schema(dsn: str) -> None:
- """Create the cubeloop v6 schema.
+ """Create the CubeLoop checkpointer schema v5.
- In a real deployment this is your Alembic migration. Existing v5
- databases should call upgrade_v5_to_v6_op() instead of this CREATE.
+ In a real deployment this DDL belongs in the host's Alembic history.
"""
conn = await asyncpg.connect(dsn)
try:
await conn.execute("""
- CREATE TABLE cubeloop_threads (
+ CREATE TABLE cubepi_threads (
thread_id TEXT PRIMARY KEY,
- parent_thread_id TEXT REFERENCES cubeloop_threads(thread_id),
+ parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),
forked_at_seq BIGINT,
extra JSONB NOT NULL DEFAULT '{}'::jsonb,
pending_request JSONB,
@@ -68,9 +67,9 @@ async def bootstrap_schema(dsn: str) -> None:
);
""")
await conn.execute("""
- CREATE TABLE cubeloop_messages (
+ CREATE TABLE cubepi_messages (
thread_id TEXT NOT NULL
- REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,
+ REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
seq BIGINT NOT NULL,
role TEXT NOT NULL,
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
@@ -82,15 +81,15 @@ async def bootstrap_schema(dsn: str) -> None:
""")
await conn.execute(create_message_partitions_op())
await conn.execute("""
- CREATE INDEX ix_cubeloop_messages_metadata_gin
- ON cubeloop_messages USING GIN (metadata jsonb_path_ops);
+ CREATE INDEX ix_cubepi_messages_metadata_gin
+ ON cubepi_messages USING GIN (metadata jsonb_path_ops);
""")
await conn.execute("""
- CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY);
+ CREATE TABLE cubepi_schema_version (version INTEGER PRIMARY KEY);
""")
await conn.execute("""
- CREATE TABLE cubeloop_runs (
- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id)
+ CREATE TABLE cubepi_runs (
+ thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id)
ON DELETE CASCADE,
run_id TEXT NOT NULL,
claimed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
@@ -101,8 +100,8 @@ async def bootstrap_schema(dsn: str) -> None:
""")
await conn.execute(create_runs_partitions_op())
await conn.execute("""
- CREATE TABLE cubeloop_hitl_answers (
- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id)
+ CREATE TABLE cubepi_hitl_answers (
+ thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id)
ON DELETE CASCADE,
run_id TEXT NOT NULL,
question_id TEXT NOT NULL,
diff --git a/pyproject.toml b/pyproject.toml
index f4d1a01..7ecaa28 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "cubeloop"
-version = "0.14.0"
+version = "0.14.1"
description = "Pythonic async-native agent framework"
readme = "README.md"
license = "MIT"
diff --git a/tests/checkpointer/test_alembic_helper_contract.py b/tests/checkpointer/test_alembic_helper_contract.py
new file mode 100644
index 0000000..7231c86
--- /dev/null
+++ b/tests/checkpointer/test_alembic_helper_contract.py
@@ -0,0 +1,45 @@
+"""Golden contracts for helpers embedded in host Alembic history."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cubeloop.checkpointer.mysql import alembic_helpers as mysql
+from cubeloop.checkpointer.postgres import alembic_helpers as postgres
+
+
+def _sha(value: str) -> str:
+ return hashlib.sha256(value.encode()).hexdigest()
+
+
+def test_postgres_v5_helper_output_is_immutable() -> None:
+ expected = {
+ "create_message_partitions_op": "57e8dd437c937ebefc18cdb48b627319391b5b3448c928d331f52e8fb617f852",
+ "add_pending_request_column_op": "318dd4212e5132f47042b78fe9be9b7e07af021e22b652fa8075dd34aa538e88",
+ "add_run_id_column_op": "3cd63949435a8b140ee47de04c765a8b52e125cd9cfefec95067db0f1a8164bf",
+ "create_runs_partitions_op": "8c20242b0b93aa78683d0f68b341483632031486b409157177822a54470d7968",
+ "upgrade_v3_to_v4_op": "69a190dbaa3c9ba842504a45fd54fc5d858d202faa6e025f72bf7882aa9853c6",
+ "upgrade_v4_to_v5_op": "a1d3efc24502a2564a8a5aba3045a0df0c13af3000c35f18407cf48811451e56",
+ "write_schema_version_op": "b2260726818d8ab4ea437f15cd6c91e272a703057b9ef6a106fe5f68130a55bc",
+ }
+ assert {name: _sha(getattr(postgres, name)()) for name in expected} == expected
+
+
+def test_mysql_v5_helper_output_and_split_contract_are_immutable() -> None:
+ expected = {
+ "messages_partition_clause": "5b81448a7b4b98b02bf81e3fbabe49de2e274c609f878aacfe1773d09cb1f83a",
+ "add_pending_request_column_op": "666f5c76247cf46ad3e4aef2b57402593108ceefa4fcf71f59a528d3424ab9e3",
+ "add_run_id_column_op": "f601e64528136e153c4e4e0c2f37b0067378c7eeef97dc5f2a544c17c3ea1f9b",
+ "runs_partition_clause": "5b81448a7b4b98b02bf81e3fbabe49de2e274c609f878aacfe1773d09cb1f83a",
+ "add_messages_run_id_column_op": "8c0406e13ccc0c027df75b98a6825cfa88bf750930eaeb59090fa3208cf91a69",
+ "create_runs_table_op": "c2fd37e2e2eb1ec2f88f0bd41c866b25cbf965012a061c34ced90031e45faf32",
+ "create_runs_partitions_op": "5b81448a7b4b98b02bf81e3fbabe49de2e274c609f878aacfe1773d09cb1f83a",
+ "upgrade_v3_to_v4_op": "e6d0a93e5e3abf4b27805fe428b813a0ae8d420e01c78964dc20988e2628dc31",
+ "create_hitl_answers_table_op": "7d92af42b539319943f0a4d23dd51c884294d1f4281f1848a09f11992776a47c",
+ "upgrade_v4_to_v5_op": "e71d86abf7d5b2d1534c577051c97faecc2386d37a9831063d1c603c64bdeb86",
+ "write_schema_version_op": "555d7168cf0880e2a821b1199dbf8f35ee953db5daca4ca9e177005b4674e624",
+ }
+ assert {name: _sha(getattr(mysql, name)()) for name in expected} == expected
+ assert (
+ len([s for s in mysql.write_schema_version_op().split(";") if s.strip()]) == 2
+ )
diff --git a/tests/checkpointer/test_hitl_answer_ledger_unit.py b/tests/checkpointer/test_hitl_answer_ledger_unit.py
index 1d18f4a..8c858c7 100644
--- a/tests/checkpointer/test_hitl_answer_ledger_unit.py
+++ b/tests/checkpointer/test_hitl_answer_ledger_unit.py
@@ -102,9 +102,9 @@ async def test_postgres_hitl_answer_ledger_crud() -> None:
await cp.clear_hitl_answers("t-1", run_id="r-1")
sqls = [sql for sql, _args in conn.exec_calls]
- assert any("cubeloop_hitl_answers" in sql for sql in sqls)
+ assert any("cubepi_hitl_answers" in sql for sql in sqls)
assert any("ON CONFLICT (thread_id, run_id, question_id)" in sql for sql in sqls)
- assert any("DELETE FROM cubeloop_hitl_answers" in sql for sql in sqls)
+ assert any("DELETE FROM cubepi_hitl_answers" in sql for sql in sqls)
@pytest.mark.asyncio
@@ -142,9 +142,9 @@ async def test_mysql_hitl_answer_ledger_crud() -> None:
await cp.clear_hitl_answers("t-1", run_id="r-1")
sqls = [sql for sql, _params in conn.exec_calls]
- assert any("cubeloop_hitl_answers" in sql for sql in sqls)
+ assert any("cubepi_hitl_answers" in sql for sql in sqls)
assert any("ON DUPLICATE KEY UPDATE" in sql for sql in sqls)
- assert any("DELETE FROM cubeloop_hitl_answers" in sql for sql in sqls)
+ assert any("DELETE FROM cubepi_hitl_answers" in sql for sql in sqls)
@pytest.mark.asyncio
diff --git a/tests/checkpointer/test_mysql.py b/tests/checkpointer/test_mysql.py
index e9a59c5..442fd48 100644
--- a/tests/checkpointer/test_mysql.py
+++ b/tests/checkpointer/test_mysql.py
@@ -1,5 +1,7 @@
"""MySQLCheckpointer tests — mirrors test_postgres.py."""
+from pathlib import Path
+
import aiomysql
import pytest
@@ -37,34 +39,34 @@ def test_models_import() -> None:
cubeloop_metadata,
)
- assert EXPECTED_SCHEMA_VERSION == 6
+ assert EXPECTED_SCHEMA_VERSION == 5
assert PARTITION_COUNT == 64
- assert CubeloopThread.__tablename__ == "cubeloop_threads"
- assert CubeloopMessage.__tablename__ == "cubeloop_messages"
- assert CubeloopHitlAnswer.__tablename__ == "cubeloop_hitl_answers"
- assert CubeloopSchemaVersion.__tablename__ == "cubeloop_schema_version"
- assert "cubeloop_threads" in cubeloop_metadata.tables
- assert "cubeloop_messages" in cubeloop_metadata.tables
- assert "cubeloop_hitl_answers" in cubeloop_metadata.tables
- assert "cubeloop_schema_version" in cubeloop_metadata.tables
+ assert CubeloopThread.__tablename__ == "cubepi_threads"
+ assert CubeloopMessage.__tablename__ == "cubepi_messages"
+ assert CubeloopHitlAnswer.__tablename__ == "cubepi_hitl_answers"
+ assert CubeloopSchemaVersion.__tablename__ == "cubepi_schema_version"
+ assert "cubepi_threads" in cubeloop_metadata.tables
+ assert "cubepi_messages" in cubeloop_metadata.tables
+ assert "cubepi_hitl_answers" in cubeloop_metadata.tables
+ assert "cubepi_schema_version" in cubeloop_metadata.tables
def test_threads_parent_self_fk_present() -> None:
"""parent_thread_id keeps a self-FK (threads table is not partitioned)."""
from cubeloop.checkpointer.mysql.models import cubeloop_metadata
- threads = cubeloop_metadata.tables["cubeloop_threads"]
+ threads = cubeloop_metadata.tables["cubepi_threads"]
fk_targets = {
fk.column.table.name for col in threads.columns for fk in col.foreign_keys
}
- assert "cubeloop_threads" in fk_targets
+ assert "cubepi_threads" in fk_targets
def test_messages_has_no_foreign_keys() -> None:
"""messages table is partitioned, so no FK is allowed."""
from cubeloop.checkpointer.mysql.models import cubeloop_metadata
- msgs = cubeloop_metadata.tables["cubeloop_messages"]
+ msgs = cubeloop_metadata.tables["cubepi_messages"]
assert msgs.foreign_keys == set()
@@ -76,9 +78,9 @@ def test_messages_has_no_metadata_index() -> None:
"""
from cubeloop.checkpointer.mysql.models import cubeloop_metadata
- msgs = cubeloop_metadata.tables["cubeloop_messages"]
+ msgs = cubeloop_metadata.tables["cubepi_messages"]
idx_names = {idx.name for idx in msgs.indexes}
- assert idx_names == {"ix_cubeloop_messages_thread_run"}
+ assert idx_names == {"ix_cubepi_messages_thread_run"}
def test_messages_partition_clause() -> None:
@@ -90,26 +92,13 @@ def test_write_schema_version_op_clears_stale_then_inserts() -> None:
from cubeloop.checkpointer.mysql.models import EXPECTED_SCHEMA_VERSION
sql = write_schema_version_op()
- assert "cubeloop_schema_version" in sql
assert "cubepi_schema_version" in sql
assert f"WHERE version <> {EXPECTED_SCHEMA_VERSION}" in sql
- assert "INSERT IGNORE INTO cubeloop_schema_version" in sql
- assert "PREPARE cp_stmt FROM @cp_del" in sql
+ assert "INSERT IGNORE INTO cubepi_schema_version" in sql
+ assert len([stmt for stmt in sql.split(";") if stmt.strip()]) == 2
assert sql.index("DELETE") < sql.index("INSERT")
-def test_upgrade_v5_to_v6_op_is_idempotent_guarded() -> None:
- from cubeloop.checkpointer.mysql.alembic_helpers import upgrade_v5_to_v6_op
-
- sql = upgrade_v5_to_v6_op()
- assert "information_schema.tables" in sql
- assert "cubeloop_threads" in sql
- assert "cubeloop_schema_version" in sql
- assert "PREPARE cp_v6 FROM @cp_sql" in sql
- assert "RENAME TABLE" in sql
- assert "DO 0" in sql
-
-
def test_role_of_known_message_types() -> None:
from cubeloop.checkpointer.mysql.checkpointer import _role_of
from cubeloop.providers.base import (
@@ -232,7 +221,7 @@ async def _setup_schema(dsn: str) -> None:
try:
async with conn.cursor() as cur:
await cur.execute("""
- CREATE TABLE cubeloop_threads (
+ CREATE TABLE cubepi_threads (
thread_id VARCHAR(255) COLLATE utf8mb4_bin PRIMARY KEY,
parent_thread_id VARCHAR(255) COLLATE utf8mb4_bin NULL,
forked_at_seq BIGINT NULL,
@@ -243,12 +232,12 @@ async def _setup_schema(dsn: str) -> None:
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP,
CONSTRAINT fk_parent FOREIGN KEY (parent_thread_id)
- REFERENCES cubeloop_threads (thread_id)
+ REFERENCES cubepi_threads (thread_id)
) ENGINE=InnoDB
""")
await cur.execute(
"""
- CREATE TABLE cubeloop_messages (
+ CREATE TABLE cubepi_messages (
thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,
seq BIGINT NOT NULL,
role VARCHAR(32) NOT NULL,
@@ -257,18 +246,18 @@ async def _setup_schema(dsn: str) -> None:
run_id VARCHAR(255) NULL,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (thread_id, seq),
- KEY ix_cubeloop_messages_thread_run (thread_id, run_id)
+ KEY ix_cubepi_messages_thread_run (thread_id, run_id)
) ENGINE=InnoDB """
+ messages_partition_clause()
)
await cur.execute("""
- CREATE TABLE cubeloop_schema_version (
+ CREATE TABLE cubepi_schema_version (
version INT PRIMARY KEY
) ENGINE=InnoDB
""")
await cur.execute(create_runs_table_op())
await cur.execute("""
- CREATE TABLE cubeloop_hitl_answers (
+ CREATE TABLE cubepi_hitl_answers (
thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,
run_id VARCHAR(255) NOT NULL,
question_id VARCHAR(255) NOT NULL,
@@ -458,7 +447,7 @@ async def test_version_mismatch_raises(clean_mysql_db) -> None:
conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))
try:
async with conn.cursor() as cur:
- await cur.execute("UPDATE cubeloop_schema_version SET version = 999")
+ await cur.execute("UPDATE cubepi_schema_version SET version = 999")
finally:
await conn.ensure_closed()
@@ -469,6 +458,8 @@ async def test_version_mismatch_raises(clean_mysql_db) -> None:
assert exc_info.value.expected == EXPECTED_SCHEMA_VERSION
assert exc_info.value.actual == 999
+ assert "withdrawn 0.14.0" in str(exc_info.value)
+ assert "call +" not in str(exc_info.value)
@pytest.mark.asyncio
@@ -569,7 +560,7 @@ async def test_empty_version_table_raises_uninitialized(clean_mysql_db) -> None:
conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))
try:
async with conn.cursor() as cur:
- await cur.execute("DELETE FROM cubeloop_schema_version")
+ await cur.execute("DELETE FROM cubepi_schema_version")
finally:
await conn.ensure_closed()
@@ -594,11 +585,9 @@ async def test_load_unknown_role_raises(clean_mysql_db) -> None:
conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))
try:
async with conn.cursor() as cur:
+ await cur.execute("INSERT INTO cubepi_threads (thread_id) VALUES ('t-bad')")
await cur.execute(
- "INSERT INTO cubeloop_threads (thread_id) VALUES ('t-bad')"
- )
- await cur.execute(
- "INSERT INTO cubeloop_messages "
+ "INSERT INTO cubepi_messages "
"(thread_id, seq, role, metadata, payload) "
"VALUES ('t-bad', 1, 'bogus', '{}', %s)",
(payload,),
@@ -610,7 +599,7 @@ async def test_load_unknown_role_raises(clean_mysql_db) -> None:
with pytest.raises(CheckpointCorruptionError, match="unknown role in DB") as ei:
await cp.load("t-bad")
assert isinstance(ei.value.__cause__, ValueError)
- assert ei.value.row_ref == "cubeloop_messages.seq=1"
+ assert ei.value.row_ref == "cubepi_messages.seq=1"
@pytest.mark.asyncio
@@ -659,10 +648,10 @@ async def test_mysql_load_corrupt_row_raises_typed(clean_mysql_db) -> None:
try:
async with conn.cursor() as cur:
await cur.execute(
- "UPDATE cubeloop_messages SET payload = %s "
+ "UPDATE cubepi_messages SET payload = %s "
"WHERE thread_id = 't-corrupt' AND seq = ("
" SELECT max_seq FROM (SELECT max(seq) AS max_seq "
- " FROM cubeloop_messages WHERE thread_id = 't-corrupt') AS sub)",
+ " FROM cubepi_messages WHERE thread_id = 't-corrupt') AS sub)",
(b"\xc1 not msgpack",),
)
finally:
@@ -674,17 +663,28 @@ async def test_mysql_load_corrupt_row_raises_typed(clean_mysql_db) -> None:
err = excinfo.value
assert err.thread_id == "t-corrupt"
assert err.backend == "mysql"
- assert err.row_ref.startswith("cubeloop_messages.seq=")
+ assert err.row_ref.startswith("cubepi_messages.seq=")
assert err.__cause__ is not None
@pytest.mark.asyncio
-async def test_v5_to_v6_rename_is_idempotent_before_version_write(
+async def test_existing_v5_schema_round_trip_without_migration(
clean_mysql_db,
) -> None:
- """Rename can retry after a failure before write_schema_version_op."""
from cubeloop.checkpointer.mysql import MySQLCheckpointer
- from cubeloop.checkpointer.mysql.alembic_helpers import upgrade_v5_to_v6_op
+ from cubeloop.providers.base import TextContent, UserMessage
+
+ await _setup_schema_v5(clean_mysql_db)
+ async with MySQLCheckpointer(clean_mysql_db) as cp:
+ await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])
+ data = await cp.load("t-mig")
+ assert data is not None
+ assert len(data.messages) == 1
+
+
+async def test_withdrawn_v6_recovery_script_round_trip(clean_mysql_db) -> None:
+ from cubeloop.checkpointer.mysql import MySQLCheckpointer
from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn
from cubeloop.providers.base import TextContent, UserMessage
@@ -692,30 +692,120 @@ async def test_v5_to_v6_rename_is_idempotent_before_version_write(
conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))
try:
async with conn.cursor() as cur:
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- await cur.execute(stmt)
- # Simulate Alembic failing before the version writer, then retry.
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- await cur.execute(stmt)
- for stmt in write_schema_version_op().split(";"):
- if stmt.strip():
- await cur.execute(stmt)
await cur.execute(
- "SELECT table_name FROM information_schema.tables "
+ "INSERT INTO cubepi_threads (thread_id, extra) VALUES ('kept', JSON_OBJECT())"
+ )
+ await cur.execute(
+ "ALTER TABLE cubepi_messages RENAME INDEX "
+ "ix_cubepi_messages_thread_run TO ix_cubeloop_messages_thread_run"
+ )
+ await cur.execute(
+ "ALTER TABLE cubepi_runs RENAME INDEX "
+ "ix_cubepi_runs_thread_seq TO ix_cubeloop_runs_thread_seq"
+ )
+ await cur.execute(
+ "RENAME TABLE cubepi_threads TO cubeloop_threads, "
+ "cubepi_messages TO cubeloop_messages, "
+ "cubepi_runs TO cubeloop_runs, "
+ "cubepi_hitl_answers TO cubeloop_hitl_answers, "
+ "cubepi_schema_version TO cubeloop_schema_version"
+ )
+ await cur.execute("UPDATE cubeloop_schema_version SET version = 6")
+ script = Path(
+ "website/static/recovery/0.14.0/mysql-v6-to-v5.sql"
+ ).read_text()
+ for statement in script.split(";"):
+ if statement.strip():
+ await cur.execute(statement)
+ await cur.execute(
+ "SELECT COUNT(*) FROM cubepi_threads WHERE thread_id = 'kept'"
+ )
+ assert (await cur.fetchone())[0] == 1
+ await cur.execute("SELECT version FROM cubepi_schema_version")
+ assert (await cur.fetchone())[0] == 5
+ await cur.execute(
+ "SELECT DISTINCT index_name FROM information_schema.statistics "
"WHERE table_schema = DATABASE()"
)
- names = {row[0] for row in await cur.fetchall()}
+ index_names = {row[0] for row in await cur.fetchall()}
+ assert "ix_cubepi_messages_thread_run" in index_names
+ assert "ix_cubepi_runs_thread_seq" in index_names
+ assert "ix_cubeloop_messages_thread_run" not in index_names
finally:
await conn.ensure_closed()
- assert "cubeloop_threads" in names
- assert "cubeloop_schema_version" in names
- assert "cubepi_threads" not in names
-
async with MySQLCheckpointer(clean_mysql_db) as cp:
- await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])
- data = await cp.load("t-mig")
+ await cp.append("recovered", [UserMessage(content=[TextContent(text="ok")])])
+ data = await cp.load("recovered")
assert data is not None
assert len(data.messages) == 1
+
+
+async def test_withdrawn_v6_recovery_collision_is_retryable(clean_mysql_db) -> None:
+ from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn
+
+ await _setup_schema_v5(clean_mysql_db)
+ conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))
+ try:
+ async with conn.cursor() as cur:
+ await cur.execute(
+ "RENAME TABLE cubepi_threads TO cubeloop_threads, "
+ "cubepi_messages TO cubeloop_messages, "
+ "cubepi_runs TO cubeloop_runs, "
+ "cubepi_hitl_answers TO cubeloop_hitl_answers, "
+ "cubepi_schema_version TO cubeloop_schema_version"
+ )
+ await cur.execute(
+ "CREATE TABLE cubepi_threads (thread_id VARCHAR(255) PRIMARY KEY)"
+ )
+ script = Path(
+ "website/static/recovery/0.14.0/mysql-v6-to-v5.sql"
+ ).read_text()
+ with pytest.raises(Exception):
+ for statement in script.split(";"):
+ if statement.strip():
+ await cur.execute(statement)
+ await cur.execute(
+ "SELECT table_name FROM information_schema.tables "
+ "WHERE table_schema = DATABASE() AND table_name IN "
+ "('cubeloop_threads', 'cubepi_threads')"
+ )
+ assert {row[0] for row in await cur.fetchall()} == {
+ "cubeloop_threads",
+ "cubepi_threads",
+ }
+ await cur.execute("DROP TABLE cubepi_threads")
+ for statement in script.split(";"):
+ if statement.strip():
+ await cur.execute(statement)
+ await cur.execute(
+ "SELECT COUNT(*) FROM information_schema.routines "
+ "WHERE routine_schema = DATABASE() "
+ "AND routine_name = 'cubeloop_0140_recovery_preflight'"
+ )
+ assert (await cur.fetchone())[0] == 0
+ finally:
+ await conn.ensure_closed()
+
+
+async def test_withdrawn_v6_schema_points_to_recovery(clean_mysql_db) -> None:
+ from cubeloop.checkpointer.mysql import CubeloopSchemaMismatch, MySQLCheckpointer
+ from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn
+
+ conn = await aiomysql.connect(autocommit=True, **_parse_dsn(clean_mysql_db))
+ try:
+ async with conn.cursor() as cur:
+ await cur.execute(
+ "CREATE TABLE cubeloop_schema_version "
+ "(version INT PRIMARY KEY) ENGINE=InnoDB"
+ )
+ await cur.execute("INSERT INTO cubeloop_schema_version VALUES (6)")
+ finally:
+ await conn.ensure_closed()
+ with pytest.raises(CubeloopSchemaMismatch) as exc_info:
+ async with MySQLCheckpointer(clean_mysql_db):
+ pass
+ assert exc_info.value.actual == 6
+ assert "withdrawn 0.14.0" in str(exc_info.value)
diff --git a/tests/checkpointer/test_mysql_runs.py b/tests/checkpointer/test_mysql_runs.py
index e9c0a3c..34446a6 100644
--- a/tests/checkpointer/test_mysql_runs.py
+++ b/tests/checkpointer/test_mysql_runs.py
@@ -26,13 +26,13 @@ async def test_claim_run_creates_threads_row_lazily(mysql_v4_dsn) -> None:
try:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT thread_id FROM cubeloop_threads WHERE thread_id = %s",
+ "SELECT thread_id FROM cubepi_threads WHERE thread_id = %s",
("t-lazy",),
)
row = await cur.fetchone()
assert row is not None
await cur.execute(
- "SELECT completed_at FROM cubeloop_runs "
+ "SELECT completed_at FROM cubepi_runs "
"WHERE thread_id = %s AND run_id = %s",
("t-lazy", "r1"),
)
@@ -96,7 +96,7 @@ async def test_completion_seq_monotonic_per_thread(mysql_v4_dsn) -> None:
try:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT run_id, completion_seq FROM cubeloop_runs "
+ "SELECT run_id, completion_seq FROM cubepi_runs "
"WHERE thread_id = %s ORDER BY completion_seq",
("t",),
)
@@ -144,7 +144,7 @@ async def test_append_persists_run_id_into_column(mysql_v4_dsn) -> None:
try:
async with conn.cursor() as cur:
await cur.execute(
- "SELECT run_id FROM cubeloop_messages WHERE thread_id = %s",
+ "SELECT run_id FROM cubepi_messages WHERE thread_id = %s",
("t",),
)
row = await cur.fetchone()
diff --git a/tests/checkpointer/test_mysql_schema.py b/tests/checkpointer/test_mysql_schema.py
index 0da1f96..fb14659 100644
--- a/tests/checkpointer/test_mysql_schema.py
+++ b/tests/checkpointer/test_mysql_schema.py
@@ -6,12 +6,12 @@ import pytest
from cubeloop.checkpointer.mysql.models import EXPECTED_SCHEMA_VERSION
-def test_expected_schema_version_is_6() -> None:
- assert EXPECTED_SCHEMA_VERSION == 6
+def test_expected_schema_version_is_5() -> None:
+ assert EXPECTED_SCHEMA_VERSION == 5
@pytest.mark.asyncio
-async def test_cubeloop_runs_table_present(mysql_v4_dsn) -> None:
+async def test_cubepi_runs_table_present(mysql_v4_dsn) -> None:
from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn
cfg = _parse_dsn(mysql_v4_dsn)
@@ -20,7 +20,7 @@ async def test_cubeloop_runs_table_present(mysql_v4_dsn) -> None:
async with conn.cursor() as cur:
await cur.execute(
"SELECT column_name FROM information_schema.columns "
- "WHERE table_schema = %s AND table_name = 'cubeloop_runs'",
+ "WHERE table_schema = %s AND table_name = 'cubepi_runs'",
(cfg["db"],),
)
rows = await cur.fetchall()
@@ -37,7 +37,7 @@ async def test_cubeloop_runs_table_present(mysql_v4_dsn) -> None:
@pytest.mark.asyncio
-async def test_cubeloop_messages_has_run_id_column(mysql_v4_dsn) -> None:
+async def test_cubepi_messages_has_run_id_column(mysql_v4_dsn) -> None:
from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn
cfg = _parse_dsn(mysql_v4_dsn)
@@ -46,7 +46,7 @@ async def test_cubeloop_messages_has_run_id_column(mysql_v4_dsn) -> None:
async with conn.cursor() as cur:
await cur.execute(
"SELECT data_type FROM information_schema.columns "
- "WHERE table_schema = %s AND table_name = 'cubeloop_messages' "
+ "WHERE table_schema = %s AND table_name = 'cubepi_messages' "
"AND column_name = 'run_id'",
(cfg["db"],),
)
@@ -57,7 +57,7 @@ async def test_cubeloop_messages_has_run_id_column(mysql_v4_dsn) -> None:
@pytest.mark.asyncio
-async def test_cubeloop_hitl_answers_table_present(mysql_v4_dsn) -> None:
+async def test_cubepi_hitl_answers_table_present(mysql_v4_dsn) -> None:
from cubeloop.checkpointer.mysql.checkpointer import _parse_dsn
cfg = _parse_dsn(mysql_v4_dsn)
@@ -67,7 +67,7 @@ async def test_cubeloop_hitl_answers_table_present(mysql_v4_dsn) -> None:
await cur.execute(
"SELECT column_name FROM information_schema.columns "
"WHERE table_schema = %s "
- "AND table_name = 'cubeloop_hitl_answers'",
+ "AND table_name = 'cubepi_hitl_answers'",
(cfg["db"],),
)
rows = await cur.fetchall()
diff --git a/tests/checkpointer/test_postgres.py b/tests/checkpointer/test_postgres.py
index be02839..23f3bb4 100644
--- a/tests/checkpointer/test_postgres.py
+++ b/tests/checkpointer/test_postgres.py
@@ -3,6 +3,8 @@
Full E2E tests are in D1.3 once PostgresCheckpointer is implemented.
"""
+from pathlib import Path
+
import asyncpg
import pytest
@@ -18,23 +20,23 @@ def test_models_import() -> None:
cubeloop_metadata,
)
- assert EXPECTED_SCHEMA_VERSION == 6
+ assert EXPECTED_SCHEMA_VERSION == 5
assert PARTITION_COUNT == 64
- assert CubeloopThread.__tablename__ == "cubeloop_threads"
- assert CubeloopMessage.__tablename__ == "cubeloop_messages"
- assert CubeloopHitlAnswer.__tablename__ == "cubeloop_hitl_answers"
- assert CubeloopSchemaVersion.__tablename__ == "cubeloop_schema_version"
- assert "cubeloop_threads" in cubeloop_metadata.tables
- assert "cubeloop_messages" in cubeloop_metadata.tables
- assert "cubeloop_hitl_answers" in cubeloop_metadata.tables
- assert "cubeloop_schema_version" in cubeloop_metadata.tables
+ assert CubeloopThread.__tablename__ == "cubepi_threads"
+ assert CubeloopMessage.__tablename__ == "cubepi_messages"
+ assert CubeloopHitlAnswer.__tablename__ == "cubepi_hitl_answers"
+ assert CubeloopSchemaVersion.__tablename__ == "cubepi_schema_version"
+ assert "cubepi_threads" in cubeloop_metadata.tables
+ assert "cubepi_messages" in cubeloop_metadata.tables
+ assert "cubepi_hitl_answers" in cubeloop_metadata.tables
+ assert "cubepi_schema_version" in cubeloop_metadata.tables
def test_cubepi_message_has_partition_by() -> None:
"""The CubepiMessage table declares HASH partitioning."""
from cubeloop.checkpointer.postgres.models import cubeloop_metadata
- msgs = cubeloop_metadata.tables["cubeloop_messages"]
+ msgs = cubeloop_metadata.tables["cubepi_messages"]
# SQLAlchemy stores PG partition clause in info or dialect-specific args
# Verify via dialect kwargs
assert msgs.kwargs.get("postgresql_partition_by") == "HASH (thread_id)"
@@ -44,9 +46,9 @@ def test_cubepi_message_has_gin_index() -> None:
"""The GIN index on metadata is registered."""
from cubeloop.checkpointer.postgres.models import cubeloop_metadata
- msgs = cubeloop_metadata.tables["cubeloop_messages"]
+ msgs = cubeloop_metadata.tables["cubepi_messages"]
idx_names = [i.name for i in msgs.indexes]
- assert "ix_cubeloop_messages_metadata_gin" in idx_names
+ assert "ix_cubepi_messages_metadata_gin" in idx_names
def test_create_message_partitions_op_yields_64_statements() -> None:
@@ -55,7 +57,7 @@ def test_create_message_partitions_op_yields_64_statements() -> None:
)
sql = create_message_partitions_op()
- assert sql.count("CREATE TABLE cubeloop_messages_p") == 64
+ assert sql.count("CREATE TABLE cubepi_messages_p") == 64
assert "modulus 64, remainder 0" in sql
assert "modulus 64, remainder 63" in sql
@@ -67,8 +69,8 @@ def test_create_message_partitions_op_partitions_are_zero_padded() -> None:
sql = create_message_partitions_op()
# Partition names use 2-digit padding so they sort lexicographically
- assert "cubeloop_messages_p00 " in sql
- assert "cubeloop_messages_p63 " in sql
+ assert "cubepi_messages_p00 " in sql
+ assert "cubepi_messages_p63 " in sql
def test_write_schema_version_op_includes_expected_version() -> None:
@@ -76,7 +78,7 @@ def test_write_schema_version_op_includes_expected_version() -> None:
from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION
sql = write_schema_version_op()
- assert "cubeloop_schema_version" in sql
+ assert "cubepi_schema_version" in sql
assert "cubepi_schema_version" in sql
assert f"VALUES ({EXPECTED_SCHEMA_VERSION})" in sql
assert "ON CONFLICT" in sql
@@ -88,7 +90,7 @@ def test_write_schema_version_op_clears_stale_rows() -> None:
from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION
sql = write_schema_version_op()
- assert "DELETE FROM cubeloop_schema_version" in sql
+ assert "DELETE FROM cubepi_schema_version" in sql
assert "DELETE FROM cubepi_schema_version" in sql
assert f"WHERE version <> {EXPECTED_SCHEMA_VERSION}" in sql
assert sql.index("DELETE") < sql.index("INSERT")
@@ -186,9 +188,9 @@ async def _setup_schema(dsn: str) -> None:
conn = await asyncpg.connect(dsn)
try:
await conn.execute("""
- CREATE TABLE cubeloop_threads (
+ CREATE TABLE cubepi_threads (
thread_id TEXT PRIMARY KEY,
- parent_thread_id TEXT REFERENCES cubeloop_threads(thread_id),
+ parent_thread_id TEXT REFERENCES cubepi_threads(thread_id),
forked_at_seq BIGINT,
extra JSONB NOT NULL DEFAULT '{}'::jsonb,
pending_request JSONB,
@@ -198,8 +200,8 @@ async def _setup_schema(dsn: str) -> None:
);
""")
await conn.execute("""
- CREATE TABLE cubeloop_messages (
- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,
+ CREATE TABLE cubepi_messages (
+ thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
seq BIGINT NOT NULL,
role TEXT NOT NULL,
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
@@ -211,21 +213,21 @@ async def _setup_schema(dsn: str) -> None:
""")
await conn.execute(create_message_partitions_op())
await conn.execute("""
- CREATE INDEX ix_cubeloop_messages_metadata_gin
- ON cubeloop_messages USING GIN (metadata jsonb_path_ops);
+ CREATE INDEX ix_cubepi_messages_metadata_gin
+ ON cubepi_messages USING GIN (metadata jsonb_path_ops);
""")
await conn.execute("""
- CREATE INDEX ix_cubeloop_messages_thread_run
- ON cubeloop_messages (thread_id, run_id);
+ CREATE INDEX ix_cubepi_messages_thread_run
+ ON cubepi_messages (thread_id, run_id);
""")
await conn.execute("""
- CREATE TABLE cubeloop_schema_version (
+ CREATE TABLE cubepi_schema_version (
version INTEGER PRIMARY KEY
);
""")
await conn.execute("""
- CREATE TABLE cubeloop_runs (
- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,
+ CREATE TABLE cubepi_runs (
+ thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
run_id TEXT NOT NULL,
claimed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
completed_at TIMESTAMPTZ,
@@ -235,12 +237,12 @@ async def _setup_schema(dsn: str) -> None:
""")
await conn.execute(create_runs_partitions_op())
await conn.execute("""
- CREATE INDEX ix_cubeloop_runs_thread_seq
- ON cubeloop_runs (thread_id, completion_seq);
+ CREATE INDEX ix_cubepi_runs_thread_seq
+ ON cubepi_runs (thread_id, completion_seq);
""")
await conn.execute("""
- CREATE TABLE cubeloop_hitl_answers (
- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,
+ CREATE TABLE cubepi_hitl_answers (
+ thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
run_id TEXT NOT NULL,
question_id TEXT NOT NULL,
answer JSONB NOT NULL,
@@ -406,7 +408,7 @@ async def test_version_mismatch_raises(clean_db) -> None:
await _setup_schema(clean_db)
conn = await asyncpg.connect(clean_db)
try:
- await conn.execute("UPDATE cubeloop_schema_version SET version = 999")
+ await conn.execute("UPDATE cubepi_schema_version SET version = 999")
finally:
await conn.close()
@@ -450,9 +452,9 @@ async def test_postgres_load_corrupt_row_raises_typed(clean_db) -> None:
conn = await asyncpg.connect(clean_db)
try:
await conn.execute(
- "UPDATE cubeloop_messages SET payload = $1 "
+ "UPDATE cubepi_messages SET payload = $1 "
"WHERE thread_id = 't-corrupt' AND seq = ("
- " SELECT max(seq) FROM cubeloop_messages "
+ " SELECT max(seq) FROM cubepi_messages "
" WHERE thread_id = 't-corrupt')",
b"\xc1 not msgpack",
)
@@ -465,7 +467,7 @@ async def test_postgres_load_corrupt_row_raises_typed(clean_db) -> None:
err = excinfo.value
assert err.thread_id == "t-corrupt"
assert err.backend == "postgres"
- assert err.row_ref.startswith("cubeloop_messages.seq=")
+ assert err.row_ref.startswith("cubepi_messages.seq=")
assert err.__cause__ is not None
@@ -481,7 +483,7 @@ async def test_postgres_load_unknown_role_raises_typed(clean_db) -> None:
conn = await asyncpg.connect(clean_db)
try:
await conn.execute(
- "UPDATE cubeloop_messages SET role = 'alien' WHERE thread_id = 't-role'"
+ "UPDATE cubepi_messages SET role = 'alien' WHERE thread_id = 't-role'"
)
finally:
await conn.close()
@@ -494,60 +496,114 @@ async def test_postgres_load_unknown_role_raises_typed(clean_db) -> None:
@pytest.mark.asyncio
-async def test_unmigrated_v5_raises_mismatch_not_uninitialized(clean_db) -> None:
- from cubeloop.checkpointer.postgres import (
- CubeloopSchemaMismatch,
- PostgresCheckpointer,
- )
+async def test_existing_v5_schema_round_trip_without_migration(clean_db) -> None:
+ from cubeloop.checkpointer.postgres import PostgresCheckpointer
+ from cubeloop.providers.base import TextContent, UserMessage
await _setup_schema_v5(clean_db)
- with pytest.raises(CubeloopSchemaMismatch) as ei:
- async with PostgresCheckpointer(clean_db):
- pass
- assert ei.value.expected == 6
- assert ei.value.actual == 5
- assert "upgrade_v5_to_v6_op" in str(ei.value)
+ async with PostgresCheckpointer(clean_db) as cp:
+ await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])
+ data = await cp.load("t-mig")
+ assert data is not None
+ assert len(data.messages) == 1
@pytest.mark.asyncio
-async def test_v5_to_v6_rename_then_round_trip(clean_db) -> None:
- from cubeloop.checkpointer.postgres.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
- )
+async def test_withdrawn_v6_recovery_script_round_trip(clean_db) -> None:
from cubeloop.checkpointer.postgres import PostgresCheckpointer
from cubeloop.providers.base import TextContent, UserMessage
await _setup_schema_v5(clean_db)
conn = await asyncpg.connect(clean_db)
try:
- await conn.execute(upgrade_v5_to_v6_op())
- await conn.execute(write_schema_version_op())
- # Idempotent on complete v6.
- await conn.execute(upgrade_v5_to_v6_op())
- names = {
- r["table_name"]
- for r in await conn.fetch(
- "SELECT table_name FROM information_schema.tables "
- "WHERE table_schema = 'public'"
+ await conn.execute(
+ "INSERT INTO cubepi_threads (thread_id, extra) VALUES ('kept', '{}')"
+ )
+ await conn.execute("ALTER TABLE cubepi_threads RENAME TO cubeloop_threads")
+ await conn.execute("ALTER TABLE cubepi_messages RENAME TO cubeloop_messages")
+ for i in range(64):
+ await conn.execute(
+ f"ALTER TABLE cubepi_messages_p{i:02d} "
+ f"RENAME TO cubeloop_messages_p{i:02d}"
+ )
+ await conn.execute("ALTER TABLE cubepi_runs RENAME TO cubeloop_runs")
+ for i in range(64):
+ await conn.execute(
+ f"ALTER TABLE cubepi_runs_p{i:02d} RENAME TO cubeloop_runs_p{i:02d}"
+ )
+ await conn.execute(
+ "ALTER TABLE cubepi_hitl_answers RENAME TO cubeloop_hitl_answers"
+ )
+ await conn.execute(
+ "ALTER TABLE cubepi_schema_version RENAME TO cubeloop_schema_version"
+ )
+ await conn.execute(
+ "ALTER INDEX ix_cubepi_messages_metadata_gin "
+ "RENAME TO ix_cubeloop_messages_metadata_gin"
+ )
+ await conn.execute(
+ "ALTER INDEX ix_cubepi_messages_thread_run "
+ "RENAME TO ix_cubeloop_messages_thread_run"
+ )
+ await conn.execute(
+ "ALTER INDEX ix_cubepi_runs_thread_seq "
+ "RENAME TO ix_cubeloop_runs_thread_seq"
+ )
+ await conn.execute("UPDATE cubeloop_schema_version SET version = 6")
+ await conn.execute(
+ Path("website/static/recovery/0.14.0/postgres-v6-to-v5.sql").read_text()
+ )
+ assert (
+ await conn.fetchval(
+ "SELECT count(*) FROM cubepi_threads WHERE thread_id = 'kept'"
+ )
+ == 1
+ )
+ assert await conn.fetchval("SELECT version FROM cubepi_schema_version") == 5
+ assert (
+ await conn.fetchval(
+ "SELECT count(*) FROM pg_inherits i "
+ "JOIN pg_class p ON p.oid = i.inhparent "
+ "WHERE p.relname IN ('cubepi_messages', 'cubepi_runs')"
+ )
+ == 128
+ )
+ index_names = {
+ row["indexname"]
+ for row in await conn.fetch(
+ "SELECT indexname FROM pg_indexes WHERE schemaname = current_schema()"
)
}
- assert "cubeloop_threads" in names
- assert "cubeloop_messages" in names
- assert "cubeloop_runs" in names
- assert "cubeloop_hitl_answers" in names
- assert "cubeloop_schema_version" in names
- assert "cubepi_threads" not in names
+ assert "ix_cubepi_messages_thread_run" in index_names
+ assert "ix_cubepi_runs_thread_seq" in index_names
finally:
await conn.close()
async with PostgresCheckpointer(clean_db) as cp:
- await cp.append("t-mig", [UserMessage(content=[TextContent(text="hi")])])
- data = await cp.load("t-mig")
+ await cp.append("recovered", [UserMessage(content=[TextContent(text="ok")])])
+ data = await cp.load("recovered")
assert data is not None
assert len(data.messages) == 1
+async def test_withdrawn_v6_recovery_collision_is_atomic(clean_db) -> None:
+ await _setup_schema_v5(clean_db)
+ conn = await asyncpg.connect(clean_db)
+ try:
+ await conn.execute("ALTER TABLE cubepi_threads RENAME TO cubeloop_threads")
+ await conn.execute("CREATE TABLE cubepi_threads (thread_id TEXT PRIMARY KEY)")
+ with pytest.raises(asyncpg.PostgresError):
+ await conn.execute(
+ Path("website/static/recovery/0.14.0/postgres-v6-to-v5.sql").read_text()
+ )
+ await conn.execute("ROLLBACK")
+ assert await conn.fetchval("SELECT to_regclass('cubeloop_threads')")
+ assert await conn.fetchval("SELECT to_regclass('cubepi_threads')")
+ finally:
+ await conn.close()
+
+
@pytest.mark.asyncio
async def test_data_tables_without_version_table_are_not_uninitialized(
clean_db,
@@ -573,3 +629,30 @@ async def test_data_tables_without_version_table_are_not_uninitialized(
pass
assert "Uninitialized" not in type(ei.value).__name__
assert not isinstance(ei.value, CubeloopSchemaUninitialized)
+
+
[email protected]("stored_version", [5, 6])
+async def test_withdrawn_v6_schema_points_to_recovery(
+ clean_db, stored_version: int
+) -> None:
+ from cubeloop.checkpointer.postgres import (
+ CubeloopSchemaMismatch,
+ PostgresCheckpointer,
+ )
+
+ conn = await asyncpg.connect(clean_db)
+ try:
+ await conn.execute(
+ "CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY)"
+ )
+ await conn.execute(
+ "INSERT INTO cubeloop_schema_version VALUES ($1)", stored_version
+ )
+ finally:
+ await conn.close()
+ with pytest.raises(CubeloopSchemaMismatch) as exc_info:
+ async with PostgresCheckpointer(clean_db):
+ pass
+ assert exc_info.value.actual == stored_version
+ assert "withdrawn 0.14.0" in str(exc_info.value)
diff --git a/tests/checkpointer/test_postgres_runs.py b/tests/checkpointer/test_postgres_runs.py
index 2071d01..4279fa2 100644
--- a/tests/checkpointer/test_postgres_runs.py
+++ b/tests/checkpointer/test_postgres_runs.py
@@ -19,12 +19,12 @@ async def test_claim_run_creates_threads_row_lazily(pg_v4_dsn):
conn = await asyncpg.connect(pg_v4_dsn)
try:
row = await conn.fetchrow(
- "SELECT thread_id FROM cubeloop_threads WHERE thread_id = $1",
+ "SELECT thread_id FROM cubepi_threads WHERE thread_id = $1",
"t-lazy",
)
assert row is not None
run = await conn.fetchrow(
- "SELECT completed_at FROM cubeloop_runs WHERE thread_id = $1 AND run_id = $2",
+ "SELECT completed_at FROM cubepi_runs WHERE thread_id = $1 AND run_id = $2",
"t-lazy",
"r1",
)
@@ -86,7 +86,7 @@ async def test_completion_seq_monotonic_per_thread(pg_v4_dsn):
conn = await asyncpg.connect(pg_v4_dsn)
try:
rows = await conn.fetch(
- "SELECT run_id, completion_seq FROM cubeloop_runs "
+ "SELECT run_id, completion_seq FROM cubepi_runs "
"WHERE thread_id = $1 ORDER BY completion_seq",
"t",
)
@@ -132,7 +132,7 @@ async def test_append_persists_run_id_into_column(pg_v4_dsn):
conn = await asyncpg.connect(pg_v4_dsn)
try:
row = await conn.fetchrow(
- "SELECT run_id FROM cubeloop_messages WHERE thread_id = $1",
+ "SELECT run_id FROM cubepi_messages WHERE thread_id = $1",
"t",
)
assert row is not None
diff --git a/tests/checkpointer/test_postgres_schema.py b/tests/checkpointer/test_postgres_schema.py
index 9a5f454..69d54f4 100644
--- a/tests/checkpointer/test_postgres_schema.py
+++ b/tests/checkpointer/test_postgres_schema.py
@@ -5,21 +5,20 @@ from cubeloop.checkpointer.postgres.checkpointer import _schema_mismatch_hint
from cubeloop.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION
-def test_expected_schema_version_is_6():
- assert EXPECTED_SCHEMA_VERSION == 6
-
-
-def test_schema_mismatch_hint_names_the_v5_to_v6_helper():
- hint = _schema_mismatch_hint(actual=5, expected=6)
- assert "upgrade_v5_to_v6_op()" in hint
- assert "add_run_id_column_op" not in hint
+def test_expected_schema_version_is_5():
+ assert EXPECTED_SCHEMA_VERSION == 5
def test_schema_mismatch_hint_names_every_step_across_multiple_versions():
- hint = _schema_mismatch_hint(actual=3, expected=6)
+ hint = _schema_mismatch_hint(actual=3, expected=5)
assert "upgrade_v3_to_v4_op()" in hint
assert "upgrade_v4_to_v5_op()" in hint
- assert "upgrade_v5_to_v6_op()" in hint
+
+
+def test_newer_schema_hint_points_to_withdrawn_release_recovery():
+ hint = _schema_mismatch_hint(actual=6, expected=5)
+ assert "withdrawn 0.14.0" in hint
+ assert "call +" not in hint
@pytest.mark.asyncio
@@ -28,7 +27,7 @@ async def test_cubepi_runs_table_present(pg_v4_dsn):
try:
rows = await conn.fetch(
"SELECT column_name FROM information_schema.columns "
- "WHERE table_name = 'cubeloop_runs'"
+ "WHERE table_name = 'cubepi_runs'"
)
cols = {r["column_name"] for r in rows}
assert {
@@ -48,7 +47,7 @@ async def test_cubepi_messages_has_run_id_column(pg_v4_dsn):
try:
row = await conn.fetchrow(
"SELECT data_type FROM information_schema.columns "
- "WHERE table_name = 'cubeloop_messages' AND column_name = 'run_id'"
+ "WHERE table_name = 'cubepi_messages' AND column_name = 'run_id'"
)
assert row is not None
finally:
@@ -61,7 +60,7 @@ async def test_cubepi_hitl_answers_table_present(pg_v4_dsn):
try:
rows = await conn.fetch(
"SELECT column_name FROM information_schema.columns "
- "WHERE table_name = 'cubeloop_hitl_answers'"
+ "WHERE table_name = 'cubepi_hitl_answers'"
)
cols = {r["column_name"] for r in rows}
assert {
diff --git a/tests/checkpointer/test_save_pending_request_run_id.py b/tests/checkpointer/test_save_pending_request_run_id.py
index bf9af8a..c6c8e24 100644
--- a/tests/checkpointer/test_save_pending_request_run_id.py
+++ b/tests/checkpointer/test_save_pending_request_run_id.py
@@ -145,9 +145,9 @@ async def _setup_pg_schema_v3(dsn: str) -> None:
conn = await asyncpg.connect(dsn)
try:
await conn.execute("""
- CREATE TABLE cubeloop_threads (
+ CREATE TABLE cubepi_threads (
thread_id TEXT PRIMARY KEY,
- parent_thread_id TEXT NULL REFERENCES cubeloop_threads(thread_id),
+ parent_thread_id TEXT NULL REFERENCES cubepi_threads(thread_id),
forked_at_seq BIGINT NULL,
extra JSONB NOT NULL DEFAULT '{}'::jsonb,
pending_request JSONB,
@@ -157,8 +157,8 @@ async def _setup_pg_schema_v3(dsn: str) -> None:
);
""")
await conn.execute("""
- CREATE TABLE cubeloop_messages (
- thread_id TEXT NOT NULL REFERENCES cubeloop_threads(thread_id) ON DELETE CASCADE,
+ CREATE TABLE cubepi_messages (
+ thread_id TEXT NOT NULL REFERENCES cubepi_threads(thread_id) ON DELETE CASCADE,
seq BIGINT NOT NULL,
role TEXT NOT NULL,
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
@@ -169,11 +169,11 @@ async def _setup_pg_schema_v3(dsn: str) -> None:
""")
await conn.execute(create_message_partitions_op())
await conn.execute("""
- CREATE INDEX ix_cubeloop_messages_metadata_gin
- ON cubeloop_messages USING GIN (metadata jsonb_path_ops);
+ CREATE INDEX ix_cubepi_messages_metadata_gin
+ ON cubepi_messages USING GIN (metadata jsonb_path_ops);
""")
await conn.execute("""
- CREATE TABLE cubeloop_schema_version (version INTEGER PRIMARY KEY);
+ CREATE TABLE cubepi_schema_version (version INTEGER PRIMARY KEY);
""")
await conn.execute(write_schema_version_op())
finally:
@@ -238,7 +238,7 @@ async def _setup_mysql_schema_v3(dsn: str) -> None:
try:
async with conn.cursor() as cur:
await cur.execute("""
- CREATE TABLE cubeloop_threads (
+ CREATE TABLE cubepi_threads (
thread_id VARCHAR(255) COLLATE utf8mb4_bin PRIMARY KEY,
parent_thread_id VARCHAR(255) COLLATE utf8mb4_bin NULL,
forked_at_seq BIGINT NULL,
@@ -249,12 +249,12 @@ async def _setup_mysql_schema_v3(dsn: str) -> None:
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP,
CONSTRAINT fk_parent FOREIGN KEY (parent_thread_id)
- REFERENCES cubeloop_threads (thread_id)
+ REFERENCES cubepi_threads (thread_id)
) ENGINE=InnoDB
""")
await cur.execute(
"""
- CREATE TABLE cubeloop_messages (
+ CREATE TABLE cubepi_messages (
thread_id VARCHAR(255) COLLATE utf8mb4_bin NOT NULL,
seq BIGINT NOT NULL,
role VARCHAR(32) NOT NULL,
@@ -266,7 +266,7 @@ async def _setup_mysql_schema_v3(dsn: str) -> None:
+ messages_partition_clause()
)
await cur.execute("""
- CREATE TABLE cubeloop_schema_version (
+ CREATE TABLE cubepi_schema_version (
version INT PRIMARY KEY
) ENGINE=InnoDB
""")
diff --git a/uv.lock b/uv.lock
index b3a51a8..618f90e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -528,7 +528,7 @@ wheels = [
[[package]]
name = "cubeloop"
-version = "0.14.0"
+version = "0.14.1"
source = { editable = "." }
dependencies = [
{ name = "anthropic" },
@@ -624,7 +624,7 @@ dev = [
[[package]]
name = "cubepi"
-version = "0.14.0"
+version = "0.14.1"
source = { editable = "compat/cubepi" }
dependencies = [
{ name = "cubeloop" },
diff --git a/website/docs/guides/checkpointing/mysql.md b/website/docs/guides/checkpointing/mysql.md
index e636840..29e3b49 100644
--- a/website/docs/guides/checkpointing/mysql.md
+++ b/website/docs/guides/checkpointing/mysql.md
@@ -61,8 +61,8 @@ async with MySQLCheckpointer(
## Schema
-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,
-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`. Like
+The checkpointer expects `cubepi_threads`, `cubepi_messages`,
+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`. Like
Postgres (and unlike SQLite), CubeLoop **does not create these for you** —
it verifies on `__aenter__` that they exist with the expected
`schema_version`.
@@ -90,7 +90,7 @@ Then autogenerate a revision:
alembic revision --autogenerate -m "add cubeloop checkpointer"
```
-The `cubeloop_messages` table is `KEY`-partitioned, which SQLAlchemy's
+The `cubepi_messages` table is `KEY`-partitioned, which SQLAlchemy's
autogenerate cannot express, so append the partition clause and the
schema-version write with the provided helpers:
@@ -102,16 +102,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import (
)
def upgrade():
- op.create_table("cubeloop_threads", ...)
+ op.create_table("cubepi_threads", ...)
op.create_table(
- "cubeloop_messages", ...,
+ "cubepi_messages", ...,
mysql_engine="InnoDB",
)
# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:
op.execute(
- "ALTER TABLE cubeloop_messages " + messages_partition_clause()
+ "ALTER TABLE cubepi_messages " + messages_partition_clause()
)
- op.create_table("cubeloop_schema_version", ...)
+ op.create_table("cubepi_schema_version", ...)
# write_schema_version_op() returns two ';'-separated statements
# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,
# so split and execute each:
@@ -128,31 +128,31 @@ again.
## Data model
```
-cubeloop_threads
+cubepi_threads
thread_id (PK) -- VARCHAR(255) utf8mb4_bin (case-sensitive)
parent_thread_id -- self-FK, for forks
forked_at_seq -- seq number at fork point
extra -- JSON
created_at / updated_at
-cubeloop_messages
+cubepi_messages
thread_id, seq -- composite PK; partitioned by KEY(thread_id) into 64
role -- "user" | "assistant" | "tool"
metadata -- JSON (not indexed; see below)
payload -- LONGBLOB (msgpack)
created_at
-cubeloop_runs
+cubepi_runs
thread_id, run_id -- composite PK
claimed_at / completed_at
completion_seq
-cubeloop_hitl_answers
+cubepi_hitl_answers
thread_id, run_id, question_id -- composite PK
answer -- JSON
answered_at
-cubeloop_schema_version
+cubepi_schema_version
version (PK)
```
@@ -199,8 +199,8 @@ from `dict.update`.)
`MySQLCheckpointer` implements the v4 `snapshot` / `fork` /
`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,
so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The
-`parent_thread_id` / `forked_at_seq` columns on `cubeloop_threads`
-record fork lineage; `cubeloop_runs` (added in v4) tracks per-run
+`parent_thread_id` / `forked_at_seq` columns on `cubepi_threads`
+record fork lineage; `cubepi_runs` (added in v4) tracks per-run
claim/completion state.
See the [Conversation Forking](../agents/forking) guide for the user-facing
@@ -258,34 +258,17 @@ def upgrade():
op.execute(stmt)
```
-## Schema v5 → v6 migration
+## CubeLoop rename
-0.14 renames the MySQL tables from `cubepi_*` to `cubeloop_*`.
-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14
-checkpointer on an existing database:
-
-```python
-from cubeloop.checkpointer.mysql.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
- for stmt in write_schema_version_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
-```
-
-Do not run the v6 `CREATE TABLE` helpers against a v5 database. See the
-[migration guide](../../migration/from-cubepi).
+The package rename does not change the persistence schema: physical names stay
+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need
+no migration. See the [migration guide](../../migration/from-cubepi), including
+the exceptional recovery path for withdrawn 0.14.0.
## Common pitfalls
- **`CubeloopSchemaUninitialized`** — Your DB is empty, your migrations
- didn't run, or the `cubeloop_schema_version` table is malformed. Apply
+ didn't run, or the `cubepi_schema_version` table is malformed. Apply
the host alembic upgrade first.
- **`CubeloopSchemaMismatch`** — You upgraded CubeLoop but didn't generate a
new migration. Generate one, apply it, and CubeLoop will start.
@@ -296,7 +279,7 @@ Do not run the v6 `CREATE TABLE` helpers against a v5 database. See the
hand-roll the DDL, keep that collation.
- **`CheckpointCorruptionError` on `load()`** — A persisted message row
failed to deserialize (bad msgpack payload, schema-invalid data, or an
- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)
+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)
locates the bad row for inspection or surgical repair; `thread_id` and
`__cause__` carry the rest. CubeLoop never skips corrupt rows silently.
diff --git a/website/docs/guides/checkpointing/postgres.md b/website/docs/guides/checkpointing/postgres.md
index 9cfc204..938a20b 100644
--- a/website/docs/guides/checkpointing/postgres.md
+++ b/website/docs/guides/checkpointing/postgres.md
@@ -54,8 +54,8 @@ async with PostgresCheckpointer(
## Schema
-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,
-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`.
+The checkpointer expects `cubepi_threads`, `cubepi_messages`,
+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`.
Unlike SQLite, CubeLoop
**does not create these for you** — it verifies on `__aenter__` that
they exist with the expected `schema_version`.
@@ -89,9 +89,9 @@ alembic revision --autogenerate -m "add cubeloop checkpointer"
Autogenerate emits the `CREATE TABLE`s from `cubeloop_metadata`, but
SQLAlchemy `MetaData` **cannot model two things CubeLoop needs**, so add
them to the generated migration by hand: the 64 hash partitions of
-`cubeloop_messages` (via `create_message_partitions_op()`), the 64
-partitions of `cubeloop_runs` (via `create_runs_partitions_op()`), and
-the `cubeloop_schema_version` row (via `write_schema_version_op()`). Use
+`cubepi_messages` (via `create_message_partitions_op()`), the 64
+partitions of `cubepi_runs` (via `create_runs_partitions_op()`), and
+the `cubepi_schema_version` row (via `write_schema_version_op()`). Use
the helpers:
```python
@@ -104,8 +104,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
def upgrade():
op.create_table(...) # auto-generated from cubeloop_metadata
- op.execute(create_message_partitions_op()) # 64 hash partitions of cubeloop_messages
- op.execute(create_runs_partitions_op()) # 64 hash partitions of cubeloop_runs
+ 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
```
@@ -120,31 +120,31 @@ again.
## Data model
```
-cubeloop_threads
+cubepi_threads
thread_id (PK)
parent_thread_id -- for forks
forked_at_seq -- seq number at fork point
extra -- JSONB
created_at / updated_at
-cubeloop_messages
+cubepi_messages
thread_id, seq -- composite PK; partitioned by HASH(thread_id) into 64
role -- "user" | "assistant" | "tool"
metadata -- JSONB (indexed via GIN)
payload -- bytea (msgpack)
created_at
-cubeloop_runs
+cubepi_runs
thread_id, run_id -- composite PK
claimed_at / completed_at
completion_seq
-cubeloop_hitl_answers
+cubepi_hitl_answers
thread_id, run_id, question_id -- composite PK
answer -- JSONB
answered_at
-cubeloop_schema_version
+cubepi_schema_version
version (PK)
```
@@ -182,7 +182,7 @@ The pool default of `min=1, max=10` is fine for most apps; bump
`save_extra` does a JSONB merge, not a replace:
```sql
-extra = cubeloop_threads.extra || EXCLUDED.extra
+extra = cubepi_threads.extra || EXCLUDED.extra
```
So writing `{"foo": 1}` then `{"bar": 2}` leaves `{"foo": 1, "bar":
@@ -194,8 +194,8 @@ keys.
`PostgresCheckpointer` implements the v4 `snapshot` / `fork` /
`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,
so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The
-`parent_thread_id` and `forked_at_seq` columns on `cubeloop_threads`
-record fork lineage; `cubeloop_runs` (the v4 partitioned table) tracks
+`parent_thread_id` and `forked_at_seq` columns on `cubepi_threads`
+record fork lineage; `cubepi_runs` (the v4 partitioned table) tracks
per-run claim/completion state.
See the [Conversation Forking](../agents/forking) guide for the user-facing
@@ -246,26 +246,12 @@ def upgrade():
op.execute(write_schema_version_op()) # bumps cubepi_schema_version to 5
```
-## Schema v5 → v6 migration
+## CubeLoop rename
-0.14 renames the Postgres tables from `cubepi_*` to `cubeloop_*`.
-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14
-checkpointer on an existing database:
-
-```python
-from cubeloop.checkpointer.postgres.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- op.execute(upgrade_v5_to_v6_op())
- op.execute(write_schema_version_op()) # writes 6 into cubeloop_schema_version
-```
-
-Do not run the v6 `CREATE TABLE` helpers against a v5 database — they
-would try to create tables that already exist under the old names.
-See the [migration guide](../../migration/from-cubepi).
+The package rename does not change the persistence schema: physical names stay
+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need
+no migration. See the [migration guide](../../migration/from-cubepi), including
+the exceptional recovery path for withdrawn 0.14.0.
## Common pitfalls
@@ -295,7 +281,7 @@ See the [migration guide](../../migration/from-cubepi).
— pass both to Alembic separately.
- **`CheckpointCorruptionError` on `load()`** — A persisted message row
failed to deserialize (bad msgpack payload, schema-invalid data, or an
- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)
+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)
locates the bad row for inspection or surgical repair; `thread_id` and
`__cause__` carry the rest. CubeLoop never skips corrupt rows silently —
dropping a message that carries `tool_calls` would leave the
diff --git a/website/docs/migration/from-cubepi.md b/website/docs/migration/from-cubepi.md
index 327a545..e201c52 100644
--- a/website/docs/migration/from-cubepi.md
+++ b/website/docs/migration/from-cubepi.md
@@ -21,25 +21,37 @@ from cubeloop import Agent, tool
from cubeloop.providers.anthropic import AnthropicProvider
```
-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on
-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.
+`pip install -U cubepi` still works: 0.14.1+ is a wrapper that depends on a
+compatible CubeLoop 0.14 release, re-exports the public API, and aliases
+`cubepi.*` imports.
It warns on first import. Prefer depending on `cubeloop` directly.
CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).
-## Checkpointer schema v5 → v6
+## Checkpointer schema stays at v5
-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.
+Postgres and MySQL keep their `cubepi_*` physical table and index names. They
+are persistent protocol identifiers, not product branding. Schema version 5 is
+unchanged, so an existing 0.13.6 database needs no migration for 0.14.1.
SQLite table names were never prefixed; they stay `messages` / `runs` / ….
-Existing databases: add an Alembic revision that runs
-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against
-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that
-helper — not “tables not found”.
+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.
-If you have data tables but no `*_schema_version` table, do not apply the
-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,
-then run the v5→v6 helper.
+### Emergency recovery from withdrawn 0.14.0
+
+0.14.0 was yanked because it briefly renamed these database objects to
+`cubeloop_*`. Only use this recovery if 0.14.0 created the database or you ran its withdrawn
+migration. Stop every application instance, take a verified backup, then run
+the script for your database with an administrative SQL client:
+
+- [Postgres v6→v5 recovery SQL](/recovery/0.14.0/postgres-v6-to-v5.sql)
+- [MySQL v6→v5 recovery SQL](/recovery/0.14.0/mysql-v6-to-v5.sql)
+
+The scripts refuse mixed/colliding schemas before renaming anything. Afterward,
+verify table and row counts, then deploy 0.14.1. Do not run them on a normal v5
+database.
## Tracing
diff --git a/website/docs/recipes/postgres-fastapi.md b/website/docs/recipes/postgres-fastapi.md
index ff26ae5..7450637 100644
--- a/website/docs/recipes/postgres-fastapi.md
+++ b/website/docs/recipes/postgres-fastapi.md
@@ -20,13 +20,13 @@ Before the service starts, run the CubeLoop schema migration. The
quickest way for this recipe:
```bash
-# Throwaway / recipe: copy the v6 bootstrap from
-# examples/checkpointing_postgres.py (cubeloop_threads, cubeloop_messages +
-# 64 partitions, cubeloop_runs + 64 partitions, cubeloop_hitl_answers,
-# cubeloop_schema_version = 6).
+# Throwaway / recipe: copy the v5 bootstrap from
+# examples/checkpointing_postgres.py (cubepi_threads, cubepi_messages +
+# 64 partitions, cubepi_runs + 64 partitions, cubepi_hitl_answers,
+# cubepi_schema_version = 5).
```
-Existing v5 databases must run `upgrade_v5_to_v6_op()` instead of CREATE.
+Existing v5 databases need no migration for the CubeLoop package rename.
For a real deployment, generate this via Alembic — see
[Postgres Checkpointing → Bootstrapping via Alembic](../guides/checkpointing/postgres#bootstrapping-via-alembic).
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 fab1637..33323fd 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
@@ -53,7 +53,7 @@ async with MySQLCheckpointer(
## Schema
-Checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。
+Checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。
若表不存在,会抛出 `CubeloopSchemaUninitialized`;若版本与当前 CubeLoop 版本不匹配,会抛出 `CubeloopSchemaMismatch`。生产数据库应由宿主应用的迁移系统(Alembic 等)管理,而非由第三方库管理。
@@ -74,7 +74,7 @@ target_metadata = [my_app_metadata, cubeloop_metadata]
alembic revision --autogenerate -m "add cubeloop checkpointer"
```
-`cubeloop_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:
+`cubepi_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:
```python
# In a migration's upgrade():
@@ -84,16 +84,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import (
)
def upgrade():
- op.create_table("cubeloop_threads", ...)
+ op.create_table("cubepi_threads", ...)
op.create_table(
- "cubeloop_messages", ...,
+ "cubepi_messages", ...,
mysql_engine="InnoDB",
)
# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:
op.execute(
- "ALTER TABLE cubeloop_messages " + messages_partition_clause()
+ "ALTER TABLE cubepi_messages " + messages_partition_clause()
)
- op.create_table("cubeloop_schema_version", ...)
+ op.create_table("cubepi_schema_version", ...)
# write_schema_version_op() returns two ';'-separated statements
# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,
# so split and execute each:
@@ -152,8 +152,8 @@ cubepi_schema_version
`MySQLCheckpointer` 实现了 v4 的 `snapshot` / `fork` /
`claim_run` / `mark_run_complete` / `load_pending` 协议方法,
因此同时支持 `Agent.fork(...)` 和 `Agent.fork_once(...)`。
-`cubeloop_threads` 上的 `parent_thread_id` / `forked_at_seq` 列
-用于记录 fork 谱系;v4 新增的 `cubeloop_runs` 表用于追踪每个 run
+`cubepi_threads` 上的 `parent_thread_id` / `forked_at_seq` 列
+用于记录 fork 谱系;v4 新增的 `cubepi_runs` 表用于追踪每个 run
的 claim/completion 状态。
用户层 API 与语义详见
@@ -186,28 +186,9 @@ def upgrade():
保留 `run_id = NULL`,仍然可读;关于混合数据的 fork 资格规则,
请参阅 [旧数据行为](../agents/forking#legacy-data-behaviour)。
-## Schema v5 → v6 migration
+## CubeLoop 更名
-0.14 把 MySQL 表从 `cubepi_*` 重命名为 `cubeloop_*`。
-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:
-
-```python
-from cubeloop.checkpointer.mysql.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
- for stmt in write_schema_version_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
-```
-
-不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper。详见
-[从 cubepi 迁移](../../migration/from-cubepi)。
+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。
## 常见陷阱
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 79dacfb..5b1e129 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
@@ -53,8 +53,8 @@ async with PostgresCheckpointer(
## Schema
-checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、
-`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。
+checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、
+`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。
与 SQLite 不同,CubeLoop **不会自动创建这些表**——
它只在 `__aenter__` 时验证它们是否存在且 `schema_version` 是否匹配预期。
@@ -75,7 +75,7 @@ from cubeloop.checkpointer.postgres import cubeloop_metadata, EXPECTED_SCHEMA_VE
target_metadata = [my_app_metadata, cubeloop_metadata]
```
-然后生成一个 revision 并执行。迁移还必须写入 `cubeloop_schema_version`。
+然后生成一个 revision 并执行。迁移还必须写入 `cubepi_schema_version`。
使用辅助函数:
```python
@@ -88,8 +88,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
def upgrade():
op.create_table(...) # 从 cubeloop_metadata 自动生成
- op.execute(create_message_partitions_op()) # cubeloop_messages 的 64 个哈希分区
- op.execute(create_runs_partitions_op()) # cubeloop_runs 的 64 个哈希分区
+ 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
```
@@ -103,31 +103,31 @@ revision,再次调用 `op.execute(write_schema_version_op())`。
## 数据模型
```
-cubeloop_threads
+cubepi_threads
thread_id (PK)
parent_thread_id -- 用于 fork
forked_at_seq -- fork 点处的序列号
extra -- JSONB
created_at / updated_at
-cubeloop_messages
+cubepi_messages
thread_id, seq -- 复合 PK;按 HASH(thread_id) 分为 64 个分区
role -- "user" | "assistant" | "tool"
metadata -- JSONB(通过 GIN 索引)
payload -- bytea (msgpack)
created_at
-cubeloop_runs
+cubepi_runs
thread_id, run_id -- 复合 PK
claimed_at / completed_at
completion_seq
-cubeloop_hitl_answers
+cubepi_hitl_answers
thread_id, run_id, question_id -- 复合 PK
answer -- JSONB
answered_at
-cubeloop_schema_version
+cubepi_schema_version
version (PK)
```
@@ -162,7 +162,7 @@ advisory lock 让同一线程上的追加操作跨进程安全:
`save_extra` 做的是 JSONB 合并,而不是替换:
```sql
-extra = cubeloop_threads.extra || EXCLUDED.extra
+extra = cubepi_threads.extra || EXCLUDED.extra
```
所以先写 `{"foo": 1}` 再写 `{"bar": 2}` 会得到 `{"foo": 1, "bar": 2}`。
@@ -172,7 +172,7 @@ extra = cubeloop_threads.extra || EXCLUDED.extra
`parent_thread_id` + `forked_at_seq` 列用于支持
[会话 Fork](../agents/forking):fork 会创建一个新的 thread,并在其
-`cubeloop_threads` 行中写入指向源 thread 的 `parent_thread_id`,
+`cubepi_threads` 行中写入指向源 thread 的 `parent_thread_id`,
以及拷贝时源 thread 末尾的 `forked_at_seq`(最后一条已拷贝消息的
`seq`)。
@@ -201,24 +201,9 @@ def upgrade():
关于混合数据的 fork 资格规则,请参阅
[旧数据行为](../agents/forking#legacy-data-behaviour)。
-## Schema v5 → v6 migration
+## CubeLoop 更名
-0.14 把 Postgres 表从 `cubepi_*` 重命名为 `cubeloop_*`。
-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:
-
-```python
-from cubeloop.checkpointer.postgres.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- op.execute(upgrade_v5_to_v6_op())
- op.execute(write_schema_version_op()) # 把 6 写入 cubeloop_schema_version
-```
-
-不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper——旧表已经在,只是名字还是 `cubepi_*`。
-详见 [从 cubepi 迁移](../../migration/from-cubepi)。
+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。
## 常见坑
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 327a545..e2da14e 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
@@ -1,19 +1,18 @@
---
-title: From cubepi
-description: "CubePi was renamed to CubeLoop in 0.14. How to update installs, imports, checkpointer schema, and traces."
+title: 从 cubepi 迁移
+description: "CubePi 在 0.14 更名为 CubeLoop;安装、导入、持久化和 trace 的迁移方法。"
---
-# Migrating from cubepi
+# 从 cubepi 迁移
-0.14 renames the project from CubePi / `cubepi` to CubeLoop / `cubeloop`.
-GitHub keeps the same repository (renamed in place to `cubeplexai/cubeloop`).
-The docs site is https://cubeloop.dev.
+0.14 将项目从 CubePi / `cubepi` 更名为 CubeLoop / `cubeloop`。GitHub 仓库
+原地更名为 `cubeplexai/cubeloop`,文档站为 https://cubeloop.dev。
-## Install and imports
+## 安装与导入
```bash
pip install cubeloop
-# extras are unchanged: cubeloop[sqlite], cubeloop[postgres], cubeloop[mysql], …
+# extras 不变:cubeloop[sqlite]、cubeloop[postgres]、cubeloop[mysql]、…
```
```python
@@ -21,36 +20,41 @@ from cubeloop import Agent, tool
from cubeloop.providers.anthropic import AnthropicProvider
```
-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on
-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.
-It warns on first import. Prefer depending on `cubeloop` directly.
+`pip install -U cubepi` 仍可使用:0.14.1+ 是兼容包装,依赖同一 0.14 系列的
+CubeLoop,重新导出公共 API,并为 `cubepi.*` 深层导入提供别名。首次导入会告警,
+新项目应直接依赖 `cubeloop`。
-CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).
+CLI 改为 `cubeloop trace`;包装包仍提供会告警的 `cubepi trace`。
-## Checkpointer schema v5 → v6
+## Checkpointer schema 保持 v5
-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.
-SQLite table names were never prefixed; they stay `messages` / `runs` / ….
+Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*`。这些名字属于
+持久化协议,不是产品品牌。schema version 保持 5,因此已有 0.13.6 数据库升级到
+0.14.1 不需要数据库迁移。SQLite 表名从未加品牌前缀,保持不变。
-Existing databases: add an Alembic revision that runs
-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against
-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that
-helper — not “tables not found”.
+历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`
+导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。
-If you have data tables but no `*_schema_version` table, do not apply the
-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,
-then run the v5→v6 helper.
+### 从已撤回的 0.14.0 紧急恢复
-## Tracing
+0.14.0 曾短暂把数据库对象改成 `cubeloop_*`,因此已被 yank。只有确实执行过
+那条迁移时才使用下面的恢复脚本。先停止全部应用实例并完成可验证备份,再用
+数据库管理客户端执行对应脚本:
+
+- [Postgres v6→v5 恢复脚本](/recovery/0.14.0/postgres-v6-to-v5.sql)
+- [MySQL v6→v5 恢复脚本](/recovery/0.14.0/mysql-v6-to-v5.sql)
-New spans use `cubeloop.*` attributes and `cubeloop.turn` span names.
-`cubeloop trace` still reads 0.13 JSONL that used `cubepi.*`.
-Dashboards you own need their own attribute-name update.
+脚本会在修改前拒绝混合或冲突 schema。完成后核对表和行数,再部署 0.14.1。
+正常 v5 数据库不要执行这些脚本。
+
+## Tracing
-Default JSONL directory is `./cubeloop-traces`.
+新 span 使用 `cubeloop.*` 属性和 `cubeloop.turn` span 名。`cubeloop trace` 仍能读取
+0.13 中使用 `cubepi.*` 的 JSONL;你自己的 dashboard 需要更新属性名。默认 JSONL
+目录为 `./cubeloop-traces`。
-## Environment variables
+## 环境变量
-`CUBELOOP_TEST_PG_DSN`, `CUBELOOP_TEST_MYSQL_DSN`, `CUBELOOP_PG_DSN`,
-`CUBELOOP_MYSQL_DSN` replace the `CUBEPI_*` names. The old names are still
-read if the new one is unset, for the rest of 0.x.
+`CUBELOOP_TEST_PG_DSN`、`CUBELOOP_TEST_MYSQL_DSN`、`CUBELOOP_PG_DSN`、
+`CUBELOOP_MYSQL_DSN` 替换对应的 `CUBEPI_*` 名称。新名称未设置时,0.x 的剩余
+周期仍会读取旧名称。
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 fab1637..33323fd 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
@@ -53,7 +53,7 @@ async with MySQLCheckpointer(
## Schema
-Checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。
+Checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。与 Postgres 一样(与 SQLite 不同),CubeLoop **不会为你创建这些表**——它会在 `__aenter__` 时验证这些表是否存在并具有预期的 `schema_version`。
若表不存在,会抛出 `CubeloopSchemaUninitialized`;若版本与当前 CubeLoop 版本不匹配,会抛出 `CubeloopSchemaMismatch`。生产数据库应由宿主应用的迁移系统(Alembic 等)管理,而非由第三方库管理。
@@ -74,7 +74,7 @@ target_metadata = [my_app_metadata, cubeloop_metadata]
alembic revision --autogenerate -m "add cubeloop checkpointer"
```
-`cubeloop_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:
+`cubepi_messages` 表使用 `KEY` 分区,SQLAlchemy 的自动生成无法表达这一点,因此需要使用提供的辅助函数手动追加分区子句和 schema 版本写入:
```python
# In a migration's upgrade():
@@ -84,16 +84,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import (
)
def upgrade():
- op.create_table("cubeloop_threads", ...)
+ op.create_table("cubepi_threads", ...)
op.create_table(
- "cubeloop_messages", ...,
+ "cubepi_messages", ...,
mysql_engine="InnoDB",
)
# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:
op.execute(
- "ALTER TABLE cubeloop_messages " + messages_partition_clause()
+ "ALTER TABLE cubepi_messages " + messages_partition_clause()
)
- op.create_table("cubeloop_schema_version", ...)
+ op.create_table("cubepi_schema_version", ...)
# write_schema_version_op() returns two ';'-separated statements
# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,
# so split and execute each:
@@ -152,8 +152,8 @@ cubepi_schema_version
`MySQLCheckpointer` 实现了 v4 的 `snapshot` / `fork` /
`claim_run` / `mark_run_complete` / `load_pending` 协议方法,
因此同时支持 `Agent.fork(...)` 和 `Agent.fork_once(...)`。
-`cubeloop_threads` 上的 `parent_thread_id` / `forked_at_seq` 列
-用于记录 fork 谱系;v4 新增的 `cubeloop_runs` 表用于追踪每个 run
+`cubepi_threads` 上的 `parent_thread_id` / `forked_at_seq` 列
+用于记录 fork 谱系;v4 新增的 `cubepi_runs` 表用于追踪每个 run
的 claim/completion 状态。
用户层 API 与语义详见
@@ -186,28 +186,9 @@ def upgrade():
保留 `run_id = NULL`,仍然可读;关于混合数据的 fork 资格规则,
请参阅 [旧数据行为](../agents/forking#legacy-data-behaviour)。
-## Schema v5 → v6 migration
+## CubeLoop 更名
-0.14 把 MySQL 表从 `cubepi_*` 重命名为 `cubeloop_*`。
-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:
-
-```python
-from cubeloop.checkpointer.mysql.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
- for stmt in write_schema_version_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
-```
-
-不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper。详见
-[从 cubepi 迁移](../../migration/from-cubepi)。
+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。
## 常见陷阱
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 79dacfb..5b1e129 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
@@ -53,8 +53,8 @@ async with PostgresCheckpointer(
## Schema
-checkpointer 需要这些表:`cubeloop_threads`、`cubeloop_messages`、
-`cubeloop_runs`、`cubeloop_hitl_answers` 和 `cubeloop_schema_version`。
+checkpointer 需要这些表:`cubepi_threads`、`cubepi_messages`、
+`cubepi_runs`、`cubepi_hitl_answers` 和 `cubepi_schema_version`。
与 SQLite 不同,CubeLoop **不会自动创建这些表**——
它只在 `__aenter__` 时验证它们是否存在且 `schema_version` 是否匹配预期。
@@ -75,7 +75,7 @@ from cubeloop.checkpointer.postgres import cubeloop_metadata, EXPECTED_SCHEMA_VE
target_metadata = [my_app_metadata, cubeloop_metadata]
```
-然后生成一个 revision 并执行。迁移还必须写入 `cubeloop_schema_version`。
+然后生成一个 revision 并执行。迁移还必须写入 `cubepi_schema_version`。
使用辅助函数:
```python
@@ -88,8 +88,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
def upgrade():
op.create_table(...) # 从 cubeloop_metadata 自动生成
- op.execute(create_message_partitions_op()) # cubeloop_messages 的 64 个哈希分区
- op.execute(create_runs_partitions_op()) # cubeloop_runs 的 64 个哈希分区
+ 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
```
@@ -103,31 +103,31 @@ revision,再次调用 `op.execute(write_schema_version_op())`。
## 数据模型
```
-cubeloop_threads
+cubepi_threads
thread_id (PK)
parent_thread_id -- 用于 fork
forked_at_seq -- fork 点处的序列号
extra -- JSONB
created_at / updated_at
-cubeloop_messages
+cubepi_messages
thread_id, seq -- 复合 PK;按 HASH(thread_id) 分为 64 个分区
role -- "user" | "assistant" | "tool"
metadata -- JSONB(通过 GIN 索引)
payload -- bytea (msgpack)
created_at
-cubeloop_runs
+cubepi_runs
thread_id, run_id -- 复合 PK
claimed_at / completed_at
completion_seq
-cubeloop_hitl_answers
+cubepi_hitl_answers
thread_id, run_id, question_id -- 复合 PK
answer -- JSONB
answered_at
-cubeloop_schema_version
+cubepi_schema_version
version (PK)
```
@@ -162,7 +162,7 @@ advisory lock 让同一线程上的追加操作跨进程安全:
`save_extra` 做的是 JSONB 合并,而不是替换:
```sql
-extra = cubeloop_threads.extra || EXCLUDED.extra
+extra = cubepi_threads.extra || EXCLUDED.extra
```
所以先写 `{"foo": 1}` 再写 `{"bar": 2}` 会得到 `{"foo": 1, "bar": 2}`。
@@ -172,7 +172,7 @@ extra = cubeloop_threads.extra || EXCLUDED.extra
`parent_thread_id` + `forked_at_seq` 列用于支持
[会话 Fork](../agents/forking):fork 会创建一个新的 thread,并在其
-`cubeloop_threads` 行中写入指向源 thread 的 `parent_thread_id`,
+`cubepi_threads` 行中写入指向源 thread 的 `parent_thread_id`,
以及拷贝时源 thread 末尾的 `forked_at_seq`(最后一条已拷贝消息的
`seq`)。
@@ -201,24 +201,9 @@ def upgrade():
关于混合数据的 fork 资格规则,请参阅
[旧数据行为](../agents/forking#legacy-data-behaviour)。
-## Schema v5 → v6 migration
+## CubeLoop 更名
-0.14 把 Postgres 表从 `cubepi_*` 重命名为 `cubeloop_*`。
-`EXPECTED_SCHEMA_VERSION` 为 6。在已有库上打开 0.14 checkpointer **之前**执行:
-
-```python
-from cubeloop.checkpointer.postgres.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- op.execute(upgrade_v5_to_v6_op())
- op.execute(write_schema_version_op()) # 把 6 写入 cubeloop_schema_version
-```
-
-不要对 v5 数据库跑 v6 的 `CREATE TABLE` helper——旧表已经在,只是名字还是 `cubepi_*`。
-详见 [从 cubepi 迁移](../../migration/from-cubepi)。
+包名更改不会改变持久化 schema:物理名称继续使用 `cubepi_*`,`EXPECTED_SCHEMA_VERSION` 保持 5。已有 0.13.6 数据库无需迁移。撤回版本 0.14.0 的特殊恢复流程见[迁移指南](../../migration/from-cubepi)。
## 常见坑
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 327a545..e2da14e 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
@@ -1,19 +1,18 @@
---
-title: From cubepi
-description: "CubePi was renamed to CubeLoop in 0.14. How to update installs, imports, checkpointer schema, and traces."
+title: 从 cubepi 迁移
+description: "CubePi 在 0.14 更名为 CubeLoop;安装、导入、持久化和 trace 的迁移方法。"
---
-# Migrating from cubepi
+# 从 cubepi 迁移
-0.14 renames the project from CubePi / `cubepi` to CubeLoop / `cubeloop`.
-GitHub keeps the same repository (renamed in place to `cubeplexai/cubeloop`).
-The docs site is https://cubeloop.dev.
+0.14 将项目从 CubePi / `cubepi` 更名为 CubeLoop / `cubeloop`。GitHub 仓库
+原地更名为 `cubeplexai/cubeloop`,文档站为 https://cubeloop.dev。
-## Install and imports
+## 安装与导入
```bash
pip install cubeloop
-# extras are unchanged: cubeloop[sqlite], cubeloop[postgres], cubeloop[mysql], …
+# extras 不变:cubeloop[sqlite]、cubeloop[postgres]、cubeloop[mysql]、…
```
```python
@@ -21,36 +20,41 @@ from cubeloop import Agent, tool
from cubeloop.providers.anthropic import AnthropicProvider
```
-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on
-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.
-It warns on first import. Prefer depending on `cubeloop` directly.
+`pip install -U cubepi` 仍可使用:0.14.1+ 是兼容包装,依赖同一 0.14 系列的
+CubeLoop,重新导出公共 API,并为 `cubepi.*` 深层导入提供别名。首次导入会告警,
+新项目应直接依赖 `cubeloop`。
-CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).
+CLI 改为 `cubeloop trace`;包装包仍提供会告警的 `cubepi trace`。
-## Checkpointer schema v5 → v6
+## Checkpointer schema 保持 v5
-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.
-SQLite table names were never prefixed; they stay `messages` / `runs` / ….
+Postgres 和 MySQL 的物理表名、分区名和索引名继续使用 `cubepi_*`。这些名字属于
+持久化协议,不是产品品牌。schema version 保持 5,因此已有 0.13.6 数据库升级到
+0.14.1 不需要数据库迁移。SQLite 表名从未加品牌前缀,保持不变。
-Existing databases: add an Alembic revision that runs
-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against
-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that
-helper — not “tables not found”.
+历史 Alembic revision 可以继续从 `cubeloop.checkpointer.*.alembic_helpers`
+导入 helper;这些 helper 保持原来的 v1–v5 SQL。不要添加表名 rename revision。
-If you have data tables but no `*_schema_version` table, do not apply the
-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,
-then run the v5→v6 helper.
+### 从已撤回的 0.14.0 紧急恢复
-## Tracing
+0.14.0 曾短暂把数据库对象改成 `cubeloop_*`,因此已被 yank。只有确实执行过
+那条迁移时才使用下面的恢复脚本。先停止全部应用实例并完成可验证备份,再用
+数据库管理客户端执行对应脚本:
+
+- [Postgres v6→v5 恢复脚本](/recovery/0.14.0/postgres-v6-to-v5.sql)
+- [MySQL v6→v5 恢复脚本](/recovery/0.14.0/mysql-v6-to-v5.sql)
-New spans use `cubeloop.*` attributes and `cubeloop.turn` span names.
-`cubeloop trace` still reads 0.13 JSONL that used `cubepi.*`.
-Dashboards you own need their own attribute-name update.
+脚本会在修改前拒绝混合或冲突 schema。完成后核对表和行数,再部署 0.14.1。
+正常 v5 数据库不要执行这些脚本。
+
+## Tracing
-Default JSONL directory is `./cubeloop-traces`.
+新 span 使用 `cubeloop.*` 属性和 `cubeloop.turn` span 名。`cubeloop trace` 仍能读取
+0.13 中使用 `cubepi.*` 的 JSONL;你自己的 dashboard 需要更新属性名。默认 JSONL
+目录为 `./cubeloop-traces`。
-## Environment variables
+## 环境变量
-`CUBELOOP_TEST_PG_DSN`, `CUBELOOP_TEST_MYSQL_DSN`, `CUBELOOP_PG_DSN`,
-`CUBELOOP_MYSQL_DSN` replace the `CUBEPI_*` names. The old names are still
-read if the new one is unset, for the rest of 0.x.
+`CUBELOOP_TEST_PG_DSN`、`CUBELOOP_TEST_MYSQL_DSN`、`CUBELOOP_PG_DSN`、
+`CUBELOOP_MYSQL_DSN` 替换对应的 `CUBEPI_*` 名称。新名称未设置时,0.x 的剩余
+周期仍会读取旧名称。
diff --git a/website/static/recovery/0.14.0/mysql-v6-to-v5.sql b/website/static/recovery/0.14.0/mysql-v6-to-v5.sql
new file mode 100644
index 0000000..52df85e
--- /dev/null
+++ b/website/static/recovery/0.14.0/mysql-v6-to-v5.sql
@@ -0,0 +1,68 @@
+-- Emergency recovery for databases created or migrated by withdrawn 0.14.0.
+-- Stop all application instances and take a backup before running this file.
+SET @cp_new_tables = (
+ SELECT COUNT(*) FROM information_schema.tables
+ WHERE table_schema = DATABASE() AND table_name IN (
+ 'cubeloop_threads', 'cubeloop_messages', 'cubeloop_runs',
+ 'cubeloop_hitl_answers', 'cubeloop_schema_version'
+ )
+);
+SET @cp_old_tables = (
+ SELECT COUNT(*) FROM information_schema.tables
+ WHERE table_schema = DATABASE() AND table_name IN (
+ 'cubepi_threads', 'cubepi_messages', 'cubepi_runs',
+ 'cubepi_hitl_answers', 'cubepi_schema_version'
+ )
+);
+SET @cp_new_indexes = (
+ SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics
+ WHERE table_schema = DATABASE() AND index_name IN (
+ 'ix_cubeloop_messages_metadata_gin',
+ 'ix_cubeloop_messages_thread_run', 'ix_cubeloop_runs_thread_seq'
+ )
+);
+SET @cp_old_indexes = (
+ SELECT COUNT(DISTINCT index_name) FROM information_schema.statistics
+ WHERE table_schema = DATABASE() AND index_name IN (
+ 'ix_cubepi_messages_metadata_gin',
+ 'ix_cubepi_messages_thread_run', 'ix_cubepi_runs_thread_seq'
+ )
+);
+SET @cp_fresh_indexes = (@cp_new_indexes > 0);
+SET @cp_guard = IF(
+ @cp_new_tables = 5 AND @cp_old_tables = 0
+ AND ((@cp_new_indexes = 0 AND @cp_old_indexes = 2)
+ OR (@cp_new_indexes = 2 AND @cp_old_indexes = 0)),
+ 'DO 0',
+ 'SELECT * FROM cubeloop_0140_recovery_preflight_failed'
+);
+PREPARE cp_guard FROM @cp_guard;
+EXECUTE cp_guard;
+DEALLOCATE PREPARE cp_guard;
+
+RENAME TABLE
+ cubeloop_threads TO cubepi_threads,
+ cubeloop_messages TO cubepi_messages,
+ cubeloop_runs TO cubepi_runs,
+ cubeloop_hitl_answers TO cubepi_hitl_answers,
+ cubeloop_schema_version TO cubepi_schema_version;
+
+SET @cp_rename_message_index = IF(
+ @cp_fresh_indexes,
+ 'ALTER TABLE cubepi_messages RENAME INDEX ix_cubeloop_messages_thread_run TO ix_cubepi_messages_thread_run',
+ 'DO 0'
+);
+PREPARE cp_stmt FROM @cp_rename_message_index;
+EXECUTE cp_stmt;
+DEALLOCATE PREPARE cp_stmt;
+SET @cp_rename_run_index = IF(
+ @cp_fresh_indexes,
+ 'ALTER TABLE cubepi_runs RENAME INDEX ix_cubeloop_runs_thread_seq TO ix_cubepi_runs_thread_seq',
+ 'DO 0'
+);
+PREPARE cp_stmt FROM @cp_rename_run_index;
+EXECUTE cp_stmt;
+DEALLOCATE PREPARE cp_stmt;
+
+DELETE FROM cubepi_schema_version WHERE version <> 5;
+INSERT IGNORE INTO cubepi_schema_version (version) VALUES (5);
diff --git a/website/static/recovery/0.14.0/postgres-v6-to-v5.sql b/website/static/recovery/0.14.0/postgres-v6-to-v5.sql
new file mode 100644
index 0000000..7a6c03f
--- /dev/null
+++ b/website/static/recovery/0.14.0/postgres-v6-to-v5.sql
@@ -0,0 +1,83 @@
+-- Emergency recovery for databases migrated by withdrawn cubeloop 0.14.0.
+-- Stop all application instances and take a backup before running this file.
+BEGIN;
+
+DO $$
+DECLARE
+ schema_name text := current_schema();
+ new_count integer;
+ old_count integer;
+ new_index_count integer;
+ old_index_count integer;
+ i integer;
+BEGIN
+ SELECT count(*) INTO new_count
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE relname IN (
+ 'cubeloop_threads', 'cubeloop_messages', 'cubeloop_runs',
+ 'cubeloop_hitl_answers', 'cubeloop_schema_version'
+ ) AND n.nspname = schema_name;
+ SELECT count(*) INTO old_count
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE relname IN (
+ 'cubepi_threads', 'cubepi_messages', 'cubepi_runs',
+ 'cubepi_hitl_answers', 'cubepi_schema_version'
+ ) AND n.nspname = schema_name;
+ IF new_count <> 5 OR old_count <> 0 THEN
+ RAISE EXCEPTION
+ 'expected a complete 0.14.0 schema (5 cubeloop tables, 0 cubepi tables); found % and %',
+ new_count, old_count;
+ END IF;
+ SELECT count(*) INTO new_index_count
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE relkind = 'i' AND relname IN (
+ 'ix_cubeloop_messages_metadata_gin',
+ 'ix_cubeloop_messages_thread_run', 'ix_cubeloop_runs_thread_seq'
+ ) AND n.nspname = schema_name;
+ SELECT count(*) INTO old_index_count
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+ WHERE relkind = 'i' AND relname IN (
+ 'ix_cubepi_messages_metadata_gin',
+ 'ix_cubepi_messages_thread_run', 'ix_cubepi_runs_thread_seq'
+ ) AND n.nspname = schema_name;
+ IF new_index_count <> 3 OR old_index_count <> 0 THEN
+ RAISE EXCEPTION
+ 'index preflight failed: expected 3 cubeloop indexes and 0 cubepi indexes';
+ END IF;
+
+ FOR i IN 0..63 LOOP
+ IF to_regclass(format('%I.%I', schema_name, 'cubeloop_messages_p' || lpad(i::text, 2, '0'))) IS NULL
+ OR to_regclass(format('%I.%I', schema_name, 'cubeloop_runs_p' || lpad(i::text, 2, '0'))) IS NULL
+ OR to_regclass(format('%I.%I', schema_name, 'cubepi_messages_p' || lpad(i::text, 2, '0'))) IS NOT NULL
+ OR to_regclass(format('%I.%I', schema_name, 'cubepi_runs_p' || lpad(i::text, 2, '0'))) IS NOT NULL THEN
+ RAISE EXCEPTION 'partition preflight failed at suffix %', i;
+ END IF;
+ END LOOP;
+
+ EXECUTE format('ALTER TABLE %I.cubeloop_threads RENAME TO cubepi_threads', schema_name);
+ EXECUTE format('ALTER TABLE %I.cubeloop_messages RENAME TO cubepi_messages', schema_name);
+ FOR i IN 0..63 LOOP
+ EXECUTE format(
+ 'ALTER TABLE %I.%I RENAME TO %I', schema_name,
+ 'cubeloop_messages_p' || lpad(i::text, 2, '0'),
+ 'cubepi_messages_p' || lpad(i::text, 2, '0')
+ );
+ END LOOP;
+ EXECUTE format('ALTER TABLE %I.cubeloop_runs RENAME TO cubepi_runs', schema_name);
+ FOR i IN 0..63 LOOP
+ EXECUTE format(
+ 'ALTER TABLE %I.%I RENAME TO %I', schema_name,
+ 'cubeloop_runs_p' || lpad(i::text, 2, '0'),
+ 'cubepi_runs_p' || lpad(i::text, 2, '0')
+ );
+ END LOOP;
+ EXECUTE format('ALTER TABLE %I.cubeloop_hitl_answers RENAME TO cubepi_hitl_answers', schema_name);
+ EXECUTE format('ALTER TABLE %I.cubeloop_schema_version RENAME TO cubepi_schema_version', schema_name);
+ EXECUTE format('ALTER INDEX %I.ix_cubeloop_messages_metadata_gin RENAME TO ix_cubepi_messages_metadata_gin', schema_name);
+ EXECUTE format('ALTER INDEX %I.ix_cubeloop_messages_thread_run RENAME TO ix_cubepi_messages_thread_run', schema_name);
+ EXECUTE format('ALTER INDEX %I.ix_cubeloop_runs_thread_seq RENAME TO ix_cubepi_runs_thread_seq', schema_name);
+ EXECUTE format('DELETE FROM %I.cubepi_schema_version WHERE version <> 5', schema_name);
+ EXECUTE format('INSERT INTO %I.cubepi_schema_version (version) VALUES (5) ON CONFLICT DO NOTHING', schema_name);
+END $$;
+
+COMMIT;
diff --git a/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx b/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx
index 71fbf3a..3efe10a 100644
--- a/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx
+++ b/website/versioned_docs/version-0.14/api/cubeloop-checkpointer.mdx
@@ -807,9 +807,9 @@ claim_run(thread_id: str, run_id: str) -> None
Atomically claim a run_id on a thread.
-Lazy-creates the cubeloop_threads row, takes a per-thread FOR UPDATE
+Lazy-creates the cubepi_threads row, takes a per-thread FOR UPDATE
lock to serialize concurrent claims for the same thread, then
-checks cubeloop_runs for an existing row before inserting. The
+checks cubepi_runs for an existing row before inserting. The
pre-check matches the Postgres approach — using INSERT + catching
IntegrityError would also work, but a pre-SELECT lets us
distinguish in-flight vs completed cleanly without relying on the
@@ -880,10 +880,10 @@ fork(
Copy completed prefix of `src_thread_id` into `new_thread_id`.
-Threads-row first: the destination `cubeloop_threads` row is
+Threads-row first: the destination `cubepi_threads` row is
inserted before the message + runs copies so callers see a
-complete view if they probe mid-fork. There is no cubeloop_runs ->
-cubeloop_threads FK on MySQL (partition limitation), but we keep
+complete view if they probe mid-fork. There is no cubepi_runs ->
+cubepi_threads FK on MySQL (partition limitation), but we keep
the same ordering for semantic parity with Postgres.
Per-thread serialization: a `SELECT … FOR UPDATE` on the source
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 e636840..29e3b49 100644
--- a/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md
+++ b/website/versioned_docs/version-0.14/guides/checkpointing/mysql.md
@@ -61,8 +61,8 @@ async with MySQLCheckpointer(
## Schema
-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,
-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`. Like
+The checkpointer expects `cubepi_threads`, `cubepi_messages`,
+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`. Like
Postgres (and unlike SQLite), CubeLoop **does not create these for you** —
it verifies on `__aenter__` that they exist with the expected
`schema_version`.
@@ -90,7 +90,7 @@ Then autogenerate a revision:
alembic revision --autogenerate -m "add cubeloop checkpointer"
```
-The `cubeloop_messages` table is `KEY`-partitioned, which SQLAlchemy's
+The `cubepi_messages` table is `KEY`-partitioned, which SQLAlchemy's
autogenerate cannot express, so append the partition clause and the
schema-version write with the provided helpers:
@@ -102,16 +102,16 @@ from cubeloop.checkpointer.mysql.alembic_helpers import (
)
def upgrade():
- op.create_table("cubeloop_threads", ...)
+ op.create_table("cubepi_threads", ...)
op.create_table(
- "cubeloop_messages", ...,
+ "cubepi_messages", ...,
mysql_engine="InnoDB",
)
# KEY(thread_id) partitioning is not autogenerated — apply it explicitly:
op.execute(
- "ALTER TABLE cubeloop_messages " + messages_partition_clause()
+ "ALTER TABLE cubepi_messages " + messages_partition_clause()
)
- op.create_table("cubeloop_schema_version", ...)
+ op.create_table("cubepi_schema_version", ...)
# write_schema_version_op() returns two ';'-separated statements
# (DELETE then INSERT). MySQL/pymysql runs one statement per execute,
# so split and execute each:
@@ -128,31 +128,31 @@ again.
## Data model
```
-cubeloop_threads
+cubepi_threads
thread_id (PK) -- VARCHAR(255) utf8mb4_bin (case-sensitive)
parent_thread_id -- self-FK, for forks
forked_at_seq -- seq number at fork point
extra -- JSON
created_at / updated_at
-cubeloop_messages
+cubepi_messages
thread_id, seq -- composite PK; partitioned by KEY(thread_id) into 64
role -- "user" | "assistant" | "tool"
metadata -- JSON (not indexed; see below)
payload -- LONGBLOB (msgpack)
created_at
-cubeloop_runs
+cubepi_runs
thread_id, run_id -- composite PK
claimed_at / completed_at
completion_seq
-cubeloop_hitl_answers
+cubepi_hitl_answers
thread_id, run_id, question_id -- composite PK
answer -- JSON
answered_at
-cubeloop_schema_version
+cubepi_schema_version
version (PK)
```
@@ -199,8 +199,8 @@ from `dict.update`.)
`MySQLCheckpointer` implements the v4 `snapshot` / `fork` /
`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,
so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The
-`parent_thread_id` / `forked_at_seq` columns on `cubeloop_threads`
-record fork lineage; `cubeloop_runs` (added in v4) tracks per-run
+`parent_thread_id` / `forked_at_seq` columns on `cubepi_threads`
+record fork lineage; `cubepi_runs` (added in v4) tracks per-run
claim/completion state.
See the [Conversation Forking](../agents/forking) guide for the user-facing
@@ -258,34 +258,17 @@ def upgrade():
op.execute(stmt)
```
-## Schema v5 → v6 migration
+## CubeLoop rename
-0.14 renames the MySQL tables from `cubepi_*` to `cubeloop_*`.
-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14
-checkpointer on an existing database:
-
-```python
-from cubeloop.checkpointer.mysql.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- for stmt in upgrade_v5_to_v6_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
- for stmt in write_schema_version_op().split(";"):
- if stmt.strip():
- op.execute(stmt)
-```
-
-Do not run the v6 `CREATE TABLE` helpers against a v5 database. See the
-[migration guide](../../migration/from-cubepi).
+The package rename does not change the persistence schema: physical names stay
+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need
+no migration. See the [migration guide](../../migration/from-cubepi), including
+the exceptional recovery path for withdrawn 0.14.0.
## Common pitfalls
- **`CubeloopSchemaUninitialized`** — Your DB is empty, your migrations
- didn't run, or the `cubeloop_schema_version` table is malformed. Apply
+ didn't run, or the `cubepi_schema_version` table is malformed. Apply
the host alembic upgrade first.
- **`CubeloopSchemaMismatch`** — You upgraded CubeLoop but didn't generate a
new migration. Generate one, apply it, and CubeLoop will start.
@@ -296,7 +279,7 @@ Do not run the v6 `CREATE TABLE` helpers against a v5 database. See the
hand-roll the DDL, keep that collation.
- **`CheckpointCorruptionError` on `load()`** — A persisted message row
failed to deserialize (bad msgpack payload, schema-invalid data, or an
- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)
+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)
locates the bad row for inspection or surgical repair; `thread_id` and
`__cause__` carry the rest. CubeLoop never skips corrupt rows silently.
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 9cfc204..938a20b 100644
--- a/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md
+++ b/website/versioned_docs/version-0.14/guides/checkpointing/postgres.md
@@ -54,8 +54,8 @@ async with PostgresCheckpointer(
## Schema
-The checkpointer expects `cubeloop_threads`, `cubeloop_messages`,
-`cubeloop_runs`, `cubeloop_hitl_answers`, and `cubeloop_schema_version`.
+The checkpointer expects `cubepi_threads`, `cubepi_messages`,
+`cubepi_runs`, `cubepi_hitl_answers`, and `cubepi_schema_version`.
Unlike SQLite, CubeLoop
**does not create these for you** — it verifies on `__aenter__` that
they exist with the expected `schema_version`.
@@ -89,9 +89,9 @@ alembic revision --autogenerate -m "add cubeloop checkpointer"
Autogenerate emits the `CREATE TABLE`s from `cubeloop_metadata`, but
SQLAlchemy `MetaData` **cannot model two things CubeLoop needs**, so add
them to the generated migration by hand: the 64 hash partitions of
-`cubeloop_messages` (via `create_message_partitions_op()`), the 64
-partitions of `cubeloop_runs` (via `create_runs_partitions_op()`), and
-the `cubeloop_schema_version` row (via `write_schema_version_op()`). Use
+`cubepi_messages` (via `create_message_partitions_op()`), the 64
+partitions of `cubepi_runs` (via `create_runs_partitions_op()`), and
+the `cubepi_schema_version` row (via `write_schema_version_op()`). Use
the helpers:
```python
@@ -104,8 +104,8 @@ from cubeloop.checkpointer.postgres.alembic_helpers import (
def upgrade():
op.create_table(...) # auto-generated from cubeloop_metadata
- op.execute(create_message_partitions_op()) # 64 hash partitions of cubeloop_messages
- op.execute(create_runs_partitions_op()) # 64 hash partitions of cubeloop_runs
+ 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
```
@@ -120,31 +120,31 @@ again.
## Data model
```
-cubeloop_threads
+cubepi_threads
thread_id (PK)
parent_thread_id -- for forks
forked_at_seq -- seq number at fork point
extra -- JSONB
created_at / updated_at
-cubeloop_messages
+cubepi_messages
thread_id, seq -- composite PK; partitioned by HASH(thread_id) into 64
role -- "user" | "assistant" | "tool"
metadata -- JSONB (indexed via GIN)
payload -- bytea (msgpack)
created_at
-cubeloop_runs
+cubepi_runs
thread_id, run_id -- composite PK
claimed_at / completed_at
completion_seq
-cubeloop_hitl_answers
+cubepi_hitl_answers
thread_id, run_id, question_id -- composite PK
answer -- JSONB
answered_at
-cubeloop_schema_version
+cubepi_schema_version
version (PK)
```
@@ -182,7 +182,7 @@ The pool default of `min=1, max=10` is fine for most apps; bump
`save_extra` does a JSONB merge, not a replace:
```sql
-extra = cubeloop_threads.extra || EXCLUDED.extra
+extra = cubepi_threads.extra || EXCLUDED.extra
```
So writing `{"foo": 1}` then `{"bar": 2}` leaves `{"foo": 1, "bar":
@@ -194,8 +194,8 @@ keys.
`PostgresCheckpointer` implements the v4 `snapshot` / `fork` /
`claim_run` / `mark_run_complete` / `load_pending` Protocol methods,
so it supports both `Agent.fork(...)` and `Agent.fork_once(...)`. The
-`parent_thread_id` and `forked_at_seq` columns on `cubeloop_threads`
-record fork lineage; `cubeloop_runs` (the v4 partitioned table) tracks
+`parent_thread_id` and `forked_at_seq` columns on `cubepi_threads`
+record fork lineage; `cubepi_runs` (the v4 partitioned table) tracks
per-run claim/completion state.
See the [Conversation Forking](../agents/forking) guide for the user-facing
@@ -246,26 +246,12 @@ def upgrade():
op.execute(write_schema_version_op()) # bumps cubepi_schema_version to 5
```
-## Schema v5 → v6 migration
+## CubeLoop rename
-0.14 renames the Postgres tables from `cubepi_*` to `cubeloop_*`.
-`EXPECTED_SCHEMA_VERSION` is 6. Apply this **before** opening a 0.14
-checkpointer on an existing database:
-
-```python
-from cubeloop.checkpointer.postgres.alembic_helpers import (
- upgrade_v5_to_v6_op,
- write_schema_version_op,
-)
-
-def upgrade():
- op.execute(upgrade_v5_to_v6_op())
- op.execute(write_schema_version_op()) # writes 6 into cubeloop_schema_version
-```
-
-Do not run the v6 `CREATE TABLE` helpers against a v5 database — they
-would try to create tables that already exist under the old names.
-See the [migration guide](../../migration/from-cubepi).
+The package rename does not change the persistence schema: physical names stay
+`cubepi_*` and `EXPECTED_SCHEMA_VERSION` stays 5. Existing 0.13.6 databases need
+no migration. See the [migration guide](../../migration/from-cubepi), including
+the exceptional recovery path for withdrawn 0.14.0.
## Common pitfalls
@@ -295,7 +281,7 @@ See the [migration guide](../../migration/from-cubepi).
— pass both to Alembic separately.
- **`CheckpointCorruptionError` on `load()`** — A persisted message row
failed to deserialize (bad msgpack payload, schema-invalid data, or an
- unknown role). The error's `row_ref` (e.g. `cubeloop_messages.seq=42`)
+ unknown role). The error's `row_ref` (e.g. `cubepi_messages.seq=42`)
locates the bad row for inspection or surgical repair; `thread_id` and
`__cause__` carry the rest. CubeLoop never skips corrupt rows silently —
dropping a message that carries `tool_calls` would leave the
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 327a545..e201c52 100644
--- a/website/versioned_docs/version-0.14/migration/from-cubepi.md
+++ b/website/versioned_docs/version-0.14/migration/from-cubepi.md
@@ -21,25 +21,37 @@ from cubeloop import Agent, tool
from cubeloop.providers.anthropic import AnthropicProvider
```
-`pip install -U cubepi` still works: 0.14+ is a wrapper that depends on
-`cubeloop==0.14.0`, re-exports the public API, and aliases `cubepi.*` imports.
+`pip install -U cubepi` still works: 0.14.1+ is a wrapper that depends on a
+compatible CubeLoop 0.14 release, re-exports the public API, and aliases
+`cubepi.*` imports.
It warns on first import. Prefer depending on `cubeloop` directly.
CLI: `cubeloop trace` (the wrapper still provides `cubepi trace` and warns).
-## Checkpointer schema v5 → v6
+## Checkpointer schema stays at v5
-Postgres and MySQL table names moved from `cubepi_*` to `cubeloop_*`.
+Postgres and MySQL keep their `cubepi_*` physical table and index names. They
+are persistent protocol identifiers, not product branding. Schema version 5 is
+unchanged, so an existing 0.13.6 database needs no migration for 0.14.1.
SQLite table names were never prefixed; they stay `messages` / `runs` / ….
-Existing databases: add an Alembic revision that runs
-`upgrade_v5_to_v6_op()` then `write_schema_version_op()`. Opening 0.14 against
-an unmigrated v5 database raises `CubeloopSchemaMismatch` pointing at that
-helper — not “tables not found”.
+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.
-If you have data tables but no `*_schema_version` table, do not apply the
-fresh v6 CREATE TABLE. Create `cubepi_schema_version` with version 5 first,
-then run the v5→v6 helper.
+### Emergency recovery from withdrawn 0.14.0
+
+0.14.0 was yanked because it briefly renamed these database objects to
+`cubeloop_*`. Only use this recovery if 0.14.0 created the database or you ran its withdrawn
+migration. Stop every application instance, take a verified backup, then run
+the script for your database with an administrative SQL client:
+
+- [Postgres v6→v5 recovery SQL](/recovery/0.14.0/postgres-v6-to-v5.sql)
+- [MySQL v6→v5 recovery SQL](/recovery/0.14.0/mysql-v6-to-v5.sql)
+
+The scripts refuse mixed/colliding schemas before renaming anything. Afterward,
+verify table and row counts, then deploy 0.14.1. Do not run them on a normal v5
+database.
## Tracing
diff --git a/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md b/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md
index ff26ae5..7450637 100644
--- a/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md
+++ b/website/versioned_docs/version-0.14/recipes/postgres-fastapi.md
@@ -20,13 +20,13 @@ Before the service starts, run the CubeLoop schema migration. The
quickest way for this recipe:
```bash
-# Throwaway / recipe: copy the v6 bootstrap from
-# examples/checkpointing_postgres.py (cubeloop_threads, cubeloop_messages +
-# 64 partitions, cubeloop_runs + 64 partitions, cubeloop_hitl_answers,
-# cubeloop_schema_version = 6).
+# Throwaway / recipe: copy the v5 bootstrap from
+# examples/checkpointing_postgres.py (cubepi_threads, cubepi_messages +
+# 64 partitions, cubepi_runs + 64 partitions, cubepi_hitl_answers,
+# cubepi_schema_version = 5).
```
-Existing v5 databases must run `upgrade_v5_to_v6_op()` instead of CREATE.
+Existing v5 databases need no migration for the CubeLoop package rename.
For a real deployment, generate this via Alembic — see
[Postgres Checkpointing → Bootstrapping via Alembic](../guides/checkpointing/postgres#bootstrapping-via-alembic).