From 1657711db67fa993f6ff10ca3b70b3e847dc73a1 Mon Sep 17 00:00:00 2001 From: Matt Lord Date: Fri, 11 Aug 2023 15:28:16 -0400 Subject: [PATCH] Document https://github.com/vitessio/vitess/pull/13656 (#1555) * Document https://github.com/vitessio/vitess/pull/13656 Signed-off-by: Matt Lord * Updates Signed-off-by: Matt Lord * Improve the docs Signed-off-by: Matt Lord --------- Signed-off-by: Matt Lord --- .../vtctldclient_MoveTables_create.md | 2 ++ .../vtctldclient_MoveTables_reversetraffic.md | 2 +- .../vtctldclient_MoveTables_switchtraffic.md | 2 ++ .../18.0/reference/vreplication/movetables.md | 36 ++++++++++++++++--- 4 files changed, 37 insertions(+), 5 deletions(-) diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md index 4a9aa52a5..85bdd2c70 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md @@ -22,11 +22,13 @@ vtctldclient --server localhost:15999 movetables --workflow commerce2customer -- --all-tables Copy all tables from the source --auto-start Start the MoveTables workflow after creating it (default true) -c, --cells strings Cells and/or CellAliases to copy table data from + --defer-secondary-keys Defer secondary index creation for a table until after it has been copied --exclude-tables strings Source tables to exclude from copying -h, --help help for create --on-ddl string What to do when DDL is encountered in the VReplication stream. Possible values are IGNORE, STOP, EXEC, and EXEC_IGNORE (default "IGNORE") --source-keyspace string Keyspace where the tables are being moved from (required) --source-shards strings Source shards to copy data from when performing a partial MoveTables (experimental) + --source-time-zone string Specifying this causes any DATETIME fields to be converted from the given time zone into UTC --stop-after-copy Stop the MoveTables workflow after it's finished copying the existing rows and before it starts replicating changes --tables strings Source tables to copy --tablet-types strings Source tablet types to replicate table data from (e.g. PRIMARY,REPLICA,RDONLY) diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md index d608be3e1..02787b0d7 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md @@ -21,7 +21,7 @@ vtctldclient --server localhost:15999 movetables --workflow commerce2customer -- ``` -c, --cells strings Cells and/or CellAliases to switch traffic in --dry-run Print the actions that would be taken and report any known errors that would have occurred - --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover (default true) + --enable-reverse-replication Setup replication going back to the original target keyspace to support switching traffic again (default true) -h, --help help for reversetraffic --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this (default 30s) --tablet-types strings Tablet types to switch traffic for diff --git a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md index b8bb22ce7..0825ad539 100644 --- a/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md +++ b/content/en/docs/18.0/reference/programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md @@ -21,7 +21,9 @@ vtctldclient --server localhost:15999 movetables --workflow commerce2customer -- ``` -c, --cells strings Cells and/or CellAliases to switch traffic in --dry-run Print the actions that would be taken and report any known errors that would have occurred + --enable-reverse-replication Setup replication going back to the original source keyspace to support rolling back the traffic cutover (default true) -h, --help help for switchtraffic + --initialize-target-sequences When moving tables from an unsharded keyspace to a sharded keyspace, initialize any sequences that are being used on the target when switching writes. --max-replication-lag-allowed duration Allow traffic to be switched only if VReplication lag is below this (default 30s) --tablet-types strings Tablet types to switch traffic for --timeout duration Specifies the maximum time to wait, in seconds, for VReplication to catch up on primary tablets. The traffic switch will be cancelled on timeout. (default 30s) diff --git a/content/en/docs/18.0/reference/vreplication/movetables.md b/content/en/docs/18.0/reference/vreplication/movetables.md index b42f3cf2a..768af7dcc 100644 --- a/content/en/docs/18.0/reference/vreplication/movetables.md +++ b/content/en/docs/18.0/reference/vreplication/movetables.md @@ -21,6 +21,7 @@ MoveTables -- [--source=] [--tables=] [--cells=] [--tablet_types=] [--all] [--exclude=] [--auto_start] [--stop_after_copy] [--timeout=timeoutDuration] [--reverse_replication] [--keep_data] [--keep_routing_rules] [--on-ddl=] [--source_time_zone=] + [--initialize-target-sequences] ``` @@ -152,10 +153,6 @@ Comma seperated list of Cell(s) and/or CellAlias(es) to replicate from. **optional**\ **default** false -{{< warning >}} -This flag is currently **experimental**. -{{< /warning >}} -
If true, any secondary keys are dropped from the table definitions on the target shard(s) as we first initialize the @@ -200,6 +197,37 @@ If moving all tables, specifies tables to be skipped.
+#### --initialize-target-sequences +**optional**\ +**default** false + +
+ +If specified, when switching write (primary tablet) traffic for tables that are being moved from an unsharded keyspace to a +sharded one, initialize any sequences being used by those tables on the target. They are initialized using the current +maximum value for the column across all shards on the target. + +
+ +###### Uses + +* It's common that users import unsharded data into Vitess — sharding it in the process — or move +tables from an unsharded keyspace to a sharded one as they become too large for a single MySQL instance. +When doing either of these you would typically be leveraging [MySQL auto_increment](https://dev.mysql.com/doc/refman/en/example-auto-increment.html) +columns for primary keys on the unsharded tables (source). On the sharded target, however, you will then +need to use [Vitess Sequences](../../features/vitess-sequences/) in order to ensure that you continue having +automatically generated incrementing unique primary keys _across all shards_. When it comes to [switching the write traffic](#switchtraffic) +during this move you would need to manually ensure that you [initialize the sequences](../../features/vitess-sequences/#initializing-a-sequence) +so that the next values they provide are higher than any already used on the source (with ample buffer in between +to avoid potential identifier reuse and duplicate key errors immediately following the cutover). This flag tells Vitess +to manage this sequence initialization for you as part of the `SwitchTraffic` operation to ensure a seamless cutover +without any additional manual steps. For more information, please see [the feature request](https://github.com/vitessio/vitess/issues/13685). + +{{< info >}} +You will still need to take the manual step of [creating each backing sequence table](../../features/vitess-sequences/#creating-a-sequence) +in an unsharded keyspace of your choosing prior to the `SwitchTraffic` operation. +{{< /info>}} + #### --keep_data **optional**\ **default** false