Skip to content

docs(rfc): define unified versioned database migrations - #1771

Open
Zxf-xufeng wants to merge 8 commits into
masterfrom
codex/unified-database-migrations-rfc
Open

Zxf-xufeng wants to merge 8 commits into
masterfrom
codex/unified-database-migrations-rfc

Conversation

@Zxf-xufeng

@Zxf-xufeng Zxf-xufeng commented Sep 28, 2026 •

Copy link
Copy Markdown
Member

Which issue or RFC does this PR close?

Refs #1756. Companion implementation Draft PR: #1772. The branches are independent; this documentation PR does not close implementation acceptance criteria.

Rationale for this change

PowerContext spreads schema changes across initialization, startup helpers, and maintenance commands. This RFC defines explicit upgrades of existing databases using Alembic, one standard version table, and verification before business access. It also defines the operational path for shared-database deployments and local services.

What changes are included in this PR?

Only the English and Chinese RFCs:

  • Use pc_schema_revision(version_num) with standard Alembic version handling, adding no generic run, step, or task tables. Each managed schema change provides an immutable revision; a release can contain several or none.
  • Separate installation from migration. One apply plans and confirms backup/lifecycle choices, stops writers, locks and rechecks, migrates, and verifies. Multiple Servers sharing one database run one migration Job; each new node checks readiness.
  • Introduce a separate BackupProvider reusing backend configuration: SQLite native backup, validated seekDB whole-database fork, and OceanBase native physical backup/log archiving. Explain fork coverage, shared-storage limitations, and the required original-database restoration path.
  • Allow PC-managed automatic backup, an entirely unverified manual-backup declaration, or explicitly accepted no-backup risk. Automatic backup warns about time/space and cannot silently fall back after failure.
  • Propose current-user service start/stop/restart and optional local lifecycle management. Migration failure keeps the service stopped; database-ready but startup-failed is reported separately. These are proposed contracts, not claims of implemented CLI behavior.
  • Define release impact manifests for tables, execution modes, API deprecation, and persisted task formats. Check legacy tasks during planning, locked execution, final verification, and Worker startup. Unsupported online choices cannot override compatibility blockers.
  • Explain integration with Profiles, AsyncDatabase, fixed maintenance connections, frozen Alembic scripts, repositories, data batches, and versioned index rebuilds. Ordinary startup becomes inspection before runtime composition.

The framework proceeds independently of #1716. Once enabled, every still-unmerged PR changing managed schema follows the standard process. The companion prototype must satisfy these acceptance criteria separately.

Are there any user-facing changes?

No runtime changes. Existing local and remote databases require explicit migration under the proposed design. Retained old API contracts can share migrated storage; API compatibility and storage compatibility remain separate commitments. Manual backup is not verified, and skipped backup may leave original data unrecoverable.

How was this change tested?

  • uv run --locked prek run -a, including Ruff and ty check.
  • Both RFCs compile through MDX with remark-gfm.
  • English/Chinese command, heading-level, reference-link, and inline-code-identifier parity checks.
  • Checked relative links and absence of internal documentation links.
  • git diff --check.

A full static website build and real-database migration acceptance are not claimed by this documentation PR.

AI usage statement

Prepared and checked with OpenAI Codex (GPT-6). The RFC states design requirements, not claims of executed backend acceptance.

@Zxf-xufeng
Zxf-xufeng marked this pull request as ready for review September 30, 2026 06:58
@Zxf-xufeng
Zxf-xufeng requested review from Teingi and frf12 September 30, 2026 06:59

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

2 participants