diff --git a/content/en/docs/18.0/concepts/vtctld.md b/content/en/docs/18.0/concepts/vtctld.md index 2f39c54d6..3236a00ec 100644 --- a/content/en/docs/18.0/concepts/vtctld.md +++ b/content/en/docs/18.0/concepts/vtctld.md @@ -4,4 +4,4 @@ title: vtctld **vtctld** is an HTTP server that lets you browse the information stored in the Topology Service. It is useful for troubleshooting or for getting a high-level overview of the servers and their current states. -`vtctld` also acts as the server for `vtctlclient` and `vtctldclient` connections. +`vtctld` also acts as the server for `vtctldclient` connections. diff --git a/content/en/docs/18.0/get-started/local-brew.md b/content/en/docs/18.0/get-started/local-brew.md index 2332d7322..94b599b31 100644 --- a/content/en/docs/18.0/get-started/local-brew.md +++ b/content/en/docs/18.0/get-started/local-brew.md @@ -191,13 +191,13 @@ rm -rf /usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot ## Setup Aliases -For ease-of-use, Vitess provides aliases for `mysql` and `vtctlclient`: +For ease-of-use, Vitess provides aliases for `mysql` and `vtctldclient`: ```bash source ../common/env.sh ``` -Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctlclient` or close your session. +Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctldclient` or close your session. ## Connect to your cluster diff --git a/content/en/docs/18.0/get-started/local.md b/content/en/docs/18.0/get-started/local.md index 2eb1bc039..2e79ab893 100644 --- a/content/en/docs/18.0/get-started/local.md +++ b/content/en/docs/18.0/get-started/local.md @@ -222,13 +222,13 @@ rm -rf vtdataroot ## Setup Aliases -For ease-of-use, Vitess provides aliases for `mysql`, `vtctlclient` and `vtcltdclient`: +For ease-of-use, Vitess provides aliases for `mysql` and `vtcltdclient`: ```bash source ../common/env.sh ``` -Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctlclient && unalias vtctldclient` or close your session. +Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctldclient` or close your session. ## Connect to your cluster diff --git a/content/en/docs/18.0/get-started/operator.md b/content/en/docs/18.0/get-started/operator.md index 55112f490..f9638b1ec 100644 --- a/content/en/docs/18.0/get-started/operator.md +++ b/content/en/docs/18.0/get-started/operator.md @@ -72,16 +72,15 @@ vitess-operator-5f47c6c45d-bgqp2 1/1 Running 0 The port-forward will only forward to a specific pod. Currently, `kubectl` does not automatically terminate a port-forward as the pod disappears due to apply/upgrade operations. You will need to manually restart the port-forward. {{}} -For ease-of-use, Vitess provides a script to port-forward from Kubernetes to your local machine. This script also recommends setting up aliases for `mysql` and `vtctlclient`: +For ease-of-use, Vitess provides a script to port-forward from Kubernetes to your local machine. This script also recommends setting up aliases for `mysql` and `vtctldclient`: ```bash ./pf.sh & alias vtctldclient="vtctldclient --server=localhost:15999" -alias vtctlclient="vtctlclient --server=localhost:15999" alias mysql="mysql -h 127.0.0.1 -P 15306 -u user" ``` -Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctlclient && unalias vtctldclient` or close your session. +Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctldclient` or close your session. Once the port-forward starts running, the VTAdmin UI will be available at [http://localhost:14000/](http://localhost:14000/) diff --git a/content/en/docs/18.0/reference/features/connection-pools.md b/content/en/docs/18.0/reference/features/connection-pools.md index d30eb0eb7..3571ce4eb 100644 --- a/content/en/docs/18.0/reference/features/connection-pools.md +++ b/content/en/docs/18.0/reference/features/connection-pools.md @@ -48,7 +48,7 @@ As a result, connection pools should be sized mindful of the capacity of the und * Max size controlled by: `--dba_pool_size` (default 20) * metric: `vttablet_dba_conn_pool_capacity` * vttablet user flag: `--db_dba_user` (default 'vt_dba') - * Used by vttablet `ExecuteFetchAsDba` RPC. This is used when using `vtctlclient ExecuteFetchAsDba` + * Used by vttablet `ExecuteFetchAsDBA` RPC. This is used when using `vtctldclient ExecuteFetchAsDBA` Also used implicitly for various internal Vitess maintenance tasks (e.g. schema reloads, etc.) ### app_conn_pool @@ -56,7 +56,7 @@ As a result, connection pools should be sized mindful of the capacity of the und * Max size controlled by: `--app_pool_size` (default 40) * metric: `vttablet_app_conn_pool_capacity` * vttablet user flag: `--db_app_user` default 'vt_app') - * Used by vttablet `ExecuteFetchAsApp` RPC. This is used when using `vtctlclient ExecuteFetchAsApp` + * Used by vttablet `ExecuteFetchAsApp` RPC. This is used when using `vtctldclient ExecuteFetchAsApp` ### tx_read_pool @@ -89,7 +89,6 @@ As a result, connection pools should be sized mindful of the capacity of the und #### `--db_allprivs_user` * (default 'vt_allprivs') - * Created on demand by `vtctlclient ExecuteFetchAsAllPrivs` #### `--db_erepl_user` diff --git a/content/en/docs/18.0/reference/features/tablet-throttler.md b/content/en/docs/18.0/reference/features/tablet-throttler.md index 67c73399d..25063c456 100644 --- a/content/en/docs/18.0/reference/features/tablet-throttler.md +++ b/content/en/docs/18.0/reference/features/tablet-throttler.md @@ -123,12 +123,12 @@ The following flag was removed: - `--enable_lag_throttler` -Updating the throttler config is done via `vtctlclient` or `vtctldclient`. For example: +Updating the throttler config is done via `vtctldclient`. For example: ```sh -$ vtctlclient -- UpdateThrottlerConfig --enable --threshold 3.0 commerce +$ vtctldclient UpdateThrottlerConfig --enable --threshold 3.0 commerce $ vtctldclient UpdateThrottlerConfig --disable commerce -$ vtctldclient UpdateThrottlerConfig --throttle-app="vreplication" --throttle-app-ratio 0.5 --throttle-app-duration "30m" commerce +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-ratio 0.5 --throttle-app-duration "30m" commerce ``` See [vtctl UpdateThrottlerConfig](../../programs/vtctl/throttler#updatethrottlerconfig). diff --git a/content/en/docs/18.0/reference/features/topology-service.md b/content/en/docs/18.0/reference/features/topology-service.md index 8ec6e1f8a..ac4ee0328 100644 --- a/content/en/docs/18.0/reference/features/topology-service.md +++ b/content/en/docs/18.0/reference/features/topology-service.md @@ -516,13 +516,13 @@ information about the local topology service: * `${CELL_NAME}` the name of our local cell in this case `US_EAST` ``` sh -# vtctlclient uses the IP address of the vtctld daemon with the `--server` flag +# vtctldclient uses the IP address of the vtctld daemon with the `--server` flag # The daemon already has the global topology information, therefore, we do not # need to explicitly provide these details. -vtctlclient --server ${VTCTLD_IP}:15999 AddCellInfo -- \ +vtctldclient --server ${VTCTLD_IP}:15999 AddCellInfo -- \ --root=/vitess/${CELL_NAME} \ - --server_address=${CELL_ETCD_SERVER} \ + --server-address=${CELL_ETCD_SERVER} \ ${CELL_NAME} ``` @@ -573,8 +573,8 @@ propagate information from the global topology service back to the local topolog services ```sh -vtctlclient --server ${VTCTLD_IP}:15999 RebuildKeyspaceGraph ${KEYSPACE_NAME} -vtctlclient --server ${VTCTLD_IP}:15999 RebuildVSchemaGraph +vtctldclient --server ${VTCTLD_IP}:15999 RebuildKeyspaceGraph ${KEYSPACE_NAME} +vtctldclient --server ${VTCTLD_IP}:15999 RebuildVSchemaGraph ``` @@ -604,7 +604,7 @@ run 5 global servers across all cells (for global topology data) and 3 local servers per cell (for per-cell topology data). To migrate to such a setup, start by adding the 3 local servers in the second -cell and run `vtctlclient AddCellinfo` as was done for the first cell. Tablets and +cell and run `vtctldclient AddCellInfo` as was done for the first cell. Tablets and vtgates can now be started in the second cell, and used normally. vtgate can then be configured with a list of cells to watch for tablets using diff --git a/content/en/docs/18.0/reference/features/vindexes.md b/content/en/docs/18.0/reference/features/vindexes.md index 386846b51..ac9175f69 100644 --- a/content/en/docs/18.0/reference/features/vindexes.md +++ b/content/en/docs/18.0/reference/features/vindexes.md @@ -267,7 +267,7 @@ You can query Vindex functions to see the resulting `keyspace_id` it produces (t First, a snippet of the VSchema: ``` shell -$ vtctlclient -server=localhost:15999 GetVSchema customer | jq '.vindexes' +$ vtctldclient --server=localhost:15999 GetVSchema customer | jq '.vindexes' { "binary_md5_vdx": { "type": "binary_md5" diff --git a/content/en/docs/18.0/reference/vreplication/createlookupvindex.md b/content/en/docs/18.0/reference/vreplication/createlookupvindex.md deleted file mode 100644 index 8acf91cbd..000000000 --- a/content/en/docs/18.0/reference/vreplication/createlookupvindex.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: CreateLookupVindex -weight: 60 ---- - -**CreateLookupVindex** is a [VReplication](../../../reference/vreplication/) workflow used to create **and** backfill -a [lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already -exists, and may have a significant amount of data in it already. - -Internally, the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) process uses -VReplication for the backfill process, until the lookup Vindex is "in sync". Then the normal process for -adding/deleting/updating rows in the lookup Vindex via the usual -[transactional flow when updating the "owner" table for the Vindex](../../../reference/features/vindexes/#lookup-vindex-types) -takes over. - -In this guide, we will walk through the process of using the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) -workflow, and give some insight into what happens underneath the covers. - -The `CreateLookupVindex` `vtctl` client command has the following syntax: - -```CreateLookupVindex -- [--cells=] [--continue_after_copy_with_owner=false] [--tablet_types=] ``` - -* ``: Use the lookup Vindex specified in `` along with - VReplication to populate/backfill the lookup Vindex from the source table. -* ``: The Vitess keyspace we are creating the lookup Vindex in. - The source table is expected to also be in this keyspace. -* `--tablet-types`: Provided to specify the tablet types - (e.g. `PRIMARY`, `REPLICA`, `RDONLY`) that are acceptable - as source tablets for the VReplication stream(s) that this command will - create. If not specified, the tablet type used will default to the value - of the [`vttablet --vreplication_tablet_type` flag](../../../reference/vreplication/flags/#vreplication_tablet_type) - value, which defaults to `in_order:REPLICA,PRIMARY`. -* `--cells`: By default VReplication streams, such as used by - `CreateLookupVindex`, will not cross cell boundaries. If you want the - VReplication streams to source their data from tablets in cells other - than the local cell, you can use the `--cells` option to specify a - comma-separated list of cells (see [VReplication tablet selection](../../../reference/vreplication/tablet_selection/)). -* `--continue_after_copy_with_owner`: By default, when an owner is provided in the ``, - the VReplication streams will stop after the backfill completes. Specify this flag if - you don't want this to happen. This is useful if, for example, the owner table is being - migrated from an unsharded keyspace to a sharded keyspace using - [`MoveTables`](../../../reference/vreplication/movetables/). - -The `` describes the lookup Vindex to be created, and details about -the table it is to be created against (on which column, etc.). However, -you do not have to specify details about the actual lookup table, Vitess -will create that automatically based on the type of the column you are -creating the Vindex column on, etc. \ No newline at end of file diff --git a/content/en/docs/18.0/reference/vreplication/internal/cutover.md b/content/en/docs/18.0/reference/vreplication/internal/cutover.md index 6267fb56e..40862b377 100644 --- a/content/en/docs/18.0/reference/vreplication/internal/cutover.md +++ b/content/en/docs/18.0/reference/vreplication/internal/cutover.md @@ -13,8 +13,8 @@ cached locally, the processes involved will refresh their topo data throughout t tablet on the source and target shards that are involved in a [VReplication](../../) workflow will refresh their topo data multiple times as the state of things transition during the cutover. If we are *not* able to confirm that all tablets involved in a VReplication worfklow are able to refresh their topo data then the cutover -command — e.g. [`vtctlclient SwitchTraffic`](../../switchtraffic) — will cancel the operation -and return an error indicating which tablet(s) are unhealthy (including for `--dry_run` executions). +command — e.g. [`vtctldclient SwitchTraffic`](../../switchtraffic) — will cancel the operation +and return an error indicating which tablet(s) are unhealthy (including for `--dry-run` executions). {{< /info >}} ## VSchema @@ -28,11 +28,16 @@ one [`Shard`](../../../features/topology-service/#shard) key per keyspace which shard that has been created within the keyspace. For each shard that is healthy there is an attribute `is_primary_serving` which is set to true. The other shards which have been created but are still not healthy and serving within the keyspace will not have this attribute set. Here is an example shard info record from an unsharded -keyspace named commerce (without the `--cell` flag being passed the `global` topo base path is used): +keyspace named commerce: ```bash -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto '/keyspaces/commerce/shards/0/Shard' -primary_alias:{cell:"zone1" uid:100} primary_term_start_time:{seconds:1650341417 nanoseconds:374817485} is_primary_serving:true +$ vtctldclient --server=localhost:15999 GetTopologyPath /global/keyspaces/commerce/shards/0/Shard +{ + "name": "Shard", + "path": "/global//keyspaces/commerce/shards/0/Shard", + "data": "primary_alias:{cell:\"zone1\" uid:101} primary_term_start_time:{seconds:1697055542 nanoseconds:430056000} is_primary_serving:true", + "children": [] +} ``` ## SrvKeyspace @@ -50,11 +55,21 @@ same unsharded commerce keyspace and here we specify the `--cell` flag so that c its `CellInfo` record in the `global` topo — is used: ```bash -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto '/cells/zone1/CellInfo' -server_address:"localhost:2379" root:"/vitess/zone1" +$ vtctldclient --server=localhost:15999 GetTopologyPath /global/cells/zone1/CellInfo +{ + "name": "CellInfo", + "path": "/global/cells/zone1/CellInfo", + "data": "server_address:\"localhost:2379\" root:\"/vitess/zone1\"", + "children": [] +} -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto --cell=zone1 '/keyspaces/commerce/SrvKeyspace' -partitions:{served_type:PRIMARY shard_references:{name:"0"}} partitions:{served_type:REPLICA shard_references:{name:"0"}} partitions:{served_type:RDONLY shard_references:{name:"0"}} +$ vtctldclient --server=localhost:15999 GetTopologyPath /zone1/keyspaces/commerce/SrvKeyspace +{ + "name": "SrvKeyspace", + "path": "/zone1/keyspaces/commerce/SrvKeyspace", + "data": "partitions:{served_type:PRIMARY shard_references:{name:\"0\"}} partitions:{served_type:REPLICA shard_references:{name:\"0\"}} partitions:{served_type:RDONLY shard_references:{name:\"0\"}}", + "children": [] +} ``` ## Routing Rules @@ -66,15 +81,20 @@ where we have an active [`MoveTables`](../../../vreplication/movetables/) workfl customer keyspace but we have not switched any traffic yet: ```bash -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto '/RoutingRules' -rules:{from_table:"corder@rdonly" to_tables:"commerce.corder"} rules:{from_table:"customer.corder" to_tables:"commerce.corder"} rules:{from_table:"customer.corder@replica" to_tables:"commerce.corder"} rules:{from_table:"customer@rdonly" to_tables:"commerce.customer"} rules:{from_table:"customer.customer@rdonly" to_tables:"commerce.customer"} rules:{from_table:"customer.corder@rdonly" to_tables:"commerce.corder"} rules:{from_table:"customer@replica" to_tables:"commerce.customer"} rules:{from_table:"corder@replica" to_tables:"commerce.corder"} rules:{from_table:"commerce.corder@replica" to_tables:"commerce.corder"} rules:{from_table:"commerce.corder@rdonly" to_tables:"commerce.corder"} rules:{from_table:"commerce.customer@rdonly" to_tables:"commerce.customer"} rules:{from_table:"corder" to_tables:"commerce.corder"} rules:{from_table:"customer.customer@replica" to_tables:"commerce.customer"} rules:{from_table:"commerce.customer@replica" to_tables:"commerce.customer"} rules:{from_table:"customer" to_tables:"commerce.customer"} rules:{from_table:"customer.customer" to_tables:"commerce.customer"} +$ vtctldclient --server=localhost:15999 GetTopologyPath /global/RoutingRules +{ + "name": "RoutingRules", + "path": "/global/RoutingRules", + "data": "rules:{from_table:\"customer.customer\" to_tables:\"commerce.customer\"} rules:{from_table:\"commerce.customer@rdonly\" to_tables:\"commerce.customer\"} rules:{from_table:\"corder\" to_tables:\"commerce.corder\"} rules:{from_table:\"corder@replica\" to_tables:\"commerce.corder\"} rules:{from_table:\"corder@rdonly\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer.corder\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer@rdonly\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer.corder@replica\" to_tables:\"commerce.corder\"} rules:{from_table:\"commerce.customer@replica\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer.customer@replica\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer.customer@rdonly\" to_tables:\"commerce.customer\"} rules:{from_table:\"commerce.corder@rdonly\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer@replica\" to_tables:\"commerce.customer\"} rules:{from_table:\"commerce.corder@replica\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer.corder@rdonly\" to_tables:\"commerce.corder\"}", + "children": [] +} ```
{{< info >}} In practice you would instead typically view the routing rules via the -dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions/#getroutingrules) +dedicated [`GetRoutingRules`](../../../programs/vtctldclient/vtctldclient_getroutingrules/) vtctl client command which will return the rules for all keyspaces in the topo. {{< /info >}} diff --git a/content/en/docs/18.0/reference/vreplication/lookupvindex.md b/content/en/docs/18.0/reference/vreplication/lookupvindex.md new file mode 100644 index 000000000..951f4cefc --- /dev/null +++ b/content/en/docs/18.0/reference/vreplication/lookupvindex.md @@ -0,0 +1,23 @@ +--- +title: LookupVindex +description: Create, backfill, and externalize Lookup Vindexes +weight: 60 +--- + +[`LookupVindex`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/) is a command used to create **and** backfill +a [Lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already +exists, and may have a significant amount of data in it already. + +Internally, the [`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command uses +VReplication for the backfill process, until the lookup Vindex is "in sync". Then the normal process for +adding/deleting/updating rows in the lookup Vindex via the usual +[transactional flow when updating the "owner" table for the Vindex](../../../reference/features/vindexes/#lookup-vindex-types) +takes over. + +## Command + +Please see the [`LookupVindex` command reference](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/) for a full list of sub-commands and their flags. + +## Additional Information + +Please see the user guide for examples of [Creating a Lookup Vindex](../../../user-guides/configuration-advanced/createlookupvindex/) for more information on how to use this command. diff --git a/content/en/docs/18.0/reference/vreplication/materialize.md b/content/en/docs/18.0/reference/vreplication/materialize.md index 4a044f274..6526510ae 100644 --- a/content/en/docs/18.0/reference/vreplication/materialize.md +++ b/content/en/docs/18.0/reference/vreplication/materialize.md @@ -1,28 +1,47 @@ --- title: Materialize -description: +description: Materialize the results of a query into a table weight: 40 --- -### Command - -``` -Materialize -- [--cells=] [--tablet_types=] -``` - ### Description -`Materialize` is a lower level vreplication command that allows for generalized materialization of tables. The target tables +[`Materialize`](../../programs/vtctldclient/vtctldclient_materialize/) is a lower level vreplication command that allows for generalized materialization of tables. The target tables can be copies, aggregations, or views. The target tables are kept in sync in near-realtime. -You can specify multiple tables to materialize using the `json_spec` parameter. +You can specify multiple tables to materialize using the [`create`](../../programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_create/) sub-command's `--table-settings` flag. {{< warning >}} Be careful to avoid using the `INSTANT ADD COLUMN` feature in [MySQL 8.0+](https://mysqlserverteam.com/mysql-8-0-innodb-now-supports-instant-add-column/) with materialization source tables as this can cause the vreplication based materialization workflow to break. {{< /warning >}} +## The Basic Materialize Workflow Lifecycle + +1. Initiate the migration using `Materialize` +2. Monitor the workflow using `show` or `status`
+`Materialize --target-keyspace show --workflow `
+`Materialize --target-keyspace status --workflow `
+3. Start accessing your views once the workflow has started Replicating + +## Command + +Please see the [`Materialize` command reference](../../programs/vtctldclient/vtctldclient_materialize/) for a full list of sub-commands and their flags. + +### Example + +```shell +vtctldclient --server localhost:15999 Materialize --workflow product_sales --target-keyspace commerce create --source-keyspace commerce --table-settings '[{"target_table": "sales_by_sku", "create_ddl": "create table sales_by_sku (sku varbinary(128) not null primary key, orders bigint, revenue bigint)", "source_expression": "select sku, count(*) as orders, sum(price) as revenue from corder group by sku"}]' --cells zone1 --cells zone2 --tablet-types replica +``` + ### Parameters +### Action + +[`Materialize`](../../programs/vtctldclient/vtctldclient_materialize/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_materialize/#see-also) defines the operation on the workflow. + +### Options + +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_materialize/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_materialize/) for the full list of command options or flags. Below we will add additional information for a subset of key options. #### --cells **optional**\ @@ -41,7 +60,7 @@ cells should be used to pick a tablet for selecting data from the source keyspac * To reduce bandwidth costs by skipping cells that are in different availability zones * Select cells where replica lags are lower -#### --tablet_types +#### --tablet-types **optional**\ **default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ **string** @@ -58,44 +77,34 @@ specified impacts [tablet selection](../tablet_selection/) for the workflow. * To reduce the load on PRIMARY tablets by using REPLICAs or RDONLYs * Reducing lag by pointing to PRIMARY -#### JSON spec details -
+#### --table-settings +**required**\ +**JSON** -* *workflow* name to refer to this materialization -* *source_keyspace* keyspace containing the source table -* *target_keyspace* keyspace to materialize to -* *table_settings* list of views to be materialized and the associated query - * *target_table* name of table to which to materialize the data to - * *source_expression* the materialization query -* Optional parameters: - * *stop_after_copy* if vreplication should be stopped after the copy phase - is complete - * *cell* name of a cell, or a comma separated list of cells, that should be - used for choosing source tablet(s) for the materialization. If this - parameter is not specified, only cell(s) local to the target tablet(s) is - considered - * *tablet_types* a Vitess tablet_type, or comma separated list of tablet - types, that should be used for choosing source tablet(s) for the - materialization. If not specified, this defaults to the tablet type(s) - specified by the `--vreplication_tablet_type` VTTablet command line flag - -
+
-#### Example +This is a JSON array where each value must contain two key/value pairs. The first required key is 'target_table' and it is the name of the table in the target-keyspace to store the results in. The second required key is 'source_expression' and its value is the select query to run against the source table. An optional key/value pair can also be specified for 'create_ddl' which provides the DDL to create the target table if it does not exist – you can alternatively specify a value of 'copy' if the target table schema should be copied as-is from the source keyspace. Here's an example value for table-settings: + +```json +[ + { + "target_table": "customer_one_email", + "source_expression": "select email from customer where customer_id = 1" + }, + { + "target_table": "states", + "source_expression": "select * from states", + "create_ddl": "copy" + }, + { + "target_table": "sales_by_sku", + "source_expression": "select sku, count(*) as orders, sum(price) as revenue from corder group by sku", + "create_ddl": "create table sales_by_sku (sku varbinary(128) not null primary key, orders bigint, revenue bigint)" + } +] ``` -Materialize '{"workflow": "product_sales", "source_keyspace": "commerce", "target_keyspace": "customer", - "table_settings": [{"target_table": "sales_by_sku", - "source_expression": "select sku, count(*), sum(price) from corder group by order_id"}], - "cell": "zone1", "tablet_types": "REPLICA"}' -``` - -### A Materialize Workflow - -Once you decide on your materialization requirements, you need to initiate a VReplication workflow as follows: -1. Initiate the migration using `Materialize` -2. Monitor the workflow using [Workflow](../workflow) -3. Start accessing your views once the workflow has started Replicating +
### Notes diff --git a/content/en/docs/18.0/reference/vreplication/migrate.md b/content/en/docs/18.0/reference/vreplication/migrate.md index b7ed3cb6a..8c0f6ad16 100644 --- a/content/en/docs/18.0/reference/vreplication/migrate.md +++ b/content/en/docs/18.0/reference/vreplication/migrate.md @@ -4,17 +4,10 @@ description: Move tables from an external cluster weight: 85 --- -### Command - -``` -Migrate -- -``` - - ### Description -Migrate is used to start and manage VReplication workflows for copying keyspaces and/or tables from a source Vitess cluster, to a target Vitess cluster. -This command is built off of [MoveTables](../movetables) but has been extended to work with independent source and target topology services. It should be +[`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) is used to start and manage VReplication workflows for copying keyspaces and/or tables from a source Vitess cluster, to a target Vitess cluster. +This command is built off of [`MoveTables`](../movetables) but has been extended to work with independent source and target topology services. It should be utilized when moving Keyspaces or Tables between two separate Vitess environments. Migrate is an advantageous strategy for large sharded environments for a few reasons: @@ -30,76 +23,60 @@ on working with external Vitess clusters. #### Differences Between Migrate and MoveTables -`Migrate` has separate semantics and behaviors from `MoveTables`: +[`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) has separate semantics and behaviors from [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/): -* `MoveTables` migrates data from one keyspace to another, within the same Vitess cluster; `Migrate` functions between two separated Vitess clusters. -* `MoveTables` erases the source data upon completion by default; Migrate keeps the source data intact. - * There are flags available in MoveTables to change the default behavior in regards to the source data. -* `MoveTables` sets up routing rules and reverse replication, allowing for rollback prior to completion. - * Switching read/write traffic is not meaningful in the case of `Migrate`, as the Source is in a different cluster. +* [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) migrates data from one keyspace to another, within the same Vitess cluster; [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) functions between two separate Vitess clusters. +* [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) erases the source data upon completion by default; Migrate keeps the source data intact. + * There are flags available in [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) to change the default behavior in regards to the source data. +* [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) sets up routing rules and reverse replication, allowing for rollback prior to completion. + * Switching read/write traffic is not meaningful in the case of [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/), as the Source is in a different cluster. * Switching traffic requires the Target to have the ability to create vreplication streams (in the `_vt` database) on the Source; this may not always be possible on production systems. -* Not all `MoveTables` options work with `Migrate`; for example [`Progress`](../progress) is unavailable with `Migrate`. - - -### Parameters - -#### action - -Migrate is an "umbrella" command. The `action` sub-command defines the operation on the workflow. -The only actions supported by Migrate are `Create`, `Complete` and `Cancel`. +* Not all [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) sub-commands work with [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/); for example `SwitchTraffic` and `ReverseTraffic` are unavailable with [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/). -The `Create` action is also modified to accommodate the external mount. The proper syntax will be highlighted below: +## Command -``` -Migrate -- --source . Create -``` - -If needed, you can rename the keyspace while migrating, simply provide a different name for the target keyspace in the ``. - - -#### options - -Each `action` has additional options/parameters that can be used to modify its behavior. - -The options for the supported commands are the same as [MoveTables](../movetables), with the exception of `--reverse_replication` as setting -up the reverse vreplication streams requires modifying the source cluster's `_vt` sidecar database which we cannot do as that database is -specific to a single Vitess cluster and these streams belong to a different one (the target cluster). +Please see the [`Migrate` command reference](../../programs/vtctldclient/vtctldclient_migrate/) for a full list of sub-commands and their flags. -A common option to give if migrating all of the tables from a source keyspace is the `--all` option. - - -#### workflow identifier - -All workflows are identified by `targetKeyspace.workflow` where `targetKeyspace` is the name of the keyspace to which the tables are being moved. `workflow` is a name you assign to the Migrate workflow to identify it. - - - -### A Migrate Workflow lifecycle +### An Example Migrate Workflow Lifecycle {{< info >}} -NOTE: there is no reverse vreplication flow with `Migrate`. After the `Migrate Complete` command is given; no writes will be replicated between the Source and Target Vitess clusters. They are essentially two identical Vitess clusters running in two different environments. Once writing resumes on one of the clusters they will begin to drift apart. +NOTE: there is no reverse vreplication flow with [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/). After the [`Migrate complete`](../../programs/vtctldclient/vtctldclient_migrate/vtctldclient_migrate_complete/) command is given; no writes will be replicated between the Source and Target Vitess clusters. They are essentially two identical Vitess clusters running in two different environments. Once writing resumes on one of the clusters they will begin to drift apart. {{< /info >}} 1. Mount the source Vitess cluster using [Mount](../mount).
-`Mount -- --type vitess --topo_type etcd2 --topo_server localhost:12379 --topo_root /vitess/global ext1` +`Mount register --name ext1 --topo-type etcd2 --topo-server localhost:12379 --topo-root /vitess/global` 1. Apply source vSchema to the Target's Keyspace.
-`ApplyVSchema -- --vschema_file commerceVschema.json commerce` -1. Initiate the migration using `Create`.
-`Migrate -- --all --source ext1.commerce Create commerce.wf` -1. Monitor the workflow using `Show`.
-`Workflow commerce.wf Show` +`ApplyVSchema --vschema-file commerceVschema.json commerce` +1. Initiate the migration using `create`.
+`Migrate --workflow import --target-keyspace customer create --source-keyspace commerce --mount-name ext1 --tablet-types replica` +1. Monitor the workflow using `show` and `status`.
+`Migrate --workflow import --target-keyspace customer show` +`Migrate --workflow import --target-keyspace customer status` 1. Confirm that data has been copied over correctly using [VDiff](../vdiff).
-`VDiff commerce.wf` 1. Stop the application from writing to the source Vitess cluster.
1. Confirm again the data has been copied over correctly using [VDiff](../vdiff).
-`VDiff commerce.wf` -1. Cleanup vreplication artifacts and source tables with `Complete`.
-`Migrate Complete commerce.wf` +1. Cleanup vreplication artifacts and source tables with `complete`.
+`Migrate --workflow import --target-keyspace customer complete` 1. Start the application pointed to the target Vitess Cluster. 1. Unmount the source cluster.
-`Mount -- --unmount ext1` +`Mount unregister --name ext1` + +### Parameters + +### Action +[`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_migrate/#see-also) defines the operation on the workflow. + +### Options + +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_migrate/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_migrate/) for the full list of command options or flags. + +The options for the supported commands are the same as [MoveTables](../movetables), with the exception of `--enable-reverse-replication` as setting +up the reverse vreplication streams requires modifying the source cluster's `_vt` sidecar database which we cannot do as that database is +specific to a single Vitess cluster and these streams belong to a different one (the target cluster). + +A common option to give if migrating all of the tables from a source keyspace is the `--all-tables` option. ### Network Considerations @@ -107,25 +84,25 @@ For Migrate to function properly, you will need to ensure communication is possi * Target vtctld/vttablet (PRIMARY) processes must reach the Source topo service. * Target vtctld/vttablet (PRIMARY) processes must reach EACH source vttablet's grpc port. - * You can limit your source vttablet's to just the replicas by using the `--tablet_types` option when creating the migration. + * You can limit your source vttablet's to just the replicas by using the `--tablet-types` option when creating the migration. If you're migrating a keyspace from a production system, you may want to target a replica to reduce your load on the primary vttablets. This will also assist you in reducing the number of network considerations you need to make. ``` -Migrate -- --all --tablet_types REPLICA --source . Create +Migrate --workflow --target-keyspace create --source-keyspace --mount-name --tablet-types replica ``` -To verify the Migration you can also perform VDiff with the `--tablet_types` option: +To verify the Migration you can also perform VDiff with the `--tablet-types` option: ``` -VDiff -- --tablet_types REPLICA . +VDiff --workflow --target-keyspace create --tablet-types REPLICA ``` ### Troubleshooting Errors `Migrate` fails right away with error: -```sh +```shell E0224 23:51:45.312536 138 main.go:76] remote error: rpc error: code = Unknown desc = table table1 not found in vschema for keyspace sharded ```
Solution: @@ -136,7 +113,7 @@ E0224 23:51:45.312536 138 main.go:76] remote error: rpc error: code = Unknow `Migrate` fails right away with error: -```sh +```shell E0224 18:55:29.275019 578 main.go:76] remote error: rpc error: code = Unknown desc = node doesn't exist ``` @@ -149,7 +126,7 @@ E0224 18:55:29.275019 578 main.go:76] remote error: rpc error: code = Unknow After issuing `Migrate` command everything is stuck at 0% progress with errors found in target vttablet logs: -```sh +```shell I0223 20:13:36.825110 1 tablet_picker.go:146] No tablet found for streaming ``` @@ -157,9 +134,9 @@ I0223 20:13:36.825110 1 tablet_picker.go:146] No tablet found for streamin * Ensure there is networking communication between Target vttablets and Source vttablets * Ensure there is networking communication between Target vttablets and the Source topology service * Older versions of Vitess may be labeling vttablets as "master" instead of "primary" - you can resolve this problem by adjusting your `tablet_types`: + you can resolve this problem by adjusting your `tablet-types`: - Migrate -- --all --tablet_types "MASTER,REPLICA,RDONLY" ... + Migrate ... create --tablet-types "MASTER,REPLICA,RDONLY" ... --- diff --git a/content/en/docs/18.0/reference/vreplication/mount.md b/content/en/docs/18.0/reference/vreplication/mount.md index 86426aaf5..64b6c83fe 100644 --- a/content/en/docs/18.0/reference/vreplication/mount.md +++ b/content/en/docs/18.0/reference/vreplication/mount.md @@ -4,13 +4,6 @@ description: Link an external cluster to the current one weight: 90 --- -### Command - -``` -Mount -- [--type vitess] [--topo_type=etcd2|consul|zookeeper] [--topo_server=topo_url] - [--topo_root=root_topo_node> [--unmount] [--list] [--show] [] -``` - ### Description Mount is used to link external Vitess clusters to the current cluster. @@ -18,32 +11,9 @@ Mount is used to link external Vitess clusters to the current cluster. Mounting Vitess clusters requires the topology information of the external cluster to be specified. Used in conjunction with [the `Migrate` command](../migrate). {{< info >}} -No validation is performed when using the `Mount` command. You must ensure your values are correct, or you may get errors when initializing a migration. +No validation is performed when using the [`Mount`](../../programs/vtctldclient/vtctldclient_mount/) command. You must ensure your values are correct, or you may get errors when initializing a migration. {{< /info >}} +## Command -### Parameters - -#### cluster_name - -The name that will be used in VReplication workflows to refer to the mounted cluster. Required when mounting, unmounting or getting details of a cluster. - -#### unmount - -Unmount an already mounted cluster. Requires `cluster_name` to be specified. - -#### --show - -Show details of an already mounted cluster. Requires `cluster_name` to be specified. - -#### --list - -List all mounted clusters. - -### Topo Parameters - -##### --topo_type=[etcd2|consul|zookeeper] -##### --topo_server= -##### --topo_root= - -Mandatory (and only specified) while mounting a Vitess cluster. These should specify the topology parameters of the cluster being mounted. +Please see the [`Mount` command reference](../../programs/vtctldclient/vtctldclient_mount/) for a full list of sub-commands and their flags. diff --git a/content/en/docs/18.0/reference/vreplication/movetables.md b/content/en/docs/18.0/reference/vreplication/movetables.md index 865e73ed0..e0bd8ac32 100644 --- a/content/en/docs/18.0/reference/vreplication/movetables.md +++ b/content/en/docs/18.0/reference/vreplication/movetables.md @@ -9,77 +9,91 @@ aliases: ['/docs/reference/vreplication/v2/movetables/'] These workflows can have a significant impact on the source tablets (which are often in production) — especially when a PRIMARY tablet is used as a source. You can limit the impact on the source tablets using the [`--vreplication_copy_phase_max_*` vttablet flags](../flags/#vreplication_copy_phase_max_innodb_history_list_length) {{< /warning >}} +## Description + +[`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) is used to start and manage workflows to move one or more tables from an external database or an existing Vitess keyspace into a new Vitess keyspace. The target keyspace can be unsharded or sharded. + +[`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) is typically used for migrating data into Vitess or to implement vertical sharding. You might use the former when you first start using Vitess and the latter if you want to distribute your load across servers without sharding tables. + ## Command -``` -MoveTables -- -``` -or +Please see the [`MoveTables` command reference](../../programs/vtctldclient/vtctldclient_movetables/) for a full list of sub-commands and their flags. -``` -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] [--no-routing-rules] - -``` +## The Basic MoveTables Workflow Lifecycle -## Description +1. Initiate the migration using `create`
+`MoveTables --workflow --target-keyspace create --source-keyspace --tables ` +1. Monitor the workflow using `show` or `status`
+`MoveTables --workflow --target-keyspace show`
+`MoveTables --workflow --target-keyspace status`
+1. Confirm that data has been copied over correctly using [VDiff](../vdiff) +1. Cutover to the target keyspace with `switchtraffic`
+`MoveTables --workflow --target-keyspace switchtraffic` +1. Cleanup vreplication artifacts and source tables with `complete`
+`MoveTables --workflow --target-keyspace complete` + +## Common Use Cases for MoveTables + +### Adopting Vitess + +For those wanting to try out Vitess for the first time, `MoveTables` provides an easy way to route part of their workload to Vitess with the ability to migrate back at any time without any risk. You point a vttablet to your existing MySQL installation, spin up an unsharded Vitess cluster and use a `MoveTables` workflow to start serving some tables from Vitess. You can also go further and use a Reshard workflow to experiment with a sharded version of a part of your database. + +See this [user guide](../../../user-guides/configuration-advanced/unmanaged-tablet/#move-legacytable-to-the-commerce-keyspace) for detailed steps. -`MoveTables` is used to start and manage workflows to move one or more tables from an external database or an existing Vitess keyspace into a new Vitess keyspace. The target keyspace can be unsharded or sharded. +### Vertical Sharding + +For existing Vitess users you can easily move one or more tables to another keyspace, either for balancing load or as preparation for sharding your tables. -`MoveTables` is typically used for migrating data into Vitess or to implement vertical sharding. You might use the former when you first start using Vitess and the latter if you want to distribute your load across servers without sharding tables. +See this [user guide](../../../user-guides/migration/move-tables/) which describes how `MoveTables` works in the local example provided in the Vitess repo. ## Parameters -### action +### Action -`MoveTables` is an "umbrella" command. The `action` sub-command defines the operation on the workflow. -Action must be one of the following: `Create`, `Show`, `Progress`, `SwitchTraffic`, `ReverseTrafffic`, `Cancel`, or `Complete`. +[`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_movetables/#see-also) defines the operation on the workflow. #### Create
-`Create` sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow. +[`create`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_create/) sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow.
#### Show
-`Show` displays useful information about a workflow. (At this time the [Workflow](../workflow) Show command gives more information. This will be improved over time.) +[`show`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_show/) displays useful information about a workflow – including recent logs.
-#### Progress +#### Status
-`Progress` reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. +[`status`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_status/) (or `progress`) reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. It also shows the current state of traffic for the tables involved in the workflow. -It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `analyze table` to update the statistics if so desired. +It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `ANALYZE TABLE` to update the statistics if so desired.
#### SwitchTraffic
-`SwitchTraffic` switches traffic forward for the `tablet_types` specified. This replaces the previous `SwitchReads` and `SwitchWrites` commands with a single one. It is now possible to switch all traffic with just one command, and this is the default behavior. Also, you can now switch replica, rdonly and primary traffic in any order: earlier you needed to first `SwitchReads` (for replicas and rdonly tablets) first before `SwitchWrites`. +[`switchtraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_switchtraffic/) switches traffic forward for the `tablet-types` specified. You can switch all traffic with just one command, and this is the default behavior. Note that you can now switch replica, rdonly, and primary traffic in any order.
#### ReverseTraffic
-`ReverseTraffic` switches traffic in the reverse direction for the `tablet_types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet_types` specified. +[`reversetraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_reversetraffic/) switches traffic in the reverse direction for the `tablet-types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet-types` specified.
#### Cancel
-`Cancel` can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. `Cancel` can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from the vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and blacklisted tables from the topo and, by default, the target tables on the target keyspace -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)). +[`cancel`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_cancel/) can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. `cancel` can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from the vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and blacklisted tables from the topo and, by default, the target tables on the target keyspace +(see `--keep-data` and `--rename-tables`).
@@ -90,27 +104,16 @@ It is too expensive to get real-time row counts of tables, using _count(*)_, say This is a destructive command {{< /warning >}} -`Complete` is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and and blacklisted tables from the topo. By default, the source tables are also dropped on the target keyspace -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)). +[`complete`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_complete/) is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and and blocklisted tables from the topo. By default, the source tables are also dropped on the target keyspace +(see `--keep-data` and `--rename-tables`). -### options +### Options -Each `action` has additional options/parameters that can be used to modify its behavior. +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_movetables/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_movetables/) for the full list of command options or flags. Below we will add additional information for a subset of key options. -`actions` are common to both `MoveTables` and `Reshard` workflows. Only the `create` action has different parameters, all other actions have common options and similar semantics. - -#### --all - -**optional** cannot specify `table_specs` if `--all` is specified -
- -Move all tables from the source keyspace. - -
- -#### --auto_start +#### --auto-start **optional**\ **default** true @@ -167,36 +170,6 @@ parallel index builds. This is logically similar to the -#### --drop_foreign_keys -**optional**\ -**default** false - -
- -If true, tables in the target keyspace will be created without any foreign keys that exist on the source. - -
- -#### --dry_run -**optional**\ -**default** false - -
- -For the `SwitchTraffic`, `ReverseTraffic`, and `Complete` actions, you can do a dry run where no actual steps are taken -but the command logs all the steps that would be taken. - -
- -#### --exclude -**optional** only applies if `--all` is specified - -
- -If moving all tables, specifies tables to be skipped. - -
- #### --initialize-target-sequences **optional**\ **default** false @@ -228,35 +201,15 @@ You will still need to take the manual step of [creating each backing sequence t in an unsharded keyspace of your choosing prior to the `SwitchTraffic` operation. {{< /info>}} -#### --keep_data +#### --max-replication-lag-allowed **optional**\ -**default** false - -
- -Usually, the target tables are deleted by `Cancel`. If this flag is used the target tables will not be deleted. - -
- -#### --keep_routing_rules -**optional**\ -**default** false - -
- -Usually, any routing rules created by the workflow in the source and target keyspace are removed by `Complete` or `Cancel`. If this flag is used the routing rules will be left in place. - -
- -#### --max_replication_lag_allowed -**optional**\ -**default** the value used for `--timeout` +**default** the value used for [`--timeout`](#--timeout)
While executing `SwitchTraffic` we ensure that the VReplication lag for the workflow is less than this duration, otherwise report an error and don't attempt the switch. The calculated VReplication lag is the estimated maximum lag across workflow streams between the last event seen at the source and the last event processed by the target (which would be a heartbeat event if we're fully caught up). Usually, when VReplication has caught up, this lag should be very small (under a second). -While switching write traffic, we temporarily make the source databases read-only, and wait for the targets to catchup. This means that the application can effectively be partially down for this cutover period as writes will pause or error out. While switching write traffic this flag can ensure that you only switch traffic if the current lag is low, thus limiting this period of write-unavailability and avoiding it entirely if we're not likely to catch up within the `--timeout` window. +While switching write traffic, we temporarily make the source databases read-only, and wait for the targets to catchup. This means that the application can effectively be partially down for this cutover period as writes will pause or error out. While switching write traffic this flag can ensure that you only switch traffic if the current lag is low, thus limiting this period of write-unavailability and avoiding it entirely if we're not likely to catch up within the [`--timeout`](#--timeout)) window. While switching read traffic this can also be used to set an approximate upper bound on how stale reads will be against the replica tablets when using `@replica` shard targeting. @@ -301,7 +254,7 @@ See https://github.com/vitessio/vitess/pull/13895 and https://github.com/vitessi and more details.
-#### --rename_tables +#### --rename-tables **optional**\ **default** false @@ -310,11 +263,11 @@ and more details. During `Complete` or `Cancel` operations, the tables are renamed instead of being deleted. Currently the new name is _<table_name>_old. We use the same renaming logic used by [`pt-online-schema-change`](https://docs.percona.com/percona-toolkit/pt-online-schema-change.html). -Such tables are automatically skipped by vreplication if they exist on the source. +Such tables are automatically skipped by VReplication if they exist on the source. -#### --reverse_replication +#### --enable-reverse-replication **optional**\ **default** true @@ -326,15 +279,7 @@ If set to false these reverse replication streams will not be created and you wi -#### --source -**mandatory** -
- -Name of existing keyspace that contains the tables to be moved. - -
- -#### --source_time_zone +#### --source-time-zone **optional**\ **default** "" @@ -356,7 +301,7 @@ setting this flag will not convert them. -#### --stop_after_copy +#### --stop-after-copy **optional** **default** false @@ -373,29 +318,7 @@ is small enough to start replicating, the workflow state will be set to Stopped. * If you just want a consistent snapshot of all the tables you can set this flag. The workflow will stop once the copy is done and you can then mark the workflow as `Complete`. -#### --tables -**optional** one of `--tables` or `--all` needs to be specified -
- -_Either_ - -* a comma-separated list of tables - * if target keyspace is unsharded OR - * if target keyspace is sharded AND the tables being moved are already defined in the target's vschema - - Example: `MoveTables -- --source commerce --tables 'customer,corder' Create customer.commerce2customer` - -_Or_ - -* the JSON table section of the vschema for associated tables - * if target keyspace is sharded AND - * tables being moved are not yet present in the target's vschema - - Example: `MoveTables -- --source commerce --tables '{"t1":{"column_vindexes": [{"column": "id1", "name": "hash"}]}, "t2":{"column_vindexes": [{"column": "id2", "name": "hash"}]}}' Create customer.commerce2customer` - -
- -#### --tablet_types +#### --tablet-types **optional**\ **default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ **string** @@ -419,43 +342,7 @@ the command will error out. For setups with high write qps you may need to incre -### workflow identifier - -
- -All workflows are identified by `targetKeyspace.workflow` where `targetKeyspace` is the name of the keyspace to which the tables are being moved. `workflow` is a name you assign to the `MoveTables` workflow to identify it. - -
- - -## The most basic MoveTables Workflow lifecycle - -1. Initiate the migration using `Create`
-`MoveTables -- --source= --tables= Create ` -1. Monitor the workflow using `Show` or `Progress`
-`MoveTables Show ` _*or*_
-`MoveTables Progress `
-1. Confirm that data has been copied over correctly using [VDiff](../vdiff) -1. Cutover to the target keyspace with `SwitchTraffic`
-`MoveTables SwitchTraffic ` -1. Cleanup vreplication artifacts and source tables with `Complete`
-`MoveTables Complete ` - - -## Common use cases for MoveTables - -### Adopting Vitess - -For those wanting to try out Vitess for the first time, `MoveTables` provides an easy way to route part of their workload to Vitess with the ability to migrate back at any time without any risk. You point a vttablet to your existing MySQL installation, spin up an unsharded Vitess cluster and use a `MoveTables` workflow to start serving some tables from Vitess. You can also go further and use a Reshard workflow to experiment with a sharded version of a part of your database. - -See this [user guide](../../../user-guides/configuration-advanced/unmanaged-tablet/#move-legacytable-to-the-commerce-keyspace) for detailed steps. - -### Vertical Sharding - -For existing Vitess users you can easily move one or more tables to another keyspace, either for balancing load or as preparation for sharding your tables. - -See this [user guide](../../../user-guides/migration/move-tables/) which describes how `MoveTables` works in the local example provided in the Vitess repo. - ### More Reading * [`MoveTables` in practice](../../../concepts/move-tables/) +* [`MoveTables` reference docs](../../programs/vtctldclient/vtctldclient_movetables/) diff --git a/content/en/docs/18.0/reference/vreplication/reshard.md b/content/en/docs/18.0/reference/vreplication/reshard.md index 0aa963eb5..9b4d7b5ee 100644 --- a/content/en/docs/18.0/reference/vreplication/reshard.md +++ b/content/en/docs/18.0/reference/vreplication/reshard.md @@ -9,75 +9,75 @@ aliases: ['/docs/reference/vreplication/v2/reshard/'] These workflows can have a significant impact on the source tablets (which are often in production) — especially when a PRIMARY tablet is used as a source. You can limit the impact on the source tablets using the [`--vreplication_copy_phase_max_*` vttablet flags](../flags/#vreplication_copy_phase_max_innodb_history_list_length) {{< /warning >}} -## Command - -``` -Reshard -- -``` +## Description -or +[`Reshard`](../../programs/vtctldclient/vtctldclient_reshard/) is used to create and manage workflows to horizontally shard an existing keyspace. The source keyspace can be unsharded or sharded. -``` -Reshard -- [--source_shards=] [--target_shards=] [--cells=] - [--tablet_types=] [--skip_schema_copy] [--auto_start] - [--stop_after_copy] [--on-ddl=] [--timeout=timeoutDuration] - [--reverse_replication] [--keep_data] [--keep_routing_rules] -``` +## Command -## Description +Please see the [`Reshard` command reference](../../programs/vtctldclient/vtctldclient_reshard/) for a full list of sub-commands and their flags. -`Reshard` is used to create and manage workflows to horizontally shard an existing keyspace. The source keyspace can be unsharded or sharded. +### The Basic Reshard Workflow Lifecycle +1. Initiate the migration using `create`
+`Reshard --workflow --target-keyspace create --source-shards --target-shards ` +1. Monitor the workflow using `show` or `status`
+`Reshard --workflow --target-keyspace show`
+`Reshard --workflow --target-keyspace status`
+1. Confirm that data has been copied over correctly using [VDiff](../vdiff) +1. Cutover to the target keyspace with `SwitchTraffic`
+`Reshard --workflow --target-keyspace switchtraffic` +1. Cleanup vreplication artifacts and source shards with `complete`
+`Reshard --workflow --target-keyspace complete` ## Parameters -### action +### Action -`Reshard` is an "umbrella" command. The `action` sub-command defines the operation on the workflow. -Action must be one of the following: `Create`, `Show`, `Progress`, `SwitchTraffic`, `ReverseTrafffic`, `Cancel`, or `Complete`. +[`Reshard`](../../programs/vtctldclient/vtctldclient_reshard/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_reshard/#see-also) defines the operation on the workflow. #### Create
-`Create` sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow. +[`create`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_create/) sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow.
#### Show
-`Show` displays useful information about a workflow. (At this time the [Workflow](../workflow) Show command gives more information. This will be improved over time.) +[`show`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_show/) displays useful information about a workflow — including recent logs.
-#### Progress +#### Status
-`Progress` reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. +[`status`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_status/) (or `progress`) reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. It also shows the current state of traffic for the tables involved in the workflow. -It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `analyze table` to update the statistics if so desired. +It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `ANALYZE TABLE` to update the statistics if so desired.
#### SwitchTraffic
-`SwitchTraffic` switches traffic forward for the `tablet_types` specified. This replaces the previous `SwitchReads` and `SwitchWrites` commands with a single one. It is now possible to switch all traffic with just one command, and this is the default behavior. Also, you can now switch replica, rdonly and primary traffic in any order: earlier you needed to first `SwitchReads` (for replicas and rdonly tablets) first before `SwitchWrites`. +[`SwitchTraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_switchtraffic) switches traffic forward for the `tablet-types` specified. This replaces the previous `SwitchReads` and `SwitchWrites` commands with a single one. It is now possible to switch all traffic with just one command, and this is the default behavior. Also, you can now switch replica, rdonly and primary traffic in any order: earlier you needed to first `SwitchReads` (for replicas and rdonly tablets) first before `SwitchWrites`.
#### ReverseTraffic
-`ReverseTraffic` switches traffic in the reverse direction for the `tablet_types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet_types` specified. +[`ReverseTraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_reversetraffic/) switches traffic in the reverse direction for the `tablet-types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet_types` specified.
#### Cancel
-`Cancel` can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. Cancel can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the new target shards from the topo and, by default, the target tables on the target keyspace -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)). +[`cancel`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_cancel/) can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. Cancel can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the new target shards from the topo and, by default, the target tables on the target keyspace +(see `--keep-data` and `--rename-tables`).
@@ -88,18 +88,16 @@ It is too expensive to get real-time row counts of tables, using _count(*)_, say This is a destructive command {{< /warning >}} -`Complete` is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the original source shards from the topo. By default, the source tables are also dropped on the source shards -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)) . +[`complete`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_complete/) is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the original source shards from the topo. By default, the source tables are also dropped on the source shards +(see `--keep-data` and `--rename-tables`) . ### options -Each `action` has additional options/parameters that can be used to modify its behavior. - -`actions` are common to both `MoveTables` and `Reshard` workflows. Only the `create` action has different parameters, all other actions have common options and similar semantics. +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_reshard/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_reshard/) for the full list of command options or flags. `actions` are common to both `MoveTables` and `Reshard` workflows. Only the `create` action has different parameters, all other actions have common options and similar semantics. Below we will add additional information for a subset of key options. -#### --auto_start +#### --auto-start **optional**\ **default** true @@ -160,37 +158,18 @@ parallel index builds. This is logically similar to the -#### --drop_foreign_keys -**optional** -**default** false - -
- -If true, tables in the target keyspace will be created without any foreign keys that exist on the source. - -
- -#### --dry_run +#### --dry-run **optional**\ **default** false
-For the `SwitchTraffic`, `ReverseTraffic`, and `Complete` actions, you can do a dry run where no actual steps are taken +For the `SwitchTraffic`, `ReverseTraffic`, and `complete` actions, you can do a dry run where no actual steps are taken but the command logs all the steps that would be taken.
-#### --exclude -**optional** only applies if `--all` is specified - -
- -If moving all tables, specifies tables to be skipped. - -
- -#### --keep_data +#### --keep-data **optional**\ **default** false @@ -200,7 +179,7 @@ Usually, the target tables are deleted by `Cancel`. If this flag is used the tar -#### --keep_routing_rules +#### --keep-routing-rules **optional**\ **default** false @@ -210,7 +189,7 @@ Usually, any routing rules created by the workflow in the source and target keys -#### --max_replication_lag_allowed +#### --max-replication-lag-allowed **optional**\ **default** the value used for `--timeout` @@ -252,7 +231,7 @@ We caution against against using `EXEC` or `EXEC_IGNORE` for the following reaso -#### --reverse_replication +#### --enable-reverse-replication **optional**\ **default** true @@ -264,7 +243,7 @@ If set to false these reverse replication streams will not be created and you wi -#### --stop_after_copy +#### --stop-after-copy **optional** **default** false @@ -281,7 +260,7 @@ is small enough to start replicating, the workflow state will be set to Stopped. * If you just want a consistent snapshot of all the tables you can set this flag. The workflow will stop once the copy is done and you can then mark the workflow as `Complete`d -#### --source_shards +#### --source-shards **mandatory**
@@ -290,7 +269,7 @@ Comma separated shard names to reshard from.
-#### --tablet_types +#### --tablet-types **optional**\ **default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ **string** @@ -302,15 +281,6 @@ specified impacts [tablet selection](../tablet_selection/) for the workflow. -#### --target_shards -**mandatory** - -
- -Comma separated shard names to reshard to. - -
- #### --timeout **optional**\ **default** 30s @@ -322,26 +292,3 @@ catchup with the point where the writes were stopped. If the wait time is longer the command will error out. For setups with high write qps you may need to increase this value. - - -#### workflow identifier - -
- -All workflows are identified by `targetKeyspace.workflow` where `targetKeyspace` is the name of the keyspace to which the tables are being moved. `workflow` is a name you assign to the `Reshard` workflow to identify it. - -
- - -### The most basic Reshard Workflow lifecycle - -1. Initiate the migration using `Create`
-`Reshard -- --source_shards= --target_shards= Create ` -1. Monitor the workflow using `Show` or `Progress`
-`Reshard Show ` _*or*_
-`Reshard Progress `
-1. Confirm that data has been copied over correctly using [VDiff](../vdiff) -1. Cutover to the target keyspace with `SwitchTraffic`
-`Reshard SwitchTraffic ` -1. Cleanup vreplication artifacts and source shards with `Complete`
-`Reshard Complete ` diff --git a/content/en/docs/18.0/reference/vreplication/shardlevelmigrations.md b/content/en/docs/18.0/reference/vreplication/shardlevelmigrations.md index 43ee5f173..8dadec37d 100644 --- a/content/en/docs/18.0/reference/vreplication/shardlevelmigrations.md +++ b/content/en/docs/18.0/reference/vreplication/shardlevelmigrations.md @@ -5,21 +5,23 @@ weight: 120 aliases: ['/docs/reference/vreplication/v2/shardlevelmigrations/'] --- +## Description + {{< warning >}} -This feature is an **experimental** variant of the `MoveTables` command that -allows you to migrate individual shards from one keyspace to another. Please be +This feature is an **experimental** variant of the [`MoveTables`](../../../reference/programs/vtctldclient/vtctldclient_movetables/) command that +allows you to migrate individual shards from one keyspace to another. Please be sure to understand the limitations and requirements below. {{< /warning >}} -The full set of options for the `MoveTables` command [can be found here](../movetables/). +The full set of options for the `MoveTables` command [can be found here](../../../reference/programs/vtctldclient/vtctldclient_movetables/). The options and other aspects specific to shard level migrations will be covered here. ## Use Case -The [`Mount`](../mount/) and [`Migrate`](../migrate/) commands are the default -method provided for moving keyspaces from one Vitess cluster to another. This -method, however, only provides a one-time one-way cutover without the ability -to revert in the way that [`MoveTables`](../movetables/) does. +The [`Mount`](../mount/) and [`Migrate`](../migrate/) commands are the default +method provided for moving keyspaces from one Vitess cluster to another. This +method, however, only provides a one-time one-way cutover without the ability +to revert in the way that [`MoveTables`](../movetables/) does. This feature introduces the concept of partial keyspaces where some shards are served from a different keyspace during migration. This is useful for a specific @@ -28,27 +30,21 @@ being migrated to a new data center or provider. Migrating the entire cluster in one go using MoveTables could cause an unacceptable downtime due to the large number of primaries that need to be synced when writes are switched. -Supporting shard level migrations allows you to move very large keyspaces from one Vitess cluster -to another in an incremental way, cutting over traffic and reverting as needed -on a per-shard basis. When using this method, there is also a -new [`vtgate`](../../programs/vtgate/) `--enable-partial-keyspace-migration` -flag that enables support for shard level query routing so that individual -shards can be routed to one side of the migration or the other during the +Supporting shard level migrations allows you to move very large keyspaces from one Vitess cluster +to another in an incremental way, cutting over traffic and reverting as needed +on a per-shard basis. When using this method, there is also a +new [`vtgate`](../../programs/vtgate/) `--enable-partial-keyspace-migration` +flag that enables support for shard level query routing so that individual +shards can be routed to one side of the migration or the other during the migration period — *including when shard targeting is used*. -## Command - -``` -MoveTables --source_shards= -``` - -## Parameters +## Key Parameter -#### --source_shards +#### --source-shards **mandatory** (for shard level migrations)
-A list of one or more shards that you want to migrate from the source keyspace +A list of one or more shards that you want to migrate from the source keyspace to the target keyspace.
@@ -57,32 +53,32 @@ to the target keyspace. - The source and target keyspaces must have the exact same shard definitions - Query routing is all or nothing per shard, so you must *move all tables in the workflow -that you wish to migrate* and you would use [`SwitchTraffic --tablet_types=RDONLY,REPLICA,PRIMARY`](../switchtraffic/) +that you wish to migrate* and you would use [`SwitchTraffic --tablet-types=RDONLY,REPLICA,PRIMARY`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_switchtraffic/) to switch *read and write traffic* all at once for the shard(s) - - When the entire migration is complete, you cannot use the standard -[`Complete`](../complete/) workflow action and the final cleanup step requires manual work: - - The _reverse workflows should be [`Cancel`](../cancel/)ed. This will clean up + - When the entire migration is complete, you cannot use the standard +[`complete`](../../../reference/programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_complete/) workflow action and the final cleanup step requires manual work: + - The _reverse workflows should be [`cancel`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_cancel/)ed. This will clean up the both the global routing rules and the shard routing rules associated with the migration - - Note: [`Workflow delete`](../workflow/) does not clean up the shard routing rules + - Note: [`Workflow delete`](../../programs/vtctldclient/vtctldclient_workflow/vtctldclient_workflow_delete/) does not clean up the shard routing rules - You would need to perform any and all source side cleanup manually ## Related Vitess Flags -In order to support the shard level query routing during the migration, -the `--enable-partial-keyspace-migration` flag must be set for all of the +In order to support the shard level query routing during the migration, +the `--enable-partial-keyspace-migration` flag must be set for all of the [`vtgate`](../../programs/vtgate/) instances in the target Vitess cluster. {{< warning >}} -This routing support has a performance impact for all traffic and thus you -should only use this flag during the migration period and remove it once the +This routing support has a performance impact for all traffic and thus you +should only use this flag during the migration period and remove it once the migration is complete. {{< /warning >}} ## Related Commands -You can view the current shard level routing rules in place using -the [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) +You can view the current shard level routing rules in place using +the [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) [`vtctldclient`](../../programs/vtctldclient/) command and you can save updated routing rules using the -[`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyshardroutingrules/) +[`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyshardroutingrules/) command. diff --git a/content/en/docs/18.0/reference/vreplication/tablet_selection.md b/content/en/docs/18.0/reference/vreplication/tablet_selection.md index 3af152649..0107ee844 100644 --- a/content/en/docs/18.0/reference/vreplication/tablet_selection.md +++ b/content/en/docs/18.0/reference/vreplication/tablet_selection.md @@ -6,7 +6,7 @@ weight: 300 ### Introduction For both [VTGate VStreams and VTTablet VReplication streams](../../../concepts/vstream/) we must choose a tablet to serve the role of *source* (vstreamer). This -tablet selection is performed by the internal `TabletPicker` component. +tablet selection is performed by the internal `TabletPicker` component. {{< info >}} For VReplication streams a tablet also serves the role of *target* (vapplier). These, however, will always be the primary tablets in the target keyspace as we @@ -34,11 +34,11 @@ When using the [VTGate VStream API](../vstream/), you can override this local ce For VReplication, the server side default which determines the candidate types made available for potential selection as the source for a stream is set using the [`vttablet` `--vreplication_tablet_type` flag](../flags/#vreplication_tablet_type) (default value is `in_order:REPLICA,PRIMARY`). The target tablet will provide this value to the `TabletPicker` to determine the viable source tablet candidates. You can override this default on the client side using your -workflow command's `--tablet_types` flag. +workflow command's `--tablet-types` flag. -You can also specify an order of preference for the tablet types using the `in_order:` prefix in both the server and client flags. For example, -`--tablet_types "in_order:REPLICA,PRIMARY"` would cause a replica source tablet to be used whenever possible and a primary tablet would only be used as -a fallback in the event that there are no viable replica tablets available at the time. +You can also specify that the tablet types should be used in the order of preference as listed in the `--tablet-types` flag using the `--tablet-types-in-preference-order` flag. For example `--tablet-types "REPLICA,PRIMARY" --tablet-types-in-preference-order` would cause a replica source tablet to be used whenever possible +and a primary tablet would only be used as a fallback in the event that there are no viable replica tablets +available at the time. {{< info >}} When using the [VTGate VStream API](../vstream/) you should instead migrate to using the new `TabletOrder` field in the [VStreamFlags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags) request object as usage of the "in_order" string hint will eventually be deprecated and removed. diff --git a/content/en/docs/18.0/reference/vreplication/throttling.md b/content/en/docs/18.0/reference/vreplication/throttling.md index 9b352184e..4cf3a3cc4 100644 --- a/content/en/docs/18.0/reference/vreplication/throttling.md +++ b/content/en/docs/18.0/reference/vreplication/throttling.md @@ -29,4 +29,4 @@ As long as `check-self` fails — meaning that the replication lag is not within VReplication throttling is designed to give preference to normal production traffic while operating in the background. Production traffic will see less contention. The downside is that VReplication can take longer to operate. Under high load in production VReplication may altogether stall, to resume later when the load subsides. -Throttling will push back VReplication on replication lag. On systems where replication lag is normally high this can prevent VReplication from being able to operate normally. In such systems consider configuring `--throttle_threshold` to a value that agrees with your constraints. The default throttling threshold is at `1` second replication lag. +Throttling will push back VReplication on replication lag. On systems where replication lag is normally high this can prevent VReplication from being able to operate normally. In such systems consider configuring `--throttle-threshold` to a value that agrees with your constraints. The default throttling threshold is at `1` second replication lag. diff --git a/content/en/docs/18.0/reference/vreplication/vdiff.md b/content/en/docs/18.0/reference/vreplication/vdiff.md index a6baa1abd..f979faac5 100644 --- a/content/en/docs/18.0/reference/vreplication/vdiff.md +++ b/content/en/docs/18.0/reference/vreplication/vdiff.md @@ -5,49 +5,37 @@ weight: 40 aliases: ['/docs/reference/vreplication/vdiff2/'] --- -{{< info >}} -This is VDiff v2 which runs on `vttablets` as compared with the legacy [VDiff v1](../vdiffv1/) which runs on `vtctld`. -{{< /info >}} +### Description + +VDiff does a row by row comparison of all tables associated with the workflow, diffing the +source keyspace and the target keyspace and reporting counts of missing/extra/unmatched rows. + +It is highly recommended that you do this before you finalize a workflow with `SwitchTraffic` and `complete`. ### Command -VDiff takes different sub-commands or actions similar to how the [`MoveTables`](../movetables/)/[`Reshard`](../reshard/) commands work. The first argument -is the <keyspace.workflow> followed by an <action>. The following actions are supported: +VDiff takes different sub-commands or actions similar to how the [`MoveTables`](../movetables/)/[`Reshard`](../reshard/) commands work. Please see [the command's reference docs](../../../reference/programs/vtctldclient/vtctldclient_vdiff/) for additional info. The following sub-commands or actions are supported: #### Start a New VDiff -These take the same parameters as VDiff1 and schedule VDiff to run on the primary tablet of each target shard to verify the subset of data that will live on the given shard. Please note that if you do not specify a sub-command or action then `create` is assumed (this eases the transition from VDiff1 to VDiff2). If you do not pass a specific UUID then one will be generated. - -``` -VDiff -- [--source_cell=] [--target_cell=] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] - [--limit=] [--tables=] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] - [--update-table-stats] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] - create [] -``` +The [`create` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_create/) schedules a VDiff to run on the primary tablet of each target shard to verify the subset of data that will live on the given shard. If you do not pass a specific UUID then one will be generated. Each scheduled VDiff has an associated UUID which is returned by the `create` action. You can use it to monitor progress. Example: -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer -VDiff bf9dfc5f-e5e6-11ec-823d-0aa62e50dd24 scheduled on target shards, use show to view progress +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer create +VDiff a35b0006-e6d9-416e-bea9-917795dc5bf3 scheduled on target shards, use show to view progress ``` #### Resume a Previous VDiff -The `resume` action allows you to resume a previously completed VDiff, picking up where it left off and comparing the records where the Primary Key column(s) are greater than the last record processed — with the progress and other status information saved when the run ends. This allows you to do approximate rolling or differential VDiffs (e.g. done after MoveTables finishes the initial copy phase and then again just before SwitchTraffic). - -``` -VDiff -- [--source_cell=] [--target_cell=] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] - [--limit=] [--tables=
] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] - [--update-table-stats] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] - resume -``` +The [`resume` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_resume/) allows you to resume a previously completed VDiff, picking up where it left off and comparing the records where the Primary Key column(s) are greater than the last record processed — with the progress and other status information saved when the run ends. This allows you to do approximate rolling or differential VDiffs (e.g. done after `MoveTables` finishes the initial copy phase and then again just before `SwitchTraffic`). Example: -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer resume 4c664dc2-eba9-11ec-9ef7-920702940ee0 +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer resume 4c664dc2-eba9-11ec-9ef7-920702940ee0 VDiff 4c664dc2-eba9-11ec-9ef7-920702940ee0 resumed on target shards, use show to view progress ``` @@ -57,14 +45,10 @@ We cannot guarantee accurate results for `resume` when different collations are #### Show Progress/Status of a VDiff -``` -VDiff -- show { | last | all} -``` +Using the [`show` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_show/) you can either `show` a specific UUID or use the `last` convenience shorthand to look at the most recently created VDiff. Example: -You can either `show` a specific UUID or use the `last` convenience shorthand to look at the most recently created VDiff. Example: - -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer show last +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer show last VDiff Summary for customer.commerce2customer (4c664dc2-eba9-11ec-9ef7-920702940ee0) State: completed @@ -75,7 +59,7 @@ CompletedAt: 2022-06-26 22:44:31 Use "--format=json" for more detailed output. -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer show last +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow commerce2customer show last { "Workflow": "commerce2customer", "Keyspace": "customer", @@ -88,7 +72,7 @@ $ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2 "CompletedAt": "2022-06-26 22:44:31" } -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.p1c2 show daf1f03a-03ed-11ed-9ab8-920702940ee0 +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow p1c2 show daf1f03a-03ed-11ed-9ab8-920702940ee0 { "Workflow": "p1c2", "Keyspace": "customer", @@ -114,22 +98,18 @@ So we instead use the statistics available in the to approximate the number of rows in each table when initializing a VDiff on the target primary tablet(s). This data is then used in the progress report and it can be significantly off (up to 50-60+%) depending on the utilization of the underlying MySQL server resources and -the age of the tables. You can manually run -[`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) to update the -statistics for the tables involved on the target primary tablet(s) before creating the -VDiff, if so desired, in order to improve the accuracy of the progress report. +the age of the tables. You can specify the `create` `--update-table-stats` flag so that VDiff +will run [`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) to update the +statistics for the tables involved on the target primary tablet(s) before executing the +VDiff in order to improve the accuracy of the progress report. {{< /info >}} #### Stopping a VDiff -``` -VDiff -- stop -``` +The [`stop` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_stop/) allows you to stop a running VDiff for any reason — for example, the load on the system(s) may be too high at the moment and you want to postpone the work until off hours. You can then later use the [`resume` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_resume/) to start the VDiff again from where it left off. Example: -The `stop` action allows you to stop a running VDiff for any reason — for example, the load on the system(s) may be too high at the moment and you want to postpone the work until off hours. You can then later use the `resume` action to start the VDiff again from where it left off. Example: - -``` -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer stop ad9bd40e-0c92-11ed-b568-920702940ee0 +```shell +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow commerce2customer stop ad9bd40e-0c92-11ed-b568-920702940ee0 { "UUID": "ad9bd40e-0c92-11ed-b568-920702940ee0", "Action": "stop", @@ -143,17 +123,13 @@ Attempting to `stop` a VDiff that is already completed is a no-op. #### Delete VDiff Results -``` -VDiff -- delete { | all} -``` +You use the [`delete` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_delete/) to either `delete` a specific UUID or use the `all` shorthand to delete all VDiffs created for the specified keyspace and workflow. Example: -You can either `delete` a specific UUID or use the `all` shorthand to delete all VDiffs created for the specified keyspace and workflow. Example: - -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer delete all -VDiff delete status is completed on target shards +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer delete all +VDiff delete completed -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer delete all +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow commerce2customer delete all { "Action": "delete", "Status": "completed" @@ -165,145 +141,3 @@ Deletes are idempotent, so attempting to `delete` VDiff data that does not exist All VDiff data associated with a VReplication workflow is deleted when the workflow is deleted. {{< /info >}} - -### Description - -VDiff does a row by row comparison of all tables associated with the workflow, diffing the -source keyspace and the target keyspace and reporting counts of missing/extra/unmatched rows. - -It is highly recommended that you do this before you finalize a workflow with `SwitchTraffic`. - -### Parameters - -#### --source_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the source tables with the target tables -
- -#### --target_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the target tables with the source tables -
- -#### --tablet_types -**optional**\ -**default** in_order:RDONLY,REPLICA,PRIMARY - -
-A comma separated list of tablet types that are used while picking a tablet for sourcing data. -One or more from PRIMARY, REPLICA, RDONLY.

-
- -#### --filtered_replication_wait_time -**optional**\ -**default** 30s - -
-VDiff finds the current position of the source primary and then waits for the target replication to reach -that position for --filtered_replication_wait_time. If the target is much behind the source or if there is -a high write qps on the source then this time will need to be increased. -
- -#### --limit -**optional**\ -**default** 9223372036854775807 - -
-Maximum number of rows to run vdiff on (across all tables specified). -This limit is usually set while diffing a large table as a quick consistency check. -
- -#### --tables -**optional**\ -**default** all tables in the workflow - -
-A comma separated list of tables to run vdiff on. -
- -#### --format -**optional**\ -**default** text (unstructured text output) - -
-Only other format supported is JSON -
- -#### --auto-retry -**optional**\ -**default** true - -
-Automatically retry vdiffs that end with an error -
- -#### --verbose -**optional** - -
-Show verbose vdiff output in summaries -
- -#### --wait -**optional** - -
-When creating or resuming a vdiff, wait for the vdiff to finish before exiting. This will print the current status of the vdiff every --wait-update-interval. -
- -#### --wait-update-interval -**optional**\ -**default** 1m (1 minute) - -
-When waiting for a vdiff to finish, check and display the current status this often. -
- -#### --max_extra_rows_to_compare -**optional**\ -**default** 1000 - -
-Limits the number of extra rows on both the source and target that we will perform a second compare pass on to confirm that the rows are in fact different in content and not simply returned in a different order on the source and target (which can happen when there are collation differences, e.g. different MySQL versions). -
- -#### --debug_query -**optional** - -
-Adds the MySQL query to the report that can be used for further debugging -
- -#### --only_pks -**optional** - -
-When reporting missing rows, only show primary keys in the report. -
- -#### --update-table-stats -**optional** - -
-When specified, ANALYZE TABLE is run on each table in the target keyspace when initializing the VDiff. This helps to ensure that the table statistics are -up-to-date and thus that the progress reporting is as accurate as possible. -
- -{{< warning >}} -[`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) takes a table level READ lock on the table while it runs — effectively making the -table read-only. While [`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) does not typically take very long to run it can still -potentially interfere with serving queries from the *target* keyspace. -{{< /warning >}} - -#### keyspace.workflow -**mandatory** - -
-Name of target keyspace and the associated workflow to run VDiff on. -
diff --git a/content/en/docs/18.0/reference/vreplication/vdiffv1.md b/content/en/docs/18.0/reference/vreplication/vdiffv1.md deleted file mode 100644 index 6253c1991..000000000 --- a/content/en/docs/18.0/reference/vreplication/vdiffv1.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: VDiff v1 -description: Compare the source and target in a workflow to ensure integrity -weight: 40 ---- - -{{< warning >}} -This is the legacy v1 VDiff command — it is deprecated in Vitess 18.0 and will be **removed** in 19.0. Please migrate all of your VDiff usage to the new [VDiff](../vdiff/) command before upgrading. -{{< /warning >}} - -### Command - -``` -VDiff -- --v1 [--source_cell=] [--target_cell=] [--tablet_types=primary,replica,rdonly] - [--limit=] [--tables=
] [--format=json] [--max_extra_rows_to_compare=1000] - [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] -``` - -### Description - -VDiff does a row by row comparison of all tables associated with the workflow, diffing the -source keyspace and the target keyspace and reporting counts of missing/extra/unmatched rows. - -It is highly recommended that you do this before you finalize a workflow with `SwitchTraffic`. - -### Parameters - -#### --source_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the source tables with the target tables -
- -#### --target_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the target tables with the source tables -
- -#### --tablet_types -**optional**\ -**default** in_order:RDONLY,REPLICA,PRIMARY - -
-A comma separated list of tablet types that are used while picking a tablet for sourcing data. -One or more from PRIMARY, REPLICA, RDONLY. -
- -#### --filtered_replication_wait_time -**optional**\ -**default** 30s - -
-VDiff finds the current position of the source primary and then waits for the target replication to reach -that position for --filtered_replication_wait_time. If the target is much behind the source or if there is -a high write qps on the source then this time will need to be increased. -
- -#### --limit -**optional**\ -**default** 9223372036854775807 - -
-Maximum number of rows to run vdiff on (across all tables specified). -This limit is usually set while diffing a large table as a quick consistency check. -
- -#### --tables -**optional**\ -**default** all tables in the workflow - -
-A comma separated list of tables to run vdiff on. -
- - -#### --format -**optional**\ -**default** unstructured text output - -
-Only other format supported is json -
- -###### _Example:_ - -``` -[{ - "ProcessedRows": 5, - "MatchingRows": 5, - "MismatchedRows": 0, - "ExtraRowsSource": 0, - "ExtraRowsTarget": 0 -},{ - "ProcessedRows": 3, - "MatchingRows": 3, - "MismatchedRows": 0, - "ExtraRowsSource": 0, - "ExtraRowsTarget": 0 -}] -``` - -#### --max_extra_rows_to_compare -**optional**\ -**default** 1000 - -
-Limits the number of extra rows on both the source and target that we will perform a second compare pass on to confirm that the rows are in fact different in content and not simply returned in a different order on the source and target (which can happen when there are collation differences, e.g. different MySQL versions). -
- -#### --debug_query -**optional** - -
-Adds a MySQL query to the report that can be used for further debugging. -
- -#### --only_pks -**optional** - -
-When reporting missing rows, only show primary keys in the report. -
- -#### keyspace.workflow -**mandatory** - -
-Name of target keyspace and the associated workflow to run VDiff on. -
- -#### Example - -``` -$ vtctlclient VDiff customer.commerce2customer - -Summary for corder: {ProcessedRows:10 MatchingRows:10 MismatchedRows:0 ExtraRowsSource:0 ExtraRowsTarget:0} -Summary for customer: {ProcessedRows:11 MatchingRows:11 MismatchedRows:0 ExtraRowsSource:0 ExtraRowsTarget:0} -``` - -### Using VDiff With Huge Tables - -Currently VDiff runs within vtctld. Each VDiff will stream rows from all sources and targets and then compare them row by row after assembling the rows in order. Since there are no database transactions, VDiff will run much faster than the actual workflow. However, for huge tables (billions of rows or terabytes in size) this can take several hours or even days depending on the number of rows, row composition, server configurations and the topology of the cluster. If your sources and/or targets are across multiple cells, for example, this can slow down the VDiff considerably. - -Actual VDiff speeds are of course dependent on several factors in your cluster. But as a reference, we have seen VDiffs run as fast as 400mrph (million rows per hour) (~9B rows/day) for tables with short rows, or as slow as 60mrph (~1.5B rows/day), for tables with larger width and complex columns. - -You may need to use one or more of the following recommendations while running long VDiffs: - -* If VDiff takes more than an hour `vtctlclient` will hit grpc/http timeouts of 1 hour. In that case you can use `vtctl` (the bundled `vctlclient` + `vtctld`) instead. -* VDiff also synchronizes sources and targets to get consistent snapshots. If you have a high write QPS then you may encounter timeouts during the sync. Use higher values of `--filtered_replication_wait_time` to prevent that, for example `--filtered_replication_wait_time=4h`. -* If VDiff takes more than a day set the `--wait-time` parameter, which is the maximum time a vtctl command can run for, to a value comfortably higher than the expected run time, for example `--wait-time=168h`. -* You can follow the progress of the command by tailing the vtctld logs. VDiff logs progress every 10 million rows. This can also give you an early indication of how long it will run for, allowing you to increase your settings if needed. - -### Note - -* There is no throttling, so you might see an increased lag in the replica used as the source. -* VDiff is currently not resumable, so any timeouts or errors mean that you will need to rerun the entire VDiff again. -* VDiff runs one table at a time. - -{{< info >}} -**[VDiff v2](../vdiff/)**, which addresses these issues, is now production-ready and we recommend you use that instead. -{{< /info >}} diff --git a/content/en/docs/18.0/reference/vreplication/vreplication.md b/content/en/docs/18.0/reference/vreplication/vreplication.md index d127d20c2..04a1ae3c9 100644 --- a/content/en/docs/18.0/reference/vreplication/vreplication.md +++ b/content/en/docs/18.0/reference/vreplication/vreplication.md @@ -1,6 +1,6 @@ --- title: Overview -description: VReplication features, design and options in a nutshell +description: VReplication features, design, and options in a nutshell weight: 2 aliases: ['/docs/reference/features/vreplication/'] --- @@ -22,10 +22,8 @@ many features. It can be used for the following use cases: * **Realtime Rollups**: Use [`Materialize`](../materialize/) with aggregation expressions in which case Vitess will create a rolled up version of the source table which can be used for realtime analytics. -* **Lookup Vindexes**: Use [`CreateLookupVindex`](../../../user-guides/vschema-guide/backfill-vindexes/#createlookupvindex) to create a new - [`lookup vindex`](../../features/vindexes/#functional-and-lookup-vindex) - and backfill it from the existing data. -* **Online Schema Changes**: Use [`ddl_stragegy=vitess`](../../../user-guides/schema-changes/ddl-strategies/) for native [online non-blocking schema +* **Lookup Vindexes**: Use the [`LookupVindex`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/) command to create and backfill Lookup Vindexes. See the [`Creating a Lookup Vindex`](../../../user-guides/vschema-guide/backfill-vindexes/#createlookupvindex) section of the vschema user guide for example usage. +* **Online Schema Changes**: Use a [`ddl strategy of vitess`](../../../user-guides/schema-changes/ddl-strategies/) for native [online non-blocking schema migrations](../../../user-guides/schema-changes/managed-online-schema-changes/) that are trackable, cancellable, revertible, and retryable. All being safe to run in production due to intelligent throttling and resource management. @@ -199,7 +197,7 @@ will contain information about what it's been doing with each stream. ### Workflow Show The current status of the workflows and streams can also be fetched by using -the `vtctl` client [`Workflow Show`](../workflow/) command. +the `vtctldclient` [`Workflow Show`](../workflow/) command. ### Monitoring Variables diff --git a/content/en/docs/18.0/reference/vreplication/vreplicationexec.md b/content/en/docs/18.0/reference/vreplication/vreplicationexec.md deleted file mode 100644 index 577b645c1..000000000 --- a/content/en/docs/18.0/reference/vreplication/vreplicationexec.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: VReplicationExec -description: Low level command to run a query on vreplication related tables -weight: 70 ---- - -{{< warning >}} -This command was deprecated in v16.0 and will be removed in a future release. -{{< /warning >}} - -### Command - -``` -VReplicationExec -- [--json] -``` - -### Description - -The `VReplicationExec` command is used to view or manage vreplication streams. You would typically use one of the higher-level commands like the [WorkFlow](../workflow) command accomplish the same task. - -### Parameters - -#### --json -**optional** - -
-The output of the command is json formatted: to be readable by scripts. -
- -#### tablet_alias -**mandatory** - -
-Id of the target tablet on which to run the sql query, specified using the vitess tablet id format -<cell>-<uid> (see example below). -
- -#### query -**mandatory** - -
-SQL query which will be run: validations are done to ensure that queries can be run only against vreplication tables. -A limited set of queries are allowed. -
- -#### Example -``` -vtctlclient VReplicationExec 'zone1-100' 'select * from _vt.vreplication' -``` diff --git a/content/en/docs/18.0/reference/vreplication/workflow.md b/content/en/docs/18.0/reference/vreplication/workflow.md index 7cd2606fc..8a09c7529 100644 --- a/content/en/docs/18.0/reference/vreplication/workflow.md +++ b/content/en/docs/18.0/reference/vreplication/workflow.md @@ -1,82 +1,9 @@ --- title: Workflow -description: Wrapper on VReplication to perform common actions on a workflow +description: VReplication command to perform common actions on all types of workflows weight: 50 --- -### Command - -``` -Workflow -- [--dry-run] [--cells=] [--tablet-types=] [--on-ddl=] [.] - -``` - ### Description -Workflow is a convenience command for useful actions on a workflow that you can use instead of -actually specifying a query to VReplication. - -### Parameters - -#### --dry-run -**optional**\ -**default** false - -
-You can do a dry run where no actual action is taken but the command logs all the actions that would be taken by the Workflow. -
- -#### --cells -**optional** (Update action only)\ -**default** false - -
-You can update an existing workflow so that a different set of cells and/or cell aliases are used when choosing replication sources. -
- -#### --tablet-types -**optional** (Update action only)\ - -
-You can update an existing workflow so that different types of tablets are selected when choosing replication sources (see [tablet selection](../tablet_selection/)). -
- -#### --on-ddl -**optional** (Update action only)\ - -
-You can update an existing workflow so that DDL in the replication stream are handled differently (see [tablet selection](../vreplication/#handle-ddl)). -
- -#### keyspace.workflow -**mandatory** - -
-Name of target keyspace and the associated workflow to take action on. -{{< info >}} -The `listall` action is an exception to this rule as with that action you only specify the keyspace. -{{< /info >}} -
- -#### action -**mandatory** - -
-The Action is one of: - -* **stop**: sets the state of the workflow to Stopped: no further vreplication will happen until workflow is restarted -* **start**: restarts a Stopped workflow -* **update**: updates configuration parameters for this workflow in the `_vt.vreplication` table -* **delete**: removes the entries for this workflow in the `_vt.vreplication` table -* **show**: returns a JSON object with details about the associated shards and also with all the columns - from the `_vt.vreplication` table -* **listall**: returns a comma separated list of all *running* workflows in a keyspace -* **tags**: a comma-separated list of key:value pairs that are used to tag the workflow -
- -#### Example -``` -vtctlclient Workflow keyspace1.workflow1 stop -vtctlclient Workflow keyspace1.workflow1 show -vtctlclient Workflow keyspace1 listall -``` +Workflow is a convenience command for useful actions that are common to all VReplication workflows. Please see the command's [reference documentation](../../../reference/programs/vtctldclient/vtctldclient_workflow/) for additional information. diff --git a/content/en/docs/18.0/reference/vtctldclient-transition/command_diff.md b/content/en/docs/18.0/reference/vtctldclient-transition/command_diff.md index 3e274e166..bd5e38bb4 100644 --- a/content/en/docs/18.0/reference/vtctldclient-transition/command_diff.md +++ b/content/en/docs/18.0/reference/vtctldclient-transition/command_diff.md @@ -16,11 +16,12 @@ For stronger guarantees of compatibility, we highly encourage programming direct |-|-|-| | | N/A | [`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyroutingrules/) | | | `CopySchemaShard` | (deleted) | -| | `CreateLookupVindex` | (not yet migrated) | +| | `CreateLookupVindex` | [`LookupVindex create`](../../programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) | | | `DeleteShard` | [`DeleteShards`](../../programs/vtctldclient/vtctldclient_deleteshards/) | | | `DeleteTablet` | [`DeleteTablets`](../../programs/vtctldclient/vtctldclient_deletetablets/) | +| | `ExecuteFetchAsAllPrivs` | (not yet migrated) | | | `ExecuteFetchAsDba` | [`ExecuteFetchAsDBA`](../../programs/vtctldclient/vtctldclient_executefetchasdba/) | -| | `ExternalizeVindex` | (not yet migrated) | +| | `ExternalizeVindex` | [`LookupVindex externalize`](../../programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_externalize/) | | | `ListBackups` | [`GetBackups`](../../programs/vtctldclient/vtctldclient_getbackups/) | | | N/A | [`GetFullStatus`](../../programs/vtctldclient/vtctldclient_getfullstatus/) | | | N/A | [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) | @@ -32,18 +33,15 @@ For stronger guarantees of compatibility, we highly encourage programming direct | | N/A | [`GetTopologyPath`](../../programs/vtctldclient/vtctldclient_gettopologypath/) | | | N/A | [`GetWorkflows`](../../programs/vtctldclient/vtctldclient_getworkflows/) | | | `InitShardPrimary` | (deleted) | -| | `Migrate` | (not yet migrated) | -| | `Mount` | (not yet migrated) | -| | `OnlineDDL` | (not yet migrated) | | | `Ping` | [`PingTablet`](../../programs/vtctldclient/vtctldclient_pingtablet/) | | | N/A | [`SetKeyspaceDurabilityPolicy`](../../programs/vtctldclient/vtctldclient_setkeyspacedurabilitypolicy/) | | | `SetReadOnly`, `SetReadWrite` | [`SetWritable`](../../programs/vtctldclient/vtctldclient_setwritable/) | | | `Sleep` | [`SleepTablet`](../../programs/vtctldclient/vtctldclient_sleeptablet/) | -| | `TopoCat`, `TopoCp` | (not yet migrated) | +| | `TopoCat` | [`GetTopologyPath`](../../programs/vtctldclient/vtctldclient_gettopologypath/) | +| | `TopoCp` | (not yet migrated) | | | `UpdateSrvKeyspacePartition` | (not yet migrated) | | | `UpdateTabletAddrs` | (deleted) | -| | `VReplicationExec` | (not yet migrated) | +| | `VReplicationExec` | (deleted) | | | `ValidatePermissionsKeyspace`, `ValidatePermissionsShard` | (deleted) | | | `VtctldCommand` | N/A | | | `WaitForFilteredReplication` | (deleted) | -| | `Workflow` | (deleted) | diff --git a/content/en/docs/18.0/user-guides/configuration-advanced/createlookupvindex.md b/content/en/docs/18.0/user-guides/configuration-advanced/createlookupvindex.md index 9418102c8..3f6047c0a 100644 --- a/content/en/docs/18.0/user-guides/configuration-advanced/createlookupvindex.md +++ b/content/en/docs/18.0/user-guides/configuration-advanced/createlookupvindex.md @@ -1,5 +1,5 @@ --- -title: CreateLookupVindex +title: Creating a LookupVindex weight: 30 aliases: ['/docs/user-guides/createlookupvindex/'] --- @@ -10,53 +10,23 @@ an [Operator](../../../get-started/operator) or [local](../../../get-started/loc are at the point where you have the sharded keyspace called `customer` setup. {{< /info >}} -**CreateLookupVindex** is a [VReplication](../../../reference/vreplication/) workflow used to create **and** backfill -a [lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already +[`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) uses a [VReplication](../../../reference/vreplication/) workflow used to create **and** backfill +a [Lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already exists, and may have a significant amount of data in it already. -Internally, the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) process uses +Internally, the [`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command uses VReplication for the backfill process, until the lookup Vindex is "in sync". Then the normal process for adding/deleting/updating rows in the lookup Vindex via the usual [transactional flow when updating the "owner" table for the Vindex](../../../reference/features/vindexes/#lookup-vindex-types) takes over. -In this guide, we will walk through the process of using the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) -workflow, and give some insight into what happens underneath the covers. - -The `CreateLookupVindex` `vtctl` client command has the following syntax: - -```CreateLookupVindex -- [--cells=] [--continue_after_copy_with_owner=false] [--tablet_types=] ``` - -* ``: Use the lookup Vindex specified in `` along with - VReplication to populate/backfill the lookup Vindex from the source table. -* ``: The Vitess keyspace we are creating the lookup Vindex in. - The source table is expected to also be in this keyspace. -* `--tablet-types`: Provided to specify the tablet types - (e.g. `PRIMARY`, `REPLICA`, `RDONLY`) that are acceptable - as source tablets for the VReplication stream(s) that this command will - create. If not specified, the tablet type used will default to the value - of the [`vttablet --vreplication_tablet_type` flag](../../../reference/vreplication/flags/#vreplication_tablet_type) - value, which defaults to `in_order:REPLICA,PRIMARY`. -* `--cells`: By default VReplication streams, such as used by - `CreateLookupVindex`, will not cross cell boundaries. If you want the - VReplication streams to source their data from tablets in cells other - than the local cell, you can use the `--cells` option to specify a - comma-separated list of cells (see [VReplication tablet selection](../../../reference/vreplication/tablet_selection/)). -* `--continue_after_copy_with_owner`: By default, when an owner is provided in the ``, - the VReplication streams will stop after the backfill completes. Specify this flag if - you don't want this to happen. This is useful if, for example, the owner table is being - migrated from an unsharded keyspace to a sharded keyspace using - [`MoveTables`](../../../reference/vreplication/movetables/). - -The `` describes the lookup Vindex to be created, and details about -the table it is to be created against (on which column, etc.). However, -you do not have to specify details about the actual lookup table, Vitess -will create that automatically based on the type of the column you are -creating the Vindex column on, etc. +In this guide, we will walk through the process of using the [`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command, and give some insight into what happens underneath the covers. + +You can see the details of the [`LookupVindex create` command](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) in the reference docs. In the context of the `customer` database that is part of the Vitess examples we started earlier, let's add some rows into the `customer.corder` table, and then -look at an example ``: +look at an example command: ```bash $ mysql -P 15306 -h 127.0.0.1 -u root --binary-as-hex=false -A @@ -217,45 +187,13 @@ Now let's say we want to add a lookup Vindex on the `sku` column. We can use a [`consistent_lookup` or `consistent_lookup_unique`](../../vschema-guide/unique-lookup/) Vindex type. In our example we will use `consistent_lookup_unique`. -Here is our example ``: - -```json -$ cat lookup_vindex.json -{ - "sharded": true, - "vindexes": { - "corder_lookup": { - "type": "consistent_lookup_unique", - "params": { - "table": "customer.corder_lookup", - "from": "sku", - "to": "keyspace_id" - }, - "owner": "corder" - } - }, - "tables": { - "corder": { - "column_vindexes": [ - { - "column": "sku", - "name": "corder_lookup" - } - ] - } - } -} -``` - -
- Note that as mentioned above, we do not have to tell Vitess about how to shard the actual backing table for the lookup Vindex or any schema to create as it will do it automatically. Now, let us -actually execute the `CreateLookupVindex` command: +actually execute the `LookupVindex create` command: ```bash -$ vtctlclient --server localhost:15999 CreateLookupVindex -- --tablet_types=RDONLY customer "$(cat lookup_vindex.json)" +vtctldclient --server localhost:15999 LookupVindex --name customer_region_lookup --table-keyspace main create --keyspace main --type consistent_lookup_unique --table-owner customer --table-owner-columns=id --tablet-types=PRIMARY ```
@@ -294,7 +232,7 @@ Now we can look what happened in greater detail: * Note that each primary tablet will start streams from each source tablet, for a total of 4 streams in this case. -Lets observe the VReplication streams that got created using the `vtctlclient Workflow show` command. +Lets observe the VReplication streams that got created using the `show` sub-command. {{< info >}} The created vreplication workflow will have a generated name of `_vdx`. @@ -302,170 +240,101 @@ So in our example here: `corder_lookup_vdx`. {{< /info >}} ```json -$ vtctlclient --server localhost:15999 Workflow customer.corder_lookup_vdx show +$ vtctldclient --server localhost:15999 LookupVindex --name customer_region_lookup --table-keyspace main show --include-logs=false { - "Workflow": "corder_lookup_vdx", - "SourceLocation": { - "Keyspace": "customer", - "Shards": [ - "-80", - "80-" - ] - }, - "TargetLocation": { - "Keyspace": "customer", - "Shards": [ - "-80", - "80-" - ] - }, - "MaxVReplicationLag": 78, - "MaxVReplicationTransactionLag": 1674479901, - "Frozen": false, - "ShardStatuses": { - "-80/zone1-0000000300": { - "PrimaryReplicationStatuses": [ - { - "Shard": "-80", - "Tablet": "zone1-0000000300", - "ID": 1, - "Bls": { - "keyspace": "customer", - "shard": "-80", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '-80') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "cb8ae288-9b1f-11ed-84ff-04ed332e05c2:1-117", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - }, - { - "Shard": "-80", - "Tablet": "zone1-0000000300", - "ID": 2, - "Bls": { - "keyspace": "customer", - "shard": "80-", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '-80') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "de051c70-9b1f-11ed-832d-04ed332e05c2:1-121", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - }, - "80-/zone1-0000000401": { - "PrimaryReplicationStatuses": [ - { - "Shard": "80-", - "Tablet": "zone1-0000000401", - "ID": 1, - "Bls": { - "keyspace": "customer", - "shard": "-80", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '80-') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "cb8ae288-9b1f-11ed-84ff-04ed332e05c2:1-117", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - }, - { - "Shard": "80-", - "Tablet": "zone1-0000000401", - "ID": 2, - "Bls": { - "keyspace": "customer", - "shard": "80-", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '80-') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "de051c70-9b1f-11ed-832d-04ed332e05c2:1-123", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" + "workflows": [ + { + "name": "customer_region_lookup", + "source": { + "keyspace": "main", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "main", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "0", + "shard_streams": { + "0/zone1-0000000100": { + "streams": [ + { + "id": "1", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 100 + }, + "binlog_source": { + "keyspace": "main", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "customer_region_lookup", + "filter": "select id as id, keyspace_id() as keyspace_id from customer where in_keyrange(id, 'main.xxhash', '-') group by id, keyspace_id", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "63c84d28-6888-11ee-93b0-81b2fbd12545:1-63", + "stop_position": "", + "state": "Running", + "db_name": "vt_main", + "transaction_timestamp": { + "seconds": "1697064644", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697064646", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [], + "log_fetch_error": "", + "tags": [], + "rows_copied": "0", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [], + "is_primary_serving": true + } + }, + "workflow_type": "CreateLookupIndex", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "0", + "defer_secondary_keys": false + } + ] } ``` @@ -530,7 +399,8 @@ the VReplication streams and also clear the `write_only` flag from the Vindex indicating that it is *not* backfilling anymore. ```bash -$ vtctlclient --server localhost:15999 ExternalizeVindex customer.corder_lookup +$ vtctldclient --server localhost:15999 LookupVindex --name customer_region_lookup --table-keyspace main externalize +LookupVindex customer_region_lookup has been externalized and the customer_region_lookup VReplication workflow has been deleted ```
diff --git a/content/en/docs/18.0/user-guides/configuration-advanced/region-sharding.md b/content/en/docs/18.0/user-guides/configuration-advanced/region-sharding.md index 423dc2588..a505c4d99 100644 --- a/content/en/docs/18.0/user-guides/configuration-advanced/region-sharding.md +++ b/content/en/docs/18.0/user-guides/configuration-advanced/region-sharding.md @@ -356,7 +356,7 @@ Now that our new tablets are up, we can go ahead with the resharding: This script executes one command: ```bash -vtctlclient Reshard -- --source_shards '0' --target_shards '-40,40-80,80-c0,c0-' --tablet_types=PRIMARY Create main.main2regions +vtctldclient Reshard --target-keyspace main --workflow main2regions create --source-shards '0' --target-shards '-40,40-80,80-c0,c0-' --tablet-types=PRIMARY ```
@@ -372,10 +372,10 @@ We can check the correctness of the copy using the [`VDiff` command](../../../re and the `.` name we used for `Reshard` command above: ```bash -$ vtctlclient VDiff -- main.main2regions create +$ vtctldclient VDiff --target-keyspace main --workflow main2regions create VDiff 044e8da0-9ba4-11ed-8bc7-920702940ee0 scheduled on target shards, use show to view progress -$ vtctlclient VDiff -- --format=json main.main2regions show last +$ vtctldclient VDiff --format=json --target-keyspace main --workflow main2regions show last { "Workflow": "main2regions", "Keyspace": "main", @@ -391,18 +391,11 @@ $ vtctlclient VDiff -- --format=json main.main2regions show last
-We can take a look at the VReplication workflow's progress and status using the -[`Progress` action](../../../reference/vreplication/reshard/#progress): +We can take a look at the VReplication workflow's status using the +[`show` action](../../../reference/programs/vtctldclient/vtctldclient_reshard/vtctldclient_reshard_show/): ```bash -$ vtctlclient Reshard -- Progress main.main2regions - -The following vreplication streams exist for workflow main.main2regions: - -id=1 on 40-80/zone1-0000000300: Status: Running. VStream Lag: 0s. -id=1 on -40/zone1-0000000200: Status: Running. VStream Lag: 0s. -id=1 on 80-c0/zone1-0000000400: Status: Running. VStream Lag: 0s. -id=1 on c0-/zone1-0000000500: Status: Running. VStream Lag: 0s. +vtctldclient Reshard --target-keyspace main --workflow main2regions show ```
@@ -410,11 +403,6 @@ id=1 on c0-/zone1-0000000500: Status: Running. VStream Lag: 0s. We now have a running stream from the source tablet (`100`) to each of of our new `main` target shards that will keep the tables up-to-date with the source shard (`0`). -{{< info >}} -You can see greater detail about the VReplication workflow and the individual streams using the following command: -`vtctlclient Workflow -- main.main2regions show` -{{< /info >}} - ## Cutover Once the VReplication workflow's [copy phase](../../../reference/vreplication/internal/life-of-a-stream/#copy) is diff --git a/content/en/docs/18.0/user-guides/configuration-advanced/resharding.md b/content/en/docs/18.0/user-guides/configuration-advanced/resharding.md index e79b15d41..0b23ddb33 100644 --- a/content/en/docs/18.0/user-guides/configuration-advanced/resharding.md +++ b/content/en/docs/18.0/user-guides/configuration-advanced/resharding.md @@ -225,7 +225,7 @@ Now we can start the [Reshard](../../../reference/vreplication/reshard/) operati will not block any read or write operations to your database: ```bash -vtctlclient Reshard -- --source_shards '0' --target_shards '-80,80-' Create customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust create --source-shards '0' --target-shards '-80,80-' ```
@@ -238,10 +238,10 @@ our [reference page for Reshard](../../../reference/vreplication/reshard). After the reshard is complete, we can use [VDiff](../../../reference/vreplication/vdiff) to check data integrity and ensure our source and target shards are consistent: ```bash -$ vtctlclient VDiff -- customer.cust2cust +$ vtctldclient VDiff --target-keyspace customer --workflow cust2cust create VDiff 60fa5738-9bad-11ed-b6de-920702940ee0 scheduled on target shards, use show to view progress -$ vtctlclient VDiff -- --format=json customer.cust2cust show last +$ vtctldclient VDiff --target-keyspace customer --workflow cust2cust show last { "Workflow": "cust2cust", "Keyspace": "customer", @@ -263,7 +263,7 @@ at the new location. By switching targeted read operations first, we are able to tablets are healthy and able to respond to requests: ```bash -vtctlclient Reshard -- --tablet_types=rdonly,replica SwitchTraffic customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust SwitchTraffic --tablet-types=rdonly,replica ``` ## Switch Writes and Primary Reads @@ -272,7 +272,7 @@ After the [`REPLICA` and `RDONLY` targeted reads](../../../reference/features/vs switched, and the health of the system has been verified, it's time to switch writes and all default traffic: ```bash -vtctlclient Reshard -- --tablet_types=primary SwitchTraffic customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust SwitchTraffic ``` ## Note @@ -329,9 +329,11 @@ After celebrating your second successful resharding, you are now ready to clean ### Using Operator ```bash -vtctlclient Reshard -- Complete customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust complete ``` + After the workflow has completed, you can go ahead and remove the shard that is no longer required - + ```bash kubectl apply -f 306_down_shard_0.yaml ``` @@ -339,7 +341,7 @@ kubectl apply -f 306_down_shard_0.yaml ### Using a Local Deployment ```bash -vtctlclient Reshard -- Complete customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust complete for i in 200 201 202; do CELL=zone1 TABLET_UID=$i ./scripts/vttablet-down.sh diff --git a/content/en/docs/18.0/user-guides/configuration-advanced/unmanaged-tablet.md b/content/en/docs/18.0/user-guides/configuration-advanced/unmanaged-tablet.md index af896cf22..1bbe25cb1 100644 --- a/content/en/docs/18.0/user-guides/configuration-advanced/unmanaged-tablet.md +++ b/content/en/docs/18.0/user-guides/configuration-advanced/unmanaged-tablet.md @@ -120,32 +120,42 @@ Empty set (0.01 sec) ## Move legacytable to the commerce keyspace Move the table: + ```bash -vtctlclient MoveTables -- --source legacy --tables 'legacytable' Create commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce create --source-keyspace legacy --tables 'legacytable' ``` +
+ Monitor the workflow: use `Show` or `Progress` + ```bash -vtctlclient MoveTables -- Show commerce.legacy2commerce -vtctlclient MoveTables -- Progress commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce show +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce status ``` -You can also use the [`Workflow show`](../../../reference/vreplication/workflow/) command to get the progress as it has much more info as well. +You can alternatively use the [`Workflow show`](../../../reference/programs/vtctldclient/vtctldclient_workflow/vtctldclient_workflow_show/) command to get the details as well. ```bash -vtctlclient Workflow commerce.legacy2commerce show +vtctldclient Workflow --keyspace commerce show --workflow legacy2commerce ``` +
Switch traffic: + ```bash -vtctlclient MoveTables -- --tablet_type=rdonly,replica SwitchTraffic commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce SwitchTraffic ``` +
Complete the `MoveTables`: + ```bash -vtctlclient MoveTables Complete commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce complete ``` +
Verify that the table was moved: + ```bash source ../common/env.sh @@ -155,6 +165,7 @@ mysql commerce -e 'show tables' # verify my unmanaged mysql is running mysql -h 127.0.0.1 -P 5726 -umsandbox -pmsandbox legacy -e 'show tables' ``` +
Output: ```text @@ -174,4 +185,3 @@ $ # verify my unmanaged mysql is running $ mysql -h 127.0.0.1 -P 5726 -umsandbox -pmsandbox legacy -e 'show tables' mysql: [Warning] Using a password on the command line interface can be insecure. ``` - diff --git a/content/en/docs/18.0/user-guides/configuration-basic/vtctld.md b/content/en/docs/18.0/user-guides/configuration-basic/vtctld.md index 9ca987558..ff2c6b8d8 100644 --- a/content/en/docs/18.0/user-guides/configuration-basic/vtctld.md +++ b/content/en/docs/18.0/user-guides/configuration-basic/vtctld.md @@ -21,7 +21,7 @@ If the TopoServer is unreachable, or if the topo flags are incorrectly configure F0426 11:11:40.363545 14833 server.go:223] Failed to open topo server (etcd2,localhost:2379,/vitess/global): dial tcp 127.0.0.1:2379: connect: connection refused ``` -The `service_map` flag allows you to configure the grpc APIs that a Vitess server exposes as grpc. If grpc-vtctl is not specified as a service\_map for vtctld, you will not be able to access it using `vtctlclient`. +The `service_map` flag allows you to configure the grpc APIs that a Vitess server exposes as grpc. If grpc-vtctl is not specified as a service\_map for vtctld, you will not be able to access it using `vtctldclient`. Similarly, if grpc-vtctld is not specified as a service\_map for vtctld, you will not be able to access it using `vtctldclient`. vtctld is usually not very resource intensive. But you may need to provision more if you plan to run the `VDiff` command. This functionality will soon be moved to vttablet. diff --git a/content/en/docs/18.0/user-guides/migration/materialize.md b/content/en/docs/18.0/user-guides/migration/materialize.md index eaeaa7f68..88fda7149 100644 --- a/content/en/docs/18.0/user-guides/migration/materialize.md +++ b/content/en/docs/18.0/user-guides/migration/materialize.md @@ -25,13 +25,13 @@ different ways for the purposes of avoiding expensive cross-shard queries. `Mate allow for you to pre-create the schema and [VSchema](../../../concepts/vschema/) for the copied table, allowing you to for example maintain a copy of a table without some of the source table's MySQL indexes. -All of the command options and parameters are listed in our [reference page for the `Materialize` command](../../../reference/vreplication/materialize). In our examples to follow we will only touch on what is possible using +All of the command options and parameters are listed in our [reference page for the `Materialize` command](../../../reference/programs/vtctldclient/vtctldclient_materialize/). In our examples to follow we will only touch on what is possible using [`Materialize`](../../../reference/vreplication/materialize). Let's start by loading some sample data: ```bash -$ mysql < ../common/insert_commerce_data.sql +mysql < ../common/insert_commerce_data.sql ``` We can look at what we just inserted: @@ -81,7 +81,7 @@ for the `corder_view_redacted` copy we will use the opportunity to drop or redac In the case where we are using `Materialize` to copy tables *between or across keyspaces* we can use the `"create_ddl": "copy"` option in the -[`Materialize` `json_spec` `table_settings`](../../../reference/vreplication/materialize/#json-spec-details) +[`Materialize --table-settings`](../../../reference/vreplication/materialize/#--table-settings) flag to create the target table for us (similar to what `MoveTables` does). However, in our case where we are using `Materialize` within a single keyspace (`commerce`) so we need to manually create the target tables. Let's go ahead and do that: @@ -112,7 +112,8 @@ We will run two `Materialize` operations, one for each copy/view of the `corder` combine these two operations into a single `Materialize` operation, but we will keep them separate for clarity. ```bash -$ vtctlclient Materialize -- '{"workflow": "copy_corder_1", "source_keyspace": "commerce", "target_keyspace": "commerce", "table_settings": [{"target_table": "corder_view", "source_expression": "select * from corder"}]}' +$ vtctldclient Materialize --workflow copy_corder_1 --target-keyspace commerce create --source-keyspace commerce --table-settings '[{"target_table": "corder_view", "source_expression": "select * from corder"}]' +Materialization workflow copy_corder_1 successfully created in the commerce keyspace. Use show to view the status. ``` Now, we should see the materialized view table `corder_view`: @@ -156,110 +157,157 @@ or removing rows in a fashion that would break the "replication" part of the VRe ## Viewing the Workflow While in Progress -While we can also see and manipulate the underlying VReplication streams created by `Materialize` there are -[Workflow](../../../reference/vreplication/workflow) commands to `show`, `stop`, `start` and `delete` the +[`Materialize`](../../../reference/programs/vtctldclient/vtctldclient_materialize/#see-also) has actions or sub-commands to `show`, `stop`, `start` and `cancel` the `Materialize` workflow. For example, once we have started the `Materialize` command above, we can observe the -status of the VReplication workflow using the [Workflow](../../../reference/vreplication/workflow) command: +status of the VReplication workflow using the [`show`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_show/) sub-command: ```json -$ vtctlclient Workflow -- commerce listall -Following workflow(s) found in keyspace commerce: copy_corder_1 +$ vtctldclient Workflow --keyspace commerce list +[ + "copy_corder_1" +] -$ vtctlclient Workflow -- commerce.copy_corder_1 show +$ vtctldclient Materialize --target-keyspace commerce show --workflow copy_corder_1 --include-logs=false { - "Workflow": "copy_corder_1", - "SourceLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "TargetLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "MaxVReplicationLag": 1, - "MaxVReplicationTransactionLag": 1, - "Frozen": false, - "ShardStatuses": { - "0/zone1-0000000101": { - "PrimaryReplicationStatuses": [ - { - "Shard": "0", - "Tablet": "zone1-0000000101", - "ID": 1, - "Bls": { - "keyspace": "commerce", - "shard": "0", - "filter": { - "rules": [ - { - "match": "corder_view", - "filter": "select * from corder" - } - ] - } - }, - "Pos": "4c89eede-8c68-11ed-a40a-6f1a36c22987:1-1070", - "StopPos": "", - "State": "Running", - "DBName": "vt_commerce", - "TransactionTimestamp": 1672862991, - "TimeUpdated": 1672862991, - "TimeHeartbeat": 1672862991, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "", - "Tags": "", - "WorkflowType": "Materialize", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" + "workflows": [ + { + "name": "copy_corder_1", + "source": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "0", + "shard_streams": { + "0/zone1-0000000101": { + "streams": [ + { + "id": "1", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "binlog_source": { + "keyspace": "commerce", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "corder_view", + "filter": "select * from corder", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "fd3ac16e-6880-11ee-be79-13f9a85fe24e:1-241", + "stop_position": "", + "state": "Running", + "db_name": "vt_commerce", + "transaction_timestamp": { + "seconds": "1697061520", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697061521", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [], + "log_fetch_error": "", + "tags": [], + "rows_copied": "5", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [], + "is_primary_serving": true + } + }, + "workflow_type": "Materialize", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "0", + "defer_secondary_keys": false + } + ] } ``` -We can now also use the `Workflow` `stop`/`start` actions to temporarily stop the materialization workflow. For +We can now also use the [`stop`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_stop/) and [`start`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_start/) actions to temporarily stop the materialization workflow. For example: ```bash -$ vtctlclient Workflow -- commerce.copy_corder_1 stop -+------------------+--------------+ -| Tablet | RowsAffected | -+------------------+--------------+ -| zone1-0000000100 | 1 | -+------------------+--------------+ +$ vtctldclient Materialize --target-keyspace commerce stop --workflow copy_corder_1 +{ + "summary": "Successfully updated the copy_corder_1 workflow on (1) target primary tablets in the commerce keyspace", + "details": [ + { + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "changed": true + } + ] +} ``` -And `start` to start the workflow again and continue with the materialization: +And [`start`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_start/) to start the workflow again and continue with the materialization: ```bash -$ vtctlclient Workflow -- commerce.copy_corder_1 start -+------------------+--------------+ -| Tablet | RowsAffected | -+------------------+--------------+ -| zone1-0000000100 | 1 | -+------------------+--------------+ +$ vtctldclient Materialize --target-keyspace commerce start --workflow copy_corder_1 +{ + "summary": "Successfully updated the copy_corder_1 workflow on (1) target primary tablets in the commerce keyspace", + "details": [ + { + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "changed": true + } + ] +} ``` If at some point, when the initial copy is done and we have fully materialized all of the (initial) data, we do not -want to continue replicating changes from the source, we can `delete` the workflow: +want to continue replicating changes from the source, we can [`cancel`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_cancel/) the workflow: ```bash -$ vtctlclient Workflow -- commerce.copy_corder_1 delete -+------------------+--------------+ -| Tablet | RowsAffected | -+------------------+--------------+ -| zone1-0000000100 | 1 | -+------------------+--------------+ +$ vtctldclient Materialize --target-keyspace commerce cancel --workflow copy_corder_1 +Successfully cancelled the copy_corder_1 workflow in the commerce keyspace ``` Note that deleting the workflow will *not* `DROP` the target table of the `Materialize` workflow or `DELETE` any of the @@ -272,7 +320,8 @@ Now we can perform the materialization of the `corder_view_redacted` table we cr this table without a price column so we will not be copying that column in our query either: ```bash -$ vtctlclient Materialize -- '{"workflow": "copy_corder_2", "source_keyspace": "commerce", "target_keyspace": "commerce", "table_settings": [{"target_table": "corder_view_redacted", "source_expression": "select order_id, customer_id, sku from corder"}]}' +$ vtctldclient Materialize --target-keyspace commerce create --workflow copy_corder_2 --source-keyspace commerce --table-settings '[{"target_table": "corder_view_redacted", "source_expression": "select order_id, customer_id, sku from corder"}]' +Materialization workflow copy_corder_2 successfully created in the commerce keyspace. Use show to view the status. ``` Again, looking the target table will show all the source table rows, this time without the `price` column: @@ -317,7 +366,7 @@ target keyspace's primary tablet, e.g. in this case: ```bash # We want to connect directly to the primary mysqld -$ SOCKETPATH=${VTDATAROOT}/$(vtctlclient ListAllTablets -- --keyspace=commerce --tablet_type=primary | awk '$1 sub(/zone1-/, "vt_") {print $1}') +$ SOCKETPATH=${VTDATAROOT}/$(vtctldclient GetTablets --keyspace=commerce --tablet-type=primary | awk '$1 sub(/zone1-/, "vt_") {print $1}') $ mysql -u root -h localhost --socket=${SOCKETPATH}/mysql.sock --binary-as-hex=false -e "select * from _vt.vreplication\G" *************************** 1. row *************************** @@ -346,8 +395,7 @@ transaction_timestamp: 1672865502 ## Cleanup -As seen earlier, you can easily use the [`Workflow delete`](../../../reference/vreplication/workflow) command to -clean up a `Materialize` workflow when it's no longer needed. +As seen earlier, you can easily use the [`Workflow delete`](../../../reference/programs/vtctldclient/vtctldclient_workflow/vtctldclient_workflow_delete/) or [`Materialize cancel`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_cancel/) command to clean up a `Materialize` workflow when it's no longer needed. {{< info >}} While this deletes the `Materialize` VReplication stream, the actual source and target tables are left unchanged diff --git a/content/en/docs/18.0/user-guides/migration/move-tables.md b/content/en/docs/18.0/user-guides/migration/move-tables.md index 26bb24ae9..331646dfd 100644 --- a/content/en/docs/18.0/user-guides/migration/move-tables.md +++ b/content/en/docs/18.0/user-guides/migration/move-tables.md @@ -153,7 +153,7 @@ In this step we will create the `MoveTables` workflow, which copies the tables f `customer`. This operation does not block any database activity; the `MoveTables` operation is performed online: ```bash -$ vtctlclient MoveTables -- --source commerce --tables 'customer,corder' Create customer.commerce2customer +vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer create --source-keyspace commerce --tables 'customer,corder' ``` A few things to note: @@ -278,82 +278,142 @@ be copied faithfully to the new copy of these tables in the `customer` keyspace. ## Monitoring Progress (Optional) -In this example there are only a few rows in the tables, so the `MoveTables` operation only takes seconds. If the tables were large, however, you may need to monitor the progress of the operation. You can get a basic summary of the progress using the [`Progress`](../../../reference/vreplication/movetables/#progress) action: +In this example there are only a few rows in the tables, so the `MoveTables` operation only takes seconds. If the tables were large, however, you may need to monitor the progress of the operation. You can get a basic summary of the progress using the [`status`](../../../reference/vreplication/movetables/#status) action: ```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 2, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51", + "status": "Running", + "info": "VStream Lag: 0s" + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` -You can get detailed status and progress information using the -[`Workflow show`](../../../reference/vreplication/workflow/) command: +You can get more detailed status information using the +[`show`](../../../reference/programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_show/) sub-command: + ```json -$ vtctlclient Workflow customer.commerce2customer show +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer show --include-logs=false { - "Workflow": "commerce2customer", - "SourceLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "TargetLocation": { - "Keyspace": "customer", - "Shards": [ - "0" - ] - }, - "MaxVReplicationLag": 1, - "MaxVReplicationTransactionLag": 1, - "Frozen": false, - "ShardStatuses": { - "0/zone1-0000000201": { - "PrimaryReplicationStatuses": [ - { - "Shard": "0", - "Tablet": "zone1-0000000201", - "ID": 1, - "Bls": { - "keyspace": "commerce", - "shard": "0", - "filter": { - "rules": [ - { - "match": "customer", - "filter": "select * from customer" - }, - { - "match": "corder", - "filter": "select * from corder" - } - ] - } - }, - "Pos": "7e765c5c-8c59-11ed-9d2e-7c501ea4de6a:1-83", - "StopPos": "", - "State": "Running", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1672857697, - "TimeHeartbeat": 1672857697, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "", - "Tags": "", - "WorkflowType": "MoveTables", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" + "workflows": [ + { + "name": "commerce2customer", + "source": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "customer", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "1", + "shard_streams": { + "0/zone1-0000000200": { + "streams": [ + { + "id": "2", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "binlog_source": { + "keyspace": "commerce", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "customer", + "filter": "select * from customer", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + }, + { + "match": "corder", + "filter": "select * from corder", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51", + "stop_position": "", + "state": "Running", + "db_name": "vt_customer", + "transaction_timestamp": { + "seconds": "0", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697060227", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [], + "log_fetch_error": "", + "tags": [], + "rows_copied": "0", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [], + "is_primary_serving": true + } + }, + "workflow_type": "MoveTables", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "1", + "defer_secondary_keys": false + } + ] } ``` @@ -363,12 +423,10 @@ We can use [`VDiff`](../../../reference/vreplication/vdiff/) to perform a logica to confirm that they are fully in sync: ```bash -$ vtctlclient VDiff -- --v2 customer.commerce2customer create -{ - "UUID": "d050262e-8c5f-11ed-ac72-920702940ee0" -} +$ vtctldclient VDiff --target-keyspace customer --workflow commerce2customer create +VDiff bc74b91b-2ee8-4869-bc39-4740ce445e20 scheduled on target shards, use show to view progress -$ vtctlclient VDiff -- --v2 --format=json --verbose customer.commerce2customer show last +$ vtctldclient VDiff --format=json --target-keyspace customer --workflow commerce2customer show last --verbose { "Workflow": "commerce2customer", "Keyspace": "customer", @@ -435,9 +493,9 @@ traffic from the old `commerce` keyspace to the `customer` keyspace for the tabl tables will continue to route to the `commerce` keyspace. ```bash -$ vtctlclient MoveTables -- SwitchTraffic customer.commerce2customer - +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer SwitchTraffic SwitchTraffic was successful for workflow customer.commerce2customer + Start State: Reads Not Switched. Writes Not Switched Current State: All Reads Switched. Writes Switched ``` @@ -560,10 +618,9 @@ $ vtctldclient GetRoutingRules ## Reverting the Switch (Optional) As part of the `SwitchTraffic` operation, Vitess will automatically setup a reverse VReplication workflow (unless -you supply the [`--reverse_replication false` flag](../../../reference/vreplication/movetables/#--reverse_replication)) -to copy changes now applied to the moved tables in the target keyspace — `customer` and `corder` in the -`customer` keyspace — back to the original source tables in the source `commerce` keyspace. This allows us to -reverse or revert the cutover using the [`ReverseTraffic`](../../../reference/vreplication/movetables/#reversetraffic) +you supply the `--enable-reverse-replication=false` flag) to copy changes now applied to the moved tables in the +target keyspace — `customer` and `corder` in the `customer` keyspace — back to the original source tables in the +source `commerce` keyspace. This allows us to reverse or revert the cutover using the [`ReverseTraffic`](../../../reference/vreplication/movetables/#reversetraffic) action, without data loss, even after we have started writing to the new `customer` keyspace. Note that the workflow for this reverse workflow is created in the original source keyspace and given the name of the original workflow with `_reverse` appended. So in our example where the `MoveTables` workflow was in the `customer` keyspace @@ -572,78 +629,155 @@ and called `commerce2customer`, the reverse workflow is in the `commerce` keyspa [`Workflow show`](../../../reference/vreplication/workflow/) command: ```json -$ vtctlclient Workflow commerce.commerce2customer_reverse show +$ vtctldclient Workflow --keyspace commerce show --workflow commerce2customer_reverse { - "Workflow": "commerce2customer_reverse", - "SourceLocation": { - "Keyspace": "customer", - "Shards": [ - "0" - ] - }, - "TargetLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "MaxVReplicationLag": 1, - "MaxVReplicationTransactionLag": 1, - "Frozen": false, - "ShardStatuses": { - "0/zone1-0000000100": { - "PrimaryReplicationStatuses": [ - { - "Shard": "0", - "Tablet": "zone1-0000000100", - "ID": 1, - "Bls": { - "keyspace": "customer", - "shard": "0", - "filter": { - "rules": [ - { - "match": "customer", - "filter": "select * from `customer`" - }, - { - "match": "corder", - "filter": "select * from `corder`" - } - ] - } - }, - "Pos": "9fb1be70-8c59-11ed-9ef5-c05f9df6f7f3:1-2361", - "StopPos": "", - "State": "Running", - "DBName": "vt_commerce", - "TransactionTimestamp": 1672858428, - "TimeUpdated": 1672859207, - "TimeHeartbeat": 1672859207, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "", - "Tags": "", - "WorkflowType": "MoveTables", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": [ - { - "tablet_type": 1, - "denied_tables": [ - "corder", - "customer" - ] - } - ], - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" -} + "workflows": [ + { + "name": "commerce2customer_reverse", + "source": { + "keyspace": "customer", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "1", + "shard_streams": { + "0/zone1-0000000101": { + "streams": [ + { + "id": "1", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "binlog_source": { + "keyspace": "customer", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "customer", + "filter": "select * from `customer`", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + }, + { + "match": "corder", + "filter": "select * from `corder`", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "751b3b58-6874-11ee-9a45-2b583b20ee4a:1-4579", + "stop_position": "", + "state": "Running", + "db_name": "vt_commerce", + "transaction_timestamp": { + "seconds": "1697060479", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697060690", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [ + { + "id": "1", + "stream_id": "1", + "type": "Stream Created", + "state": "Stopped", + "created_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "updated_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "message": "{\"component_throttled\":\"\",\"db_name\":\"vt_commerce\",\"defer_secondary_keys\":\"0\",\"id\":\"1\",\"max_replication_lag\":\"9223372036854775807\",\"max_tps\":\"9223372036854775807\",\"pos\":\"MySQL56/751b3b58-6874-11ee-9a45-2b583b20ee4a:1-4577\",\"rows_copied\":\"0\",\"source\":\"keyspace:\\\"customer\\\" shard:\\\"0\\\" filter:{rules:{match:\\\"customer\\\" filter:\\\"select * from `customer`\\\"} rules:{match:\\\"corder\\\" filter:\\\"select * from `corder`\\\"}}\",\"state\":\"Stopped\",\"tags\":\"\",\"time_heartbeat\":\"0\",\"time_throttled\":\"0\",\"time_updated\":\"1697060479\",\"transaction_timestamp\":\"0\",\"workflow\":\"commerce2customer_reverse\",\"workflow_sub_type\":\"0\",\"workflow_type\":\"1\"}", + "count": "1" + }, + { + "id": "2", + "stream_id": "1", + "type": "State Changed", + "state": "Running", + "created_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "updated_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "message": "", + "count": "1" + } + ], + "log_fetch_error": "", + "tags": [], + "rows_copied": "0", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [ + { + "tablet_type": "PRIMARY", + "cells": [], + "denied_tables": [ + "corder", + "customer" + ], + "frozen": false + } + ], + "is_primary_serving": true + } + }, + "workflow_type": "MoveTables", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "1", + "defer_secondary_keys": false + } + ] +} ``` ## Finalize and Cleanup @@ -656,11 +790,8 @@ for the `customer` and `corder` tables to the `commerce` keyspace, it is much b error, rather than return incorrect/stale data: ```bash -$ vtctlclient MoveTables -- Complete customer.commerce2customer - -Complete was successful for workflow customer.commerce2customer -Start State: All Reads Switched. Writes Switched -Current State: Workflow Not Found +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer complete +Successfully completed the commerce2customer workflow in the customer keyspace ``` {{< info >}} @@ -684,12 +815,12 @@ $ vtctldclient GetRoutingRules } # Workflow is gone -$ vtctlclient Workflow customer listall -No workflows found in keyspace customer +$ vtctldclient Workflow --keyspace customer list +[] # Reverse workflow is also gone -$ vtctlclient Workflow commerce listall -No workflows found in keyspace commerce +$ vtctldclient Workflow --keyspace commerce list +[] ``` This confirms that the data and routing rules have been properly cleaned up. Note that the `Complete` process also cleans up the reverse VReplication workflow mentioned above. diff --git a/content/en/docs/18.0/user-guides/migration/troubleshooting.md b/content/en/docs/18.0/user-guides/migration/troubleshooting.md index 48523e07d..05e880400 100644 --- a/content/en/docs/18.0/user-guides/migration/troubleshooting.md +++ b/content/en/docs/18.0/user-guides/migration/troubleshooting.md @@ -20,7 +20,7 @@ you have setup the shell aliases from the example, e.g. `env.sh` in the [local]( ### Execute a Dry Run -The `SwitchTraffic`/`ReverseTraffic` and `Complete` actions support a dry run using the `--dry_run` flag where no +The `SwitchTraffic`/`ReverseTraffic` and `Complete` actions support a dry run using the `--dry-run` flag where no actual steps are taken but instead the command logs all the steps that *would* be taken. This command will also verify that the cluster is generally in a state where it can perform the action successfully without potentially timing out along the way. Given that traffic cutovers can potentially cause read/write pauses or outages this can @@ -51,8 +51,8 @@ tablet so it's recommended to use non-PRIMARY tablets whenever possible to limit ## Monitoring It's important to properly monitor your VReplication workflows in order to detect any issues. Your primary tools for this are: - - The [`Workflow show`](../../../reference/vreplication/workflow/) command - - The `Progress`/`Show` action (e.g. [`MoveTables -- Progress`](../../../reference/vreplication/movetables/#progress)) + - The `show`sub-command (e.g. [`MoveTables show`](../../../reference/vreplication/movetables/#show)) + - The `status ` sub-command (e.g. [`MoveTables status`](../../../reference/vreplication/movetables/#status)) - The [VReplication related metrics](../../../reference/vreplication/metrics/) - Note that in most production systems the tablet endpoints would be scraped and stored in something like [Prometheus](https://prometheus.io) where you can build dashboards and alerting on the data @@ -62,11 +62,13 @@ The `Create`, `SwitchTraffic`/`ReverseTraffic`, and `Cancel`/`Complete` actions [routing rules](../../../reference/features/schema-routing-rules/). You may want to save the routing rules before taking an action just in case you want to restore them for any reason (note that e.g. the `ReverseTraffic` action will automatically revert the routing rules): + ```bash $ vtctldclient GetRoutingRules > /tmp/routingrules.backup.json ``` Those can later be applied this way: + ```bash $ vtctldclient ApplyRoutingRules --rules-file=/tmp/routingrules.backup.json ``` @@ -77,57 +79,77 @@ $ vtctldclient ApplyRoutingRules --rules-file=/tmp/routingrules.backup.json ### Stream Never Starts This can be exhibited in one of two ways: -1. This error is shown in the `Progress`/`Show` action output or the `Workflow show` output: `Error picking tablet: context has expired` +1. This error is shown in the `status`/`show` action output or the `Workflow show` output: `Error picking tablet: context has expired` 2. The stream never starts, which can be seen in the following ways: - 1. The `Workflow show` output is showing an empty value in the `Pos` field for the stream - 2. The `Progress`/`Show` action output is showing `VStream has not started` for the stream + 1. The `show` output is showing an empty value in the `Pos` field for the stream + 2. The `status`/`show` action output is showing `VStream has not started` for the stream When a VReplication workflow starts or restarts the [tablet selection process](../../../reference/vreplication/tablet_selection/) -runs to find a viable source tablet for the stream. The `cells` and `tablet_types` play a key role in this process and +runs to find a viable source tablet for the stream. The `--cells` and `--tablet-types` play a key role in this process and if we cannot ever find a viable source tablet for the stream then you may want to expand the cells and/or tablet types made available for the selection process. #### Corrective Action -If the workflow was only created and has not yet made any progress then you should `Cancel` the workflow and `Create` a new -one using different values for the `--cells` and `--tablet_types` flags. If, however, this workflow has made significant +If the workflow was only created and has not yet made any progress then you should `cancel` the workflow and `create` a new +one using different values for the `--cells` and `--tablet-types` flags. If, however, this workflow has made significant progress that you do not wish you lose, you can update the underlying workflow record directly to modify either of those values. For example: -```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000200: Status: Running. VStream has not started. - -$ vtctlclient Workflow -- --tablet-types="replica,primary" customer.commerce2customer update - -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: -id=1 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +```bash +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 1, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-49", + "status": "Running", + "info": "VStream Lag: 0s; ; Tx time: Wed Oct 11 16:49:02 2023." + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` ### Workflow Has SQL Errors We can encounter persistent SQL errors when applying replicated events on the target for a variety of reasons, but the most common cause is incompatible DDL having been executed against the source table while the workflow is running. -You would see this error in the `Show`/`Progress` or `Workflow show` output. For example: -```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000201: Status: Error: Unknown column 'notes' in 'field list' (errno 1054) (sqlstate 42S22) during query: insert into customer(customer_id,email,notes) values (100,'test@tester.com','Lots of notes'). +You would see this error in the `status`/`show` or `Workflow show` output. For example: -# OR a variant - -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000201: Status: Error: vttablet: rpc error: code = Unknown desc = stream (at source tablet) error @ a2d90338-916d-11ed-820a-498bdfbb0b03:1-90: cannot determine table columns for customer: event has [8 15 15], schema has [name:"customer_id" type:INT64 table:"customer" org_table:"customer" database:"vt_commerce" org_name:"customer_id" column_length:20 charset:63 flags:49667 name:"email" type:VARBINARY table:"customer" org_table:"customer" database:"vt_commerce" org_name:"email" column_length:128 charset:63 flags:128]. +```bash +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 1, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-49", + "status": "Error: Unknown column 'notes' in 'field list' (errno 1054) (sqlstate 42S22) during query: insert into customer(customer_id,email,notes) values (100,'test@tester.com','Lots of notes')", + "info": "VStream Lag: 0s; ; Tx time: Wed Oct 11 16:49:02 2023." + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` This can be caused by a DDL executed on the source table as by default — controlled by the @@ -136,67 +158,75 @@ This can be caused by a DDL executed on the source table as by default — contr #### Corrective Action If you want the same or similar DDL to be applied on the target then you can apply that DDL on the target keyspace and then restart the workflow. For example, using the example above: + ```bash -$ vtctldclient ApplySchema --ddl-strategy=direct --sql="alter table customer add notes varchar(100) not null" customer +vtctldclient ApplySchema --ddl-strategy=direct --sql="alter table customer add notes varchar(100) not null" customer -$ vtctldclient Workflow customer.commerce2customer start +vtctldclient Workflow customer.commerce2customer start ``` If the tables are not very large or the workflow has not made much progress, you can alternatively `Cancel` the current worfklow and `Create` another. For example: -```bash -$ vtctlclient MoveTables -- Cancel customer.commerce2customer -Cancel was successful for workflow customer.commerce2customer -Start State: Reads Not Switched. Writes Not Switched -Current State: Workflow Not Found - - -$ vtctlclient MoveTables -- --source commerce --tables 'customer,corder' Create customer.commerce2customer -Waiting for workflow to start: - -Workflow started successfully with 1 stream(s) - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=2 on 0/zone1-0000000201: Status: Copying. VStream Lag: 0s. +```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer cancel +Successfully cancelled the commerce2customer workflow in the customer keyspace +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer create --source-keyspace commerce --tables 'customer,corder' The following vreplication streams exist for workflow customer.commerce2customer: -id=2 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +id=2 on customer/zone1-200: Status: Running. VStream has not started. + +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 2, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51", + "status": "Running", + "info": "VStream Lag: 0s" + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` ### Switching Traffic Fails You can encounter a variety of failures during the `SwitchTraffic`/`ReverseTraffic` step as a number of operations are performed. To demonstrate that we can look at an example dry run output: + ```bash -$ vtctlclient MoveTables -- --dry_run SwitchTraffic customer.commerce2customer -Dry Run results for SwitchTraffic run at 11 Jan 23 08:51 EST -Parameters: --dry_run SwitchTraffic customer.commerce2customer +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer SwitchTraffic --dry-run +SwitchTraffic dry run results for workflow customer.commerce2customer at 11 Oct 23 21:23 UTC Lock keyspace commerce -Switch reads for tables [corder,customer] to keyspace customer for tablet types [RDONLY,REPLICA] +Switch reads for tables [corder,customer] to keyspace customer for tablet types [PRIMARY,REPLICA,RDONLY] Routing rules for tables [corder,customer] will be updated Unlock keyspace commerce Lock keyspace commerce Lock keyspace customer -Stop writes on keyspace commerce, tables [corder,customer]: - Keyspace commerce, Shard 0 at Position MySQL56/a2d90338-916d-11ed-820a-498bdfbb0b03:1-94 -Wait for VReplication on stopped streams to catchup for up to 30s -Create reverse replication workflow commerce2customer_reverse +Stop writes on keyspace commerce for tables [corder,customer]: [keyspace:commerce;shard:0;position:MySQL56/5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51] +Wait for vreplication on stopped streams to catchup for up to 30s +Create reverse vreplication workflow commerce2customer_reverse Create journal entries on source databases -Enable writes on keyspace customer tables [corder,customer] +Enable writes on keyspace customer for tables [corder,customer] Switch routing from keyspace commerce to keyspace customer Routing rules for tables [corder,customer] will be updated -Switch writes completed, freeze and delete vreplication streams on: - tablet 201 -Start reverse replication streams on: - tablet 101 -Mark vreplication streams frozen on: - Keyspace customer, Shard 0, Tablet 201, Workflow commerce2customer, DbName vt_customer +Switch writes completed, freeze and delete vreplication streams on: [tablet:200] +Start reverse vreplication streams on: [tablet:101] +Mark vreplication streams frozen on: [keyspace:customer;shard:0;tablet:200;workflow:commerce2customer;dbname:vt_customer] Unlock keyspace customer Unlock keyspace commerce ``` @@ -206,17 +236,19 @@ Unlock keyspace commerce #### disallowed due to rule: enforce denied tables If your queries start failing with this error then you most likely had some leftover artifacts from a previous `MoveTables` operation -that were not properly cleaned up by running [`MoveTables -- Cancel`](../../../reference/vreplication/movetables/#cancel). For +that were not properly cleaned up by running [`MoveTables cancel`](../../../reference/vreplication/movetables/#cancel). For `MoveTables` operations, shard query serving control records (denied tables lists) are used in addition to [routing rules](../../../reference/features/schema-routing-rules/) to ensure that all query traffic is managed by the correct keyspace as you are often only moving some tables from one keyspace to another. If those control records are not properly cleaned up then queries may be incorrectly denied when traffic is switched. If you e.g. were to see the following error for queries after switching traffic for the customer table from the commerce keyspace to the customer keyspace: + ``` code = FailedPrecondition desc = disallowed due to rule: enforce denied tables (CallerID: matt) for query SELECT * FROM customer WHERE customer_id = 1 ``` Then you can remove those unwanted/errant denied table rules from the customer keyspace this way: + ```bash $ for type in primary replica rdonly; do vtctldclient SetShardTabletControl --remove customer/0 ${type} @@ -230,23 +262,27 @@ $ vtctldclient RefreshStateByShard customer/0 The completion action performs a number of steps that could potentially fail. We can again use the dry run output to demonstrate the various actions that are taken: + ```bash -$ vtctlclient MoveTables -- --dry_run Complete customer.commerce2customer -Dry Run results for Complete run at 11 Jan 23 10:22 EST -Parameters: --dry_run Complete customer.commerce2customer +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer SwitchTraffic --dry-run +SwitchTraffic dry run results for workflow customer.commerce2customer at 11 Oct 23 21:23 UTC +Lock keyspace commerce +Switch reads for tables [corder,customer] to keyspace customer for tablet types [PRIMARY,REPLICA,RDONLY] +Routing rules for tables [corder,customer] will be updated +Unlock keyspace commerce Lock keyspace commerce Lock keyspace customer -Dropping these tables from the database and removing them from the vschema for keyspace commerce: - Keyspace commerce Shard 0 DbName vt_commerce Tablet 101 Table corder - Keyspace commerce Shard 0 DbName vt_commerce Tablet 101 Table customer -Denied tables [corder,customer] will be removed from: - Keyspace commerce Shard 0 Tablet 101 -Delete reverse vreplication streams on source: - Keyspace commerce Shard 0 Workflow commerce2customer_reverse DbName vt_commerce Tablet 101 -Delete vreplication streams on target: - Keyspace customer Shard 0 Workflow commerce2customer DbName vt_customer Tablet 201 -Routing rules for participating tables will be deleted +Stop writes on keyspace commerce for tables [corder,customer]: [keyspace:commerce;shard:0;position:MySQL56/5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51] +Wait for vreplication on stopped streams to catchup for up to 30s +Create reverse vreplication workflow commerce2customer_reverse +Create journal entries on source databases +Enable writes on keyspace customer for tables [corder,customer] +Switch routing from keyspace commerce to keyspace customer +Routing rules for tables [corder,customer] will be updated +Switch writes completed, freeze and delete vreplication streams on: [tablet:200] +Start reverse vreplication streams on: [tablet:101] +Mark vreplication streams frozen on: [keyspace:customer;shard:0;tablet:200;workflow:commerce2customer;dbname:vt_customer] Unlock keyspace customer Unlock keyspace commerce -``` \ No newline at end of file +``` diff --git a/content/en/docs/18.0/user-guides/vschema-guide/backfill-vindexes.md b/content/en/docs/18.0/user-guides/vschema-guide/backfill-vindexes.md index 657494b60..c4c03bc29 100644 --- a/content/en/docs/18.0/user-guides/vschema-guide/backfill-vindexes.md +++ b/content/en/docs/18.0/user-guides/vschema-guide/backfill-vindexes.md @@ -3,14 +3,14 @@ title: Backfill Lookup Vindexes weight: 11 --- -Creating a lookup vindex after the main table already contains rows does not automatically backfill the lookup table for the existing entries. +Creating a Lookup Vindex after the main table already contains rows does not automatically backfill the lookup table for the existing entries. Only newer inserts cause automatic population of the lookup table. -This backfill can be set up using the [CreateLookupVindex](#createlookupvindex) command covered below. +This backfill can be set up using the [LookupVindex create](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command covered below. ### Manual Backfill Checklist -Creating a unique lookup Vindex is an elaborate process. It is good to use the following checklist if this is done manually: +Creating a unique Lookup Vindex is an elaborate process. It is good to use the following checklist if this is done manually: * Create the lookup table as sharded or unsharded. Make the `from` column the primary key. * Create a VSchema entry for the lookup table. If sharded, assign a Primary Vindex for the `from` column. @@ -21,9 +21,9 @@ Creating a unique lookup Vindex is an elaborate process. It is good to use the f * Specify the `Owner` as the main table * Associate the column of the owner table with the new Vindex. -### CreateLookupVindex +### Creating a Lookup Vindex -vtctld supports the [CreateLookupVindex](../../configuration-advanced/createlookupvindex) command that can perform all the above steps as well as the backfill. +vtctldclient supports the [LookupVindex create](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command that can perform all the above steps as well as the backfill. {{< warning >}} This will not work against the `vtcombo` based demo app because it does not support vreplication. You can only try this against a real Vitess cluster. @@ -31,7 +31,7 @@ This will not work against the `vtcombo` based demo app because it does not supp The workflow automatically infers the schema and vschema for the lookup table and creates it. It also sets up the necessary VReplication streams to backfill the lookup table. -After the backfill is done, you should clean up the workflow. More detailed instructions are available in the [CreateLookupVindex Reference](../../configuration-advanced/createlookupvindex) +After the backfill is done, you should clean up the workflow. More detailed instructions are available in the [Creating a Lookup Vindex Guide](../../configuration-advanced/createlookupvindex) To create such a lookup vindex on a real Vitess cluster, you can use the following instructions: diff --git a/content/en/docs/19.0/concepts/vtctld.md b/content/en/docs/19.0/concepts/vtctld.md index 2f39c54d6..3236a00ec 100644 --- a/content/en/docs/19.0/concepts/vtctld.md +++ b/content/en/docs/19.0/concepts/vtctld.md @@ -4,4 +4,4 @@ title: vtctld **vtctld** is an HTTP server that lets you browse the information stored in the Topology Service. It is useful for troubleshooting or for getting a high-level overview of the servers and their current states. -`vtctld` also acts as the server for `vtctlclient` and `vtctldclient` connections. +`vtctld` also acts as the server for `vtctldclient` connections. diff --git a/content/en/docs/19.0/get-started/local-brew.md b/content/en/docs/19.0/get-started/local-brew.md index 2332d7322..94b599b31 100644 --- a/content/en/docs/19.0/get-started/local-brew.md +++ b/content/en/docs/19.0/get-started/local-brew.md @@ -191,13 +191,13 @@ rm -rf /usr/local/Cellar/vitess/9.0.0/share/vitess/examples/local/vtdataroot ## Setup Aliases -For ease-of-use, Vitess provides aliases for `mysql` and `vtctlclient`: +For ease-of-use, Vitess provides aliases for `mysql` and `vtctldclient`: ```bash source ../common/env.sh ``` -Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctlclient` or close your session. +Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctldclient` or close your session. ## Connect to your cluster diff --git a/content/en/docs/19.0/get-started/local.md b/content/en/docs/19.0/get-started/local.md index 1667580df..9ae162afc 100644 --- a/content/en/docs/19.0/get-started/local.md +++ b/content/en/docs/19.0/get-started/local.md @@ -65,7 +65,7 @@ Download the [latest binary release](https://github.com/vitessio/vitess/releases * Ubuntu is the only fully supported OS, for another OS please [build Vitess by yourself](/docs/contributing) or use the Docker images. ```sh -version=17.0.0 +version=19.0.0 file=vitess-${version}-70a9466.tar.gz wget https://github.com/vitessio/vitess/releases/download/v${version}/${file} tar -xzf ${file} @@ -222,13 +222,13 @@ rm -rf vtdataroot ## Setup Aliases -For ease-of-use, Vitess provides aliases for `mysql`, `vtctlclient` and `vtcltdclient`: +For ease-of-use, Vitess provides aliases for `mysql` and `vtcltdclient`: ```bash source ../common/env.sh ``` -Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctlclient && unalias vtctldclient` or close your session. +Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctldclient` or close your session. ## Connect to your cluster diff --git a/content/en/docs/19.0/get-started/operator.md b/content/en/docs/19.0/get-started/operator.md index 55112f490..f9638b1ec 100644 --- a/content/en/docs/19.0/get-started/operator.md +++ b/content/en/docs/19.0/get-started/operator.md @@ -72,16 +72,15 @@ vitess-operator-5f47c6c45d-bgqp2 1/1 Running 0 The port-forward will only forward to a specific pod. Currently, `kubectl` does not automatically terminate a port-forward as the pod disappears due to apply/upgrade operations. You will need to manually restart the port-forward. {{}} -For ease-of-use, Vitess provides a script to port-forward from Kubernetes to your local machine. This script also recommends setting up aliases for `mysql` and `vtctlclient`: +For ease-of-use, Vitess provides a script to port-forward from Kubernetes to your local machine. This script also recommends setting up aliases for `mysql` and `vtctldclient`: ```bash ./pf.sh & alias vtctldclient="vtctldclient --server=localhost:15999" -alias vtctlclient="vtctlclient --server=localhost:15999" alias mysql="mysql -h 127.0.0.1 -P 15306 -u user" ``` -Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctlclient && unalias vtctldclient` or close your session. +Setting up aliases changes `mysql` to always connect to Vitess for your current session. To revert this, type `unalias mysql && unalias vtctldclient` or close your session. Once the port-forward starts running, the VTAdmin UI will be available at [http://localhost:14000/](http://localhost:14000/) diff --git a/content/en/docs/19.0/reference/features/connection-pools.md b/content/en/docs/19.0/reference/features/connection-pools.md index d30eb0eb7..3571ce4eb 100644 --- a/content/en/docs/19.0/reference/features/connection-pools.md +++ b/content/en/docs/19.0/reference/features/connection-pools.md @@ -48,7 +48,7 @@ As a result, connection pools should be sized mindful of the capacity of the und * Max size controlled by: `--dba_pool_size` (default 20) * metric: `vttablet_dba_conn_pool_capacity` * vttablet user flag: `--db_dba_user` (default 'vt_dba') - * Used by vttablet `ExecuteFetchAsDba` RPC. This is used when using `vtctlclient ExecuteFetchAsDba` + * Used by vttablet `ExecuteFetchAsDBA` RPC. This is used when using `vtctldclient ExecuteFetchAsDBA` Also used implicitly for various internal Vitess maintenance tasks (e.g. schema reloads, etc.) ### app_conn_pool @@ -56,7 +56,7 @@ As a result, connection pools should be sized mindful of the capacity of the und * Max size controlled by: `--app_pool_size` (default 40) * metric: `vttablet_app_conn_pool_capacity` * vttablet user flag: `--db_app_user` default 'vt_app') - * Used by vttablet `ExecuteFetchAsApp` RPC. This is used when using `vtctlclient ExecuteFetchAsApp` + * Used by vttablet `ExecuteFetchAsApp` RPC. This is used when using `vtctldclient ExecuteFetchAsApp` ### tx_read_pool @@ -89,7 +89,6 @@ As a result, connection pools should be sized mindful of the capacity of the und #### `--db_allprivs_user` * (default 'vt_allprivs') - * Created on demand by `vtctlclient ExecuteFetchAsAllPrivs` #### `--db_erepl_user` diff --git a/content/en/docs/19.0/reference/features/tablet-throttler.md b/content/en/docs/19.0/reference/features/tablet-throttler.md index 67c73399d..25063c456 100644 --- a/content/en/docs/19.0/reference/features/tablet-throttler.md +++ b/content/en/docs/19.0/reference/features/tablet-throttler.md @@ -123,12 +123,12 @@ The following flag was removed: - `--enable_lag_throttler` -Updating the throttler config is done via `vtctlclient` or `vtctldclient`. For example: +Updating the throttler config is done via `vtctldclient`. For example: ```sh -$ vtctlclient -- UpdateThrottlerConfig --enable --threshold 3.0 commerce +$ vtctldclient UpdateThrottlerConfig --enable --threshold 3.0 commerce $ vtctldclient UpdateThrottlerConfig --disable commerce -$ vtctldclient UpdateThrottlerConfig --throttle-app="vreplication" --throttle-app-ratio 0.5 --throttle-app-duration "30m" commerce +$ vtctldclient UpdateThrottlerConfig --throttle-app "vreplication" --throttle-app-ratio 0.5 --throttle-app-duration "30m" commerce ``` See [vtctl UpdateThrottlerConfig](../../programs/vtctl/throttler#updatethrottlerconfig). diff --git a/content/en/docs/19.0/reference/features/topology-service.md b/content/en/docs/19.0/reference/features/topology-service.md index 8ec6e1f8a..ac4ee0328 100644 --- a/content/en/docs/19.0/reference/features/topology-service.md +++ b/content/en/docs/19.0/reference/features/topology-service.md @@ -516,13 +516,13 @@ information about the local topology service: * `${CELL_NAME}` the name of our local cell in this case `US_EAST` ``` sh -# vtctlclient uses the IP address of the vtctld daemon with the `--server` flag +# vtctldclient uses the IP address of the vtctld daemon with the `--server` flag # The daemon already has the global topology information, therefore, we do not # need to explicitly provide these details. -vtctlclient --server ${VTCTLD_IP}:15999 AddCellInfo -- \ +vtctldclient --server ${VTCTLD_IP}:15999 AddCellInfo -- \ --root=/vitess/${CELL_NAME} \ - --server_address=${CELL_ETCD_SERVER} \ + --server-address=${CELL_ETCD_SERVER} \ ${CELL_NAME} ``` @@ -573,8 +573,8 @@ propagate information from the global topology service back to the local topolog services ```sh -vtctlclient --server ${VTCTLD_IP}:15999 RebuildKeyspaceGraph ${KEYSPACE_NAME} -vtctlclient --server ${VTCTLD_IP}:15999 RebuildVSchemaGraph +vtctldclient --server ${VTCTLD_IP}:15999 RebuildKeyspaceGraph ${KEYSPACE_NAME} +vtctldclient --server ${VTCTLD_IP}:15999 RebuildVSchemaGraph ``` @@ -604,7 +604,7 @@ run 5 global servers across all cells (for global topology data) and 3 local servers per cell (for per-cell topology data). To migrate to such a setup, start by adding the 3 local servers in the second -cell and run `vtctlclient AddCellinfo` as was done for the first cell. Tablets and +cell and run `vtctldclient AddCellInfo` as was done for the first cell. Tablets and vtgates can now be started in the second cell, and used normally. vtgate can then be configured with a list of cells to watch for tablets using diff --git a/content/en/docs/19.0/reference/features/vindexes.md b/content/en/docs/19.0/reference/features/vindexes.md index 386846b51..ac9175f69 100644 --- a/content/en/docs/19.0/reference/features/vindexes.md +++ b/content/en/docs/19.0/reference/features/vindexes.md @@ -267,7 +267,7 @@ You can query Vindex functions to see the resulting `keyspace_id` it produces (t First, a snippet of the VSchema: ``` shell -$ vtctlclient -server=localhost:15999 GetVSchema customer | jq '.vindexes' +$ vtctldclient --server=localhost:15999 GetVSchema customer | jq '.vindexes' { "binary_md5_vdx": { "type": "binary_md5" diff --git a/content/en/docs/19.0/reference/vreplication/createlookupvindex.md b/content/en/docs/19.0/reference/vreplication/createlookupvindex.md deleted file mode 100644 index 8acf91cbd..000000000 --- a/content/en/docs/19.0/reference/vreplication/createlookupvindex.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: CreateLookupVindex -weight: 60 ---- - -**CreateLookupVindex** is a [VReplication](../../../reference/vreplication/) workflow used to create **and** backfill -a [lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already -exists, and may have a significant amount of data in it already. - -Internally, the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) process uses -VReplication for the backfill process, until the lookup Vindex is "in sync". Then the normal process for -adding/deleting/updating rows in the lookup Vindex via the usual -[transactional flow when updating the "owner" table for the Vindex](../../../reference/features/vindexes/#lookup-vindex-types) -takes over. - -In this guide, we will walk through the process of using the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) -workflow, and give some insight into what happens underneath the covers. - -The `CreateLookupVindex` `vtctl` client command has the following syntax: - -```CreateLookupVindex -- [--cells=] [--continue_after_copy_with_owner=false] [--tablet_types=] ``` - -* ``: Use the lookup Vindex specified in `` along with - VReplication to populate/backfill the lookup Vindex from the source table. -* ``: The Vitess keyspace we are creating the lookup Vindex in. - The source table is expected to also be in this keyspace. -* `--tablet-types`: Provided to specify the tablet types - (e.g. `PRIMARY`, `REPLICA`, `RDONLY`) that are acceptable - as source tablets for the VReplication stream(s) that this command will - create. If not specified, the tablet type used will default to the value - of the [`vttablet --vreplication_tablet_type` flag](../../../reference/vreplication/flags/#vreplication_tablet_type) - value, which defaults to `in_order:REPLICA,PRIMARY`. -* `--cells`: By default VReplication streams, such as used by - `CreateLookupVindex`, will not cross cell boundaries. If you want the - VReplication streams to source their data from tablets in cells other - than the local cell, you can use the `--cells` option to specify a - comma-separated list of cells (see [VReplication tablet selection](../../../reference/vreplication/tablet_selection/)). -* `--continue_after_copy_with_owner`: By default, when an owner is provided in the ``, - the VReplication streams will stop after the backfill completes. Specify this flag if - you don't want this to happen. This is useful if, for example, the owner table is being - migrated from an unsharded keyspace to a sharded keyspace using - [`MoveTables`](../../../reference/vreplication/movetables/). - -The `` describes the lookup Vindex to be created, and details about -the table it is to be created against (on which column, etc.). However, -you do not have to specify details about the actual lookup table, Vitess -will create that automatically based on the type of the column you are -creating the Vindex column on, etc. \ No newline at end of file diff --git a/content/en/docs/19.0/reference/vreplication/internal/cutover.md b/content/en/docs/19.0/reference/vreplication/internal/cutover.md index 6267fb56e..40862b377 100644 --- a/content/en/docs/19.0/reference/vreplication/internal/cutover.md +++ b/content/en/docs/19.0/reference/vreplication/internal/cutover.md @@ -13,8 +13,8 @@ cached locally, the processes involved will refresh their topo data throughout t tablet on the source and target shards that are involved in a [VReplication](../../) workflow will refresh their topo data multiple times as the state of things transition during the cutover. If we are *not* able to confirm that all tablets involved in a VReplication worfklow are able to refresh their topo data then the cutover -command — e.g. [`vtctlclient SwitchTraffic`](../../switchtraffic) — will cancel the operation -and return an error indicating which tablet(s) are unhealthy (including for `--dry_run` executions). +command — e.g. [`vtctldclient SwitchTraffic`](../../switchtraffic) — will cancel the operation +and return an error indicating which tablet(s) are unhealthy (including for `--dry-run` executions). {{< /info >}} ## VSchema @@ -28,11 +28,16 @@ one [`Shard`](../../../features/topology-service/#shard) key per keyspace which shard that has been created within the keyspace. For each shard that is healthy there is an attribute `is_primary_serving` which is set to true. The other shards which have been created but are still not healthy and serving within the keyspace will not have this attribute set. Here is an example shard info record from an unsharded -keyspace named commerce (without the `--cell` flag being passed the `global` topo base path is used): +keyspace named commerce: ```bash -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto '/keyspaces/commerce/shards/0/Shard' -primary_alias:{cell:"zone1" uid:100} primary_term_start_time:{seconds:1650341417 nanoseconds:374817485} is_primary_serving:true +$ vtctldclient --server=localhost:15999 GetTopologyPath /global/keyspaces/commerce/shards/0/Shard +{ + "name": "Shard", + "path": "/global//keyspaces/commerce/shards/0/Shard", + "data": "primary_alias:{cell:\"zone1\" uid:101} primary_term_start_time:{seconds:1697055542 nanoseconds:430056000} is_primary_serving:true", + "children": [] +} ``` ## SrvKeyspace @@ -50,11 +55,21 @@ same unsharded commerce keyspace and here we specify the `--cell` flag so that c its `CellInfo` record in the `global` topo — is used: ```bash -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto '/cells/zone1/CellInfo' -server_address:"localhost:2379" root:"/vitess/zone1" +$ vtctldclient --server=localhost:15999 GetTopologyPath /global/cells/zone1/CellInfo +{ + "name": "CellInfo", + "path": "/global/cells/zone1/CellInfo", + "data": "server_address:\"localhost:2379\" root:\"/vitess/zone1\"", + "children": [] +} -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto --cell=zone1 '/keyspaces/commerce/SrvKeyspace' -partitions:{served_type:PRIMARY shard_references:{name:"0"}} partitions:{served_type:REPLICA shard_references:{name:"0"}} partitions:{served_type:RDONLY shard_references:{name:"0"}} +$ vtctldclient --server=localhost:15999 GetTopologyPath /zone1/keyspaces/commerce/SrvKeyspace +{ + "name": "SrvKeyspace", + "path": "/zone1/keyspaces/commerce/SrvKeyspace", + "data": "partitions:{served_type:PRIMARY shard_references:{name:\"0\"}} partitions:{served_type:REPLICA shard_references:{name:\"0\"}} partitions:{served_type:RDONLY shard_references:{name:\"0\"}}", + "children": [] +} ``` ## Routing Rules @@ -66,15 +81,20 @@ where we have an active [`MoveTables`](../../../vreplication/movetables/) workfl customer keyspace but we have not switched any traffic yet: ```bash -$ vtctlclient --server=localhost:15999 TopoCat -- --decode_proto '/RoutingRules' -rules:{from_table:"corder@rdonly" to_tables:"commerce.corder"} rules:{from_table:"customer.corder" to_tables:"commerce.corder"} rules:{from_table:"customer.corder@replica" to_tables:"commerce.corder"} rules:{from_table:"customer@rdonly" to_tables:"commerce.customer"} rules:{from_table:"customer.customer@rdonly" to_tables:"commerce.customer"} rules:{from_table:"customer.corder@rdonly" to_tables:"commerce.corder"} rules:{from_table:"customer@replica" to_tables:"commerce.customer"} rules:{from_table:"corder@replica" to_tables:"commerce.corder"} rules:{from_table:"commerce.corder@replica" to_tables:"commerce.corder"} rules:{from_table:"commerce.corder@rdonly" to_tables:"commerce.corder"} rules:{from_table:"commerce.customer@rdonly" to_tables:"commerce.customer"} rules:{from_table:"corder" to_tables:"commerce.corder"} rules:{from_table:"customer.customer@replica" to_tables:"commerce.customer"} rules:{from_table:"commerce.customer@replica" to_tables:"commerce.customer"} rules:{from_table:"customer" to_tables:"commerce.customer"} rules:{from_table:"customer.customer" to_tables:"commerce.customer"} +$ vtctldclient --server=localhost:15999 GetTopologyPath /global/RoutingRules +{ + "name": "RoutingRules", + "path": "/global/RoutingRules", + "data": "rules:{from_table:\"customer.customer\" to_tables:\"commerce.customer\"} rules:{from_table:\"commerce.customer@rdonly\" to_tables:\"commerce.customer\"} rules:{from_table:\"corder\" to_tables:\"commerce.corder\"} rules:{from_table:\"corder@replica\" to_tables:\"commerce.corder\"} rules:{from_table:\"corder@rdonly\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer.corder\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer@rdonly\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer.corder@replica\" to_tables:\"commerce.corder\"} rules:{from_table:\"commerce.customer@replica\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer.customer@replica\" to_tables:\"commerce.customer\"} rules:{from_table:\"customer.customer@rdonly\" to_tables:\"commerce.customer\"} rules:{from_table:\"commerce.corder@rdonly\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer@replica\" to_tables:\"commerce.customer\"} rules:{from_table:\"commerce.corder@replica\" to_tables:\"commerce.corder\"} rules:{from_table:\"customer.corder@rdonly\" to_tables:\"commerce.corder\"}", + "children": [] +} ```
{{< info >}} In practice you would instead typically view the routing rules via the -dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions/#getroutingrules) +dedicated [`GetRoutingRules`](../../../programs/vtctldclient/vtctldclient_getroutingrules/) vtctl client command which will return the rules for all keyspaces in the topo. {{< /info >}} diff --git a/content/en/docs/19.0/reference/vreplication/lookupvindex.md b/content/en/docs/19.0/reference/vreplication/lookupvindex.md new file mode 100644 index 000000000..951f4cefc --- /dev/null +++ b/content/en/docs/19.0/reference/vreplication/lookupvindex.md @@ -0,0 +1,23 @@ +--- +title: LookupVindex +description: Create, backfill, and externalize Lookup Vindexes +weight: 60 +--- + +[`LookupVindex`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/) is a command used to create **and** backfill +a [Lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already +exists, and may have a significant amount of data in it already. + +Internally, the [`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command uses +VReplication for the backfill process, until the lookup Vindex is "in sync". Then the normal process for +adding/deleting/updating rows in the lookup Vindex via the usual +[transactional flow when updating the "owner" table for the Vindex](../../../reference/features/vindexes/#lookup-vindex-types) +takes over. + +## Command + +Please see the [`LookupVindex` command reference](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/) for a full list of sub-commands and their flags. + +## Additional Information + +Please see the user guide for examples of [Creating a Lookup Vindex](../../../user-guides/configuration-advanced/createlookupvindex/) for more information on how to use this command. diff --git a/content/en/docs/19.0/reference/vreplication/materialize.md b/content/en/docs/19.0/reference/vreplication/materialize.md index 4a044f274..6526510ae 100644 --- a/content/en/docs/19.0/reference/vreplication/materialize.md +++ b/content/en/docs/19.0/reference/vreplication/materialize.md @@ -1,28 +1,47 @@ --- title: Materialize -description: +description: Materialize the results of a query into a table weight: 40 --- -### Command - -``` -Materialize -- [--cells=] [--tablet_types=] -``` - ### Description -`Materialize` is a lower level vreplication command that allows for generalized materialization of tables. The target tables +[`Materialize`](../../programs/vtctldclient/vtctldclient_materialize/) is a lower level vreplication command that allows for generalized materialization of tables. The target tables can be copies, aggregations, or views. The target tables are kept in sync in near-realtime. -You can specify multiple tables to materialize using the `json_spec` parameter. +You can specify multiple tables to materialize using the [`create`](../../programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_create/) sub-command's `--table-settings` flag. {{< warning >}} Be careful to avoid using the `INSTANT ADD COLUMN` feature in [MySQL 8.0+](https://mysqlserverteam.com/mysql-8-0-innodb-now-supports-instant-add-column/) with materialization source tables as this can cause the vreplication based materialization workflow to break. {{< /warning >}} +## The Basic Materialize Workflow Lifecycle + +1. Initiate the migration using `Materialize` +2. Monitor the workflow using `show` or `status`
+`Materialize --target-keyspace show --workflow `
+`Materialize --target-keyspace status --workflow `
+3. Start accessing your views once the workflow has started Replicating + +## Command + +Please see the [`Materialize` command reference](../../programs/vtctldclient/vtctldclient_materialize/) for a full list of sub-commands and their flags. + +### Example + +```shell +vtctldclient --server localhost:15999 Materialize --workflow product_sales --target-keyspace commerce create --source-keyspace commerce --table-settings '[{"target_table": "sales_by_sku", "create_ddl": "create table sales_by_sku (sku varbinary(128) not null primary key, orders bigint, revenue bigint)", "source_expression": "select sku, count(*) as orders, sum(price) as revenue from corder group by sku"}]' --cells zone1 --cells zone2 --tablet-types replica +``` + ### Parameters +### Action + +[`Materialize`](../../programs/vtctldclient/vtctldclient_materialize/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_materialize/#see-also) defines the operation on the workflow. + +### Options + +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_materialize/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_materialize/) for the full list of command options or flags. Below we will add additional information for a subset of key options. #### --cells **optional**\ @@ -41,7 +60,7 @@ cells should be used to pick a tablet for selecting data from the source keyspac * To reduce bandwidth costs by skipping cells that are in different availability zones * Select cells where replica lags are lower -#### --tablet_types +#### --tablet-types **optional**\ **default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ **string** @@ -58,44 +77,34 @@ specified impacts [tablet selection](../tablet_selection/) for the workflow. * To reduce the load on PRIMARY tablets by using REPLICAs or RDONLYs * Reducing lag by pointing to PRIMARY -#### JSON spec details -
+#### --table-settings +**required**\ +**JSON** -* *workflow* name to refer to this materialization -* *source_keyspace* keyspace containing the source table -* *target_keyspace* keyspace to materialize to -* *table_settings* list of views to be materialized and the associated query - * *target_table* name of table to which to materialize the data to - * *source_expression* the materialization query -* Optional parameters: - * *stop_after_copy* if vreplication should be stopped after the copy phase - is complete - * *cell* name of a cell, or a comma separated list of cells, that should be - used for choosing source tablet(s) for the materialization. If this - parameter is not specified, only cell(s) local to the target tablet(s) is - considered - * *tablet_types* a Vitess tablet_type, or comma separated list of tablet - types, that should be used for choosing source tablet(s) for the - materialization. If not specified, this defaults to the tablet type(s) - specified by the `--vreplication_tablet_type` VTTablet command line flag - -
+
-#### Example +This is a JSON array where each value must contain two key/value pairs. The first required key is 'target_table' and it is the name of the table in the target-keyspace to store the results in. The second required key is 'source_expression' and its value is the select query to run against the source table. An optional key/value pair can also be specified for 'create_ddl' which provides the DDL to create the target table if it does not exist – you can alternatively specify a value of 'copy' if the target table schema should be copied as-is from the source keyspace. Here's an example value for table-settings: + +```json +[ + { + "target_table": "customer_one_email", + "source_expression": "select email from customer where customer_id = 1" + }, + { + "target_table": "states", + "source_expression": "select * from states", + "create_ddl": "copy" + }, + { + "target_table": "sales_by_sku", + "source_expression": "select sku, count(*) as orders, sum(price) as revenue from corder group by sku", + "create_ddl": "create table sales_by_sku (sku varbinary(128) not null primary key, orders bigint, revenue bigint)" + } +] ``` -Materialize '{"workflow": "product_sales", "source_keyspace": "commerce", "target_keyspace": "customer", - "table_settings": [{"target_table": "sales_by_sku", - "source_expression": "select sku, count(*), sum(price) from corder group by order_id"}], - "cell": "zone1", "tablet_types": "REPLICA"}' -``` - -### A Materialize Workflow - -Once you decide on your materialization requirements, you need to initiate a VReplication workflow as follows: -1. Initiate the migration using `Materialize` -2. Monitor the workflow using [Workflow](../workflow) -3. Start accessing your views once the workflow has started Replicating +
### Notes diff --git a/content/en/docs/19.0/reference/vreplication/migrate.md b/content/en/docs/19.0/reference/vreplication/migrate.md index b7ed3cb6a..8c0f6ad16 100644 --- a/content/en/docs/19.0/reference/vreplication/migrate.md +++ b/content/en/docs/19.0/reference/vreplication/migrate.md @@ -4,17 +4,10 @@ description: Move tables from an external cluster weight: 85 --- -### Command - -``` -Migrate -- -``` - - ### Description -Migrate is used to start and manage VReplication workflows for copying keyspaces and/or tables from a source Vitess cluster, to a target Vitess cluster. -This command is built off of [MoveTables](../movetables) but has been extended to work with independent source and target topology services. It should be +[`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) is used to start and manage VReplication workflows for copying keyspaces and/or tables from a source Vitess cluster, to a target Vitess cluster. +This command is built off of [`MoveTables`](../movetables) but has been extended to work with independent source and target topology services. It should be utilized when moving Keyspaces or Tables between two separate Vitess environments. Migrate is an advantageous strategy for large sharded environments for a few reasons: @@ -30,76 +23,60 @@ on working with external Vitess clusters. #### Differences Between Migrate and MoveTables -`Migrate` has separate semantics and behaviors from `MoveTables`: +[`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) has separate semantics and behaviors from [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/): -* `MoveTables` migrates data from one keyspace to another, within the same Vitess cluster; `Migrate` functions between two separated Vitess clusters. -* `MoveTables` erases the source data upon completion by default; Migrate keeps the source data intact. - * There are flags available in MoveTables to change the default behavior in regards to the source data. -* `MoveTables` sets up routing rules and reverse replication, allowing for rollback prior to completion. - * Switching read/write traffic is not meaningful in the case of `Migrate`, as the Source is in a different cluster. +* [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) migrates data from one keyspace to another, within the same Vitess cluster; [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) functions between two separate Vitess clusters. +* [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) erases the source data upon completion by default; Migrate keeps the source data intact. + * There are flags available in [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) to change the default behavior in regards to the source data. +* [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) sets up routing rules and reverse replication, allowing for rollback prior to completion. + * Switching read/write traffic is not meaningful in the case of [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/), as the Source is in a different cluster. * Switching traffic requires the Target to have the ability to create vreplication streams (in the `_vt` database) on the Source; this may not always be possible on production systems. -* Not all `MoveTables` options work with `Migrate`; for example [`Progress`](../progress) is unavailable with `Migrate`. - - -### Parameters - -#### action - -Migrate is an "umbrella" command. The `action` sub-command defines the operation on the workflow. -The only actions supported by Migrate are `Create`, `Complete` and `Cancel`. +* Not all [`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) sub-commands work with [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/); for example `SwitchTraffic` and `ReverseTraffic` are unavailable with [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/). -The `Create` action is also modified to accommodate the external mount. The proper syntax will be highlighted below: +## Command -``` -Migrate -- --source . Create -``` - -If needed, you can rename the keyspace while migrating, simply provide a different name for the target keyspace in the ``. - - -#### options - -Each `action` has additional options/parameters that can be used to modify its behavior. - -The options for the supported commands are the same as [MoveTables](../movetables), with the exception of `--reverse_replication` as setting -up the reverse vreplication streams requires modifying the source cluster's `_vt` sidecar database which we cannot do as that database is -specific to a single Vitess cluster and these streams belong to a different one (the target cluster). +Please see the [`Migrate` command reference](../../programs/vtctldclient/vtctldclient_migrate/) for a full list of sub-commands and their flags. -A common option to give if migrating all of the tables from a source keyspace is the `--all` option. - - -#### workflow identifier - -All workflows are identified by `targetKeyspace.workflow` where `targetKeyspace` is the name of the keyspace to which the tables are being moved. `workflow` is a name you assign to the Migrate workflow to identify it. - - - -### A Migrate Workflow lifecycle +### An Example Migrate Workflow Lifecycle {{< info >}} -NOTE: there is no reverse vreplication flow with `Migrate`. After the `Migrate Complete` command is given; no writes will be replicated between the Source and Target Vitess clusters. They are essentially two identical Vitess clusters running in two different environments. Once writing resumes on one of the clusters they will begin to drift apart. +NOTE: there is no reverse vreplication flow with [`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/). After the [`Migrate complete`](../../programs/vtctldclient/vtctldclient_migrate/vtctldclient_migrate_complete/) command is given; no writes will be replicated between the Source and Target Vitess clusters. They are essentially two identical Vitess clusters running in two different environments. Once writing resumes on one of the clusters they will begin to drift apart. {{< /info >}} 1. Mount the source Vitess cluster using [Mount](../mount).
-`Mount -- --type vitess --topo_type etcd2 --topo_server localhost:12379 --topo_root /vitess/global ext1` +`Mount register --name ext1 --topo-type etcd2 --topo-server localhost:12379 --topo-root /vitess/global` 1. Apply source vSchema to the Target's Keyspace.
-`ApplyVSchema -- --vschema_file commerceVschema.json commerce` -1. Initiate the migration using `Create`.
-`Migrate -- --all --source ext1.commerce Create commerce.wf` -1. Monitor the workflow using `Show`.
-`Workflow commerce.wf Show` +`ApplyVSchema --vschema-file commerceVschema.json commerce` +1. Initiate the migration using `create`.
+`Migrate --workflow import --target-keyspace customer create --source-keyspace commerce --mount-name ext1 --tablet-types replica` +1. Monitor the workflow using `show` and `status`.
+`Migrate --workflow import --target-keyspace customer show` +`Migrate --workflow import --target-keyspace customer status` 1. Confirm that data has been copied over correctly using [VDiff](../vdiff).
-`VDiff commerce.wf` 1. Stop the application from writing to the source Vitess cluster.
1. Confirm again the data has been copied over correctly using [VDiff](../vdiff).
-`VDiff commerce.wf` -1. Cleanup vreplication artifacts and source tables with `Complete`.
-`Migrate Complete commerce.wf` +1. Cleanup vreplication artifacts and source tables with `complete`.
+`Migrate --workflow import --target-keyspace customer complete` 1. Start the application pointed to the target Vitess Cluster. 1. Unmount the source cluster.
-`Mount -- --unmount ext1` +`Mount unregister --name ext1` + +### Parameters + +### Action +[`Migrate`](../../programs/vtctldclient/vtctldclient_migrate/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_migrate/#see-also) defines the operation on the workflow. + +### Options + +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_migrate/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_migrate/) for the full list of command options or flags. + +The options for the supported commands are the same as [MoveTables](../movetables), with the exception of `--enable-reverse-replication` as setting +up the reverse vreplication streams requires modifying the source cluster's `_vt` sidecar database which we cannot do as that database is +specific to a single Vitess cluster and these streams belong to a different one (the target cluster). + +A common option to give if migrating all of the tables from a source keyspace is the `--all-tables` option. ### Network Considerations @@ -107,25 +84,25 @@ For Migrate to function properly, you will need to ensure communication is possi * Target vtctld/vttablet (PRIMARY) processes must reach the Source topo service. * Target vtctld/vttablet (PRIMARY) processes must reach EACH source vttablet's grpc port. - * You can limit your source vttablet's to just the replicas by using the `--tablet_types` option when creating the migration. + * You can limit your source vttablet's to just the replicas by using the `--tablet-types` option when creating the migration. If you're migrating a keyspace from a production system, you may want to target a replica to reduce your load on the primary vttablets. This will also assist you in reducing the number of network considerations you need to make. ``` -Migrate -- --all --tablet_types REPLICA --source . Create +Migrate --workflow --target-keyspace create --source-keyspace --mount-name --tablet-types replica ``` -To verify the Migration you can also perform VDiff with the `--tablet_types` option: +To verify the Migration you can also perform VDiff with the `--tablet-types` option: ``` -VDiff -- --tablet_types REPLICA . +VDiff --workflow --target-keyspace create --tablet-types REPLICA ``` ### Troubleshooting Errors `Migrate` fails right away with error: -```sh +```shell E0224 23:51:45.312536 138 main.go:76] remote error: rpc error: code = Unknown desc = table table1 not found in vschema for keyspace sharded ```
Solution: @@ -136,7 +113,7 @@ E0224 23:51:45.312536 138 main.go:76] remote error: rpc error: code = Unknow `Migrate` fails right away with error: -```sh +```shell E0224 18:55:29.275019 578 main.go:76] remote error: rpc error: code = Unknown desc = node doesn't exist ``` @@ -149,7 +126,7 @@ E0224 18:55:29.275019 578 main.go:76] remote error: rpc error: code = Unknow After issuing `Migrate` command everything is stuck at 0% progress with errors found in target vttablet logs: -```sh +```shell I0223 20:13:36.825110 1 tablet_picker.go:146] No tablet found for streaming ``` @@ -157,9 +134,9 @@ I0223 20:13:36.825110 1 tablet_picker.go:146] No tablet found for streamin * Ensure there is networking communication between Target vttablets and Source vttablets * Ensure there is networking communication between Target vttablets and the Source topology service * Older versions of Vitess may be labeling vttablets as "master" instead of "primary" - you can resolve this problem by adjusting your `tablet_types`: + you can resolve this problem by adjusting your `tablet-types`: - Migrate -- --all --tablet_types "MASTER,REPLICA,RDONLY" ... + Migrate ... create --tablet-types "MASTER,REPLICA,RDONLY" ... --- diff --git a/content/en/docs/19.0/reference/vreplication/mount.md b/content/en/docs/19.0/reference/vreplication/mount.md index 86426aaf5..64b6c83fe 100644 --- a/content/en/docs/19.0/reference/vreplication/mount.md +++ b/content/en/docs/19.0/reference/vreplication/mount.md @@ -4,13 +4,6 @@ description: Link an external cluster to the current one weight: 90 --- -### Command - -``` -Mount -- [--type vitess] [--topo_type=etcd2|consul|zookeeper] [--topo_server=topo_url] - [--topo_root=root_topo_node> [--unmount] [--list] [--show] [] -``` - ### Description Mount is used to link external Vitess clusters to the current cluster. @@ -18,32 +11,9 @@ Mount is used to link external Vitess clusters to the current cluster. Mounting Vitess clusters requires the topology information of the external cluster to be specified. Used in conjunction with [the `Migrate` command](../migrate). {{< info >}} -No validation is performed when using the `Mount` command. You must ensure your values are correct, or you may get errors when initializing a migration. +No validation is performed when using the [`Mount`](../../programs/vtctldclient/vtctldclient_mount/) command. You must ensure your values are correct, or you may get errors when initializing a migration. {{< /info >}} +## Command -### Parameters - -#### cluster_name - -The name that will be used in VReplication workflows to refer to the mounted cluster. Required when mounting, unmounting or getting details of a cluster. - -#### unmount - -Unmount an already mounted cluster. Requires `cluster_name` to be specified. - -#### --show - -Show details of an already mounted cluster. Requires `cluster_name` to be specified. - -#### --list - -List all mounted clusters. - -### Topo Parameters - -##### --topo_type=[etcd2|consul|zookeeper] -##### --topo_server= -##### --topo_root= - -Mandatory (and only specified) while mounting a Vitess cluster. These should specify the topology parameters of the cluster being mounted. +Please see the [`Mount` command reference](../../programs/vtctldclient/vtctldclient_mount/) for a full list of sub-commands and their flags. diff --git a/content/en/docs/19.0/reference/vreplication/movetables.md b/content/en/docs/19.0/reference/vreplication/movetables.md index 865e73ed0..e0bd8ac32 100644 --- a/content/en/docs/19.0/reference/vreplication/movetables.md +++ b/content/en/docs/19.0/reference/vreplication/movetables.md @@ -9,77 +9,91 @@ aliases: ['/docs/reference/vreplication/v2/movetables/'] These workflows can have a significant impact on the source tablets (which are often in production) — especially when a PRIMARY tablet is used as a source. You can limit the impact on the source tablets using the [`--vreplication_copy_phase_max_*` vttablet flags](../flags/#vreplication_copy_phase_max_innodb_history_list_length) {{< /warning >}} +## Description + +[`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) is used to start and manage workflows to move one or more tables from an external database or an existing Vitess keyspace into a new Vitess keyspace. The target keyspace can be unsharded or sharded. + +[`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) is typically used for migrating data into Vitess or to implement vertical sharding. You might use the former when you first start using Vitess and the latter if you want to distribute your load across servers without sharding tables. + ## Command -``` -MoveTables -- -``` -or +Please see the [`MoveTables` command reference](../../programs/vtctldclient/vtctldclient_movetables/) for a full list of sub-commands and their flags. -``` -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] [--no-routing-rules] - -``` +## The Basic MoveTables Workflow Lifecycle -## Description +1. Initiate the migration using `create`
+`MoveTables --workflow --target-keyspace create --source-keyspace --tables ` +1. Monitor the workflow using `show` or `status`
+`MoveTables --workflow --target-keyspace show`
+`MoveTables --workflow --target-keyspace status`
+1. Confirm that data has been copied over correctly using [VDiff](../vdiff) +1. Cutover to the target keyspace with `switchtraffic`
+`MoveTables --workflow --target-keyspace switchtraffic` +1. Cleanup vreplication artifacts and source tables with `complete`
+`MoveTables --workflow --target-keyspace complete` + +## Common Use Cases for MoveTables + +### Adopting Vitess + +For those wanting to try out Vitess for the first time, `MoveTables` provides an easy way to route part of their workload to Vitess with the ability to migrate back at any time without any risk. You point a vttablet to your existing MySQL installation, spin up an unsharded Vitess cluster and use a `MoveTables` workflow to start serving some tables from Vitess. You can also go further and use a Reshard workflow to experiment with a sharded version of a part of your database. + +See this [user guide](../../../user-guides/configuration-advanced/unmanaged-tablet/#move-legacytable-to-the-commerce-keyspace) for detailed steps. -`MoveTables` is used to start and manage workflows to move one or more tables from an external database or an existing Vitess keyspace into a new Vitess keyspace. The target keyspace can be unsharded or sharded. +### Vertical Sharding + +For existing Vitess users you can easily move one or more tables to another keyspace, either for balancing load or as preparation for sharding your tables. -`MoveTables` is typically used for migrating data into Vitess or to implement vertical sharding. You might use the former when you first start using Vitess and the latter if you want to distribute your load across servers without sharding tables. +See this [user guide](../../../user-guides/migration/move-tables/) which describes how `MoveTables` works in the local example provided in the Vitess repo. ## Parameters -### action +### Action -`MoveTables` is an "umbrella" command. The `action` sub-command defines the operation on the workflow. -Action must be one of the following: `Create`, `Show`, `Progress`, `SwitchTraffic`, `ReverseTrafffic`, `Cancel`, or `Complete`. +[`MoveTables`](../../programs/vtctldclient/vtctldclient_movetables/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_movetables/#see-also) defines the operation on the workflow. #### Create
-`Create` sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow. +[`create`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_create/) sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow.
#### Show
-`Show` displays useful information about a workflow. (At this time the [Workflow](../workflow) Show command gives more information. This will be improved over time.) +[`show`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_show/) displays useful information about a workflow – including recent logs.
-#### Progress +#### Status
-`Progress` reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. +[`status`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_status/) (or `progress`) reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. It also shows the current state of traffic for the tables involved in the workflow. -It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `analyze table` to update the statistics if so desired. +It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `ANALYZE TABLE` to update the statistics if so desired.
#### SwitchTraffic
-`SwitchTraffic` switches traffic forward for the `tablet_types` specified. This replaces the previous `SwitchReads` and `SwitchWrites` commands with a single one. It is now possible to switch all traffic with just one command, and this is the default behavior. Also, you can now switch replica, rdonly and primary traffic in any order: earlier you needed to first `SwitchReads` (for replicas and rdonly tablets) first before `SwitchWrites`. +[`switchtraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_switchtraffic/) switches traffic forward for the `tablet-types` specified. You can switch all traffic with just one command, and this is the default behavior. Note that you can now switch replica, rdonly, and primary traffic in any order.
#### ReverseTraffic
-`ReverseTraffic` switches traffic in the reverse direction for the `tablet_types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet_types` specified. +[`reversetraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_reversetraffic/) switches traffic in the reverse direction for the `tablet-types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet-types` specified.
#### Cancel
-`Cancel` can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. `Cancel` can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from the vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and blacklisted tables from the topo and, by default, the target tables on the target keyspace -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)). +[`cancel`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_cancel/) can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. `cancel` can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from the vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and blacklisted tables from the topo and, by default, the target tables on the target keyspace +(see `--keep-data` and `--rename-tables`).
@@ -90,27 +104,16 @@ It is too expensive to get real-time row counts of tables, using _count(*)_, say This is a destructive command {{< /warning >}} -`Complete` is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and and blacklisted tables from the topo. By default, the source tables are also dropped on the target keyspace -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)). +[`complete`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_complete/) is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with routing rules and and blocklisted tables from the topo. By default, the source tables are also dropped on the target keyspace +(see `--keep-data` and `--rename-tables`). -### options +### Options -Each `action` has additional options/parameters that can be used to modify its behavior. +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_movetables/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_movetables/) for the full list of command options or flags. Below we will add additional information for a subset of key options. -`actions` are common to both `MoveTables` and `Reshard` workflows. Only the `create` action has different parameters, all other actions have common options and similar semantics. - -#### --all - -**optional** cannot specify `table_specs` if `--all` is specified -
- -Move all tables from the source keyspace. - -
- -#### --auto_start +#### --auto-start **optional**\ **default** true @@ -167,36 +170,6 @@ parallel index builds. This is logically similar to the -#### --drop_foreign_keys -**optional**\ -**default** false - -
- -If true, tables in the target keyspace will be created without any foreign keys that exist on the source. - -
- -#### --dry_run -**optional**\ -**default** false - -
- -For the `SwitchTraffic`, `ReverseTraffic`, and `Complete` actions, you can do a dry run where no actual steps are taken -but the command logs all the steps that would be taken. - -
- -#### --exclude -**optional** only applies if `--all` is specified - -
- -If moving all tables, specifies tables to be skipped. - -
- #### --initialize-target-sequences **optional**\ **default** false @@ -228,35 +201,15 @@ You will still need to take the manual step of [creating each backing sequence t in an unsharded keyspace of your choosing prior to the `SwitchTraffic` operation. {{< /info>}} -#### --keep_data +#### --max-replication-lag-allowed **optional**\ -**default** false - -
- -Usually, the target tables are deleted by `Cancel`. If this flag is used the target tables will not be deleted. - -
- -#### --keep_routing_rules -**optional**\ -**default** false - -
- -Usually, any routing rules created by the workflow in the source and target keyspace are removed by `Complete` or `Cancel`. If this flag is used the routing rules will be left in place. - -
- -#### --max_replication_lag_allowed -**optional**\ -**default** the value used for `--timeout` +**default** the value used for [`--timeout`](#--timeout)
While executing `SwitchTraffic` we ensure that the VReplication lag for the workflow is less than this duration, otherwise report an error and don't attempt the switch. The calculated VReplication lag is the estimated maximum lag across workflow streams between the last event seen at the source and the last event processed by the target (which would be a heartbeat event if we're fully caught up). Usually, when VReplication has caught up, this lag should be very small (under a second). -While switching write traffic, we temporarily make the source databases read-only, and wait for the targets to catchup. This means that the application can effectively be partially down for this cutover period as writes will pause or error out. While switching write traffic this flag can ensure that you only switch traffic if the current lag is low, thus limiting this period of write-unavailability and avoiding it entirely if we're not likely to catch up within the `--timeout` window. +While switching write traffic, we temporarily make the source databases read-only, and wait for the targets to catchup. This means that the application can effectively be partially down for this cutover period as writes will pause or error out. While switching write traffic this flag can ensure that you only switch traffic if the current lag is low, thus limiting this period of write-unavailability and avoiding it entirely if we're not likely to catch up within the [`--timeout`](#--timeout)) window. While switching read traffic this can also be used to set an approximate upper bound on how stale reads will be against the replica tablets when using `@replica` shard targeting. @@ -301,7 +254,7 @@ See https://github.com/vitessio/vitess/pull/13895 and https://github.com/vitessi and more details.
-#### --rename_tables +#### --rename-tables **optional**\ **default** false @@ -310,11 +263,11 @@ and more details. During `Complete` or `Cancel` operations, the tables are renamed instead of being deleted. Currently the new name is _<table_name>_old. We use the same renaming logic used by [`pt-online-schema-change`](https://docs.percona.com/percona-toolkit/pt-online-schema-change.html). -Such tables are automatically skipped by vreplication if they exist on the source. +Such tables are automatically skipped by VReplication if they exist on the source. -#### --reverse_replication +#### --enable-reverse-replication **optional**\ **default** true @@ -326,15 +279,7 @@ If set to false these reverse replication streams will not be created and you wi -#### --source -**mandatory** -
- -Name of existing keyspace that contains the tables to be moved. - -
- -#### --source_time_zone +#### --source-time-zone **optional**\ **default** "" @@ -356,7 +301,7 @@ setting this flag will not convert them. -#### --stop_after_copy +#### --stop-after-copy **optional** **default** false @@ -373,29 +318,7 @@ is small enough to start replicating, the workflow state will be set to Stopped. * If you just want a consistent snapshot of all the tables you can set this flag. The workflow will stop once the copy is done and you can then mark the workflow as `Complete`. -#### --tables -**optional** one of `--tables` or `--all` needs to be specified -
- -_Either_ - -* a comma-separated list of tables - * if target keyspace is unsharded OR - * if target keyspace is sharded AND the tables being moved are already defined in the target's vschema - - Example: `MoveTables -- --source commerce --tables 'customer,corder' Create customer.commerce2customer` - -_Or_ - -* the JSON table section of the vschema for associated tables - * if target keyspace is sharded AND - * tables being moved are not yet present in the target's vschema - - Example: `MoveTables -- --source commerce --tables '{"t1":{"column_vindexes": [{"column": "id1", "name": "hash"}]}, "t2":{"column_vindexes": [{"column": "id2", "name": "hash"}]}}' Create customer.commerce2customer` - -
- -#### --tablet_types +#### --tablet-types **optional**\ **default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ **string** @@ -419,43 +342,7 @@ the command will error out. For setups with high write qps you may need to incre -### workflow identifier - -
- -All workflows are identified by `targetKeyspace.workflow` where `targetKeyspace` is the name of the keyspace to which the tables are being moved. `workflow` is a name you assign to the `MoveTables` workflow to identify it. - -
- - -## The most basic MoveTables Workflow lifecycle - -1. Initiate the migration using `Create`
-`MoveTables -- --source= --tables= Create ` -1. Monitor the workflow using `Show` or `Progress`
-`MoveTables Show ` _*or*_
-`MoveTables Progress `
-1. Confirm that data has been copied over correctly using [VDiff](../vdiff) -1. Cutover to the target keyspace with `SwitchTraffic`
-`MoveTables SwitchTraffic ` -1. Cleanup vreplication artifacts and source tables with `Complete`
-`MoveTables Complete ` - - -## Common use cases for MoveTables - -### Adopting Vitess - -For those wanting to try out Vitess for the first time, `MoveTables` provides an easy way to route part of their workload to Vitess with the ability to migrate back at any time without any risk. You point a vttablet to your existing MySQL installation, spin up an unsharded Vitess cluster and use a `MoveTables` workflow to start serving some tables from Vitess. You can also go further and use a Reshard workflow to experiment with a sharded version of a part of your database. - -See this [user guide](../../../user-guides/configuration-advanced/unmanaged-tablet/#move-legacytable-to-the-commerce-keyspace) for detailed steps. - -### Vertical Sharding - -For existing Vitess users you can easily move one or more tables to another keyspace, either for balancing load or as preparation for sharding your tables. - -See this [user guide](../../../user-guides/migration/move-tables/) which describes how `MoveTables` works in the local example provided in the Vitess repo. - ### More Reading * [`MoveTables` in practice](../../../concepts/move-tables/) +* [`MoveTables` reference docs](../../programs/vtctldclient/vtctldclient_movetables/) diff --git a/content/en/docs/19.0/reference/vreplication/reshard.md b/content/en/docs/19.0/reference/vreplication/reshard.md index 0aa963eb5..9b4d7b5ee 100644 --- a/content/en/docs/19.0/reference/vreplication/reshard.md +++ b/content/en/docs/19.0/reference/vreplication/reshard.md @@ -9,75 +9,75 @@ aliases: ['/docs/reference/vreplication/v2/reshard/'] These workflows can have a significant impact on the source tablets (which are often in production) — especially when a PRIMARY tablet is used as a source. You can limit the impact on the source tablets using the [`--vreplication_copy_phase_max_*` vttablet flags](../flags/#vreplication_copy_phase_max_innodb_history_list_length) {{< /warning >}} -## Command - -``` -Reshard -- -``` +## Description -or +[`Reshard`](../../programs/vtctldclient/vtctldclient_reshard/) is used to create and manage workflows to horizontally shard an existing keyspace. The source keyspace can be unsharded or sharded. -``` -Reshard -- [--source_shards=] [--target_shards=] [--cells=] - [--tablet_types=] [--skip_schema_copy] [--auto_start] - [--stop_after_copy] [--on-ddl=] [--timeout=timeoutDuration] - [--reverse_replication] [--keep_data] [--keep_routing_rules] -``` +## Command -## Description +Please see the [`Reshard` command reference](../../programs/vtctldclient/vtctldclient_reshard/) for a full list of sub-commands and their flags. -`Reshard` is used to create and manage workflows to horizontally shard an existing keyspace. The source keyspace can be unsharded or sharded. +### The Basic Reshard Workflow Lifecycle +1. Initiate the migration using `create`
+`Reshard --workflow --target-keyspace create --source-shards --target-shards ` +1. Monitor the workflow using `show` or `status`
+`Reshard --workflow --target-keyspace show`
+`Reshard --workflow --target-keyspace status`
+1. Confirm that data has been copied over correctly using [VDiff](../vdiff) +1. Cutover to the target keyspace with `SwitchTraffic`
+`Reshard --workflow --target-keyspace switchtraffic` +1. Cleanup vreplication artifacts and source shards with `complete`
+`Reshard --workflow --target-keyspace complete` ## Parameters -### action +### Action -`Reshard` is an "umbrella" command. The `action` sub-command defines the operation on the workflow. -Action must be one of the following: `Create`, `Show`, `Progress`, `SwitchTraffic`, `ReverseTrafffic`, `Cancel`, or `Complete`. +[`Reshard`](../../programs/vtctldclient/vtctldclient_reshard/) is an "umbrella" command. The [`action` or sub-command](../../programs/vtctldclient/vtctldclient_reshard/#see-also) defines the operation on the workflow. #### Create
-`Create` sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow. +[`create`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_create/) sets up and creates a new workflow. The workflow name should not conflict with that of an existing workflow.
#### Show
-`Show` displays useful information about a workflow. (At this time the [Workflow](../workflow) Show command gives more information. This will be improved over time.) +[`show`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_show/) displays useful information about a workflow — including recent logs.
-#### Progress +#### Status
-`Progress` reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. +[`status`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_status/) (or `progress`) reports the progress of a workflow by showing the percentage of data copied across targets, if workflow is in copy state, and the replication lag between the target and the source once the copy phase is completed. It also shows the current state of traffic for the tables involved in the workflow. -It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `analyze table` to update the statistics if so desired. +It is too expensive to get real-time row counts of tables, using _count(*)_, say. So we use the statistics available in the `information_schema` to approximate copy progress. This data can be significantly off (up to 50-60%) depending on the utilization of the underlying mysql server resources. You can manually run `ANALYZE TABLE` to update the statistics if so desired.
#### SwitchTraffic
-`SwitchTraffic` switches traffic forward for the `tablet_types` specified. This replaces the previous `SwitchReads` and `SwitchWrites` commands with a single one. It is now possible to switch all traffic with just one command, and this is the default behavior. Also, you can now switch replica, rdonly and primary traffic in any order: earlier you needed to first `SwitchReads` (for replicas and rdonly tablets) first before `SwitchWrites`. +[`SwitchTraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_switchtraffic) switches traffic forward for the `tablet-types` specified. This replaces the previous `SwitchReads` and `SwitchWrites` commands with a single one. It is now possible to switch all traffic with just one command, and this is the default behavior. Also, you can now switch replica, rdonly and primary traffic in any order: earlier you needed to first `SwitchReads` (for replicas and rdonly tablets) first before `SwitchWrites`.
#### ReverseTraffic
-`ReverseTraffic` switches traffic in the reverse direction for the `tablet_types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet_types` specified. +[`ReverseTraffic`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_reversetraffic/) switches traffic in the reverse direction for the `tablet-types` specified. The traffic should have been previously switched forward using `SwitchTraffic` for the `cells` and `tablet_types` specified.
#### Cancel
-`Cancel` can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. Cancel can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the new target shards from the topo and, by default, the target tables on the target keyspace -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)). +[`cancel`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_cancel/) can be used if a workflow was created in error or was misconfigured and you prefer to create a new workflow instead of fixing this one. Cancel can only be called if no traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the new target shards from the topo and, by default, the target tables on the target keyspace +(see `--keep-data` and `--rename-tables`).
@@ -88,18 +88,16 @@ It is too expensive to get real-time row counts of tables, using _count(*)_, say This is a destructive command {{< /warning >}} -`Complete` is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the original source shards from the topo. By default, the source tables are also dropped on the source shards -(see [`--keep_data`](./#--keep_data) and [`--rename_tables`](#--rename_tables)) . +[`complete`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_complete/) is used after all traffic has been switched. It removes vreplication-related artifacts like rows from vreplication and copy_state tables in the sidecar `_vt` database along with the original source shards from the topo. By default, the source tables are also dropped on the source shards +(see `--keep-data` and `--rename-tables`) . ### options -Each `action` has additional options/parameters that can be used to modify its behavior. - -`actions` are common to both `MoveTables` and `Reshard` workflows. Only the `create` action has different parameters, all other actions have common options and similar semantics. +Each [`action` or sub-command](../../programs/vtctldclient/vtctldclient_reshard/#see-also) has additional options/parameters that can be used to modify its behavior. Please see the [command's reference docs](../../programs/vtctldclient/vtctldclient_reshard/) for the full list of command options or flags. `actions` are common to both `MoveTables` and `Reshard` workflows. Only the `create` action has different parameters, all other actions have common options and similar semantics. Below we will add additional information for a subset of key options. -#### --auto_start +#### --auto-start **optional**\ **default** true @@ -160,37 +158,18 @@ parallel index builds. This is logically similar to the -#### --drop_foreign_keys -**optional** -**default** false - -
- -If true, tables in the target keyspace will be created without any foreign keys that exist on the source. - -
- -#### --dry_run +#### --dry-run **optional**\ **default** false
-For the `SwitchTraffic`, `ReverseTraffic`, and `Complete` actions, you can do a dry run where no actual steps are taken +For the `SwitchTraffic`, `ReverseTraffic`, and `complete` actions, you can do a dry run where no actual steps are taken but the command logs all the steps that would be taken.
-#### --exclude -**optional** only applies if `--all` is specified - -
- -If moving all tables, specifies tables to be skipped. - -
- -#### --keep_data +#### --keep-data **optional**\ **default** false @@ -200,7 +179,7 @@ Usually, the target tables are deleted by `Cancel`. If this flag is used the tar -#### --keep_routing_rules +#### --keep-routing-rules **optional**\ **default** false @@ -210,7 +189,7 @@ Usually, any routing rules created by the workflow in the source and target keys -#### --max_replication_lag_allowed +#### --max-replication-lag-allowed **optional**\ **default** the value used for `--timeout` @@ -252,7 +231,7 @@ We caution against against using `EXEC` or `EXEC_IGNORE` for the following reaso -#### --reverse_replication +#### --enable-reverse-replication **optional**\ **default** true @@ -264,7 +243,7 @@ If set to false these reverse replication streams will not be created and you wi -#### --stop_after_copy +#### --stop-after-copy **optional** **default** false @@ -281,7 +260,7 @@ is small enough to start replicating, the workflow state will be set to Stopped. * If you just want a consistent snapshot of all the tables you can set this flag. The workflow will stop once the copy is done and you can then mark the workflow as `Complete`d -#### --source_shards +#### --source-shards **mandatory**
@@ -290,7 +269,7 @@ Comma separated shard names to reshard from.
-#### --tablet_types +#### --tablet-types **optional**\ **default** `--vreplication_tablet_type` parameter value for the tablet. `--vreplication_tablet_type` has the default value of "in_order:REPLICA,PRIMARY".\ **string** @@ -302,15 +281,6 @@ specified impacts [tablet selection](../tablet_selection/) for the workflow. -#### --target_shards -**mandatory** - -
- -Comma separated shard names to reshard to. - -
- #### --timeout **optional**\ **default** 30s @@ -322,26 +292,3 @@ catchup with the point where the writes were stopped. If the wait time is longer the command will error out. For setups with high write qps you may need to increase this value. - - -#### workflow identifier - -
- -All workflows are identified by `targetKeyspace.workflow` where `targetKeyspace` is the name of the keyspace to which the tables are being moved. `workflow` is a name you assign to the `Reshard` workflow to identify it. - -
- - -### The most basic Reshard Workflow lifecycle - -1. Initiate the migration using `Create`
-`Reshard -- --source_shards= --target_shards= Create ` -1. Monitor the workflow using `Show` or `Progress`
-`Reshard Show ` _*or*_
-`Reshard Progress `
-1. Confirm that data has been copied over correctly using [VDiff](../vdiff) -1. Cutover to the target keyspace with `SwitchTraffic`
-`Reshard SwitchTraffic ` -1. Cleanup vreplication artifacts and source shards with `Complete`
-`Reshard Complete ` diff --git a/content/en/docs/19.0/reference/vreplication/shardlevelmigrations.md b/content/en/docs/19.0/reference/vreplication/shardlevelmigrations.md index 43ee5f173..8dadec37d 100644 --- a/content/en/docs/19.0/reference/vreplication/shardlevelmigrations.md +++ b/content/en/docs/19.0/reference/vreplication/shardlevelmigrations.md @@ -5,21 +5,23 @@ weight: 120 aliases: ['/docs/reference/vreplication/v2/shardlevelmigrations/'] --- +## Description + {{< warning >}} -This feature is an **experimental** variant of the `MoveTables` command that -allows you to migrate individual shards from one keyspace to another. Please be +This feature is an **experimental** variant of the [`MoveTables`](../../../reference/programs/vtctldclient/vtctldclient_movetables/) command that +allows you to migrate individual shards from one keyspace to another. Please be sure to understand the limitations and requirements below. {{< /warning >}} -The full set of options for the `MoveTables` command [can be found here](../movetables/). +The full set of options for the `MoveTables` command [can be found here](../../../reference/programs/vtctldclient/vtctldclient_movetables/). The options and other aspects specific to shard level migrations will be covered here. ## Use Case -The [`Mount`](../mount/) and [`Migrate`](../migrate/) commands are the default -method provided for moving keyspaces from one Vitess cluster to another. This -method, however, only provides a one-time one-way cutover without the ability -to revert in the way that [`MoveTables`](../movetables/) does. +The [`Mount`](../mount/) and [`Migrate`](../migrate/) commands are the default +method provided for moving keyspaces from one Vitess cluster to another. This +method, however, only provides a one-time one-way cutover without the ability +to revert in the way that [`MoveTables`](../movetables/) does. This feature introduces the concept of partial keyspaces where some shards are served from a different keyspace during migration. This is useful for a specific @@ -28,27 +30,21 @@ being migrated to a new data center or provider. Migrating the entire cluster in one go using MoveTables could cause an unacceptable downtime due to the large number of primaries that need to be synced when writes are switched. -Supporting shard level migrations allows you to move very large keyspaces from one Vitess cluster -to another in an incremental way, cutting over traffic and reverting as needed -on a per-shard basis. When using this method, there is also a -new [`vtgate`](../../programs/vtgate/) `--enable-partial-keyspace-migration` -flag that enables support for shard level query routing so that individual -shards can be routed to one side of the migration or the other during the +Supporting shard level migrations allows you to move very large keyspaces from one Vitess cluster +to another in an incremental way, cutting over traffic and reverting as needed +on a per-shard basis. When using this method, there is also a +new [`vtgate`](../../programs/vtgate/) `--enable-partial-keyspace-migration` +flag that enables support for shard level query routing so that individual +shards can be routed to one side of the migration or the other during the migration period — *including when shard targeting is used*. -## Command - -``` -MoveTables --source_shards= -``` - -## Parameters +## Key Parameter -#### --source_shards +#### --source-shards **mandatory** (for shard level migrations)
-A list of one or more shards that you want to migrate from the source keyspace +A list of one or more shards that you want to migrate from the source keyspace to the target keyspace.
@@ -57,32 +53,32 @@ to the target keyspace. - The source and target keyspaces must have the exact same shard definitions - Query routing is all or nothing per shard, so you must *move all tables in the workflow -that you wish to migrate* and you would use [`SwitchTraffic --tablet_types=RDONLY,REPLICA,PRIMARY`](../switchtraffic/) +that you wish to migrate* and you would use [`SwitchTraffic --tablet-types=RDONLY,REPLICA,PRIMARY`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_switchtraffic/) to switch *read and write traffic* all at once for the shard(s) - - When the entire migration is complete, you cannot use the standard -[`Complete`](../complete/) workflow action and the final cleanup step requires manual work: - - The _reverse workflows should be [`Cancel`](../cancel/)ed. This will clean up + - When the entire migration is complete, you cannot use the standard +[`complete`](../../../reference/programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_complete/) workflow action and the final cleanup step requires manual work: + - The _reverse workflows should be [`cancel`](../../programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_cancel/)ed. This will clean up the both the global routing rules and the shard routing rules associated with the migration - - Note: [`Workflow delete`](../workflow/) does not clean up the shard routing rules + - Note: [`Workflow delete`](../../programs/vtctldclient/vtctldclient_workflow/vtctldclient_workflow_delete/) does not clean up the shard routing rules - You would need to perform any and all source side cleanup manually ## Related Vitess Flags -In order to support the shard level query routing during the migration, -the `--enable-partial-keyspace-migration` flag must be set for all of the +In order to support the shard level query routing during the migration, +the `--enable-partial-keyspace-migration` flag must be set for all of the [`vtgate`](../../programs/vtgate/) instances in the target Vitess cluster. {{< warning >}} -This routing support has a performance impact for all traffic and thus you -should only use this flag during the migration period and remove it once the +This routing support has a performance impact for all traffic and thus you +should only use this flag during the migration period and remove it once the migration is complete. {{< /warning >}} ## Related Commands -You can view the current shard level routing rules in place using -the [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) +You can view the current shard level routing rules in place using +the [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) [`vtctldclient`](../../programs/vtctldclient/) command and you can save updated routing rules using the -[`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyshardroutingrules/) +[`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyshardroutingrules/) command. diff --git a/content/en/docs/19.0/reference/vreplication/tablet_selection.md b/content/en/docs/19.0/reference/vreplication/tablet_selection.md index 3af152649..0107ee844 100644 --- a/content/en/docs/19.0/reference/vreplication/tablet_selection.md +++ b/content/en/docs/19.0/reference/vreplication/tablet_selection.md @@ -6,7 +6,7 @@ weight: 300 ### Introduction For both [VTGate VStreams and VTTablet VReplication streams](../../../concepts/vstream/) we must choose a tablet to serve the role of *source* (vstreamer). This -tablet selection is performed by the internal `TabletPicker` component. +tablet selection is performed by the internal `TabletPicker` component. {{< info >}} For VReplication streams a tablet also serves the role of *target* (vapplier). These, however, will always be the primary tablets in the target keyspace as we @@ -34,11 +34,11 @@ When using the [VTGate VStream API](../vstream/), you can override this local ce For VReplication, the server side default which determines the candidate types made available for potential selection as the source for a stream is set using the [`vttablet` `--vreplication_tablet_type` flag](../flags/#vreplication_tablet_type) (default value is `in_order:REPLICA,PRIMARY`). The target tablet will provide this value to the `TabletPicker` to determine the viable source tablet candidates. You can override this default on the client side using your -workflow command's `--tablet_types` flag. +workflow command's `--tablet-types` flag. -You can also specify an order of preference for the tablet types using the `in_order:` prefix in both the server and client flags. For example, -`--tablet_types "in_order:REPLICA,PRIMARY"` would cause a replica source tablet to be used whenever possible and a primary tablet would only be used as -a fallback in the event that there are no viable replica tablets available at the time. +You can also specify that the tablet types should be used in the order of preference as listed in the `--tablet-types` flag using the `--tablet-types-in-preference-order` flag. For example `--tablet-types "REPLICA,PRIMARY" --tablet-types-in-preference-order` would cause a replica source tablet to be used whenever possible +and a primary tablet would only be used as a fallback in the event that there are no viable replica tablets +available at the time. {{< info >}} When using the [VTGate VStream API](../vstream/) you should instead migrate to using the new `TabletOrder` field in the [VStreamFlags](https://pkg.go.dev/vitess.io/vitess/go/vt/proto/vtgate#VStreamFlags) request object as usage of the "in_order" string hint will eventually be deprecated and removed. diff --git a/content/en/docs/19.0/reference/vreplication/throttling.md b/content/en/docs/19.0/reference/vreplication/throttling.md index 9b352184e..4cf3a3cc4 100644 --- a/content/en/docs/19.0/reference/vreplication/throttling.md +++ b/content/en/docs/19.0/reference/vreplication/throttling.md @@ -29,4 +29,4 @@ As long as `check-self` fails — meaning that the replication lag is not within VReplication throttling is designed to give preference to normal production traffic while operating in the background. Production traffic will see less contention. The downside is that VReplication can take longer to operate. Under high load in production VReplication may altogether stall, to resume later when the load subsides. -Throttling will push back VReplication on replication lag. On systems where replication lag is normally high this can prevent VReplication from being able to operate normally. In such systems consider configuring `--throttle_threshold` to a value that agrees with your constraints. The default throttling threshold is at `1` second replication lag. +Throttling will push back VReplication on replication lag. On systems where replication lag is normally high this can prevent VReplication from being able to operate normally. In such systems consider configuring `--throttle-threshold` to a value that agrees with your constraints. The default throttling threshold is at `1` second replication lag. diff --git a/content/en/docs/19.0/reference/vreplication/vdiff.md b/content/en/docs/19.0/reference/vreplication/vdiff.md index a6baa1abd..f979faac5 100644 --- a/content/en/docs/19.0/reference/vreplication/vdiff.md +++ b/content/en/docs/19.0/reference/vreplication/vdiff.md @@ -5,49 +5,37 @@ weight: 40 aliases: ['/docs/reference/vreplication/vdiff2/'] --- -{{< info >}} -This is VDiff v2 which runs on `vttablets` as compared with the legacy [VDiff v1](../vdiffv1/) which runs on `vtctld`. -{{< /info >}} +### Description + +VDiff does a row by row comparison of all tables associated with the workflow, diffing the +source keyspace and the target keyspace and reporting counts of missing/extra/unmatched rows. + +It is highly recommended that you do this before you finalize a workflow with `SwitchTraffic` and `complete`. ### Command -VDiff takes different sub-commands or actions similar to how the [`MoveTables`](../movetables/)/[`Reshard`](../reshard/) commands work. The first argument -is the <keyspace.workflow> followed by an <action>. The following actions are supported: +VDiff takes different sub-commands or actions similar to how the [`MoveTables`](../movetables/)/[`Reshard`](../reshard/) commands work. Please see [the command's reference docs](../../../reference/programs/vtctldclient/vtctldclient_vdiff/) for additional info. The following sub-commands or actions are supported: #### Start a New VDiff -These take the same parameters as VDiff1 and schedule VDiff to run on the primary tablet of each target shard to verify the subset of data that will live on the given shard. Please note that if you do not specify a sub-command or action then `create` is assumed (this eases the transition from VDiff1 to VDiff2). If you do not pass a specific UUID then one will be generated. - -``` -VDiff -- [--source_cell=] [--target_cell=] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] - [--limit=] [--tables=
] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] - [--update-table-stats] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] - create [] -``` +The [`create` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_create/) schedules a VDiff to run on the primary tablet of each target shard to verify the subset of data that will live on the given shard. If you do not pass a specific UUID then one will be generated. Each scheduled VDiff has an associated UUID which is returned by the `create` action. You can use it to monitor progress. Example: -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer -VDiff bf9dfc5f-e5e6-11ec-823d-0aa62e50dd24 scheduled on target shards, use show to view progress +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer create +VDiff a35b0006-e6d9-416e-bea9-917795dc5bf3 scheduled on target shards, use show to view progress ``` #### Resume a Previous VDiff -The `resume` action allows you to resume a previously completed VDiff, picking up where it left off and comparing the records where the Primary Key column(s) are greater than the last record processed — with the progress and other status information saved when the run ends. This allows you to do approximate rolling or differential VDiffs (e.g. done after MoveTables finishes the initial copy phase and then again just before SwitchTraffic). - -``` -VDiff -- [--source_cell=] [--target_cell=] [--tablet_types=in_order:RDONLY,REPLICA,PRIMARY] - [--limit=] [--tables=
] [--format=json] [--auto-retry] [--verbose] [--max_extra_rows_to_compare=1000] - [--update-table-stats] [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] [--wait] [--wait-update-interval=1m] - resume -``` +The [`resume` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_resume/) allows you to resume a previously completed VDiff, picking up where it left off and comparing the records where the Primary Key column(s) are greater than the last record processed — with the progress and other status information saved when the run ends. This allows you to do approximate rolling or differential VDiffs (e.g. done after `MoveTables` finishes the initial copy phase and then again just before `SwitchTraffic`). Example: -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer resume 4c664dc2-eba9-11ec-9ef7-920702940ee0 +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer resume 4c664dc2-eba9-11ec-9ef7-920702940ee0 VDiff 4c664dc2-eba9-11ec-9ef7-920702940ee0 resumed on target shards, use show to view progress ``` @@ -57,14 +45,10 @@ We cannot guarantee accurate results for `resume` when different collations are #### Show Progress/Status of a VDiff -``` -VDiff -- show { | last | all} -``` +Using the [`show` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_show/) you can either `show` a specific UUID or use the `last` convenience shorthand to look at the most recently created VDiff. Example: -You can either `show` a specific UUID or use the `last` convenience shorthand to look at the most recently created VDiff. Example: - -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer show last +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer show last VDiff Summary for customer.commerce2customer (4c664dc2-eba9-11ec-9ef7-920702940ee0) State: completed @@ -75,7 +59,7 @@ CompletedAt: 2022-06-26 22:44:31 Use "--format=json" for more detailed output. -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer show last +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow commerce2customer show last { "Workflow": "commerce2customer", "Keyspace": "customer", @@ -88,7 +72,7 @@ $ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2 "CompletedAt": "2022-06-26 22:44:31" } -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.p1c2 show daf1f03a-03ed-11ed-9ab8-920702940ee0 +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow p1c2 show daf1f03a-03ed-11ed-9ab8-920702940ee0 { "Workflow": "p1c2", "Keyspace": "customer", @@ -114,22 +98,18 @@ So we instead use the statistics available in the to approximate the number of rows in each table when initializing a VDiff on the target primary tablet(s). This data is then used in the progress report and it can be significantly off (up to 50-60+%) depending on the utilization of the underlying MySQL server resources and -the age of the tables. You can manually run -[`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) to update the -statistics for the tables involved on the target primary tablet(s) before creating the -VDiff, if so desired, in order to improve the accuracy of the progress report. +the age of the tables. You can specify the `create` `--update-table-stats` flag so that VDiff +will run [`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) to update the +statistics for the tables involved on the target primary tablet(s) before executing the +VDiff in order to improve the accuracy of the progress report. {{< /info >}} #### Stopping a VDiff -``` -VDiff -- stop -``` +The [`stop` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_stop/) allows you to stop a running VDiff for any reason — for example, the load on the system(s) may be too high at the moment and you want to postpone the work until off hours. You can then later use the [`resume` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_resume/) to start the VDiff again from where it left off. Example: -The `stop` action allows you to stop a running VDiff for any reason — for example, the load on the system(s) may be too high at the moment and you want to postpone the work until off hours. You can then later use the `resume` action to start the VDiff again from where it left off. Example: - -``` -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer stop ad9bd40e-0c92-11ed-b568-920702940ee0 +```shell +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow commerce2customer stop ad9bd40e-0c92-11ed-b568-920702940ee0 { "UUID": "ad9bd40e-0c92-11ed-b568-920702940ee0", "Action": "stop", @@ -143,17 +123,13 @@ Attempting to `stop` a VDiff that is already completed is a no-op. #### Delete VDiff Results -``` -VDiff -- delete { | all} -``` +You use the [`delete` action](../../../reference/programs/vtctldclient/vtctldclient_vdiff/vtctldclient_vdiff_delete/) to either `delete` a specific UUID or use the `all` shorthand to delete all VDiffs created for the specified keyspace and workflow. Example: -You can either `delete` a specific UUID or use the `all` shorthand to delete all VDiffs created for the specified keyspace and workflow. Example: - -``` -$ vtctlclient --server=localhost:15999 VDiff -- customer.commerce2customer delete all -VDiff delete status is completed on target shards +```shell +$ vtctldclient --server=localhost:15999 VDiff --target-keyspace customer --workflow commerce2customer delete all +VDiff delete completed -$ vtctlclient --server=localhost:15999 VDiff -- --format=json customer.commerce2customer delete all +$ vtctldclient --server=localhost:15999 VDiff --format=json --target-keyspace customer --workflow commerce2customer delete all { "Action": "delete", "Status": "completed" @@ -165,145 +141,3 @@ Deletes are idempotent, so attempting to `delete` VDiff data that does not exist All VDiff data associated with a VReplication workflow is deleted when the workflow is deleted. {{< /info >}} - -### Description - -VDiff does a row by row comparison of all tables associated with the workflow, diffing the -source keyspace and the target keyspace and reporting counts of missing/extra/unmatched rows. - -It is highly recommended that you do this before you finalize a workflow with `SwitchTraffic`. - -### Parameters - -#### --source_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the source tables with the target tables -
- -#### --target_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the target tables with the source tables -
- -#### --tablet_types -**optional**\ -**default** in_order:RDONLY,REPLICA,PRIMARY - -
-A comma separated list of tablet types that are used while picking a tablet for sourcing data. -One or more from PRIMARY, REPLICA, RDONLY.

-
- -#### --filtered_replication_wait_time -**optional**\ -**default** 30s - -
-VDiff finds the current position of the source primary and then waits for the target replication to reach -that position for --filtered_replication_wait_time. If the target is much behind the source or if there is -a high write qps on the source then this time will need to be increased. -
- -#### --limit -**optional**\ -**default** 9223372036854775807 - -
-Maximum number of rows to run vdiff on (across all tables specified). -This limit is usually set while diffing a large table as a quick consistency check. -
- -#### --tables -**optional**\ -**default** all tables in the workflow - -
-A comma separated list of tables to run vdiff on. -
- -#### --format -**optional**\ -**default** text (unstructured text output) - -
-Only other format supported is JSON -
- -#### --auto-retry -**optional**\ -**default** true - -
-Automatically retry vdiffs that end with an error -
- -#### --verbose -**optional** - -
-Show verbose vdiff output in summaries -
- -#### --wait -**optional** - -
-When creating or resuming a vdiff, wait for the vdiff to finish before exiting. This will print the current status of the vdiff every --wait-update-interval. -
- -#### --wait-update-interval -**optional**\ -**default** 1m (1 minute) - -
-When waiting for a vdiff to finish, check and display the current status this often. -
- -#### --max_extra_rows_to_compare -**optional**\ -**default** 1000 - -
-Limits the number of extra rows on both the source and target that we will perform a second compare pass on to confirm that the rows are in fact different in content and not simply returned in a different order on the source and target (which can happen when there are collation differences, e.g. different MySQL versions). -
- -#### --debug_query -**optional** - -
-Adds the MySQL query to the report that can be used for further debugging -
- -#### --only_pks -**optional** - -
-When reporting missing rows, only show primary keys in the report. -
- -#### --update-table-stats -**optional** - -
-When specified, ANALYZE TABLE is run on each table in the target keyspace when initializing the VDiff. This helps to ensure that the table statistics are -up-to-date and thus that the progress reporting is as accurate as possible. -
- -{{< warning >}} -[`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) takes a table level READ lock on the table while it runs — effectively making the -table read-only. While [`ANALYZE TABLE`](https://dev.mysql.com/doc/refman/en/analyze-table.html) does not typically take very long to run it can still -potentially interfere with serving queries from the *target* keyspace. -{{< /warning >}} - -#### keyspace.workflow -**mandatory** - -
-Name of target keyspace and the associated workflow to run VDiff on. -
diff --git a/content/en/docs/19.0/reference/vreplication/vdiffv1.md b/content/en/docs/19.0/reference/vreplication/vdiffv1.md deleted file mode 100644 index 74cfaed9b..000000000 --- a/content/en/docs/19.0/reference/vreplication/vdiffv1.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: VDiff v1 -description: Compare the source and target in a workflow to ensure integrity -weight: 40 ---- - -{{< warning >}} -This is the legacy v1 VDiff command — it was deprecated in Vitess 18.0 and will be **removed** in 19.0. Please migrate all of your VDiff usage to the new [VDiff](../vdiff/) command before upgrading. -{{< /warning >}} - -### Command - -``` -VDiff -- --v1 [--source_cell=] [--target_cell=] [--tablet_types=primary,replica,rdonly] - [--limit=] [--tables=
] [--format=json] [--max_extra_rows_to_compare=1000] - [--filtered_replication_wait_time=30s] [--debug_query] [--only_pks] -``` - -### Description - -VDiff does a row by row comparison of all tables associated with the workflow, diffing the -source keyspace and the target keyspace and reporting counts of missing/extra/unmatched rows. - -It is highly recommended that you do this before you finalize a workflow with `SwitchTraffic`. - -### Parameters - -#### --source_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the source tables with the target tables -
- -#### --target_cell -**optional**\ -**default** all - -
-VDiff will choose a tablet from this cell to diff the target tables with the source tables -
- -#### --tablet_types -**optional**\ -**default** in_order:RDONLY,REPLICA,PRIMARY - -
-A comma separated list of tablet types that are used while picking a tablet for sourcing data. -One or more from PRIMARY, REPLICA, RDONLY. -
- -#### --filtered_replication_wait_time -**optional**\ -**default** 30s - -
-VDiff finds the current position of the source primary and then waits for the target replication to reach -that position for --filtered_replication_wait_time. If the target is much behind the source or if there is -a high write qps on the source then this time will need to be increased. -
- -#### --limit -**optional**\ -**default** 9223372036854775807 - -
-Maximum number of rows to run vdiff on (across all tables specified). -This limit is usually set while diffing a large table as a quick consistency check. -
- -#### --tables -**optional**\ -**default** all tables in the workflow - -
-A comma separated list of tables to run vdiff on. -
- - -#### --format -**optional**\ -**default** unstructured text output - -
-Only other format supported is json -
- -###### _Example:_ - -``` -[{ - "ProcessedRows": 5, - "MatchingRows": 5, - "MismatchedRows": 0, - "ExtraRowsSource": 0, - "ExtraRowsTarget": 0 -},{ - "ProcessedRows": 3, - "MatchingRows": 3, - "MismatchedRows": 0, - "ExtraRowsSource": 0, - "ExtraRowsTarget": 0 -}] -``` - -#### --max_extra_rows_to_compare -**optional**\ -**default** 1000 - -
-Limits the number of extra rows on both the source and target that we will perform a second compare pass on to confirm that the rows are in fact different in content and not simply returned in a different order on the source and target (which can happen when there are collation differences, e.g. different MySQL versions). -
- -#### --debug_query -**optional** - -
-Adds a MySQL query to the report that can be used for further debugging. -
- -#### --only_pks -**optional** - -
-When reporting missing rows, only show primary keys in the report. -
- -#### keyspace.workflow -**mandatory** - -
-Name of target keyspace and the associated workflow to run VDiff on. -
- -#### Example - -``` -$ vtctlclient VDiff customer.commerce2customer - -Summary for corder: {ProcessedRows:10 MatchingRows:10 MismatchedRows:0 ExtraRowsSource:0 ExtraRowsTarget:0} -Summary for customer: {ProcessedRows:11 MatchingRows:11 MismatchedRows:0 ExtraRowsSource:0 ExtraRowsTarget:0} -``` - -### Using VDiff With Huge Tables - -Currently VDiff runs within vtctld. Each VDiff will stream rows from all sources and targets and then compare them row by row after assembling the rows in order. Since there are no database transactions, VDiff will run much faster than the actual workflow. However, for huge tables (billions of rows or terabytes in size) this can take several hours or even days depending on the number of rows, row composition, server configurations and the topology of the cluster. If your sources and/or targets are across multiple cells, for example, this can slow down the VDiff considerably. - -Actual VDiff speeds are of course dependent on several factors in your cluster. But as a reference, we have seen VDiffs run as fast as 400mrph (million rows per hour) (~9B rows/day) for tables with short rows, or as slow as 60mrph (~1.5B rows/day), for tables with larger width and complex columns. - -You may need to use one or more of the following recommendations while running long VDiffs: - -* If VDiff takes more than an hour `vtctlclient` will hit grpc/http timeouts of 1 hour. In that case you can use `vtctl` (the bundled `vctlclient` + `vtctld`) instead. -* VDiff also synchronizes sources and targets to get consistent snapshots. If you have a high write QPS then you may encounter timeouts during the sync. Use higher values of `--filtered_replication_wait_time` to prevent that, for example `--filtered_replication_wait_time=4h`. -* If VDiff takes more than a day set the `--wait-time` parameter, which is the maximum time a vtctl command can run for, to a value comfortably higher than the expected run time, for example `--wait-time=168h`. -* You can follow the progress of the command by tailing the vtctld logs. VDiff logs progress every 10 million rows. This can also give you an early indication of how long it will run for, allowing you to increase your settings if needed. - -### Note - -* There is no throttling, so you might see an increased lag in the replica used as the source. -* VDiff is currently not resumable, so any timeouts or errors mean that you will need to rerun the entire VDiff again. -* VDiff runs one table at a time. - -{{< info >}} -**[VDiff v2](../vdiff/)**, which addresses these issues, is now production-ready and we recommend you use that instead. -{{< /info >}} diff --git a/content/en/docs/19.0/reference/vreplication/vreplication.md b/content/en/docs/19.0/reference/vreplication/vreplication.md index d127d20c2..04a1ae3c9 100644 --- a/content/en/docs/19.0/reference/vreplication/vreplication.md +++ b/content/en/docs/19.0/reference/vreplication/vreplication.md @@ -1,6 +1,6 @@ --- title: Overview -description: VReplication features, design and options in a nutshell +description: VReplication features, design, and options in a nutshell weight: 2 aliases: ['/docs/reference/features/vreplication/'] --- @@ -22,10 +22,8 @@ many features. It can be used for the following use cases: * **Realtime Rollups**: Use [`Materialize`](../materialize/) with aggregation expressions in which case Vitess will create a rolled up version of the source table which can be used for realtime analytics. -* **Lookup Vindexes**: Use [`CreateLookupVindex`](../../../user-guides/vschema-guide/backfill-vindexes/#createlookupvindex) to create a new - [`lookup vindex`](../../features/vindexes/#functional-and-lookup-vindex) - and backfill it from the existing data. -* **Online Schema Changes**: Use [`ddl_stragegy=vitess`](../../../user-guides/schema-changes/ddl-strategies/) for native [online non-blocking schema +* **Lookup Vindexes**: Use the [`LookupVindex`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/) command to create and backfill Lookup Vindexes. See the [`Creating a Lookup Vindex`](../../../user-guides/vschema-guide/backfill-vindexes/#createlookupvindex) section of the vschema user guide for example usage. +* **Online Schema Changes**: Use a [`ddl strategy of vitess`](../../../user-guides/schema-changes/ddl-strategies/) for native [online non-blocking schema migrations](../../../user-guides/schema-changes/managed-online-schema-changes/) that are trackable, cancellable, revertible, and retryable. All being safe to run in production due to intelligent throttling and resource management. @@ -199,7 +197,7 @@ will contain information about what it's been doing with each stream. ### Workflow Show The current status of the workflows and streams can also be fetched by using -the `vtctl` client [`Workflow Show`](../workflow/) command. +the `vtctldclient` [`Workflow Show`](../workflow/) command. ### Monitoring Variables diff --git a/content/en/docs/19.0/reference/vreplication/vreplicationexec.md b/content/en/docs/19.0/reference/vreplication/vreplicationexec.md deleted file mode 100644 index 577b645c1..000000000 --- a/content/en/docs/19.0/reference/vreplication/vreplicationexec.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: VReplicationExec -description: Low level command to run a query on vreplication related tables -weight: 70 ---- - -{{< warning >}} -This command was deprecated in v16.0 and will be removed in a future release. -{{< /warning >}} - -### Command - -``` -VReplicationExec -- [--json] -``` - -### Description - -The `VReplicationExec` command is used to view or manage vreplication streams. You would typically use one of the higher-level commands like the [WorkFlow](../workflow) command accomplish the same task. - -### Parameters - -#### --json -**optional** - -
-The output of the command is json formatted: to be readable by scripts. -
- -#### tablet_alias -**mandatory** - -
-Id of the target tablet on which to run the sql query, specified using the vitess tablet id format -<cell>-<uid> (see example below). -
- -#### query -**mandatory** - -
-SQL query which will be run: validations are done to ensure that queries can be run only against vreplication tables. -A limited set of queries are allowed. -
- -#### Example -``` -vtctlclient VReplicationExec 'zone1-100' 'select * from _vt.vreplication' -``` diff --git a/content/en/docs/19.0/reference/vreplication/workflow.md b/content/en/docs/19.0/reference/vreplication/workflow.md index 7cd2606fc..8a09c7529 100644 --- a/content/en/docs/19.0/reference/vreplication/workflow.md +++ b/content/en/docs/19.0/reference/vreplication/workflow.md @@ -1,82 +1,9 @@ --- title: Workflow -description: Wrapper on VReplication to perform common actions on a workflow +description: VReplication command to perform common actions on all types of workflows weight: 50 --- -### Command - -``` -Workflow -- [--dry-run] [--cells=] [--tablet-types=] [--on-ddl=] [.] - -``` - ### Description -Workflow is a convenience command for useful actions on a workflow that you can use instead of -actually specifying a query to VReplication. - -### Parameters - -#### --dry-run -**optional**\ -**default** false - -
-You can do a dry run where no actual action is taken but the command logs all the actions that would be taken by the Workflow. -
- -#### --cells -**optional** (Update action only)\ -**default** false - -
-You can update an existing workflow so that a different set of cells and/or cell aliases are used when choosing replication sources. -
- -#### --tablet-types -**optional** (Update action only)\ - -
-You can update an existing workflow so that different types of tablets are selected when choosing replication sources (see [tablet selection](../tablet_selection/)). -
- -#### --on-ddl -**optional** (Update action only)\ - -
-You can update an existing workflow so that DDL in the replication stream are handled differently (see [tablet selection](../vreplication/#handle-ddl)). -
- -#### keyspace.workflow -**mandatory** - -
-Name of target keyspace and the associated workflow to take action on. -{{< info >}} -The `listall` action is an exception to this rule as with that action you only specify the keyspace. -{{< /info >}} -
- -#### action -**mandatory** - -
-The Action is one of: - -* **stop**: sets the state of the workflow to Stopped: no further vreplication will happen until workflow is restarted -* **start**: restarts a Stopped workflow -* **update**: updates configuration parameters for this workflow in the `_vt.vreplication` table -* **delete**: removes the entries for this workflow in the `_vt.vreplication` table -* **show**: returns a JSON object with details about the associated shards and also with all the columns - from the `_vt.vreplication` table -* **listall**: returns a comma separated list of all *running* workflows in a keyspace -* **tags**: a comma-separated list of key:value pairs that are used to tag the workflow -
- -#### Example -``` -vtctlclient Workflow keyspace1.workflow1 stop -vtctlclient Workflow keyspace1.workflow1 show -vtctlclient Workflow keyspace1 listall -``` +Workflow is a convenience command for useful actions that are common to all VReplication workflows. Please see the command's [reference documentation](../../../reference/programs/vtctldclient/vtctldclient_workflow/) for additional information. diff --git a/content/en/docs/19.0/reference/vtctldclient-transition/command_diff.md b/content/en/docs/19.0/reference/vtctldclient-transition/command_diff.md index 3e274e166..bd5e38bb4 100644 --- a/content/en/docs/19.0/reference/vtctldclient-transition/command_diff.md +++ b/content/en/docs/19.0/reference/vtctldclient-transition/command_diff.md @@ -16,11 +16,12 @@ For stronger guarantees of compatibility, we highly encourage programming direct |-|-|-| | | N/A | [`ApplyShardRoutingRules`](../../programs/vtctldclient/vtctldclient_applyroutingrules/) | | | `CopySchemaShard` | (deleted) | -| | `CreateLookupVindex` | (not yet migrated) | +| | `CreateLookupVindex` | [`LookupVindex create`](../../programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) | | | `DeleteShard` | [`DeleteShards`](../../programs/vtctldclient/vtctldclient_deleteshards/) | | | `DeleteTablet` | [`DeleteTablets`](../../programs/vtctldclient/vtctldclient_deletetablets/) | +| | `ExecuteFetchAsAllPrivs` | (not yet migrated) | | | `ExecuteFetchAsDba` | [`ExecuteFetchAsDBA`](../../programs/vtctldclient/vtctldclient_executefetchasdba/) | -| | `ExternalizeVindex` | (not yet migrated) | +| | `ExternalizeVindex` | [`LookupVindex externalize`](../../programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_externalize/) | | | `ListBackups` | [`GetBackups`](../../programs/vtctldclient/vtctldclient_getbackups/) | | | N/A | [`GetFullStatus`](../../programs/vtctldclient/vtctldclient_getfullstatus/) | | | N/A | [`GetShardRoutingRules`](../../programs/vtctldclient/vtctldclient_getshardroutingrules/) | @@ -32,18 +33,15 @@ For stronger guarantees of compatibility, we highly encourage programming direct | | N/A | [`GetTopologyPath`](../../programs/vtctldclient/vtctldclient_gettopologypath/) | | | N/A | [`GetWorkflows`](../../programs/vtctldclient/vtctldclient_getworkflows/) | | | `InitShardPrimary` | (deleted) | -| | `Migrate` | (not yet migrated) | -| | `Mount` | (not yet migrated) | -| | `OnlineDDL` | (not yet migrated) | | | `Ping` | [`PingTablet`](../../programs/vtctldclient/vtctldclient_pingtablet/) | | | N/A | [`SetKeyspaceDurabilityPolicy`](../../programs/vtctldclient/vtctldclient_setkeyspacedurabilitypolicy/) | | | `SetReadOnly`, `SetReadWrite` | [`SetWritable`](../../programs/vtctldclient/vtctldclient_setwritable/) | | | `Sleep` | [`SleepTablet`](../../programs/vtctldclient/vtctldclient_sleeptablet/) | -| | `TopoCat`, `TopoCp` | (not yet migrated) | +| | `TopoCat` | [`GetTopologyPath`](../../programs/vtctldclient/vtctldclient_gettopologypath/) | +| | `TopoCp` | (not yet migrated) | | | `UpdateSrvKeyspacePartition` | (not yet migrated) | | | `UpdateTabletAddrs` | (deleted) | -| | `VReplicationExec` | (not yet migrated) | +| | `VReplicationExec` | (deleted) | | | `ValidatePermissionsKeyspace`, `ValidatePermissionsShard` | (deleted) | | | `VtctldCommand` | N/A | | | `WaitForFilteredReplication` | (deleted) | -| | `Workflow` | (deleted) | diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/createlookupvindex.md b/content/en/docs/19.0/user-guides/configuration-advanced/createlookupvindex.md index 9418102c8..3f6047c0a 100644 --- a/content/en/docs/19.0/user-guides/configuration-advanced/createlookupvindex.md +++ b/content/en/docs/19.0/user-guides/configuration-advanced/createlookupvindex.md @@ -1,5 +1,5 @@ --- -title: CreateLookupVindex +title: Creating a LookupVindex weight: 30 aliases: ['/docs/user-guides/createlookupvindex/'] --- @@ -10,53 +10,23 @@ an [Operator](../../../get-started/operator) or [local](../../../get-started/loc are at the point where you have the sharded keyspace called `customer` setup. {{< /info >}} -**CreateLookupVindex** is a [VReplication](../../../reference/vreplication/) workflow used to create **and** backfill -a [lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already +[`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) uses a [VReplication](../../../reference/vreplication/) workflow used to create **and** backfill +a [Lookup Vindex](../../../reference/features/vindexes/#lookup-vindex-types) automatically for a table that already exists, and may have a significant amount of data in it already. -Internally, the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) process uses +Internally, the [`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command uses VReplication for the backfill process, until the lookup Vindex is "in sync". Then the normal process for adding/deleting/updating rows in the lookup Vindex via the usual [transactional flow when updating the "owner" table for the Vindex](../../../reference/features/vindexes/#lookup-vindex-types) takes over. -In this guide, we will walk through the process of using the [`CreateLookupVindex`](../../../reference/vreplication/createlookupvindex/) -workflow, and give some insight into what happens underneath the covers. - -The `CreateLookupVindex` `vtctl` client command has the following syntax: - -```CreateLookupVindex -- [--cells=] [--continue_after_copy_with_owner=false] [--tablet_types=] ``` - -* ``: Use the lookup Vindex specified in `` along with - VReplication to populate/backfill the lookup Vindex from the source table. -* ``: The Vitess keyspace we are creating the lookup Vindex in. - The source table is expected to also be in this keyspace. -* `--tablet-types`: Provided to specify the tablet types - (e.g. `PRIMARY`, `REPLICA`, `RDONLY`) that are acceptable - as source tablets for the VReplication stream(s) that this command will - create. If not specified, the tablet type used will default to the value - of the [`vttablet --vreplication_tablet_type` flag](../../../reference/vreplication/flags/#vreplication_tablet_type) - value, which defaults to `in_order:REPLICA,PRIMARY`. -* `--cells`: By default VReplication streams, such as used by - `CreateLookupVindex`, will not cross cell boundaries. If you want the - VReplication streams to source their data from tablets in cells other - than the local cell, you can use the `--cells` option to specify a - comma-separated list of cells (see [VReplication tablet selection](../../../reference/vreplication/tablet_selection/)). -* `--continue_after_copy_with_owner`: By default, when an owner is provided in the ``, - the VReplication streams will stop after the backfill completes. Specify this flag if - you don't want this to happen. This is useful if, for example, the owner table is being - migrated from an unsharded keyspace to a sharded keyspace using - [`MoveTables`](../../../reference/vreplication/movetables/). - -The `` describes the lookup Vindex to be created, and details about -the table it is to be created against (on which column, etc.). However, -you do not have to specify details about the actual lookup table, Vitess -will create that automatically based on the type of the column you are -creating the Vindex column on, etc. +In this guide, we will walk through the process of using the [`LookupVindex create`](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command, and give some insight into what happens underneath the covers. + +You can see the details of the [`LookupVindex create` command](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) in the reference docs. In the context of the `customer` database that is part of the Vitess examples we started earlier, let's add some rows into the `customer.corder` table, and then -look at an example ``: +look at an example command: ```bash $ mysql -P 15306 -h 127.0.0.1 -u root --binary-as-hex=false -A @@ -217,45 +187,13 @@ Now let's say we want to add a lookup Vindex on the `sku` column. We can use a [`consistent_lookup` or `consistent_lookup_unique`](../../vschema-guide/unique-lookup/) Vindex type. In our example we will use `consistent_lookup_unique`. -Here is our example ``: - -```json -$ cat lookup_vindex.json -{ - "sharded": true, - "vindexes": { - "corder_lookup": { - "type": "consistent_lookup_unique", - "params": { - "table": "customer.corder_lookup", - "from": "sku", - "to": "keyspace_id" - }, - "owner": "corder" - } - }, - "tables": { - "corder": { - "column_vindexes": [ - { - "column": "sku", - "name": "corder_lookup" - } - ] - } - } -} -``` - -
- Note that as mentioned above, we do not have to tell Vitess about how to shard the actual backing table for the lookup Vindex or any schema to create as it will do it automatically. Now, let us -actually execute the `CreateLookupVindex` command: +actually execute the `LookupVindex create` command: ```bash -$ vtctlclient --server localhost:15999 CreateLookupVindex -- --tablet_types=RDONLY customer "$(cat lookup_vindex.json)" +vtctldclient --server localhost:15999 LookupVindex --name customer_region_lookup --table-keyspace main create --keyspace main --type consistent_lookup_unique --table-owner customer --table-owner-columns=id --tablet-types=PRIMARY ```
@@ -294,7 +232,7 @@ Now we can look what happened in greater detail: * Note that each primary tablet will start streams from each source tablet, for a total of 4 streams in this case. -Lets observe the VReplication streams that got created using the `vtctlclient Workflow show` command. +Lets observe the VReplication streams that got created using the `show` sub-command. {{< info >}} The created vreplication workflow will have a generated name of `_vdx`. @@ -302,170 +240,101 @@ So in our example here: `corder_lookup_vdx`. {{< /info >}} ```json -$ vtctlclient --server localhost:15999 Workflow customer.corder_lookup_vdx show +$ vtctldclient --server localhost:15999 LookupVindex --name customer_region_lookup --table-keyspace main show --include-logs=false { - "Workflow": "corder_lookup_vdx", - "SourceLocation": { - "Keyspace": "customer", - "Shards": [ - "-80", - "80-" - ] - }, - "TargetLocation": { - "Keyspace": "customer", - "Shards": [ - "-80", - "80-" - ] - }, - "MaxVReplicationLag": 78, - "MaxVReplicationTransactionLag": 1674479901, - "Frozen": false, - "ShardStatuses": { - "-80/zone1-0000000300": { - "PrimaryReplicationStatuses": [ - { - "Shard": "-80", - "Tablet": "zone1-0000000300", - "ID": 1, - "Bls": { - "keyspace": "customer", - "shard": "-80", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '-80') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "cb8ae288-9b1f-11ed-84ff-04ed332e05c2:1-117", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - }, - { - "Shard": "-80", - "Tablet": "zone1-0000000300", - "ID": 2, - "Bls": { - "keyspace": "customer", - "shard": "80-", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '-80') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "de051c70-9b1f-11ed-832d-04ed332e05c2:1-121", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - }, - "80-/zone1-0000000401": { - "PrimaryReplicationStatuses": [ - { - "Shard": "80-", - "Tablet": "zone1-0000000401", - "ID": 1, - "Bls": { - "keyspace": "customer", - "shard": "-80", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '80-') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "cb8ae288-9b1f-11ed-84ff-04ed332e05c2:1-117", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - }, - { - "Shard": "80-", - "Tablet": "zone1-0000000401", - "ID": 2, - "Bls": { - "keyspace": "customer", - "shard": "80-", - "filter": { - "rules": [ - { - "match": "corder_lookup", - "filter": "select sku as sku, keyspace_id() as keyspace_id from corder where in_keyrange(sku, 'customer.binary_md5', '80-') group by sku, keyspace_id" - } - ] - }, - "stop_after_copy": true - }, - "Pos": "de051c70-9b1f-11ed-832d-04ed332e05c2:1-123", - "StopPos": "", - "State": "Stopped", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1674479823, - "TimeHeartbeat": 0, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "Stopped after copy.", - "Tags": "", - "WorkflowType": "CreateLookupIndex", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" + "workflows": [ + { + "name": "customer_region_lookup", + "source": { + "keyspace": "main", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "main", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "0", + "shard_streams": { + "0/zone1-0000000100": { + "streams": [ + { + "id": "1", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 100 + }, + "binlog_source": { + "keyspace": "main", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "customer_region_lookup", + "filter": "select id as id, keyspace_id() as keyspace_id from customer where in_keyrange(id, 'main.xxhash', '-') group by id, keyspace_id", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "63c84d28-6888-11ee-93b0-81b2fbd12545:1-63", + "stop_position": "", + "state": "Running", + "db_name": "vt_main", + "transaction_timestamp": { + "seconds": "1697064644", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697064646", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [], + "log_fetch_error": "", + "tags": [], + "rows_copied": "0", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [], + "is_primary_serving": true + } + }, + "workflow_type": "CreateLookupIndex", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "0", + "defer_secondary_keys": false + } + ] } ``` @@ -530,7 +399,8 @@ the VReplication streams and also clear the `write_only` flag from the Vindex indicating that it is *not* backfilling anymore. ```bash -$ vtctlclient --server localhost:15999 ExternalizeVindex customer.corder_lookup +$ vtctldclient --server localhost:15999 LookupVindex --name customer_region_lookup --table-keyspace main externalize +LookupVindex customer_region_lookup has been externalized and the customer_region_lookup VReplication workflow has been deleted ```
diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/region-sharding.md b/content/en/docs/19.0/user-guides/configuration-advanced/region-sharding.md index 423dc2588..a505c4d99 100644 --- a/content/en/docs/19.0/user-guides/configuration-advanced/region-sharding.md +++ b/content/en/docs/19.0/user-guides/configuration-advanced/region-sharding.md @@ -356,7 +356,7 @@ Now that our new tablets are up, we can go ahead with the resharding: This script executes one command: ```bash -vtctlclient Reshard -- --source_shards '0' --target_shards '-40,40-80,80-c0,c0-' --tablet_types=PRIMARY Create main.main2regions +vtctldclient Reshard --target-keyspace main --workflow main2regions create --source-shards '0' --target-shards '-40,40-80,80-c0,c0-' --tablet-types=PRIMARY ```
@@ -372,10 +372,10 @@ We can check the correctness of the copy using the [`VDiff` command](../../../re and the `.` name we used for `Reshard` command above: ```bash -$ vtctlclient VDiff -- main.main2regions create +$ vtctldclient VDiff --target-keyspace main --workflow main2regions create VDiff 044e8da0-9ba4-11ed-8bc7-920702940ee0 scheduled on target shards, use show to view progress -$ vtctlclient VDiff -- --format=json main.main2regions show last +$ vtctldclient VDiff --format=json --target-keyspace main --workflow main2regions show last { "Workflow": "main2regions", "Keyspace": "main", @@ -391,18 +391,11 @@ $ vtctlclient VDiff -- --format=json main.main2regions show last
-We can take a look at the VReplication workflow's progress and status using the -[`Progress` action](../../../reference/vreplication/reshard/#progress): +We can take a look at the VReplication workflow's status using the +[`show` action](../../../reference/programs/vtctldclient/vtctldclient_reshard/vtctldclient_reshard_show/): ```bash -$ vtctlclient Reshard -- Progress main.main2regions - -The following vreplication streams exist for workflow main.main2regions: - -id=1 on 40-80/zone1-0000000300: Status: Running. VStream Lag: 0s. -id=1 on -40/zone1-0000000200: Status: Running. VStream Lag: 0s. -id=1 on 80-c0/zone1-0000000400: Status: Running. VStream Lag: 0s. -id=1 on c0-/zone1-0000000500: Status: Running. VStream Lag: 0s. +vtctldclient Reshard --target-keyspace main --workflow main2regions show ```
@@ -410,11 +403,6 @@ id=1 on c0-/zone1-0000000500: Status: Running. VStream Lag: 0s. We now have a running stream from the source tablet (`100`) to each of of our new `main` target shards that will keep the tables up-to-date with the source shard (`0`). -{{< info >}} -You can see greater detail about the VReplication workflow and the individual streams using the following command: -`vtctlclient Workflow -- main.main2regions show` -{{< /info >}} - ## Cutover Once the VReplication workflow's [copy phase](../../../reference/vreplication/internal/life-of-a-stream/#copy) is diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/resharding.md b/content/en/docs/19.0/user-guides/configuration-advanced/resharding.md index e79b15d41..0b23ddb33 100644 --- a/content/en/docs/19.0/user-guides/configuration-advanced/resharding.md +++ b/content/en/docs/19.0/user-guides/configuration-advanced/resharding.md @@ -225,7 +225,7 @@ Now we can start the [Reshard](../../../reference/vreplication/reshard/) operati will not block any read or write operations to your database: ```bash -vtctlclient Reshard -- --source_shards '0' --target_shards '-80,80-' Create customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust create --source-shards '0' --target-shards '-80,80-' ```
@@ -238,10 +238,10 @@ our [reference page for Reshard](../../../reference/vreplication/reshard). After the reshard is complete, we can use [VDiff](../../../reference/vreplication/vdiff) to check data integrity and ensure our source and target shards are consistent: ```bash -$ vtctlclient VDiff -- customer.cust2cust +$ vtctldclient VDiff --target-keyspace customer --workflow cust2cust create VDiff 60fa5738-9bad-11ed-b6de-920702940ee0 scheduled on target shards, use show to view progress -$ vtctlclient VDiff -- --format=json customer.cust2cust show last +$ vtctldclient VDiff --target-keyspace customer --workflow cust2cust show last { "Workflow": "cust2cust", "Keyspace": "customer", @@ -263,7 +263,7 @@ at the new location. By switching targeted read operations first, we are able to tablets are healthy and able to respond to requests: ```bash -vtctlclient Reshard -- --tablet_types=rdonly,replica SwitchTraffic customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust SwitchTraffic --tablet-types=rdonly,replica ``` ## Switch Writes and Primary Reads @@ -272,7 +272,7 @@ After the [`REPLICA` and `RDONLY` targeted reads](../../../reference/features/vs switched, and the health of the system has been verified, it's time to switch writes and all default traffic: ```bash -vtctlclient Reshard -- --tablet_types=primary SwitchTraffic customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust SwitchTraffic ``` ## Note @@ -329,9 +329,11 @@ After celebrating your second successful resharding, you are now ready to clean ### Using Operator ```bash -vtctlclient Reshard -- Complete customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust complete ``` + After the workflow has completed, you can go ahead and remove the shard that is no longer required - + ```bash kubectl apply -f 306_down_shard_0.yaml ``` @@ -339,7 +341,7 @@ kubectl apply -f 306_down_shard_0.yaml ### Using a Local Deployment ```bash -vtctlclient Reshard -- Complete customer.cust2cust +vtctldclient Reshard --target-keyspace customer --workflow cust2cust complete for i in 200 201 202; do CELL=zone1 TABLET_UID=$i ./scripts/vttablet-down.sh diff --git a/content/en/docs/19.0/user-guides/configuration-advanced/unmanaged-tablet.md b/content/en/docs/19.0/user-guides/configuration-advanced/unmanaged-tablet.md index af896cf22..1bbe25cb1 100644 --- a/content/en/docs/19.0/user-guides/configuration-advanced/unmanaged-tablet.md +++ b/content/en/docs/19.0/user-guides/configuration-advanced/unmanaged-tablet.md @@ -120,32 +120,42 @@ Empty set (0.01 sec) ## Move legacytable to the commerce keyspace Move the table: + ```bash -vtctlclient MoveTables -- --source legacy --tables 'legacytable' Create commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce create --source-keyspace legacy --tables 'legacytable' ``` +
+ Monitor the workflow: use `Show` or `Progress` + ```bash -vtctlclient MoveTables -- Show commerce.legacy2commerce -vtctlclient MoveTables -- Progress commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce show +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce status ``` -You can also use the [`Workflow show`](../../../reference/vreplication/workflow/) command to get the progress as it has much more info as well. +You can alternatively use the [`Workflow show`](../../../reference/programs/vtctldclient/vtctldclient_workflow/vtctldclient_workflow_show/) command to get the details as well. ```bash -vtctlclient Workflow commerce.legacy2commerce show +vtctldclient Workflow --keyspace commerce show --workflow legacy2commerce ``` +
Switch traffic: + ```bash -vtctlclient MoveTables -- --tablet_type=rdonly,replica SwitchTraffic commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce SwitchTraffic ``` +
Complete the `MoveTables`: + ```bash -vtctlclient MoveTables Complete commerce.legacy2commerce +vtctldclient MoveTables --target-keyspace commerce --workflow legacy2commerce complete ``` +
Verify that the table was moved: + ```bash source ../common/env.sh @@ -155,6 +165,7 @@ mysql commerce -e 'show tables' # verify my unmanaged mysql is running mysql -h 127.0.0.1 -P 5726 -umsandbox -pmsandbox legacy -e 'show tables' ``` +
Output: ```text @@ -174,4 +185,3 @@ $ # verify my unmanaged mysql is running $ mysql -h 127.0.0.1 -P 5726 -umsandbox -pmsandbox legacy -e 'show tables' mysql: [Warning] Using a password on the command line interface can be insecure. ``` - diff --git a/content/en/docs/19.0/user-guides/configuration-basic/vtctld.md b/content/en/docs/19.0/user-guides/configuration-basic/vtctld.md index 9ca987558..ff2c6b8d8 100644 --- a/content/en/docs/19.0/user-guides/configuration-basic/vtctld.md +++ b/content/en/docs/19.0/user-guides/configuration-basic/vtctld.md @@ -21,7 +21,7 @@ If the TopoServer is unreachable, or if the topo flags are incorrectly configure F0426 11:11:40.363545 14833 server.go:223] Failed to open topo server (etcd2,localhost:2379,/vitess/global): dial tcp 127.0.0.1:2379: connect: connection refused ``` -The `service_map` flag allows you to configure the grpc APIs that a Vitess server exposes as grpc. If grpc-vtctl is not specified as a service\_map for vtctld, you will not be able to access it using `vtctlclient`. +The `service_map` flag allows you to configure the grpc APIs that a Vitess server exposes as grpc. If grpc-vtctl is not specified as a service\_map for vtctld, you will not be able to access it using `vtctldclient`. Similarly, if grpc-vtctld is not specified as a service\_map for vtctld, you will not be able to access it using `vtctldclient`. vtctld is usually not very resource intensive. But you may need to provision more if you plan to run the `VDiff` command. This functionality will soon be moved to vttablet. diff --git a/content/en/docs/19.0/user-guides/migration/materialize.md b/content/en/docs/19.0/user-guides/migration/materialize.md index eaeaa7f68..88fda7149 100644 --- a/content/en/docs/19.0/user-guides/migration/materialize.md +++ b/content/en/docs/19.0/user-guides/migration/materialize.md @@ -25,13 +25,13 @@ different ways for the purposes of avoiding expensive cross-shard queries. `Mate allow for you to pre-create the schema and [VSchema](../../../concepts/vschema/) for the copied table, allowing you to for example maintain a copy of a table without some of the source table's MySQL indexes. -All of the command options and parameters are listed in our [reference page for the `Materialize` command](../../../reference/vreplication/materialize). In our examples to follow we will only touch on what is possible using +All of the command options and parameters are listed in our [reference page for the `Materialize` command](../../../reference/programs/vtctldclient/vtctldclient_materialize/). In our examples to follow we will only touch on what is possible using [`Materialize`](../../../reference/vreplication/materialize). Let's start by loading some sample data: ```bash -$ mysql < ../common/insert_commerce_data.sql +mysql < ../common/insert_commerce_data.sql ``` We can look at what we just inserted: @@ -81,7 +81,7 @@ for the `corder_view_redacted` copy we will use the opportunity to drop or redac In the case where we are using `Materialize` to copy tables *between or across keyspaces* we can use the `"create_ddl": "copy"` option in the -[`Materialize` `json_spec` `table_settings`](../../../reference/vreplication/materialize/#json-spec-details) +[`Materialize --table-settings`](../../../reference/vreplication/materialize/#--table-settings) flag to create the target table for us (similar to what `MoveTables` does). However, in our case where we are using `Materialize` within a single keyspace (`commerce`) so we need to manually create the target tables. Let's go ahead and do that: @@ -112,7 +112,8 @@ We will run two `Materialize` operations, one for each copy/view of the `corder` combine these two operations into a single `Materialize` operation, but we will keep them separate for clarity. ```bash -$ vtctlclient Materialize -- '{"workflow": "copy_corder_1", "source_keyspace": "commerce", "target_keyspace": "commerce", "table_settings": [{"target_table": "corder_view", "source_expression": "select * from corder"}]}' +$ vtctldclient Materialize --workflow copy_corder_1 --target-keyspace commerce create --source-keyspace commerce --table-settings '[{"target_table": "corder_view", "source_expression": "select * from corder"}]' +Materialization workflow copy_corder_1 successfully created in the commerce keyspace. Use show to view the status. ``` Now, we should see the materialized view table `corder_view`: @@ -156,110 +157,157 @@ or removing rows in a fashion that would break the "replication" part of the VRe ## Viewing the Workflow While in Progress -While we can also see and manipulate the underlying VReplication streams created by `Materialize` there are -[Workflow](../../../reference/vreplication/workflow) commands to `show`, `stop`, `start` and `delete` the +[`Materialize`](../../../reference/programs/vtctldclient/vtctldclient_materialize/#see-also) has actions or sub-commands to `show`, `stop`, `start` and `cancel` the `Materialize` workflow. For example, once we have started the `Materialize` command above, we can observe the -status of the VReplication workflow using the [Workflow](../../../reference/vreplication/workflow) command: +status of the VReplication workflow using the [`show`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_show/) sub-command: ```json -$ vtctlclient Workflow -- commerce listall -Following workflow(s) found in keyspace commerce: copy_corder_1 +$ vtctldclient Workflow --keyspace commerce list +[ + "copy_corder_1" +] -$ vtctlclient Workflow -- commerce.copy_corder_1 show +$ vtctldclient Materialize --target-keyspace commerce show --workflow copy_corder_1 --include-logs=false { - "Workflow": "copy_corder_1", - "SourceLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "TargetLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "MaxVReplicationLag": 1, - "MaxVReplicationTransactionLag": 1, - "Frozen": false, - "ShardStatuses": { - "0/zone1-0000000101": { - "PrimaryReplicationStatuses": [ - { - "Shard": "0", - "Tablet": "zone1-0000000101", - "ID": 1, - "Bls": { - "keyspace": "commerce", - "shard": "0", - "filter": { - "rules": [ - { - "match": "corder_view", - "filter": "select * from corder" - } - ] - } - }, - "Pos": "4c89eede-8c68-11ed-a40a-6f1a36c22987:1-1070", - "StopPos": "", - "State": "Running", - "DBName": "vt_commerce", - "TransactionTimestamp": 1672862991, - "TimeUpdated": 1672862991, - "TimeHeartbeat": 1672862991, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "", - "Tags": "", - "WorkflowType": "Materialize", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" + "workflows": [ + { + "name": "copy_corder_1", + "source": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "0", + "shard_streams": { + "0/zone1-0000000101": { + "streams": [ + { + "id": "1", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "binlog_source": { + "keyspace": "commerce", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "corder_view", + "filter": "select * from corder", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "fd3ac16e-6880-11ee-be79-13f9a85fe24e:1-241", + "stop_position": "", + "state": "Running", + "db_name": "vt_commerce", + "transaction_timestamp": { + "seconds": "1697061520", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697061521", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [], + "log_fetch_error": "", + "tags": [], + "rows_copied": "5", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [], + "is_primary_serving": true + } + }, + "workflow_type": "Materialize", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "0", + "defer_secondary_keys": false + } + ] } ``` -We can now also use the `Workflow` `stop`/`start` actions to temporarily stop the materialization workflow. For +We can now also use the [`stop`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_stop/) and [`start`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_start/) actions to temporarily stop the materialization workflow. For example: ```bash -$ vtctlclient Workflow -- commerce.copy_corder_1 stop -+------------------+--------------+ -| Tablet | RowsAffected | -+------------------+--------------+ -| zone1-0000000100 | 1 | -+------------------+--------------+ +$ vtctldclient Materialize --target-keyspace commerce stop --workflow copy_corder_1 +{ + "summary": "Successfully updated the copy_corder_1 workflow on (1) target primary tablets in the commerce keyspace", + "details": [ + { + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "changed": true + } + ] +} ``` -And `start` to start the workflow again and continue with the materialization: +And [`start`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_start/) to start the workflow again and continue with the materialization: ```bash -$ vtctlclient Workflow -- commerce.copy_corder_1 start -+------------------+--------------+ -| Tablet | RowsAffected | -+------------------+--------------+ -| zone1-0000000100 | 1 | -+------------------+--------------+ +$ vtctldclient Materialize --target-keyspace commerce start --workflow copy_corder_1 +{ + "summary": "Successfully updated the copy_corder_1 workflow on (1) target primary tablets in the commerce keyspace", + "details": [ + { + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "changed": true + } + ] +} ``` If at some point, when the initial copy is done and we have fully materialized all of the (initial) data, we do not -want to continue replicating changes from the source, we can `delete` the workflow: +want to continue replicating changes from the source, we can [`cancel`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_cancel/) the workflow: ```bash -$ vtctlclient Workflow -- commerce.copy_corder_1 delete -+------------------+--------------+ -| Tablet | RowsAffected | -+------------------+--------------+ -| zone1-0000000100 | 1 | -+------------------+--------------+ +$ vtctldclient Materialize --target-keyspace commerce cancel --workflow copy_corder_1 +Successfully cancelled the copy_corder_1 workflow in the commerce keyspace ``` Note that deleting the workflow will *not* `DROP` the target table of the `Materialize` workflow or `DELETE` any of the @@ -272,7 +320,8 @@ Now we can perform the materialization of the `corder_view_redacted` table we cr this table without a price column so we will not be copying that column in our query either: ```bash -$ vtctlclient Materialize -- '{"workflow": "copy_corder_2", "source_keyspace": "commerce", "target_keyspace": "commerce", "table_settings": [{"target_table": "corder_view_redacted", "source_expression": "select order_id, customer_id, sku from corder"}]}' +$ vtctldclient Materialize --target-keyspace commerce create --workflow copy_corder_2 --source-keyspace commerce --table-settings '[{"target_table": "corder_view_redacted", "source_expression": "select order_id, customer_id, sku from corder"}]' +Materialization workflow copy_corder_2 successfully created in the commerce keyspace. Use show to view the status. ``` Again, looking the target table will show all the source table rows, this time without the `price` column: @@ -317,7 +366,7 @@ target keyspace's primary tablet, e.g. in this case: ```bash # We want to connect directly to the primary mysqld -$ SOCKETPATH=${VTDATAROOT}/$(vtctlclient ListAllTablets -- --keyspace=commerce --tablet_type=primary | awk '$1 sub(/zone1-/, "vt_") {print $1}') +$ SOCKETPATH=${VTDATAROOT}/$(vtctldclient GetTablets --keyspace=commerce --tablet-type=primary | awk '$1 sub(/zone1-/, "vt_") {print $1}') $ mysql -u root -h localhost --socket=${SOCKETPATH}/mysql.sock --binary-as-hex=false -e "select * from _vt.vreplication\G" *************************** 1. row *************************** @@ -346,8 +395,7 @@ transaction_timestamp: 1672865502 ## Cleanup -As seen earlier, you can easily use the [`Workflow delete`](../../../reference/vreplication/workflow) command to -clean up a `Materialize` workflow when it's no longer needed. +As seen earlier, you can easily use the [`Workflow delete`](../../../reference/programs/vtctldclient/vtctldclient_workflow/vtctldclient_workflow_delete/) or [`Materialize cancel`](../../../reference/programs/vtctldclient/vtctldclient_materialize/vtctldclient_materialize_cancel/) command to clean up a `Materialize` workflow when it's no longer needed. {{< info >}} While this deletes the `Materialize` VReplication stream, the actual source and target tables are left unchanged diff --git a/content/en/docs/19.0/user-guides/migration/move-tables.md b/content/en/docs/19.0/user-guides/migration/move-tables.md index 26bb24ae9..331646dfd 100644 --- a/content/en/docs/19.0/user-guides/migration/move-tables.md +++ b/content/en/docs/19.0/user-guides/migration/move-tables.md @@ -153,7 +153,7 @@ In this step we will create the `MoveTables` workflow, which copies the tables f `customer`. This operation does not block any database activity; the `MoveTables` operation is performed online: ```bash -$ vtctlclient MoveTables -- --source commerce --tables 'customer,corder' Create customer.commerce2customer +vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer create --source-keyspace commerce --tables 'customer,corder' ``` A few things to note: @@ -278,82 +278,142 @@ be copied faithfully to the new copy of these tables in the `customer` keyspace. ## Monitoring Progress (Optional) -In this example there are only a few rows in the tables, so the `MoveTables` operation only takes seconds. If the tables were large, however, you may need to monitor the progress of the operation. You can get a basic summary of the progress using the [`Progress`](../../../reference/vreplication/movetables/#progress) action: +In this example there are only a few rows in the tables, so the `MoveTables` operation only takes seconds. If the tables were large, however, you may need to monitor the progress of the operation. You can get a basic summary of the progress using the [`status`](../../../reference/vreplication/movetables/#status) action: ```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 2, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51", + "status": "Running", + "info": "VStream Lag: 0s" + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` -You can get detailed status and progress information using the -[`Workflow show`](../../../reference/vreplication/workflow/) command: +You can get more detailed status information using the +[`show`](../../../reference/programs/vtctldclient/vtctldclient_movetables/vtctldclient_movetables_show/) sub-command: + ```json -$ vtctlclient Workflow customer.commerce2customer show +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer show --include-logs=false { - "Workflow": "commerce2customer", - "SourceLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "TargetLocation": { - "Keyspace": "customer", - "Shards": [ - "0" - ] - }, - "MaxVReplicationLag": 1, - "MaxVReplicationTransactionLag": 1, - "Frozen": false, - "ShardStatuses": { - "0/zone1-0000000201": { - "PrimaryReplicationStatuses": [ - { - "Shard": "0", - "Tablet": "zone1-0000000201", - "ID": 1, - "Bls": { - "keyspace": "commerce", - "shard": "0", - "filter": { - "rules": [ - { - "match": "customer", - "filter": "select * from customer" - }, - { - "match": "corder", - "filter": "select * from corder" - } - ] - } - }, - "Pos": "7e765c5c-8c59-11ed-9d2e-7c501ea4de6a:1-83", - "StopPos": "", - "State": "Running", - "DBName": "vt_customer", - "TransactionTimestamp": 0, - "TimeUpdated": 1672857697, - "TimeHeartbeat": 1672857697, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "", - "Tags": "", - "WorkflowType": "MoveTables", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": null, - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" + "workflows": [ + { + "name": "commerce2customer", + "source": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "customer", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "1", + "shard_streams": { + "0/zone1-0000000200": { + "streams": [ + { + "id": "2", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "binlog_source": { + "keyspace": "commerce", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "customer", + "filter": "select * from customer", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + }, + { + "match": "corder", + "filter": "select * from corder", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51", + "stop_position": "", + "state": "Running", + "db_name": "vt_customer", + "transaction_timestamp": { + "seconds": "0", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697060227", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [], + "log_fetch_error": "", + "tags": [], + "rows_copied": "0", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [], + "is_primary_serving": true + } + }, + "workflow_type": "MoveTables", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "1", + "defer_secondary_keys": false + } + ] } ``` @@ -363,12 +423,10 @@ We can use [`VDiff`](../../../reference/vreplication/vdiff/) to perform a logica to confirm that they are fully in sync: ```bash -$ vtctlclient VDiff -- --v2 customer.commerce2customer create -{ - "UUID": "d050262e-8c5f-11ed-ac72-920702940ee0" -} +$ vtctldclient VDiff --target-keyspace customer --workflow commerce2customer create +VDiff bc74b91b-2ee8-4869-bc39-4740ce445e20 scheduled on target shards, use show to view progress -$ vtctlclient VDiff -- --v2 --format=json --verbose customer.commerce2customer show last +$ vtctldclient VDiff --format=json --target-keyspace customer --workflow commerce2customer show last --verbose { "Workflow": "commerce2customer", "Keyspace": "customer", @@ -435,9 +493,9 @@ traffic from the old `commerce` keyspace to the `customer` keyspace for the tabl tables will continue to route to the `commerce` keyspace. ```bash -$ vtctlclient MoveTables -- SwitchTraffic customer.commerce2customer - +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer SwitchTraffic SwitchTraffic was successful for workflow customer.commerce2customer + Start State: Reads Not Switched. Writes Not Switched Current State: All Reads Switched. Writes Switched ``` @@ -560,10 +618,9 @@ $ vtctldclient GetRoutingRules ## Reverting the Switch (Optional) As part of the `SwitchTraffic` operation, Vitess will automatically setup a reverse VReplication workflow (unless -you supply the [`--reverse_replication false` flag](../../../reference/vreplication/movetables/#--reverse_replication)) -to copy changes now applied to the moved tables in the target keyspace — `customer` and `corder` in the -`customer` keyspace — back to the original source tables in the source `commerce` keyspace. This allows us to -reverse or revert the cutover using the [`ReverseTraffic`](../../../reference/vreplication/movetables/#reversetraffic) +you supply the `--enable-reverse-replication=false` flag) to copy changes now applied to the moved tables in the +target keyspace — `customer` and `corder` in the `customer` keyspace — back to the original source tables in the +source `commerce` keyspace. This allows us to reverse or revert the cutover using the [`ReverseTraffic`](../../../reference/vreplication/movetables/#reversetraffic) action, without data loss, even after we have started writing to the new `customer` keyspace. Note that the workflow for this reverse workflow is created in the original source keyspace and given the name of the original workflow with `_reverse` appended. So in our example where the `MoveTables` workflow was in the `customer` keyspace @@ -572,78 +629,155 @@ and called `commerce2customer`, the reverse workflow is in the `commerce` keyspa [`Workflow show`](../../../reference/vreplication/workflow/) command: ```json -$ vtctlclient Workflow commerce.commerce2customer_reverse show +$ vtctldclient Workflow --keyspace commerce show --workflow commerce2customer_reverse { - "Workflow": "commerce2customer_reverse", - "SourceLocation": { - "Keyspace": "customer", - "Shards": [ - "0" - ] - }, - "TargetLocation": { - "Keyspace": "commerce", - "Shards": [ - "0" - ] - }, - "MaxVReplicationLag": 1, - "MaxVReplicationTransactionLag": 1, - "Frozen": false, - "ShardStatuses": { - "0/zone1-0000000100": { - "PrimaryReplicationStatuses": [ - { - "Shard": "0", - "Tablet": "zone1-0000000100", - "ID": 1, - "Bls": { - "keyspace": "customer", - "shard": "0", - "filter": { - "rules": [ - { - "match": "customer", - "filter": "select * from `customer`" - }, - { - "match": "corder", - "filter": "select * from `corder`" - } - ] - } - }, - "Pos": "9fb1be70-8c59-11ed-9ef5-c05f9df6f7f3:1-2361", - "StopPos": "", - "State": "Running", - "DBName": "vt_commerce", - "TransactionTimestamp": 1672858428, - "TimeUpdated": 1672859207, - "TimeHeartbeat": 1672859207, - "TimeThrottled": 0, - "ComponentThrottled": "", - "Message": "", - "Tags": "", - "WorkflowType": "MoveTables", - "WorkflowSubType": "None", - "CopyState": null - } - ], - "TabletControls": [ - { - "tablet_type": 1, - "denied_tables": [ - "corder", - "customer" - ] - } - ], - "PrimaryIsServing": true - } - }, - "SourceTimeZone": "", - "TargetTimeZone": "" -} + "workflows": [ + { + "name": "commerce2customer_reverse", + "source": { + "keyspace": "customer", + "shards": [ + "0" + ] + }, + "target": { + "keyspace": "commerce", + "shards": [ + "0" + ] + }, + "max_v_replication_lag": "1", + "shard_streams": { + "0/zone1-0000000101": { + "streams": [ + { + "id": "1", + "shard": "0", + "tablet": { + "cell": "zone1", + "uid": 101 + }, + "binlog_source": { + "keyspace": "customer", + "shard": "0", + "tablet_type": "UNKNOWN", + "key_range": null, + "tables": [], + "filter": { + "rules": [ + { + "match": "customer", + "filter": "select * from `customer`", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + }, + { + "match": "corder", + "filter": "select * from `corder`", + "convert_enum_to_text": {}, + "convert_charset": {}, + "source_unique_key_columns": "", + "target_unique_key_columns": "", + "source_unique_key_target_columns": "", + "convert_int_to_enum": {} + } + ], + "field_event_mode": "ERR_ON_MISMATCH", + "workflow_type": "0", + "workflow_name": "" + }, + "on_ddl": "IGNORE", + "external_mysql": "", + "stop_after_copy": false, + "external_cluster": "", + "source_time_zone": "", + "target_time_zone": "" + }, + "position": "751b3b58-6874-11ee-9a45-2b583b20ee4a:1-4579", + "stop_position": "", + "state": "Running", + "db_name": "vt_commerce", + "transaction_timestamp": { + "seconds": "1697060479", + "nanoseconds": 0 + }, + "time_updated": { + "seconds": "1697060690", + "nanoseconds": 0 + }, + "message": "", + "copy_states": [], + "logs": [ + { + "id": "1", + "stream_id": "1", + "type": "Stream Created", + "state": "Stopped", + "created_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "updated_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "message": "{\"component_throttled\":\"\",\"db_name\":\"vt_commerce\",\"defer_secondary_keys\":\"0\",\"id\":\"1\",\"max_replication_lag\":\"9223372036854775807\",\"max_tps\":\"9223372036854775807\",\"pos\":\"MySQL56/751b3b58-6874-11ee-9a45-2b583b20ee4a:1-4577\",\"rows_copied\":\"0\",\"source\":\"keyspace:\\\"customer\\\" shard:\\\"0\\\" filter:{rules:{match:\\\"customer\\\" filter:\\\"select * from `customer`\\\"} rules:{match:\\\"corder\\\" filter:\\\"select * from `corder`\\\"}}\",\"state\":\"Stopped\",\"tags\":\"\",\"time_heartbeat\":\"0\",\"time_throttled\":\"0\",\"time_updated\":\"1697060479\",\"transaction_timestamp\":\"0\",\"workflow\":\"commerce2customer_reverse\",\"workflow_sub_type\":\"0\",\"workflow_type\":\"1\"}", + "count": "1" + }, + { + "id": "2", + "stream_id": "1", + "type": "State Changed", + "state": "Running", + "created_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "updated_at": { + "seconds": "1697046079", + "nanoseconds": 0 + }, + "message": "", + "count": "1" + } + ], + "log_fetch_error": "", + "tags": [], + "rows_copied": "0", + "throttler_status": { + "component_throttled": "", + "time_throttled": { + "seconds": "0", + "nanoseconds": 0 + } + } + } + ], + "tablet_controls": [ + { + "tablet_type": "PRIMARY", + "cells": [], + "denied_tables": [ + "corder", + "customer" + ], + "frozen": false + } + ], + "is_primary_serving": true + } + }, + "workflow_type": "MoveTables", + "workflow_sub_type": "None", + "max_v_replication_transaction_lag": "1", + "defer_secondary_keys": false + } + ] +} ``` ## Finalize and Cleanup @@ -656,11 +790,8 @@ for the `customer` and `corder` tables to the `commerce` keyspace, it is much b error, rather than return incorrect/stale data: ```bash -$ vtctlclient MoveTables -- Complete customer.commerce2customer - -Complete was successful for workflow customer.commerce2customer -Start State: All Reads Switched. Writes Switched -Current State: Workflow Not Found +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer complete +Successfully completed the commerce2customer workflow in the customer keyspace ``` {{< info >}} @@ -684,12 +815,12 @@ $ vtctldclient GetRoutingRules } # Workflow is gone -$ vtctlclient Workflow customer listall -No workflows found in keyspace customer +$ vtctldclient Workflow --keyspace customer list +[] # Reverse workflow is also gone -$ vtctlclient Workflow commerce listall -No workflows found in keyspace commerce +$ vtctldclient Workflow --keyspace commerce list +[] ``` This confirms that the data and routing rules have been properly cleaned up. Note that the `Complete` process also cleans up the reverse VReplication workflow mentioned above. diff --git a/content/en/docs/19.0/user-guides/migration/troubleshooting.md b/content/en/docs/19.0/user-guides/migration/troubleshooting.md index 48523e07d..05e880400 100644 --- a/content/en/docs/19.0/user-guides/migration/troubleshooting.md +++ b/content/en/docs/19.0/user-guides/migration/troubleshooting.md @@ -20,7 +20,7 @@ you have setup the shell aliases from the example, e.g. `env.sh` in the [local]( ### Execute a Dry Run -The `SwitchTraffic`/`ReverseTraffic` and `Complete` actions support a dry run using the `--dry_run` flag where no +The `SwitchTraffic`/`ReverseTraffic` and `Complete` actions support a dry run using the `--dry-run` flag where no actual steps are taken but instead the command logs all the steps that *would* be taken. This command will also verify that the cluster is generally in a state where it can perform the action successfully without potentially timing out along the way. Given that traffic cutovers can potentially cause read/write pauses or outages this can @@ -51,8 +51,8 @@ tablet so it's recommended to use non-PRIMARY tablets whenever possible to limit ## Monitoring It's important to properly monitor your VReplication workflows in order to detect any issues. Your primary tools for this are: - - The [`Workflow show`](../../../reference/vreplication/workflow/) command - - The `Progress`/`Show` action (e.g. [`MoveTables -- Progress`](../../../reference/vreplication/movetables/#progress)) + - The `show`sub-command (e.g. [`MoveTables show`](../../../reference/vreplication/movetables/#show)) + - The `status ` sub-command (e.g. [`MoveTables status`](../../../reference/vreplication/movetables/#status)) - The [VReplication related metrics](../../../reference/vreplication/metrics/) - Note that in most production systems the tablet endpoints would be scraped and stored in something like [Prometheus](https://prometheus.io) where you can build dashboards and alerting on the data @@ -62,11 +62,13 @@ The `Create`, `SwitchTraffic`/`ReverseTraffic`, and `Cancel`/`Complete` actions [routing rules](../../../reference/features/schema-routing-rules/). You may want to save the routing rules before taking an action just in case you want to restore them for any reason (note that e.g. the `ReverseTraffic` action will automatically revert the routing rules): + ```bash $ vtctldclient GetRoutingRules > /tmp/routingrules.backup.json ``` Those can later be applied this way: + ```bash $ vtctldclient ApplyRoutingRules --rules-file=/tmp/routingrules.backup.json ``` @@ -77,57 +79,77 @@ $ vtctldclient ApplyRoutingRules --rules-file=/tmp/routingrules.backup.json ### Stream Never Starts This can be exhibited in one of two ways: -1. This error is shown in the `Progress`/`Show` action output or the `Workflow show` output: `Error picking tablet: context has expired` +1. This error is shown in the `status`/`show` action output or the `Workflow show` output: `Error picking tablet: context has expired` 2. The stream never starts, which can be seen in the following ways: - 1. The `Workflow show` output is showing an empty value in the `Pos` field for the stream - 2. The `Progress`/`Show` action output is showing `VStream has not started` for the stream + 1. The `show` output is showing an empty value in the `Pos` field for the stream + 2. The `status`/`show` action output is showing `VStream has not started` for the stream When a VReplication workflow starts or restarts the [tablet selection process](../../../reference/vreplication/tablet_selection/) -runs to find a viable source tablet for the stream. The `cells` and `tablet_types` play a key role in this process and +runs to find a viable source tablet for the stream. The `--cells` and `--tablet-types` play a key role in this process and if we cannot ever find a viable source tablet for the stream then you may want to expand the cells and/or tablet types made available for the selection process. #### Corrective Action -If the workflow was only created and has not yet made any progress then you should `Cancel` the workflow and `Create` a new -one using different values for the `--cells` and `--tablet_types` flags. If, however, this workflow has made significant +If the workflow was only created and has not yet made any progress then you should `cancel` the workflow and `create` a new +one using different values for the `--cells` and `--tablet-types` flags. If, however, this workflow has made significant progress that you do not wish you lose, you can update the underlying workflow record directly to modify either of those values. For example: -```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000200: Status: Running. VStream has not started. - -$ vtctlclient Workflow -- --tablet-types="replica,primary" customer.commerce2customer update - -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: -id=1 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +```bash +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 1, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-49", + "status": "Running", + "info": "VStream Lag: 0s; ; Tx time: Wed Oct 11 16:49:02 2023." + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` ### Workflow Has SQL Errors We can encounter persistent SQL errors when applying replicated events on the target for a variety of reasons, but the most common cause is incompatible DDL having been executed against the source table while the workflow is running. -You would see this error in the `Show`/`Progress` or `Workflow show` output. For example: -```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000201: Status: Error: Unknown column 'notes' in 'field list' (errno 1054) (sqlstate 42S22) during query: insert into customer(customer_id,email,notes) values (100,'test@tester.com','Lots of notes'). +You would see this error in the `status`/`show` or `Workflow show` output. For example: -# OR a variant - -$ vtctlclient MoveTables -- Progress customer.commerce2customer - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=1 on 0/zone1-0000000201: Status: Error: vttablet: rpc error: code = Unknown desc = stream (at source tablet) error @ a2d90338-916d-11ed-820a-498bdfbb0b03:1-90: cannot determine table columns for customer: event has [8 15 15], schema has [name:"customer_id" type:INT64 table:"customer" org_table:"customer" database:"vt_commerce" org_name:"customer_id" column_length:20 charset:63 flags:49667 name:"email" type:VARBINARY table:"customer" org_table:"customer" database:"vt_commerce" org_name:"email" column_length:128 charset:63 flags:128]. +```bash +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 1, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-49", + "status": "Error: Unknown column 'notes' in 'field list' (errno 1054) (sqlstate 42S22) during query: insert into customer(customer_id,email,notes) values (100,'test@tester.com','Lots of notes')", + "info": "VStream Lag: 0s; ; Tx time: Wed Oct 11 16:49:02 2023." + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` This can be caused by a DDL executed on the source table as by default — controlled by the @@ -136,67 +158,75 @@ This can be caused by a DDL executed on the source table as by default — contr #### Corrective Action If you want the same or similar DDL to be applied on the target then you can apply that DDL on the target keyspace and then restart the workflow. For example, using the example above: + ```bash -$ vtctldclient ApplySchema --ddl-strategy=direct --sql="alter table customer add notes varchar(100) not null" customer +vtctldclient ApplySchema --ddl-strategy=direct --sql="alter table customer add notes varchar(100) not null" customer -$ vtctldclient Workflow customer.commerce2customer start +vtctldclient Workflow customer.commerce2customer start ``` If the tables are not very large or the workflow has not made much progress, you can alternatively `Cancel` the current worfklow and `Create` another. For example: -```bash -$ vtctlclient MoveTables -- Cancel customer.commerce2customer -Cancel was successful for workflow customer.commerce2customer -Start State: Reads Not Switched. Writes Not Switched -Current State: Workflow Not Found - - -$ vtctlclient MoveTables -- --source commerce --tables 'customer,corder' Create customer.commerce2customer -Waiting for workflow to start: - -Workflow started successfully with 1 stream(s) - -The following vreplication streams exist for workflow customer.commerce2customer: - -id=2 on 0/zone1-0000000201: Status: Copying. VStream Lag: 0s. +```bash -$ vtctlclient MoveTables -- Progress customer.commerce2customer +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer cancel +Successfully cancelled the commerce2customer workflow in the customer keyspace +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer create --source-keyspace commerce --tables 'customer,corder' The following vreplication streams exist for workflow customer.commerce2customer: -id=2 on 0/zone1-0000000201: Status: Running. VStream Lag: 0s. +id=2 on customer/zone1-200: Status: Running. VStream has not started. + +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer status --format=json +{ + "table_copy_state": {}, + "shard_streams": { + "customer/0": { + "streams": [ + { + "id": 2, + "tablet": { + "cell": "zone1", + "uid": 200 + }, + "source_shard": "commerce/0", + "position": "5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51", + "status": "Running", + "info": "VStream Lag: 0s" + } + ] + } + }, + "traffic_state": "Reads Not Switched. Writes Not Switched" +} ``` ### Switching Traffic Fails You can encounter a variety of failures during the `SwitchTraffic`/`ReverseTraffic` step as a number of operations are performed. To demonstrate that we can look at an example dry run output: + ```bash -$ vtctlclient MoveTables -- --dry_run SwitchTraffic customer.commerce2customer -Dry Run results for SwitchTraffic run at 11 Jan 23 08:51 EST -Parameters: --dry_run SwitchTraffic customer.commerce2customer +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer SwitchTraffic --dry-run +SwitchTraffic dry run results for workflow customer.commerce2customer at 11 Oct 23 21:23 UTC Lock keyspace commerce -Switch reads for tables [corder,customer] to keyspace customer for tablet types [RDONLY,REPLICA] +Switch reads for tables [corder,customer] to keyspace customer for tablet types [PRIMARY,REPLICA,RDONLY] Routing rules for tables [corder,customer] will be updated Unlock keyspace commerce Lock keyspace commerce Lock keyspace customer -Stop writes on keyspace commerce, tables [corder,customer]: - Keyspace commerce, Shard 0 at Position MySQL56/a2d90338-916d-11ed-820a-498bdfbb0b03:1-94 -Wait for VReplication on stopped streams to catchup for up to 30s -Create reverse replication workflow commerce2customer_reverse +Stop writes on keyspace commerce for tables [corder,customer]: [keyspace:commerce;shard:0;position:MySQL56/5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51] +Wait for vreplication on stopped streams to catchup for up to 30s +Create reverse vreplication workflow commerce2customer_reverse Create journal entries on source databases -Enable writes on keyspace customer tables [corder,customer] +Enable writes on keyspace customer for tables [corder,customer] Switch routing from keyspace commerce to keyspace customer Routing rules for tables [corder,customer] will be updated -Switch writes completed, freeze and delete vreplication streams on: - tablet 201 -Start reverse replication streams on: - tablet 101 -Mark vreplication streams frozen on: - Keyspace customer, Shard 0, Tablet 201, Workflow commerce2customer, DbName vt_customer +Switch writes completed, freeze and delete vreplication streams on: [tablet:200] +Start reverse vreplication streams on: [tablet:101] +Mark vreplication streams frozen on: [keyspace:customer;shard:0;tablet:200;workflow:commerce2customer;dbname:vt_customer] Unlock keyspace customer Unlock keyspace commerce ``` @@ -206,17 +236,19 @@ Unlock keyspace commerce #### disallowed due to rule: enforce denied tables If your queries start failing with this error then you most likely had some leftover artifacts from a previous `MoveTables` operation -that were not properly cleaned up by running [`MoveTables -- Cancel`](../../../reference/vreplication/movetables/#cancel). For +that were not properly cleaned up by running [`MoveTables cancel`](../../../reference/vreplication/movetables/#cancel). For `MoveTables` operations, shard query serving control records (denied tables lists) are used in addition to [routing rules](../../../reference/features/schema-routing-rules/) to ensure that all query traffic is managed by the correct keyspace as you are often only moving some tables from one keyspace to another. If those control records are not properly cleaned up then queries may be incorrectly denied when traffic is switched. If you e.g. were to see the following error for queries after switching traffic for the customer table from the commerce keyspace to the customer keyspace: + ``` code = FailedPrecondition desc = disallowed due to rule: enforce denied tables (CallerID: matt) for query SELECT * FROM customer WHERE customer_id = 1 ``` Then you can remove those unwanted/errant denied table rules from the customer keyspace this way: + ```bash $ for type in primary replica rdonly; do vtctldclient SetShardTabletControl --remove customer/0 ${type} @@ -230,23 +262,27 @@ $ vtctldclient RefreshStateByShard customer/0 The completion action performs a number of steps that could potentially fail. We can again use the dry run output to demonstrate the various actions that are taken: + ```bash -$ vtctlclient MoveTables -- --dry_run Complete customer.commerce2customer -Dry Run results for Complete run at 11 Jan 23 10:22 EST -Parameters: --dry_run Complete customer.commerce2customer +$ vtctldclient MoveTables --target-keyspace customer --workflow commerce2customer SwitchTraffic --dry-run +SwitchTraffic dry run results for workflow customer.commerce2customer at 11 Oct 23 21:23 UTC +Lock keyspace commerce +Switch reads for tables [corder,customer] to keyspace customer for tablet types [PRIMARY,REPLICA,RDONLY] +Routing rules for tables [corder,customer] will be updated +Unlock keyspace commerce Lock keyspace commerce Lock keyspace customer -Dropping these tables from the database and removing them from the vschema for keyspace commerce: - Keyspace commerce Shard 0 DbName vt_commerce Tablet 101 Table corder - Keyspace commerce Shard 0 DbName vt_commerce Tablet 101 Table customer -Denied tables [corder,customer] will be removed from: - Keyspace commerce Shard 0 Tablet 101 -Delete reverse vreplication streams on source: - Keyspace commerce Shard 0 Workflow commerce2customer_reverse DbName vt_commerce Tablet 101 -Delete vreplication streams on target: - Keyspace customer Shard 0 Workflow commerce2customer DbName vt_customer Tablet 201 -Routing rules for participating tables will be deleted +Stop writes on keyspace commerce for tables [corder,customer]: [keyspace:commerce;shard:0;position:MySQL56/5d8e0b24-6873-11ee-9359-49d03ab2cdee:1-51] +Wait for vreplication on stopped streams to catchup for up to 30s +Create reverse vreplication workflow commerce2customer_reverse +Create journal entries on source databases +Enable writes on keyspace customer for tables [corder,customer] +Switch routing from keyspace commerce to keyspace customer +Routing rules for tables [corder,customer] will be updated +Switch writes completed, freeze and delete vreplication streams on: [tablet:200] +Start reverse vreplication streams on: [tablet:101] +Mark vreplication streams frozen on: [keyspace:customer;shard:0;tablet:200;workflow:commerce2customer;dbname:vt_customer] Unlock keyspace customer Unlock keyspace commerce -``` \ No newline at end of file +``` diff --git a/content/en/docs/19.0/user-guides/vschema-guide/backfill-vindexes.md b/content/en/docs/19.0/user-guides/vschema-guide/backfill-vindexes.md index 657494b60..c4c03bc29 100644 --- a/content/en/docs/19.0/user-guides/vschema-guide/backfill-vindexes.md +++ b/content/en/docs/19.0/user-guides/vschema-guide/backfill-vindexes.md @@ -3,14 +3,14 @@ title: Backfill Lookup Vindexes weight: 11 --- -Creating a lookup vindex after the main table already contains rows does not automatically backfill the lookup table for the existing entries. +Creating a Lookup Vindex after the main table already contains rows does not automatically backfill the lookup table for the existing entries. Only newer inserts cause automatic population of the lookup table. -This backfill can be set up using the [CreateLookupVindex](#createlookupvindex) command covered below. +This backfill can be set up using the [LookupVindex create](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command covered below. ### Manual Backfill Checklist -Creating a unique lookup Vindex is an elaborate process. It is good to use the following checklist if this is done manually: +Creating a unique Lookup Vindex is an elaborate process. It is good to use the following checklist if this is done manually: * Create the lookup table as sharded or unsharded. Make the `from` column the primary key. * Create a VSchema entry for the lookup table. If sharded, assign a Primary Vindex for the `from` column. @@ -21,9 +21,9 @@ Creating a unique lookup Vindex is an elaborate process. It is good to use the f * Specify the `Owner` as the main table * Associate the column of the owner table with the new Vindex. -### CreateLookupVindex +### Creating a Lookup Vindex -vtctld supports the [CreateLookupVindex](../../configuration-advanced/createlookupvindex) command that can perform all the above steps as well as the backfill. +vtctldclient supports the [LookupVindex create](../../../reference/programs/vtctldclient/vtctldclient_lookupvindex/vtctldclient_lookupvindex_create/) command that can perform all the above steps as well as the backfill. {{< warning >}} This will not work against the `vtcombo` based demo app because it does not support vreplication. You can only try this against a real Vitess cluster. @@ -31,7 +31,7 @@ This will not work against the `vtcombo` based demo app because it does not supp The workflow automatically infers the schema and vschema for the lookup table and creates it. It also sets up the necessary VReplication streams to backfill the lookup table. -After the backfill is done, you should clean up the workflow. More detailed instructions are available in the [CreateLookupVindex Reference](../../configuration-advanced/createlookupvindex) +After the backfill is done, you should clean up the workflow. More detailed instructions are available in the [Creating a Lookup Vindex Guide](../../configuration-advanced/createlookupvindex) To create such a lookup vindex on a real Vitess cluster, you can use the following instructions: