Builder Guide

Upgrade DB: staged database inventory

Review missing database dependencies before preparing a controlled SaaS upgrade.

Open your SaaS app's Backups page and find Upgrade DB — Staged database inventory. The panel displays the latest operator-published assessment of the Core, Logs, and AI databases.

What the assessment checks

The scan compares database structure with the reviewed golden contracts: tables, column definitions and data types, SQL types, functions, views, stored procedures, dependencies, and permissions. It does not copy or display customer record values.

Stage 1: missing procedures

• Ready: the procedure passes the dependency checks and can proceed to a restored-copy rehearsal.
• Blocked: required objects, columns, types, roles, or table contracts are missing or incompatible.
• Manual review: dynamic SQL, external references, triggers, unresolved dependencies, or other conditions need an operator's review.

Expand Review missing procedures to see names and reasons. Ready does not mean installed or approved. Existing procedures are not overwritten by the missing-procedure plan.

Stage 2: missing schema and older modules

Stage 2 counts identify work needed before the remaining procedures can be installed: missing tables, columns, SQL types, functions/views, and reviewed updates to older modules. Operators must prepare migration-owned changes, including any required backfill or reference data. An inventory cannot safely decide those data transformations on its own.

Refresh and approval are different actions

Refresh inventory status reloads the latest published assessment; it does not run a scan or change a database. If no inventory appears, ask the operator to run and publish the read-only scan. Scan time and fingerprint identify the assessment; the worker must recheck current state before applying a release.

The existing Back up and upgrade this app button queues the currently registered reviewed release. It does not automatically convert the Stage 1 or Stage 2 worklist into SQL. The queued request is tied to the exact release-manifest SHA-256, so the database worker refuses a different or modified plan.

Required safeguards

Before applying a registered release, the operator worker makes verified COPY_ONLY/CHECKSUM backups of all three databases. It restores owned disposable copies, runs each migration there, checks integrity before and after, and records the expected schema fingerprints. The app enters maintenance only after all three rehearsals pass. Live results must match the rehearsed results.

If live application fails, the worker immediately attempts to restore all three retained source backups. The app stays suspended unless every restored plane passes its source-version verification. The Builder status and the operator receipt distinguish Succeeded, Failed, Restore required, and Restored; a failure is never reported as success merely because recovery was attempted.

A golden database update does not silently update existing customer databases. Operators must still convert inventory findings into reviewed, immutable migrations and register the release before it can be approved.

No database credentials or SQL execution permissions are given to the browser. Builder access remains scoped to the owned SaaS app through the existing authorized API. Platform operators verify the stored-procedure boundary during the controlled release and restored-copy rehearsal; builders use the published release status and receipts.

Capability review: 2026-09-14. See current features and setup requirements, the generated API Map and first-class module inventory.