From c5dd3177319bb4e6226c98767083736c947164c4 Mon Sep 17 00:00:00 2001 From: Matt Lord Date: Fri, 20 Jan 2023 13:31:13 -0500 Subject: [PATCH] Title capitalization Signed-off-by: Matt Lord --- .../vreplication/internal/cutover.md | 26 +++++++++---------- .../reference/vreplication/internal/keys.md | 20 +++++++------- .../vreplication/internal/life-of-a-stream.md | 8 +++--- .../vreplication/internal/tracker.md | 2 +- .../vreplication/internal/cutover.md | 26 +++++++++---------- .../reference/vreplication/internal/keys.md | 20 +++++++------- .../vreplication/internal/life-of-a-stream.md | 8 +++--- .../vreplication/internal/tracker.md | 2 +- .../vreplication/internal/cutover.md | 26 +++++++++---------- .../reference/vreplication/internal/keys.md | 20 +++++++------- .../vreplication/internal/life-of-a-stream.md | 8 +++--- .../vreplication/internal/tracker.md | 2 +- .../vreplication/internal/cutover.md | 26 +++++++++---------- .../reference/vreplication/internal/keys.md | 20 +++++++------- .../vreplication/internal/life-of-a-stream.md | 8 +++--- .../vreplication/internal/tracker.md | 2 +- 16 files changed, 112 insertions(+), 112 deletions(-) diff --git a/content/en/docs/13.0/reference/vreplication/internal/cutover.md b/content/en/docs/13.0/reference/vreplication/internal/cutover.md index f733a5e3c..376ffc7dc 100644 --- a/content/en/docs/13.0/reference/vreplication/internal/cutover.md +++ b/content/en/docs/13.0/reference/vreplication/internal/cutover.md @@ -1,11 +1,11 @@ --- -title: How traffic is switched +title: How Traffic Is Switched description: How Vitess signals traffic cutover for Reshard and MoveTables weight: 2 aliases: ['/docs/design-docs/vreplication/cutover/'] --- -# Related persistent Vitess objects +# Related Persistent Vitess Objects {{< info >}} As the objects or keys noted below are stored in [the topo server](../../../features/topology-service/) and @@ -76,7 +76,7 @@ dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions vtctl client command which will return the rules for all keyspaces in the topo. {{< /info >}} -# How VTGate routes a query +# How VTGate Routes a Query This section walks through a simplified version of the logic used to determine which keyspace and table vtgate will route a simple query of the form `select * from t1 where id = 1` (a _read_ query) or `insert into t1 (id, val) values (1,'abc')` @@ -93,7 +93,7 @@ and selecting the ones whose `query_service_disabled` field is *not* set and who [`VSchema`](../../../features/vschema/) (stored in the `global` topo), the shard for the relevant row is computed based on the keyrange to which the id is mapped to using the declared [`VIndex` function/type](../../../features/vindexes/#predefined-vindexes). -# Changes made to the topo when traffic is switched +# Changes Made to the Topo When Traffic Is Switched This document outlines the steps involved in the cutover process of [`MoveTables`](../../movetables/) and [`Reshard`](../../reshard/) @@ -105,11 +105,11 @@ in the workflow. Items in italics are topo keys and the following snippet the value of the key {{< /info >}} -## What happens when a Reshard is cutover +## What Happens When a Reshard Is Cutover For brevity we only show the records for the `80-` shard. There will be similar records for the `-80` shard. -#### Before Resharding, after -80/80- shards are created +#### Before Resharding, After -80/80- Shards Are Created Only shard `0` has `is_primary_serving` set to true. The `SrvKeyspace` record only has references to `0` for both `PRIMARY` and `REPLICA` tablet types. @@ -137,7 +137,7 @@ partitions:{served_type:PRIMARY shard_references:{name:"0"}} partitions:{served_type:REPLICA shard_references:{name:"0"}} ``` -### After replica traffic is switched using `SwitchTraffic` (previously known as SwitchReads) +### After Replica Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchReads) Shard `0` still has the `is_primary_serving` set as true. The primary partition is still the same. @@ -178,7 +178,7 @@ partitions:{served_type:REPLICA } ``` -#### After primary traffic is switched using `SwitchTraffic` (previously known as SwitchWrites) +#### After Primary Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchWrites) * `is_primary_serving` is removed from shard `0` * `is_primary_serving` is added to shards `-80` and `80-` @@ -220,9 +220,9 @@ partitions:{served_type:REPLICA } ``` -## What happens when a MoveTables workflow is cutover +## What Happens When a MoveTables Workflow Is Cutover -#### Before MoveTables is initiated +#### Before MoveTables Is Initiated The [`VSchema`](../../../features/vschema/) for the source keyspace contains the table name, so vtgate routes queries to that keyspace. @@ -241,7 +241,7 @@ rules:{from_table:"customer@replica" to_tables:"commerce.customer"} rules:{from_table:"customer.customer@replica" to_tables:"commerce.customer"} ``` -#### On switching replica traffic to target +#### On Switching Replica Traffic to Target The routing rules for replica targeted reads are updated to map the table on the source to the target. @@ -253,7 +253,7 @@ rules:{from_table:"customer" to_tables:"commerce.customer"} rules:{from_table:"customer@replica" to_tables:"customer.customer"} ``` -#### On switching primary traffic +#### On Switching Primary Traffic The routing rules for default read-write traffic are updated to map the table on the source to the target. In addition the tables are added to the “denylist” on the source keyspace which `vttablet` uses to reject queries for these tables on the @@ -277,7 +277,7 @@ tablet_controls:{tablet_type:PRIMARY denylisted_tables:"customer"} is_primary_serving:true ``` -# Miscellaneous Notes: +# Miscellaneous Notes * In VReplication workflows, cutovers are performed manually by the user executing the `SwitchTraffic` and `ReverseTraffic` actions e.g. for a [`MoveTables`](../../movetables/#switchtraffic) or [`Reshard`](../../reshard/#reversetraffic) vtctl diff --git a/content/en/docs/13.0/reference/vreplication/internal/keys.md b/content/en/docs/13.0/reference/vreplication/internal/keys.md index ae3bee759..0be41810e 100644 --- a/content/en/docs/13.0/reference/vreplication/internal/keys.md +++ b/content/en/docs/13.0/reference/vreplication/internal/keys.md @@ -1,11 +1,11 @@ --- -title: Role of table keys in VReplication +title: Role of Table Keys in VReplication description: Uses and requirements for primary and unique keys in source and target tables in VReplication Workflows weight: 3 aliases: ['/docs/design-docs/vreplication/keys/'] --- -# The use of unique keys +# The Use of Unique Keys A VReplication stream copies data from a table on a source tablet to a table on a target tablet. In some cases, the two tablets may be the same one, but the stream is oblivious to such nuance. VReplication needs to be able to copy existing @@ -23,7 +23,7 @@ In fact, in the most common use case, both tables will have the same `PRIMARY KE the same order. This is the default assumption and expectation by VReplication. But this doesn't have to be the case, and it is possible to have different keys on the source and the target table. -## Which keys are eligible? +## Which Keys Are Eligible? Any `UNIQUE KEY` that is non-`NULL`able potentially qualifies. A `NULL`able `UNIQUE KEY` is a key that covers one or more `NULL`able columns. It doesn't matter if column values do or do not actually contain `NULL`s. If a column is `NULL` @@ -38,7 +38,7 @@ prioritizes smaller data types over larger data types. However, not all eligible `UNIQUE KEY`s, or even `PRIMARY KEY`s are usable for all VReplication streams, as described below. -## Comparable rows +## Comparable Rows VReplication needs to be able to determine, given a row in the source table, which row it maps to in the target table. @@ -94,9 +94,9 @@ To clarify, it is **OK** if: All it takes is _one_ viable key that can be used to uniquely identify rows in the source table, and one such viable key in the target table to allow VReplication to work. -### Examples of valid cases +### Examples of Valid Cases -#### Source table and target table are the same +#### Source Table and Target Table Are the Same ```sql CREATE TABLE `entry` ( @@ -110,7 +110,7 @@ CREATE TABLE `entry` ( The above is a trivial scenario. -#### Source table and target table share the same PRIMARY KEY +#### Source Table and Target table Share the Same PRIMARY KEY ```sql CREATE TABLE `source` ( @@ -227,7 +227,7 @@ The only eligible solution in the above is: Incidentally, in the above, the chosen keys differ by name, but share the same columns (`uuid`). -### Examples of invalid cases +### Examples of Invalid Cases #### NULLable columns @@ -272,7 +272,7 @@ CREATE TABLE `target` ( `target` only has one possible key, the `PRIMARY KEY`, covering `id`. But `id` is not found in `source`. -## Configuring the stream +## Configuring The Stream If both source and target table share the same `PRIMARY KEY` (covering the same columns in the same order) then there's nothing to be done. VReplication will pick `PRIMARY KEY` on both ends by default. @@ -396,7 +396,7 @@ With the introduction of mechanisms to automatically determine the optimal key t the `source_unique_key_columns`, `target_unique_key_columns`, and `source_unique_key_target_columns` fields for more fine-grained control, VReplication changes its behavior as needed. -#### Notes about the code +#### Notes About The Code Much of the code uses "PK" terminology. With the introduction of _any_ unique key utilization the "PK" terminology becomes incorrect. However, to avoid mass rewrites we kept this terminology, and wherever VReplication discusses diff --git a/content/en/docs/13.0/reference/vreplication/internal/life-of-a-stream.md b/content/en/docs/13.0/reference/vreplication/internal/life-of-a-stream.md index 1d58d9e97..5648fc2fe 100644 --- a/content/en/docs/13.0/reference/vreplication/internal/life-of-a-stream.md +++ b/content/en/docs/13.0/reference/vreplication/internal/life-of-a-stream.md @@ -1,5 +1,5 @@ --- -title: Life of a stream +title: Life of a Stream description: How VReplication replicates data weight: 1 aliases: ['/docs/design-docs/vreplication/life-of-a-stream/'] @@ -18,7 +18,7 @@ streams events from the binlog. ![VReplication Flow](/img/VReplicationFlow.png) -#### Full table copy +#### Full Table Copy If the entire table data is requested then the simple streaming done by the _replication_ mode can create an avalanche of events (think 100s of millions of rows). Moreover, and more importantly, it is highly likely that necesasry older @@ -54,7 +54,7 @@ not able to process them in time. For example, in resharding workflows we need t statements and execute them on the target's mysqld instance, which are usually much slower than just selecting data on the source. -### Modes, in detail +### Modes, in Detail #### Replicate @@ -158,7 +158,7 @@ As detailed above the catchup phase runs between copy phase cycles (time limited GTID position can move significantly ahead. So we run a catchup and fast-forward phase until we come close to the current position — i.e. the replication lag is small. At that point we execute another Copy cycle. -#### Fast forward +#### Fast Forward During the copy phase we first take a snapshot. Then we fast-forward: we replicate from the gtid position where we stopped the Catchup to the position of the new snapshot. diff --git a/content/en/docs/13.0/reference/vreplication/internal/tracker.md b/content/en/docs/13.0/reference/vreplication/internal/tracker.md index 08fd12941..4a9a73478 100644 --- a/content/en/docs/13.0/reference/vreplication/internal/tracker.md +++ b/content/en/docs/13.0/reference/vreplication/internal/tracker.md @@ -176,7 +176,7 @@ If version tracking is turned off on the `PRIMARY` for some time, correct versio which will always return the latest schema. This might result in an incorrect schema when a vstream is processing events in the past. -#### Possible new features around this functionality +#### Possible New Features Around This Functionality - Schema tracking vstream client for notifications of all ddls - Raw history of schema changes for auditing, root cause analysis, etc. diff --git a/content/en/docs/14.0/reference/vreplication/internal/cutover.md b/content/en/docs/14.0/reference/vreplication/internal/cutover.md index f733a5e3c..376ffc7dc 100644 --- a/content/en/docs/14.0/reference/vreplication/internal/cutover.md +++ b/content/en/docs/14.0/reference/vreplication/internal/cutover.md @@ -1,11 +1,11 @@ --- -title: How traffic is switched +title: How Traffic Is Switched description: How Vitess signals traffic cutover for Reshard and MoveTables weight: 2 aliases: ['/docs/design-docs/vreplication/cutover/'] --- -# Related persistent Vitess objects +# Related Persistent Vitess Objects {{< info >}} As the objects or keys noted below are stored in [the topo server](../../../features/topology-service/) and @@ -76,7 +76,7 @@ dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions vtctl client command which will return the rules for all keyspaces in the topo. {{< /info >}} -# How VTGate routes a query +# How VTGate Routes a Query This section walks through a simplified version of the logic used to determine which keyspace and table vtgate will route a simple query of the form `select * from t1 where id = 1` (a _read_ query) or `insert into t1 (id, val) values (1,'abc')` @@ -93,7 +93,7 @@ and selecting the ones whose `query_service_disabled` field is *not* set and who [`VSchema`](../../../features/vschema/) (stored in the `global` topo), the shard for the relevant row is computed based on the keyrange to which the id is mapped to using the declared [`VIndex` function/type](../../../features/vindexes/#predefined-vindexes). -# Changes made to the topo when traffic is switched +# Changes Made to the Topo When Traffic Is Switched This document outlines the steps involved in the cutover process of [`MoveTables`](../../movetables/) and [`Reshard`](../../reshard/) @@ -105,11 +105,11 @@ in the workflow. Items in italics are topo keys and the following snippet the value of the key {{< /info >}} -## What happens when a Reshard is cutover +## What Happens When a Reshard Is Cutover For brevity we only show the records for the `80-` shard. There will be similar records for the `-80` shard. -#### Before Resharding, after -80/80- shards are created +#### Before Resharding, After -80/80- Shards Are Created Only shard `0` has `is_primary_serving` set to true. The `SrvKeyspace` record only has references to `0` for both `PRIMARY` and `REPLICA` tablet types. @@ -137,7 +137,7 @@ partitions:{served_type:PRIMARY shard_references:{name:"0"}} partitions:{served_type:REPLICA shard_references:{name:"0"}} ``` -### After replica traffic is switched using `SwitchTraffic` (previously known as SwitchReads) +### After Replica Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchReads) Shard `0` still has the `is_primary_serving` set as true. The primary partition is still the same. @@ -178,7 +178,7 @@ partitions:{served_type:REPLICA } ``` -#### After primary traffic is switched using `SwitchTraffic` (previously known as SwitchWrites) +#### After Primary Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchWrites) * `is_primary_serving` is removed from shard `0` * `is_primary_serving` is added to shards `-80` and `80-` @@ -220,9 +220,9 @@ partitions:{served_type:REPLICA } ``` -## What happens when a MoveTables workflow is cutover +## What Happens When a MoveTables Workflow Is Cutover -#### Before MoveTables is initiated +#### Before MoveTables Is Initiated The [`VSchema`](../../../features/vschema/) for the source keyspace contains the table name, so vtgate routes queries to that keyspace. @@ -241,7 +241,7 @@ rules:{from_table:"customer@replica" to_tables:"commerce.customer"} rules:{from_table:"customer.customer@replica" to_tables:"commerce.customer"} ``` -#### On switching replica traffic to target +#### On Switching Replica Traffic to Target The routing rules for replica targeted reads are updated to map the table on the source to the target. @@ -253,7 +253,7 @@ rules:{from_table:"customer" to_tables:"commerce.customer"} rules:{from_table:"customer@replica" to_tables:"customer.customer"} ``` -#### On switching primary traffic +#### On Switching Primary Traffic The routing rules for default read-write traffic are updated to map the table on the source to the target. In addition the tables are added to the “denylist” on the source keyspace which `vttablet` uses to reject queries for these tables on the @@ -277,7 +277,7 @@ tablet_controls:{tablet_type:PRIMARY denylisted_tables:"customer"} is_primary_serving:true ``` -# Miscellaneous Notes: +# Miscellaneous Notes * In VReplication workflows, cutovers are performed manually by the user executing the `SwitchTraffic` and `ReverseTraffic` actions e.g. for a [`MoveTables`](../../movetables/#switchtraffic) or [`Reshard`](../../reshard/#reversetraffic) vtctl diff --git a/content/en/docs/14.0/reference/vreplication/internal/keys.md b/content/en/docs/14.0/reference/vreplication/internal/keys.md index ae3bee759..0be41810e 100644 --- a/content/en/docs/14.0/reference/vreplication/internal/keys.md +++ b/content/en/docs/14.0/reference/vreplication/internal/keys.md @@ -1,11 +1,11 @@ --- -title: Role of table keys in VReplication +title: Role of Table Keys in VReplication description: Uses and requirements for primary and unique keys in source and target tables in VReplication Workflows weight: 3 aliases: ['/docs/design-docs/vreplication/keys/'] --- -# The use of unique keys +# The Use of Unique Keys A VReplication stream copies data from a table on a source tablet to a table on a target tablet. In some cases, the two tablets may be the same one, but the stream is oblivious to such nuance. VReplication needs to be able to copy existing @@ -23,7 +23,7 @@ In fact, in the most common use case, both tables will have the same `PRIMARY KE the same order. This is the default assumption and expectation by VReplication. But this doesn't have to be the case, and it is possible to have different keys on the source and the target table. -## Which keys are eligible? +## Which Keys Are Eligible? Any `UNIQUE KEY` that is non-`NULL`able potentially qualifies. A `NULL`able `UNIQUE KEY` is a key that covers one or more `NULL`able columns. It doesn't matter if column values do or do not actually contain `NULL`s. If a column is `NULL` @@ -38,7 +38,7 @@ prioritizes smaller data types over larger data types. However, not all eligible `UNIQUE KEY`s, or even `PRIMARY KEY`s are usable for all VReplication streams, as described below. -## Comparable rows +## Comparable Rows VReplication needs to be able to determine, given a row in the source table, which row it maps to in the target table. @@ -94,9 +94,9 @@ To clarify, it is **OK** if: All it takes is _one_ viable key that can be used to uniquely identify rows in the source table, and one such viable key in the target table to allow VReplication to work. -### Examples of valid cases +### Examples of Valid Cases -#### Source table and target table are the same +#### Source Table and Target Table Are the Same ```sql CREATE TABLE `entry` ( @@ -110,7 +110,7 @@ CREATE TABLE `entry` ( The above is a trivial scenario. -#### Source table and target table share the same PRIMARY KEY +#### Source Table and Target table Share the Same PRIMARY KEY ```sql CREATE TABLE `source` ( @@ -227,7 +227,7 @@ The only eligible solution in the above is: Incidentally, in the above, the chosen keys differ by name, but share the same columns (`uuid`). -### Examples of invalid cases +### Examples of Invalid Cases #### NULLable columns @@ -272,7 +272,7 @@ CREATE TABLE `target` ( `target` only has one possible key, the `PRIMARY KEY`, covering `id`. But `id` is not found in `source`. -## Configuring the stream +## Configuring The Stream If both source and target table share the same `PRIMARY KEY` (covering the same columns in the same order) then there's nothing to be done. VReplication will pick `PRIMARY KEY` on both ends by default. @@ -396,7 +396,7 @@ With the introduction of mechanisms to automatically determine the optimal key t the `source_unique_key_columns`, `target_unique_key_columns`, and `source_unique_key_target_columns` fields for more fine-grained control, VReplication changes its behavior as needed. -#### Notes about the code +#### Notes About The Code Much of the code uses "PK" terminology. With the introduction of _any_ unique key utilization the "PK" terminology becomes incorrect. However, to avoid mass rewrites we kept this terminology, and wherever VReplication discusses diff --git a/content/en/docs/14.0/reference/vreplication/internal/life-of-a-stream.md b/content/en/docs/14.0/reference/vreplication/internal/life-of-a-stream.md index 1d58d9e97..5648fc2fe 100644 --- a/content/en/docs/14.0/reference/vreplication/internal/life-of-a-stream.md +++ b/content/en/docs/14.0/reference/vreplication/internal/life-of-a-stream.md @@ -1,5 +1,5 @@ --- -title: Life of a stream +title: Life of a Stream description: How VReplication replicates data weight: 1 aliases: ['/docs/design-docs/vreplication/life-of-a-stream/'] @@ -18,7 +18,7 @@ streams events from the binlog. ![VReplication Flow](/img/VReplicationFlow.png) -#### Full table copy +#### Full Table Copy If the entire table data is requested then the simple streaming done by the _replication_ mode can create an avalanche of events (think 100s of millions of rows). Moreover, and more importantly, it is highly likely that necesasry older @@ -54,7 +54,7 @@ not able to process them in time. For example, in resharding workflows we need t statements and execute them on the target's mysqld instance, which are usually much slower than just selecting data on the source. -### Modes, in detail +### Modes, in Detail #### Replicate @@ -158,7 +158,7 @@ As detailed above the catchup phase runs between copy phase cycles (time limited GTID position can move significantly ahead. So we run a catchup and fast-forward phase until we come close to the current position — i.e. the replication lag is small. At that point we execute another Copy cycle. -#### Fast forward +#### Fast Forward During the copy phase we first take a snapshot. Then we fast-forward: we replicate from the gtid position where we stopped the Catchup to the position of the new snapshot. diff --git a/content/en/docs/14.0/reference/vreplication/internal/tracker.md b/content/en/docs/14.0/reference/vreplication/internal/tracker.md index 08fd12941..4a9a73478 100644 --- a/content/en/docs/14.0/reference/vreplication/internal/tracker.md +++ b/content/en/docs/14.0/reference/vreplication/internal/tracker.md @@ -176,7 +176,7 @@ If version tracking is turned off on the `PRIMARY` for some time, correct versio which will always return the latest schema. This might result in an incorrect schema when a vstream is processing events in the past. -#### Possible new features around this functionality +#### Possible New Features Around This Functionality - Schema tracking vstream client for notifications of all ddls - Raw history of schema changes for auditing, root cause analysis, etc. diff --git a/content/en/docs/15.0/reference/vreplication/internal/cutover.md b/content/en/docs/15.0/reference/vreplication/internal/cutover.md index f733a5e3c..376ffc7dc 100644 --- a/content/en/docs/15.0/reference/vreplication/internal/cutover.md +++ b/content/en/docs/15.0/reference/vreplication/internal/cutover.md @@ -1,11 +1,11 @@ --- -title: How traffic is switched +title: How Traffic Is Switched description: How Vitess signals traffic cutover for Reshard and MoveTables weight: 2 aliases: ['/docs/design-docs/vreplication/cutover/'] --- -# Related persistent Vitess objects +# Related Persistent Vitess Objects {{< info >}} As the objects or keys noted below are stored in [the topo server](../../../features/topology-service/) and @@ -76,7 +76,7 @@ dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions vtctl client command which will return the rules for all keyspaces in the topo. {{< /info >}} -# How VTGate routes a query +# How VTGate Routes a Query This section walks through a simplified version of the logic used to determine which keyspace and table vtgate will route a simple query of the form `select * from t1 where id = 1` (a _read_ query) or `insert into t1 (id, val) values (1,'abc')` @@ -93,7 +93,7 @@ and selecting the ones whose `query_service_disabled` field is *not* set and who [`VSchema`](../../../features/vschema/) (stored in the `global` topo), the shard for the relevant row is computed based on the keyrange to which the id is mapped to using the declared [`VIndex` function/type](../../../features/vindexes/#predefined-vindexes). -# Changes made to the topo when traffic is switched +# Changes Made to the Topo When Traffic Is Switched This document outlines the steps involved in the cutover process of [`MoveTables`](../../movetables/) and [`Reshard`](../../reshard/) @@ -105,11 +105,11 @@ in the workflow. Items in italics are topo keys and the following snippet the value of the key {{< /info >}} -## What happens when a Reshard is cutover +## What Happens When a Reshard Is Cutover For brevity we only show the records for the `80-` shard. There will be similar records for the `-80` shard. -#### Before Resharding, after -80/80- shards are created +#### Before Resharding, After -80/80- Shards Are Created Only shard `0` has `is_primary_serving` set to true. The `SrvKeyspace` record only has references to `0` for both `PRIMARY` and `REPLICA` tablet types. @@ -137,7 +137,7 @@ partitions:{served_type:PRIMARY shard_references:{name:"0"}} partitions:{served_type:REPLICA shard_references:{name:"0"}} ``` -### After replica traffic is switched using `SwitchTraffic` (previously known as SwitchReads) +### After Replica Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchReads) Shard `0` still has the `is_primary_serving` set as true. The primary partition is still the same. @@ -178,7 +178,7 @@ partitions:{served_type:REPLICA } ``` -#### After primary traffic is switched using `SwitchTraffic` (previously known as SwitchWrites) +#### After Primary Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchWrites) * `is_primary_serving` is removed from shard `0` * `is_primary_serving` is added to shards `-80` and `80-` @@ -220,9 +220,9 @@ partitions:{served_type:REPLICA } ``` -## What happens when a MoveTables workflow is cutover +## What Happens When a MoveTables Workflow Is Cutover -#### Before MoveTables is initiated +#### Before MoveTables Is Initiated The [`VSchema`](../../../features/vschema/) for the source keyspace contains the table name, so vtgate routes queries to that keyspace. @@ -241,7 +241,7 @@ rules:{from_table:"customer@replica" to_tables:"commerce.customer"} rules:{from_table:"customer.customer@replica" to_tables:"commerce.customer"} ``` -#### On switching replica traffic to target +#### On Switching Replica Traffic to Target The routing rules for replica targeted reads are updated to map the table on the source to the target. @@ -253,7 +253,7 @@ rules:{from_table:"customer" to_tables:"commerce.customer"} rules:{from_table:"customer@replica" to_tables:"customer.customer"} ``` -#### On switching primary traffic +#### On Switching Primary Traffic The routing rules for default read-write traffic are updated to map the table on the source to the target. In addition the tables are added to the “denylist” on the source keyspace which `vttablet` uses to reject queries for these tables on the @@ -277,7 +277,7 @@ tablet_controls:{tablet_type:PRIMARY denylisted_tables:"customer"} is_primary_serving:true ``` -# Miscellaneous Notes: +# Miscellaneous Notes * In VReplication workflows, cutovers are performed manually by the user executing the `SwitchTraffic` and `ReverseTraffic` actions e.g. for a [`MoveTables`](../../movetables/#switchtraffic) or [`Reshard`](../../reshard/#reversetraffic) vtctl diff --git a/content/en/docs/15.0/reference/vreplication/internal/keys.md b/content/en/docs/15.0/reference/vreplication/internal/keys.md index ae3bee759..0be41810e 100644 --- a/content/en/docs/15.0/reference/vreplication/internal/keys.md +++ b/content/en/docs/15.0/reference/vreplication/internal/keys.md @@ -1,11 +1,11 @@ --- -title: Role of table keys in VReplication +title: Role of Table Keys in VReplication description: Uses and requirements for primary and unique keys in source and target tables in VReplication Workflows weight: 3 aliases: ['/docs/design-docs/vreplication/keys/'] --- -# The use of unique keys +# The Use of Unique Keys A VReplication stream copies data from a table on a source tablet to a table on a target tablet. In some cases, the two tablets may be the same one, but the stream is oblivious to such nuance. VReplication needs to be able to copy existing @@ -23,7 +23,7 @@ In fact, in the most common use case, both tables will have the same `PRIMARY KE the same order. This is the default assumption and expectation by VReplication. But this doesn't have to be the case, and it is possible to have different keys on the source and the target table. -## Which keys are eligible? +## Which Keys Are Eligible? Any `UNIQUE KEY` that is non-`NULL`able potentially qualifies. A `NULL`able `UNIQUE KEY` is a key that covers one or more `NULL`able columns. It doesn't matter if column values do or do not actually contain `NULL`s. If a column is `NULL` @@ -38,7 +38,7 @@ prioritizes smaller data types over larger data types. However, not all eligible `UNIQUE KEY`s, or even `PRIMARY KEY`s are usable for all VReplication streams, as described below. -## Comparable rows +## Comparable Rows VReplication needs to be able to determine, given a row in the source table, which row it maps to in the target table. @@ -94,9 +94,9 @@ To clarify, it is **OK** if: All it takes is _one_ viable key that can be used to uniquely identify rows in the source table, and one such viable key in the target table to allow VReplication to work. -### Examples of valid cases +### Examples of Valid Cases -#### Source table and target table are the same +#### Source Table and Target Table Are the Same ```sql CREATE TABLE `entry` ( @@ -110,7 +110,7 @@ CREATE TABLE `entry` ( The above is a trivial scenario. -#### Source table and target table share the same PRIMARY KEY +#### Source Table and Target table Share the Same PRIMARY KEY ```sql CREATE TABLE `source` ( @@ -227,7 +227,7 @@ The only eligible solution in the above is: Incidentally, in the above, the chosen keys differ by name, but share the same columns (`uuid`). -### Examples of invalid cases +### Examples of Invalid Cases #### NULLable columns @@ -272,7 +272,7 @@ CREATE TABLE `target` ( `target` only has one possible key, the `PRIMARY KEY`, covering `id`. But `id` is not found in `source`. -## Configuring the stream +## Configuring The Stream If both source and target table share the same `PRIMARY KEY` (covering the same columns in the same order) then there's nothing to be done. VReplication will pick `PRIMARY KEY` on both ends by default. @@ -396,7 +396,7 @@ With the introduction of mechanisms to automatically determine the optimal key t the `source_unique_key_columns`, `target_unique_key_columns`, and `source_unique_key_target_columns` fields for more fine-grained control, VReplication changes its behavior as needed. -#### Notes about the code +#### Notes About The Code Much of the code uses "PK" terminology. With the introduction of _any_ unique key utilization the "PK" terminology becomes incorrect. However, to avoid mass rewrites we kept this terminology, and wherever VReplication discusses diff --git a/content/en/docs/15.0/reference/vreplication/internal/life-of-a-stream.md b/content/en/docs/15.0/reference/vreplication/internal/life-of-a-stream.md index 1d58d9e97..5648fc2fe 100644 --- a/content/en/docs/15.0/reference/vreplication/internal/life-of-a-stream.md +++ b/content/en/docs/15.0/reference/vreplication/internal/life-of-a-stream.md @@ -1,5 +1,5 @@ --- -title: Life of a stream +title: Life of a Stream description: How VReplication replicates data weight: 1 aliases: ['/docs/design-docs/vreplication/life-of-a-stream/'] @@ -18,7 +18,7 @@ streams events from the binlog. ![VReplication Flow](/img/VReplicationFlow.png) -#### Full table copy +#### Full Table Copy If the entire table data is requested then the simple streaming done by the _replication_ mode can create an avalanche of events (think 100s of millions of rows). Moreover, and more importantly, it is highly likely that necesasry older @@ -54,7 +54,7 @@ not able to process them in time. For example, in resharding workflows we need t statements and execute them on the target's mysqld instance, which are usually much slower than just selecting data on the source. -### Modes, in detail +### Modes, in Detail #### Replicate @@ -158,7 +158,7 @@ As detailed above the catchup phase runs between copy phase cycles (time limited GTID position can move significantly ahead. So we run a catchup and fast-forward phase until we come close to the current position — i.e. the replication lag is small. At that point we execute another Copy cycle. -#### Fast forward +#### Fast Forward During the copy phase we first take a snapshot. Then we fast-forward: we replicate from the gtid position where we stopped the Catchup to the position of the new snapshot. diff --git a/content/en/docs/15.0/reference/vreplication/internal/tracker.md b/content/en/docs/15.0/reference/vreplication/internal/tracker.md index 08fd12941..4a9a73478 100644 --- a/content/en/docs/15.0/reference/vreplication/internal/tracker.md +++ b/content/en/docs/15.0/reference/vreplication/internal/tracker.md @@ -176,7 +176,7 @@ If version tracking is turned off on the `PRIMARY` for some time, correct versio which will always return the latest schema. This might result in an incorrect schema when a vstream is processing events in the past. -#### Possible new features around this functionality +#### Possible New Features Around This Functionality - Schema tracking vstream client for notifications of all ddls - Raw history of schema changes for auditing, root cause analysis, etc. diff --git a/content/en/docs/16.0/reference/vreplication/internal/cutover.md b/content/en/docs/16.0/reference/vreplication/internal/cutover.md index f733a5e3c..376ffc7dc 100644 --- a/content/en/docs/16.0/reference/vreplication/internal/cutover.md +++ b/content/en/docs/16.0/reference/vreplication/internal/cutover.md @@ -1,11 +1,11 @@ --- -title: How traffic is switched +title: How Traffic Is Switched description: How Vitess signals traffic cutover for Reshard and MoveTables weight: 2 aliases: ['/docs/design-docs/vreplication/cutover/'] --- -# Related persistent Vitess objects +# Related Persistent Vitess Objects {{< info >}} As the objects or keys noted below are stored in [the topo server](../../../features/topology-service/) and @@ -76,7 +76,7 @@ dedicated [`GetRoutingRules`](../../../programs/vtctl/schema-version-permissions vtctl client command which will return the rules for all keyspaces in the topo. {{< /info >}} -# How VTGate routes a query +# How VTGate Routes a Query This section walks through a simplified version of the logic used to determine which keyspace and table vtgate will route a simple query of the form `select * from t1 where id = 1` (a _read_ query) or `insert into t1 (id, val) values (1,'abc')` @@ -93,7 +93,7 @@ and selecting the ones whose `query_service_disabled` field is *not* set and who [`VSchema`](../../../features/vschema/) (stored in the `global` topo), the shard for the relevant row is computed based on the keyrange to which the id is mapped to using the declared [`VIndex` function/type](../../../features/vindexes/#predefined-vindexes). -# Changes made to the topo when traffic is switched +# Changes Made to the Topo When Traffic Is Switched This document outlines the steps involved in the cutover process of [`MoveTables`](../../movetables/) and [`Reshard`](../../reshard/) @@ -105,11 +105,11 @@ in the workflow. Items in italics are topo keys and the following snippet the value of the key {{< /info >}} -## What happens when a Reshard is cutover +## What Happens When a Reshard Is Cutover For brevity we only show the records for the `80-` shard. There will be similar records for the `-80` shard. -#### Before Resharding, after -80/80- shards are created +#### Before Resharding, After -80/80- Shards Are Created Only shard `0` has `is_primary_serving` set to true. The `SrvKeyspace` record only has references to `0` for both `PRIMARY` and `REPLICA` tablet types. @@ -137,7 +137,7 @@ partitions:{served_type:PRIMARY shard_references:{name:"0"}} partitions:{served_type:REPLICA shard_references:{name:"0"}} ``` -### After replica traffic is switched using `SwitchTraffic` (previously known as SwitchReads) +### After Replica Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchReads) Shard `0` still has the `is_primary_serving` set as true. The primary partition is still the same. @@ -178,7 +178,7 @@ partitions:{served_type:REPLICA } ``` -#### After primary traffic is switched using `SwitchTraffic` (previously known as SwitchWrites) +#### After Primary Traffic Is Switched Using `SwitchTraffic` (Previously Known as SwitchWrites) * `is_primary_serving` is removed from shard `0` * `is_primary_serving` is added to shards `-80` and `80-` @@ -220,9 +220,9 @@ partitions:{served_type:REPLICA } ``` -## What happens when a MoveTables workflow is cutover +## What Happens When a MoveTables Workflow Is Cutover -#### Before MoveTables is initiated +#### Before MoveTables Is Initiated The [`VSchema`](../../../features/vschema/) for the source keyspace contains the table name, so vtgate routes queries to that keyspace. @@ -241,7 +241,7 @@ rules:{from_table:"customer@replica" to_tables:"commerce.customer"} rules:{from_table:"customer.customer@replica" to_tables:"commerce.customer"} ``` -#### On switching replica traffic to target +#### On Switching Replica Traffic to Target The routing rules for replica targeted reads are updated to map the table on the source to the target. @@ -253,7 +253,7 @@ rules:{from_table:"customer" to_tables:"commerce.customer"} rules:{from_table:"customer@replica" to_tables:"customer.customer"} ``` -#### On switching primary traffic +#### On Switching Primary Traffic The routing rules for default read-write traffic are updated to map the table on the source to the target. In addition the tables are added to the “denylist” on the source keyspace which `vttablet` uses to reject queries for these tables on the @@ -277,7 +277,7 @@ tablet_controls:{tablet_type:PRIMARY denylisted_tables:"customer"} is_primary_serving:true ``` -# Miscellaneous Notes: +# Miscellaneous Notes * In VReplication workflows, cutovers are performed manually by the user executing the `SwitchTraffic` and `ReverseTraffic` actions e.g. for a [`MoveTables`](../../movetables/#switchtraffic) or [`Reshard`](../../reshard/#reversetraffic) vtctl diff --git a/content/en/docs/16.0/reference/vreplication/internal/keys.md b/content/en/docs/16.0/reference/vreplication/internal/keys.md index ae3bee759..0be41810e 100644 --- a/content/en/docs/16.0/reference/vreplication/internal/keys.md +++ b/content/en/docs/16.0/reference/vreplication/internal/keys.md @@ -1,11 +1,11 @@ --- -title: Role of table keys in VReplication +title: Role of Table Keys in VReplication description: Uses and requirements for primary and unique keys in source and target tables in VReplication Workflows weight: 3 aliases: ['/docs/design-docs/vreplication/keys/'] --- -# The use of unique keys +# The Use of Unique Keys A VReplication stream copies data from a table on a source tablet to a table on a target tablet. In some cases, the two tablets may be the same one, but the stream is oblivious to such nuance. VReplication needs to be able to copy existing @@ -23,7 +23,7 @@ In fact, in the most common use case, both tables will have the same `PRIMARY KE the same order. This is the default assumption and expectation by VReplication. But this doesn't have to be the case, and it is possible to have different keys on the source and the target table. -## Which keys are eligible? +## Which Keys Are Eligible? Any `UNIQUE KEY` that is non-`NULL`able potentially qualifies. A `NULL`able `UNIQUE KEY` is a key that covers one or more `NULL`able columns. It doesn't matter if column values do or do not actually contain `NULL`s. If a column is `NULL` @@ -38,7 +38,7 @@ prioritizes smaller data types over larger data types. However, not all eligible `UNIQUE KEY`s, or even `PRIMARY KEY`s are usable for all VReplication streams, as described below. -## Comparable rows +## Comparable Rows VReplication needs to be able to determine, given a row in the source table, which row it maps to in the target table. @@ -94,9 +94,9 @@ To clarify, it is **OK** if: All it takes is _one_ viable key that can be used to uniquely identify rows in the source table, and one such viable key in the target table to allow VReplication to work. -### Examples of valid cases +### Examples of Valid Cases -#### Source table and target table are the same +#### Source Table and Target Table Are the Same ```sql CREATE TABLE `entry` ( @@ -110,7 +110,7 @@ CREATE TABLE `entry` ( The above is a trivial scenario. -#### Source table and target table share the same PRIMARY KEY +#### Source Table and Target table Share the Same PRIMARY KEY ```sql CREATE TABLE `source` ( @@ -227,7 +227,7 @@ The only eligible solution in the above is: Incidentally, in the above, the chosen keys differ by name, but share the same columns (`uuid`). -### Examples of invalid cases +### Examples of Invalid Cases #### NULLable columns @@ -272,7 +272,7 @@ CREATE TABLE `target` ( `target` only has one possible key, the `PRIMARY KEY`, covering `id`. But `id` is not found in `source`. -## Configuring the stream +## Configuring The Stream If both source and target table share the same `PRIMARY KEY` (covering the same columns in the same order) then there's nothing to be done. VReplication will pick `PRIMARY KEY` on both ends by default. @@ -396,7 +396,7 @@ With the introduction of mechanisms to automatically determine the optimal key t the `source_unique_key_columns`, `target_unique_key_columns`, and `source_unique_key_target_columns` fields for more fine-grained control, VReplication changes its behavior as needed. -#### Notes about the code +#### Notes About The Code Much of the code uses "PK" terminology. With the introduction of _any_ unique key utilization the "PK" terminology becomes incorrect. However, to avoid mass rewrites we kept this terminology, and wherever VReplication discusses diff --git a/content/en/docs/16.0/reference/vreplication/internal/life-of-a-stream.md b/content/en/docs/16.0/reference/vreplication/internal/life-of-a-stream.md index 1d58d9e97..5648fc2fe 100644 --- a/content/en/docs/16.0/reference/vreplication/internal/life-of-a-stream.md +++ b/content/en/docs/16.0/reference/vreplication/internal/life-of-a-stream.md @@ -1,5 +1,5 @@ --- -title: Life of a stream +title: Life of a Stream description: How VReplication replicates data weight: 1 aliases: ['/docs/design-docs/vreplication/life-of-a-stream/'] @@ -18,7 +18,7 @@ streams events from the binlog. ![VReplication Flow](/img/VReplicationFlow.png) -#### Full table copy +#### Full Table Copy If the entire table data is requested then the simple streaming done by the _replication_ mode can create an avalanche of events (think 100s of millions of rows). Moreover, and more importantly, it is highly likely that necesasry older @@ -54,7 +54,7 @@ not able to process them in time. For example, in resharding workflows we need t statements and execute them on the target's mysqld instance, which are usually much slower than just selecting data on the source. -### Modes, in detail +### Modes, in Detail #### Replicate @@ -158,7 +158,7 @@ As detailed above the catchup phase runs between copy phase cycles (time limited GTID position can move significantly ahead. So we run a catchup and fast-forward phase until we come close to the current position — i.e. the replication lag is small. At that point we execute another Copy cycle. -#### Fast forward +#### Fast Forward During the copy phase we first take a snapshot. Then we fast-forward: we replicate from the gtid position where we stopped the Catchup to the position of the new snapshot. diff --git a/content/en/docs/16.0/reference/vreplication/internal/tracker.md b/content/en/docs/16.0/reference/vreplication/internal/tracker.md index 08fd12941..4a9a73478 100644 --- a/content/en/docs/16.0/reference/vreplication/internal/tracker.md +++ b/content/en/docs/16.0/reference/vreplication/internal/tracker.md @@ -176,7 +176,7 @@ If version tracking is turned off on the `PRIMARY` for some time, correct versio which will always return the latest schema. This might result in an incorrect schema when a vstream is processing events in the past. -#### Possible new features around this functionality +#### Possible New Features Around This Functionality - Schema tracking vstream client for notifications of all ddls - Raw history of schema changes for auditing, root cause analysis, etc.