Skip to content

feat: ALTER TABLE SET (REPLICATION_MODE) to demote a table to a replica - #59280

Closed
Enjection wants to merge 1 commit into
ydb-platform:mainfrom
Enjection:feat/alter-table-replication-mode
Closed

Enjection wants to merge 1 commit into
ydb-platform:mainfrom
Enjection:feat/alter-table-replication-mode

Conversation

@Enjection

Copy link
Copy Markdown
Member

Changelog entry

ALTER TABLE <table> SET (REPLICATION_MODE = READ_ONLY | NONE, REPLICATION_CONSISTENCY_LEVEL = ROW | GLOBAL) turns an existing table into a read-only async-replication replica in place, and back. Admitted from a cluster administrator only.

Description for reviewers

SchemeShard can already demote a table to a replica, but only for an Internal ModifyScheme, and the only client that forwards a raw one is the legacy MsgBus SchemeOperation call. This gives the operation a supported door; it is what a manual replication switchover uses to fence writes on the old primary without copying the data again.

READ_ONLY sets ReplicationConfig { Mode: READ_ONLY, ConsistencyLevel, ImportState: IMPORTED } on the table and, in the same operation, on the implementation tables of its synchronous and unique indexes, each an independent replication target. IMPORTED and a matching consistency level are what the replication's attach path requires of a table it did not create (dst_creator.cpp): ROW is the default, GLOBAL is for a globally consistent replication, and the setting is rejected without REPLICATION_MODE. NONE reverses the demote.

Authorization: a new TModifyScheme.AllowReplicationModeChange stands in for Internal on this path, and SchemeShard honours it only for a real cluster administrator — IsAdministrator() with a non-empty AdministrationAllowedSIDs, the rule index implementation table alters already use — so "all users are admins by default" does not grant it. The flag is not reachable from the public AlterTableRequest, which has no replication field; KQP builds the scheme transaction for these two settings.

Tests: 5 parser cases in SqlParsingOnly, and KqpScheme::AlterTableReplicationMode — administrator succeeds, non-administrator is denied, unknown values rejected, base and index implementation tables demoted with the right consistency level, writes rejected and reads served, back to writable.

ALTER TABLE <t> SET (REPLICATION_MODE = READ_ONLY | NONE,
REPLICATION_CONSISTENCY_LEVEL = ROW | GLOBAL) turns an existing table
into a read-only async-replication replica in place, and back. SchemeShard
could already do it, but only for an Internal ModifyScheme, and the only
client that forwards a raw one is the legacy MsgBus SchemeOperation call.

READ_ONLY also sets ImportState = IMPORTED and the consistency level,
which is what the replication's attach path requires of a table it did
not create (dst_creator.cpp), and applies to the implementation tables
of the table's synchronous and unique indexes, each an independent
replication target. A new TModifyScheme.AllowReplicationModeChange
stands in for Internal on this path, and SchemeShard honours it only for
a real cluster administrator -- IsAdministrator() with a non-empty
AdministrationAllowedSIDs, the rule index implementation table alters
already use -- because the demote bypasses every protection a replica
table has.
@Enjection
Enjection requested review from a team as code owners November 13, 2026 00:21
@github-actions

Copy link
Copy Markdown
Contributor

✅ Documentation build

Revision built successfully
Revision preview link

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

⚪ 2026-11-13 01:04:58 UTC Pre-commit check linux-x86_64-relwithdebinfo for 08466bd has started.
⚪ 2026-11-13 01:05:35 UTC Artifacts will be uploaded here
⚪ 2026-11-13 01:07:04 UTC ya make is running...
🟡 2026-11-13 03:16:38 UTC Some tests failed, follow the links below. Going to retry failed tests...

Details

Ya make output

TESTS PASSED ERRORS FAILED SKIPPED MUTED?
64751 62906 0 5 1833 7

⚪ 2026-11-13 03:17:01 UTC ya make is running... (failed tests rerun, try 2)
🟢 2026-11-13 03:24:26 UTC Tests successful.

Ya make output

TESTS PASSED ERRORS FAILED SKIPPED MUTED?
133 (only retried tests) 132 0 0 0 1

🟢 2026-11-13 03:24:30 UTC Build successful.
🟡 2026-11-13 03:25:04 UTC ydbd size 2.8 GiB changed* by +10.4 MiB, which is >= 100.0 KiB vs main: Warning

ydbd size dash main: 7c1bcec merge: 08466bd diff diff %
ydbd size 3 045 473 272 Bytes 3 056 350 120 Bytes +10.4 MiB +0.357%
ydbd stripped size 643 672 192 Bytes 644 441 504 Bytes +751.3 KiB +0.120%

*please be aware that the difference is based on comparing your commit and the last completed build from the post-commit, check comparation

@Enjection

Copy link
Copy Markdown
Member Author

Superseded by #59328, which exposes the same capability as CREATE ASYNC REPLICATION ... WITH (ADOPT_EXISTING = TRUE) instead of a per-table ALTER.

The replication performs the demote itself, so the mode, consistency level and ImportState come from its own configuration and cannot disagree with it; index implementation tables are adopted by their own targets rather than by a propagation rule; and one statement covers the whole set instead of N separate alters with no atomicity between them. It also needs no new admin-gated DDL on tables -- the demote stays an internal operation owned by the controller, gated at the statement.

Closing in favour of that PR. Keeping this branch around in case the standalone primitive turns out to be wanted for repair paths.

@Enjection Enjection closed this Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant