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.