Overview
This article explains the internal DDL verification mechanism in YugabyteDB, how "stuck" states occur, and details the specific G-Flags that control these behaviors.
What is DDL Verification?
When a DDL (e.g., ALTER TABLE) is run, YugabyteDB’s YB-Master:
- Runs a background check to compare the PostgreSQL catalog against the DocDB schema.
- If not matched before/after change: Rolls forward or rolls back changes for atomicity.
- Clears the DDL verification state upon completion.
If the check fails/crashes, the table remains “stuck” in DDL verification state, blocking further DDL, backups, and restores.
What’s Impacted?
A stuck DDL verification state can block:
- Backups/restores
- CI/CD deployments or app schema migrations
- Automation/scripts running DDL
- Manual DDL commands (ALTER, DROP, etc.)
Key Flags & Settings
1. ysql_ddl_rollback_enabled (G-Flag)
- Type: Preview
- Purpose: Ensures catalog rollback on DDL failure for metadata safety.
- Limit: Does NOT unblock operations during DDL verification. Only improves failure handling.
- Warning: Use preview flags only with explicit approval and full platform support, or risk stuck states.
2. yb.backup.enable_backups_during_ddl (Runtime Config, YBA)
- Type: Early Access
- Purpose: Lets backups run during DDL verification (YugabyteDB Anywhere only).
- Default: Remains off for safety, even in 2025.x+.
- Requirement: Must be enabled by a Super Admin.
Best Practices
- Avoid running DDL and backup jobs at the same time.
- Monitor YB-Master logs for stuck DDL verifications.
- Don’t enable preview flags (like
ysql_ddl_rollback_enabled) in production unless vetted and approved.
OSS users: “Backup during DDL” is not available by default—run backups during DDL-free periods.
Reference ID: SUPPORT-863
Comments
0 comments
Please sign in to leave a comment.