Document vitessio/vitess#13656 (#1555)

* Document vitessio/vitess#13656 Signed-off-by: Matt Lord <[email protected]> * Updates Signed-off-by: Matt Lord <[email protected]> * Improve the docs Signed-off-by: Matt Lord <[email protected]> --------- Signed-off-by: Matt Lord <[email protected]>
vitessio · Aug 11, 2023 · 1657711 · 1657711
1 parent 22a6950
commit 1657711
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 5 deletions.
diff --git a/...programs/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_create.md b/...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/.../vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_reversetraffic.md b/.../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/...s/vtctldclient/vtctldclient_MoveTables/vtctldclient_MoveTables_switchtraffic.md b/...s/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
@@ -21,6 +21,7 @@ MoveTables -- [--source=<sourceKs>] [--tables=<tableSpecs>] [--cells=<cells>]
   [--tablet_types=<source_tablet_types>] [--all] [--exclude=<tables>] [--auto_start] 
   [--stop_after_copy] [--timeout=timeoutDuration] [--reverse_replication] [--keep_data] 
   [--keep_routing_rules] [--on-ddl=<ddl-action>] [--source_time_zone=<mysql_time_zone>]
+  [--initialize-target-sequences]
   <action> <workflow identifier>
 ```
 
@@ -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 >}}
-
 <div class="cmd">
 
 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.
 
 </div>
 
+#### --initialize-target-sequences
+**optional**\
+**default** false
+
+<div class="cmd">
+
+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.
+
+</div>
+
+###### 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