Catalog, startup readiness and upgrade boundaries

Baseline: v4.2.5. Catalog, runtime metadata caches and user-visible system tables are related but not interchangeable explanations of all DDL behavior.

DDL visibility

parse/bind/authorize DDL → transaction metadata change → commit
    → Catalog/Logtail propagation → CN cache/table definition → new binding/execution

Database/table IDs, schemas, objects and transaction timestamps determine visibility. DROP/CREATE with the same name need not preserve table identity. Schema changes also affect existing plans, prepared statements and internal executors. DDL succeeding in one session does not replace another-CN validation.

Invariant: a statement’s table definition must match its transaction/read state. Check DDL transaction/implicit-commit behavior per statement rather than assuming generic MySQL behavior or one rule for all DDL.

Startup and control plane

configuration/storage → LogService/HAKeeper bootstrap
    → TN recovery/service → CN engine, internal executor and Catalog subscription
    → database readiness → Proxy/client access

This is a dependency graph, not a promise of one sequential startup script. HAKeeper tracks heartbeats/cluster state and schedules commands; ClusterService, TaskService and Operator have distinct roles. Pod Running, open ports, synchronized Catalog and successful commits are separate checks.

Proxy and upgrades

Tenant/label routing, connection migration, active transactions and distributed queries need separate handling. Migration carries session/protocol state and does not promise arbitrary transparent active-transaction movement. Rolling upgrades also require build/RPC/plan compatibility, lock bindings and background work checks.

Record source/target/Operator versions, configuration, compatibility and rollback criteria. Rehearse active transactions, prepared execution, cancellation, long queries, CDC/index tasks and recovery. Data/metadata upgrades do not automatically support binary downgrade.

Diagnosis

Separate storage/log initialization, HAKeeper bootstrap, TN Replay, Catalog subscription, internal SQL and readiness. For post-DDL metadata problems retain table ID, Schema, SQL, commit state, CN and build; clearing caches is not a root-cause analysis.

See Operator, Proxy and implicit transactions.

Source and regression entry points