AppBase 云控制台
浏览全部文档 · 17/37
AppBase 增强已进入 main

Schema Version：创建、查询与回滚

Database、Table、Column 与 Row

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
0363062a1c7ea08741975bb5ba0c3361663c9353

功能简介

Schema Version 保存一份目标 Table 结构，服务端与当前 active 版本计算迁移计划并异步应用。只有新版本成功后才切换当前可见结构；历史版本可用于逻辑回滚，但回滚不会撤销已经执行的物理 DDL，也不会恢复业务数据。

当前支持范围

  • Schema Version 创建与查询（APPBASE_ENHANCED）：保存目标表结构为版本，查看活动、历史和失败记录，并只在新版本成功后切换当前可见结构。
  • Schema Version 回滚（APPBASE_ENHANCED）：把当前可见 Schema 切回历史版本；回滚不撤销物理 DDL，也不会恢复已经变化的业务数据。

适用场景

  • 为多张 Table 的结构变更保留统一历史。
  • 观察 pending、running、applying、active、deprecated 或 failed 状态。
  • 在兼容范围内切回历史可见 Schema。

前置条件

  • Database 已存在。
  • API Key/Admin 具备 databases.write。
  • 已备份关键数据，并评估破坏性变更。

Console 操作路径

Console → Project → Databases → Database → Schema Versions。创建版本后观察状态与错误；选择历史版本执行 rollback 前先阅读影响提示。

SDK 示例

SDK · TypeScript
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 version = await tables.createSchemaVersion({
  databaseId: '<DATABASE_ID>',
  schema: {
    tables: [{
      tableId: 'articles',
      columns: [{ key: 'title', type: 'string', size: 255, required: true }],
      indexes: []
    }]
  }
});

await tables.getSchemaVersion({
  databaseId: '<DATABASE_ID>',
  versionId: version.$id
});

REST 示例

REST · Bash
curl 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/schema/versions' \
  -X POST \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{"schema":{"tables":[]}}'

权限模型

创建与 rollback 是结构管理操作，只接受 Admin/API Key 并要求 databases.write；读取列表和详情按 Action 声明的数据库 Scope 执行。终端用户 Session 不应直接管理 Schema。

常见错误

现象处理建议
版本长时间 pending/running检查 Schema Worker、Redis、数据库和任务状态，不要盲目重复提交。
failed读取错误，修正目标 Schema 后重新提交新版本。
结构冲突等待同一 Database 的当前变更完成；服务端使用 mutation lock 串行化关键步骤。
rollback 后数据未恢复这是预期边界；从备份或业务恢复流程处理数据。

当前限制

  • 逻辑 rollback 只切换当前可见 Schema，不保证反向执行物理 DDL。
  • 删除列、缩窄类型和唯一约束等可能造成不可逆影响。
  • 没有独立 compare preview 或 retry Action；见边界页。

Appwrite 兼容说明

Database/Table/Column 仍保持兼容；Schema Version 是 AppBase 结构演进增强。

AppBase 增强说明

AppBase 保存版本状态与历史，只在成功后切换 active，并提供创建、列表、详情和 rollback SDK/REST。

发布状态和验证 Commit

origin/main 已核验。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353。

权威来源文件列表

  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Schema/CreateVersion.php
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Schema/GetVersion.php
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Schema/ListVersions.php
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Http/TablesDB/Schema/RollbackVersion.php
  • backend-candidate:src/Appwrite/Platform/Modules/Databases/Schema/SchemaVersionService.php
  • backend-candidate:tests/e2e/Services/TablesDB/TablesDBSchemaVersioningTest.php
  • backend-candidate:tests/unit/Database/SchemaVersionServiceRollbackTest.php

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

继续阅读