Schema Version 比较与重试边界

功能简介

提交 Schema Version 时，服务端会自动把目标结构与 active 版本比较并形成执行计划；当前没有独立、只读的 compare/preview HTTP API。Pending 流程支持幂等续跑，但 failed 版本没有 first-class retry Action，必须修正目标结构并重新提交。

当前支持范围

• Schema Version 比较（PARTIAL）：提交 Schema Version 时会自动与活动结构比较并生成执行计划；当前没有独立的只读差异预览接口。

• Schema Version 重试（PARTIAL）：待处理版本支持幂等续跑；失败版本需要修正目标结构后重新提交，当前没有独立 Retry 接口。

适用场景

• 理解提交前后何时发生差异计算。
• 设计失败版本的人工修正与重新提交流程。
• 避免前端伪造不存在的 Compare 或 Retry 按钮。

前置条件

• 已阅读 Schema Version 创建与回滚页。
• 能读取版本状态和失败信息。
• 具备提交新版本的数据库写权限。

Console 操作路径

Console → Project → Databases → Database → Schema Versions 可查看状态与错误。当前页面不得展示独立 Compare Preview 或 Retry Action；失败后回到目标 Schema 编辑流程并创建新版本。

SDK 示例

import { Client, TablesDB } from 'appbase-console-sdk';

const client = new Client()
  .setEndpoint('https://<APPBASE_HOST>/v1')
  .setProject('<PROJECT_ID>')
  .setKey('<API_KEY>');
const tables = new TablesDB(client);

const failed = await tables.getSchemaVersion({
  databaseId: '<DATABASE_ID>',
  versionId: '<FAILED_VERSION_ID>'
});

// 修正 schema 后创建新版本；没有 retrySchemaVersion 方法。
const replacement = await tables.createSchemaVersion({
  databaseId: '<DATABASE_ID>',
  schema: { tables: [] }
});
void [failed, replacement];

REST 示例

# 查询失败版本；修正后再次 POST /schema/versions。
curl 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/schema/versions/<VERSION_ID>' \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-Key: <API_KEY>'

发布状态和验证 Commit

origin/main 条件支持。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353；使用前必须同时满足本页“当前限制”。

权威来源文件列表

• backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Schema/CreateVersion.php
• backend-candidate:src/Appwrite/Platform/Modules/Databases/Schema/SchemaDiffer.php
• backend-candidate:src/Appwrite/Platform/Modules/Databases/Schema/SchemaVersionService.php
• backend-candidate:tests/e2e/Services/TablesDB/TablesDBSchemaVersioningTest.php
• negative-evidence:未发现 first-class retry HTTP action
• negative-evidence:未发现独立的只读 compare 或 preview HTTP API

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/products/databases。上游页面不是 AppBase 实现证据。

继续阅读

• Schema Version
• 能力兼容矩阵